# 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. 推荐执行顺序

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

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