new_sdk_wu/md_go_migration_api/12-development-roadmap-todo.md

GoFrame 重构开发计划 TODO

本文档用于规划 new_sdk 从当前 PHP/ThinkPHP 项目迁移到 GoFrame 技术栈的阶段路线。计划先排 5 个版本，每个版本都要有明确边界，避免一开始就陷入“大重写”。

0. 总体原则

• 先搭底座，再迁业务。
• 先做可观测、配置、数据库访问、协议兼容，再做复杂支付。
• 先做模块化单体，不急着拆微服务。
• 新系统先兼容老 SDK 协议和老数据表，后续再逐步优化字段、状态和接口。
• 每个版本都必须可运行、可回滚、可验收。
• 支付、订单、发货、渠道回调必须有幂等和日志，不允许只靠控制器临时逻辑。

1. 版本总览

版本	名称	核心目标	主要交付
V0.1	技术栈底座版	搭建 GoFrame 基础工程和运行环境	项目骨架、配置、日志、DB、Redis、Docker、基础监控
V0.2	基础账户体系版	跑通前后台基础账号和权限	后台管理员、前台用户、登录、Token、RBAC 雏形
V0.3	SDK 协议与基础业务版	兼容老 SDK API 协议，迁移低风险读取接口	AES/sign/token、游戏配置、版本、公告、礼包查询
V0.4	支付订单核心版	建立订单、支付、回调、发货状态机	下单、支付渠道抽象、回调幂等、Redis Stream、CP 通知
V0.5	渠道与运营闭环版	迁移 complex 渠道、运营能力和观测闭环	渠道适配器、优惠券/礼包、Dashboard、告警、灰度切流

2. V0.1 技术栈底座版

版本目标

搭建一个可运行、可配置、可观测、可部署的 GoFrame 服务底座。这个版本不追求业务完整，只解决工程基础。

V0.1 必须优先采用 GoFrame 官方脚手架和轻量 Docker 镜像策略，避免一开始就做出偏离框架习惯、镜像体积过大、后续维护成本高的工程底座。

技术范围

• Go 1.26.x
• GoFrame v2
• GoFrame CLI：gf init、gf gen dao、gf run、gf build
• MySQL
• Redis
• Redis Stream 预留
• OpenAPI
• Docker Compose
• Nginx
• Prometheus
• Grafana
• Loki
• Tempo
• OpenTelemetry
• Grafana Alloy

工程约束

• 项目必须使用 gf init 初始化，不手写一套偏离 GoFrame 官方习惯的目录。
• 保留 GoFrame 官方目录结构，再根据业务复杂度补充 domain、adapter、provider 等目录。
• 数据库访问层优先使用 gf gen dao 生成。
• 核心支付、订单、资产流水等高风险 SQL 可以保留手写 SQL 或独立 repository，不强行全部套 DAO。
• Docker 必须使用 multi-stage build。
• 生产镜像不能直接使用 golang 构建镜像。
• V0.1 初期允许使用 alpine 作为运行镜像，便于排查问题。
• 稳定后生产候选优先使用 distroless/static-debian12。
• 暂不优先使用 scratch，避免证书、时区、DNS、调试成本过高。
• 镜像内不放源码、不放编译工具、不放 .env、不放证书私钥和支付密钥。
• 配置通过环境变量、挂载配置或配置中心注入。
• Docker Compose 仅用于本地开发和测试，不直接等同于生产部署方案。

TODO

• 使用 gf init 初始化 GoFrame 项目结构。
• 固化 GoFrame CLI 版本和 Go 版本。
• 设计目录结构：api、internal/controller、internal/service、internal/dao、internal/model、internal/logic、internal/pkg。
• 在官方目录基础上预留：internal/domain、internal/adapter、internal/provider。
• 接入配置系统，区分 local、dev、prod。
• 接入 MySQL，确认连接池、超时、慢查询日志。
• 配置 gf gen dao，先生成基础 DAO/Entity/Model。
• 接入 Redis，确认连接池和 key 前缀。
• 设计统一响应结构。
• 设计统一错误码结构。
• 设计统一日志字段：trace_id、request_id、appid、user_id、order_no、channel、route。
• 接入 OpenAPI 文档生成。
• 编写 multi-stage Dockerfile。
• 构建阶段使用 golang:<version>-alpine 或官方 Go 镜像。
• 运行阶段初期使用 alpine，稳定后评估切换 distroless/static-debian12。
• 确认运行镜像中包含 CA 证书和正确时区。
• 编写 Docker Compose：Go 服务、MySQL 可选、Redis、Nginx、Prometheus、Grafana、Loki、Tempo、Alloy。
• 接入 Prometheus 基础指标：请求量、耗时、错误数。
• 接入 Loki JSON 日志采集。
• 接入 OpenTelemetry trace_id 生成和透传。
• 编写健康检查接口：/health、/ready。

验收标准

• 本地 docker compose up 后服务可启动。
• /health 返回正常。
• Go 服务可以连接 MySQL 和 Redis。
• Grafana 可以看到基础请求指标。
• Loki 可以按 trace_id 查询日志。
• OpenAPI 页面可以访问。
• Docker 生产候选镜像不包含 Go 编译器。
• Docker 生产候选镜像不包含项目源码。
• Docker 镜像体积符合预期，避免直接使用 golang runtime。
• gf gen dao 可以稳定生成数据库访问层。

暂不做

• 不迁移支付。
• 不迁移 complex 渠道。
• 不改老数据库结构。
• 不拆微服务。

3. V0.2 基础账户体系版

版本目标

搭建基础前后台账户体系，为后续管理端、运营端、SDK 用户体系迁移做准备。

这里的“前台账户”和“后台账户”要分清：

• 后台账户：运营/管理人员使用，用于管理游戏、渠道、订单、礼包等。
• 前台账户：SDK 用户体系，对应玩家登录、注册、实名、子账号等业务。

TODO

• 梳理当前后台管理员表、角色表、权限表。
• 梳理当前 SDK 用户表、实名表、设备表、子账号表。
• 设计后台管理员登录接口。
• 设计后台 RBAC 权限模型。
• 设计后台菜单、按钮、接口权限的关系。
• 设计前台用户基础模型。
• 设计用户登录 Token 模型。
• 兼容老 Token 或设计 Token 兼容层。
• 接入密码加密策略，确认是否兼容老密码算法。
• 接入登录日志。
• 接入操作日志。
• 设计账号封禁、解封、状态变更流程。
• 编写账户相关单元测试。

交付接口

• 后台登录。
• 后台退出。
• 后台当前用户信息。
• 后台权限菜单。
• 前台用户登录雏形。
• 前台用户 Token 校验。

验收标准

• 后台账号可以登录并获取权限。
• 后台接口可以通过中间件校验权限。
• 前台用户可以完成登录和 Token 校验。
• 登录日志和操作日志可查。
• Grafana/Loki 能按用户和请求 ID 查到登录链路。

暂不做

• 不做完整支付。
• 不做 complex 渠道登录。
• 不做复杂运营功能。

4. V0.3 SDK 协议与基础业务版

版本目标

开始承接老 application/api 的基础能力，优先迁移低风险读取接口和 SDK 公共协议层。

TODO

• 实现 SDK 请求解析中间件。
• 实现 AES 解密兼容。
• 实现 MD5 sign 校验兼容。
• 实现 appid/appkey 配置校验。
• 实现统一响应加密兼容。
• 实现 debug 明文请求兼容。
• 实现 auth_code/token 解析兼容。
• 整理并迁移游戏基础信息接口。
• 整理并迁移版本配置接口。
• 整理并迁移公告接口。
• 整理并迁移礼包列表/福利查询接口。
• 整理并迁移区服/角色查询类接口。
• 为 AES/sign/token 准备 golden tests。
• 为低风险接口做 PHP/Go 响应对比。

交付接口

• SDK 加解密协议。
• SDK 签名校验。
• 游戏配置读取。
• 版本信息读取。
• 公告读取。
• 礼包/福利读取。
• 区服/角色基础查询。

验收标准

• 老 SDK 请求样本在 Go 侧可以正确解析。
• Go 响应格式与 PHP 兼容。
• AES/sign/token golden tests 通过。
• 低风险读取接口可灰度切流。
• 日志里能按 appid、route、trace_id 追踪请求。

暂不做

• 不迁移真实支付回调。
• 不迁移复杂渠道适配器。
• 不调整客户端协议。

5. V0.4 支付订单核心版

版本目标

建立支付、订单、回调、发货、补单的核心闭环。这个版本是整个重构里风险最高的一版，必须先做状态机和幂等。

TODO

• 梳理支付相关表：订单表、CP 通知表、平台币表、优惠券表、流水表。
• 明确订单状态机。
• 明确支付回调幂等规则。
• 明确金额单位，统一使用整数分或 decimal。
• 设计支付渠道接口 PaymentProvider。
• 设计订单服务 OrderService。
• 设计回调服务 NotifyService。
• 设计 CP 通知任务。
• 接入 Redis Stream，用于 CP 通知、补单、异步任务。
• 实现支付下单接口。
• 实现 1 到 2 个低风险支付渠道。
• 实现支付回调验签。
• 实现订单状态更新事务。
• 实现重复回调处理。
• 实现 CP 通知重试。
• 实现补单入口。
• 实现支付相关 Dashboard。
• 实现支付失败告警。

交付接口/能力

• 创建订单。
• 支付参数生成。
• 支付异步回调。
• 订单查询。
• CP 通知。
• CP 通知重试。
• 补单。
• 支付日志和支付指标。

验收标准

• 重复支付回调不会重复发货。
• 金额不一致会拒绝并记录告警日志。
• CP 通知失败不会导致第三方支付回调无限失败。
• Redis Stream pending 可监控。
• 支付回调可通过 order_no 查日志和 trace。
• 支付状态机有单元测试和集成测试。

暂不做

• 不一次性迁移所有支付渠道。
• 不在这个版本重构全部历史订单表。
• 不改变现有 CP 回调协议。

6. V0.5 渠道与运营闭环版

版本目标

迁移 complex 联运渠道能力，并补齐运营类功能和观测闭环。这个版本重点是渠道适配器模式，不允许把渠道逻辑重新堆进大控制器。

TODO

• 梳理 complex 渠道清单。
• 按流量和风险给渠道排序。
• 设计 ComplexAdapter 接口。
• 设计渠道登录统一结果模型。
• 设计渠道支付回调统一结果模型。
• 设计渠道特殊参数扩展点。
• 优先迁移 3 到 5 个高价值渠道。
• 为每个渠道准备登录样本和支付回调样本。
• 实现渠道适配器注册表。
• 实现渠道级指标：登录成功率、支付成功率、验签失败率。
• 实现渠道级日志字段：channel、game_id、appid、order_no。
• 迁移优惠券基础功能。
• 迁移礼包码基础功能。
• 迁移运营查询类接口。
• 完善后台运营页面接口。
• 配置渠道异常告警。
• 设计灰度切流方案。

交付接口/能力

• complex 渠道登录。
• complex 渠道支付回调。
• 渠道特殊参数接口。
• 优惠券领取/使用。
• 礼包码领取/核销。
• 后台运营查询接口。
• 渠道 Dashboard。

验收标准

• 每个迁移渠道都有 contract test。
• 渠道失败率可以在 Grafana 按 channel 查看。
• 渠道回调可通过 order_no 追踪。
• 灰度切流时可回退到 PHP。
• 运营人员可以通过后台查看核心数据。

暂不做

• 不一次性迁移所有 complex 渠道。
• 不改第三方渠道协议。
• 不把运营后台做成完整新产品，只做重构需要的核心闭环。

7. 版本后续预留

V0.6 之后可以考虑：

• 全量支付渠道迁移。
• 全量 complex 渠道迁移。
• 管理后台完整重构。
• 数据表清理和字段规范化。
• Redis key 规范化。
• 服务拆分。
• Kubernetes 部署。
• 更完整的风控、防沉迷、实名、数据报表体系。

8. 当前最优先 TODO

在真正进入 V0.1 开发前，还需要完成以下前置工作：

• 生成 06-database-schema-inventory.md：全量表结构、字段、索引。
• 生成 07-api-table-access-map.md：API 代码读写表关系。
• 生成 08-business-domain-data-map.md：业务域和数据表映射。
• 生成 09-payment-and-order-state-machine.md：支付订单状态机。
• 确认 GoFrame 项目目录放置位置。
• 确认是否需要保留 PHP 与 Go 并行灰度。
• 确认第一版后台是否使用现有管理后台页面，还是新建 Go 后台 API。

9. 推荐执行顺序

先做文档和数据映射
  -> V0.1 技术栈底座
  -> V0.2 账户体系
  -> V0.3 SDK 协议和基础业务
  -> V0.4 支付订单核心
  -> V0.5 渠道和运营闭环

这个顺序的核心原因：支付和渠道是最高风险模块，必须建立在协议、账户、日志、指标、队列、状态机都清楚的基础上。