# api 模块 Go 重构梳理索引

生成时间：2026-06-09

源代码范围：`C:\web\composer\qi_meng\new_sdk\www\new_sdk\application\api`

目标用途：为后续将当前 PHP/ThinkPHP SDK API 重构为 Go 服务提供业务逻辑、接口边界、数据依赖和迁移顺序参考。

## 文档清单

1. `01-api-architecture-and-business-domains.md`
   - 当前 `api` 模块的入口协议、公共基类逻辑、业务域拆分。
2. `02-controller-endpoint-inventory.md`
   - 控制器、服务类、渠道适配器清单，便于迁移时逐个勾兑。
3. `03-core-business-flows.md`
   - 登录注册、支付下单、支付回调、聚合渠道、实名防沉迷、MLBB 活动等核心流程。
4. `04-data-dependencies-and-risks.md`
   - 数据表、Redis key、外部 SDK/支付渠道、敏感配置和迁移风险。
5. `05-go-refactor-blueprint.md`
   - Go 分层结构、接口抽象、迁移阶段和测试策略。
6. `11-observability-stack-guide.md`
   - Prometheus、Grafana、Loki、Tempo、OpenTelemetry、Alloy 的用途说明和第一版落地建议。
7. `12-development-roadmap-todo.md`
   - GoFrame 重构 5 个版本的开发计划 TODO，包括底座、账户、SDK 协议、支付订单、渠道运营。

## 当前判断

当前项目不是单纯的 API CRUD 服务，而是一个游戏 SDK 中台：

- 客户端请求统一经过 AES 解密、MD5 签名、App 配置校验、Token/IMEI 校验。
- 账号体系同时承载主账号、子账号、游戏归属渠道、实名状态、设备信息。
- 支付链路是最大复杂度来源，包含游戏充值、平台币充值、专属币、代金券、混合支付、第三方支付参数生成、支付异步通知、CP 发货通知。
- `complex` 是聚合/联运渠道适配层，约 50 多个渠道类，接口形式相似但细节差异很大。
- `v2` 已经在重构部分业务，例如用户中心、订单、平台币、代金券、聚合渠道处理，Go 迁移时应优先吸收这些较新的边界。
- `api/config.php` 和部分服务代码里混有渠道密钥、证书、回调地址等敏感配置，Go 版本不要照搬到代码仓库，应移入环境变量、密钥管理或配置中心。

## 建议迁移路线

建议使用 strangler pattern 渐进迁移，不建议一次性重写全部接口：

1. 先迁移公共协议层：AES、签名、App 校验、Token 校验、响应加密。
2. 再迁移低风险读取类接口：版本配置、公告、游戏包信息、礼包列表、订单查询。
3. 然后迁移账号安全类接口：登录、注册、短信、设备、实名，保留 PHP 旁路比对。
4. 支付下单和支付回调最后迁移，必须先补齐 golden case、幂等、金额校验和事务测试。
5. `complex` 渠道适配器单独做 Go 插件式注册表，按渠道逐个迁移，不要重新堆成一个大控制器。

## 迁移时必须保留的兼容点

- 客户端密文协议：默认 `AES-128-ECB`，debug 请求可明文。
- 签名算法：过滤 `sign`，按 key 升序拼接 `key=value`，追加 `client_appkey`，小写后 MD5。
- Token 格式：`userid|username|gameid|sub_username|token_random|sdk` 经 `auth_code` 加密。
- Redis 登录态：`token => imeil`，`token|sdk|userid|gameid => token_random`。
- 响应结构：`code/msg/time/data/err_code`，生产环境需要加密输出。
- 支付订单状态：`cy_pay.status`、`cy_paycpinfo.payflag`、`member_coin_pay.status` 的历史语义不能改。
- CP 回调签名字段和成功判定：当前多数逻辑以 CP 返回字符串 `success` 为成功。

## 迁移优先级概览

| 优先级 | 模块 | 理由 |
| --- | --- | --- |
| P0 | 协议层、认证层、配置层 | 所有接口共享，错了会全量不可用 |
| P0 | 支付订单与回调状态机 | 涉及资金、发货、幂等、退款 |
| P1 | 登录注册、子账号、实名防沉迷 | 用户入口，强依赖历史数据兼容 |
| P1 | `complex` 渠道适配 | 渠道多，适合抽象接口后逐个迁移 |
| P2 | 订单/礼包/代金券/平台币查询 | 可先灰度，风险相对可控 |
| P2 | MLBB 活动、第三方数据 API | 活动/渠道专项，可按需求迁移 |