new_sdk_wu/md_go_migration_api/01-api-architecture-and-business-domains.md

api 架构与业务域梳理

模块定位

application\api 是 SDK 侧的对外接口模块，覆盖客户端 SDK、游戏 CP、聚合渠道、支付渠道、推广页和专项活动。

从业务职责看，它不是一个单一 API 模块，而是多个业务中台能力混在同一模块下：

• SDK 客户端协议：加解密、签名、App 校验、Token 校验、统一响应。
• 玩家账号：注册、登录、第三方登录、子账号、设备、短信、邮箱、找回密码。
• 游戏关系：游戏详情、渠道包、启动上报、区服角色、版本更新。
• 支付：游戏充值、平台币充值、代金券、专属币、混合支付、支付通知、CP 发货通知。
• 聚合渠道：渠道登录、渠道支付、渠道回调、渠道角色/区服数据。
• 用户中心：手机号/邮箱绑定、密码修改、实名、防沉迷、新设备校验。
• 活动和渠道专项：MLBB 活动、抖音游戏开放、YQL 数据、聚合报表、风控。

目录职责

目录	当前职责	Go 迁移建议
controller	HTTP 控制器，包含根控制器、v1、v2、mlbb	拆到 internal/http/handler，按业务域分 handler
controller\Api.php	API 公共协议、验签、登录校验、响应加密、设备/区服保存	拆成 middleware + auth service + response codec
service	支付通知、聚合通知、道具发放、专项福利、MLBB 礼包	拆成 domain service，不要依赖 HTTP 全局输入
complex	聚合渠道适配器	抽象为 ComplexAdapter 注册表，按渠道实现
library\mlbb	MLBB 相关 SDK/抽奖算法	拆入 internal/module/mlbb 或独立活动模块
validate	ThinkPHP 表单校验	Go 中改为 request DTO + validator
view	推广页、支付成功页、账号安全页等 HTML	如 Go 只做 API，可迁移到前端/静态服务；若保留页面，另设 web handler

请求生命周期

多数继承 app\api\controller\Api 的接口会走以下流程：

1. initDevice
   • 从 header device 或 body device 识别设备来源。
   • 当前值含义：1=PC、2=Android、3=iOS、4=H5。
2. 读取请求体
   • 默认从 php://input 读取密文。
   • 使用 Env::get('aes_key') 执行 AES-128-ECB 解密。
   • header qmapidebug=true 时允许明文参数。
3. App 校验
   • 必须传 appid。
   • 通过 cy_app 对应模型 App 查询 id/appkey/client_appkey/gameid。
4. 签名校验
   • 去掉 sign 字段。
   • 参数 key 升序排序。
   • 按 key=value 拼接，追加 client_appkey。
   • 字符串转小写后 MD5。
   • api_debug=false 时签名失败拒绝。
5. 默认渠道
   • 如果没有 channel_id，使用配置 initial_channel_id。
6. 登录校验
   • 非白名单控制器/方法需要 imeil 和 token。
   • Redis 中校验 token => imeil。
   • auth_code 解出 userid|username|gameid|sub_username|token_random|sdk。
   • Redis 再校验 token|sdk|userid|gameid => token_random。
   • 校验通过后把 userid/gameid/username/token/sub_username/member_channel_id 注入 $this->input。
7. 响应输出
   • debug 模式返回明文 JSON。
   • 生产模式 JSON 再经 AES 加密。
   • jsonResult 会把正数 code 映射成 1，非正数映射成 0，并保留 err_code。

Go 迁移时应把上面 7 步拆为独立中间件，避免 handler 直接操作全局请求。

入口和路由

application\route.php 中域名别名大致把以下入口映射到 api：

• sdkapi、t 映射到 api。
• devsdkapi、devt 在开发环境映射到 api。
• 显式路由包括：
  • POST mp/get_wxmp_code -> Api/ThreePlatform/getWxAuthCode
  • POST mp/get_order_info -> Api/ThreePlatform/getOrderInfo
  • POST mp/get_pay -> Api/ThreePlatform/getPay
  • GET mp/get_article_list -> Api/ThreePlatform/getArticleList
  • GET mp/get_article_info -> Api/ThreePlatform/getArticleInfo
  • GET mlbb/:code -> Api/Index/mlbbDownload
  • POST /gh/get_role -> Api/JhApi/getRole
  • POST /gh/get_sub -> Api/JhApi/getSubList
  • POST /gh/channel_data_summary -> Api/JhApi/getChannelDataSummary
  • POST /gh/channel_data_summary_v2 -> Api/JhApi/getChannelDataSummaryV2
  • POST /gh/get_pay_list -> Api/JhApi/getPayList
  • POST /gh/get_sub_user_list -> Api/JhApi/getSubUserList
  • GET /game/detail -> Api/Game/detail

除了显式路由，ThinkPHP 默认还支持类似 sdkapi/v1/login/index、sdkapi/v2/user/userInfo 的模块/控制器/方法访问方式。Go 迁移时需要先从 nginx/access log 或客户端 SDK 配置确认真实使用路径。

核心业务域

1. SDK 协议与认证

主要代码：

• controller\Api.php
• api\common.php
• api\config.php

职责：

• AES 解密和响应加密。
• MD5 请求验签。
• App 配置校验。
• Token/IMEI 登录态校验。
• 请求频率管控。
• 保存设备、角色、区服信息。

Go 建议：

• internal/protocol/codec：AES、JSON、响应封装。
• internal/protocol/sign：客户端签名算法。
• internal/auth/session：Token decode、Redis 校验、用户上下文。
• internal/module/game_role：设备和区服角色保存。

2. 账号与登录注册

主要代码：

• v1\Login.php
• v1\Register.php
• v1\SendSms.php
• v2\User.php
• v2\Forget.php
• v2\Captcha.php
• v1\PasswordFind.php

职责：

• 账号密码登录、短信登录、QQ/微信/抖音等第三方登录。
• 注册时校验用户名、密码、游戏、渠道、设备、IP、游戏/渠道冻结状态。
• 创建主账号 cy_members、实名扩展 cy_memberstwo、游戏渠道关系 cy_member_channel_game_rel、子账号 nw_subaccount。
• 生成 SDK token，并写 Redis 登录态。
• 账号安全：手机号、邮箱、找回密码、新设备验证、密码修改。

Go 建议：

• internal/module/account：主账号、登录注册、密码。
• internal/module/session：token 和 Redis 会话。
• internal/module/security：短信、验证码、设备校验。
• internal/module/identity：实名与防沉迷。

3. 游戏、角色、启动和版本

主要代码：

• Game.php
• v1\Role.php
• v1\Startup.php
• v1\CheckUpdate.php
• v2\GameVersion.php
• v2\GameNotify.php

职责：

• 游戏详情、推广下载页、渠道包和安装包信息。
• 客户端启动/设备上报。
• 区服角色新增/更新。
• 游戏通知、版本检查、包更新。

Go 建议：

• internal/module/game：游戏配置、包信息、版本。
• internal/module/role：角色和区服写入。
• internal/module/startup：设备启动上报。

4. 支付、订单和资产

主要代码：

• v1\Pay.php
• v1\PayNotify.php
• v1\PayNotifyCoin.php
• v2\Coin.php
• v2\Order.php
• service\PayNotifyService.php
• application\service\GamePayService.php
• application\service\MemberCoinService.php
• application\service\PayService.php
• common\logic\Pay.php
• common\logic\PayCallback.php

职责：

• 游戏充值下单。
• 平台币充值下单。
• 专属币、平台币、代金券、混合支付金额计算。
• 支付方式随机/路由。
• 第三方支付参数生成。
• 支付异步回调验签。
• 订单置为成功、资产扣减/增加、CP 发货回调。

Go 建议：

• internal/module/payment/order：订单状态机和事务。
• internal/module/payment/provider：第三方支付适配器。
• internal/module/payment/notify：支付回调验签与归一化。
• internal/module/payment/asset：平台币、专属币、代金券资产变动。
• internal/module/payment/callback：CP 发货通知。

5. 聚合渠道和联运适配

主要代码：

• v1\ComplexLogin.php
• v1\ComplexPay.php
• v1\ComplexPayNotify.php
• v2\Complex.php
• v2\ComplexAuthentication.php
• service\NotifyService.php
• complex\*.php

职责：

• 渠道登录验签与用户映射。
• 渠道支付下单和回调验签。
• 渠道通知数据归一化。
• 渠道自定义成功/失败响应。
• 渠道实名接口。
• 渠道角色/区服数据同步。

Go 建议：

• internal/module/complex：聚合领域服务。
• internal/module/complex/adapter：渠道适配器注册表。
• internal/module/complex/auth：渠道实名。
• 所有渠道统一实现接口，不再动态拼 class name。

6. 用户中心、实名和防沉迷

主要代码：

• v1\UserCenter.php
• v1\UserCenterAuth.php
• v1\Identity.php
• v1\IsIdentity.php
• v1\YhIdentity.php
• v2\User.php
• application\service\CommonService.php

职责：

• 用户详情、账号安全、手机号/邮箱绑定。
• 平台实名和中宣部实名。
• 未成年登录时间限制。
• 未成年充值限额。
• 渠道归属保护。

Go 建议：

• internal/module/user
• internal/module/identity
• internal/module/antiaddiction
• internal/module/channel_belonging

7. 代金券、礼包、福利

主要代码：

• v2\Coupon.php
• v1\Gift.php
• v2\Gift.php
• service\SpecialService.php
• application\service\WelfareService.php
• common\logic\PayCallback::specialCallback

职责：

• 代金券领取、兑换、支付可用券查询。
• 礼包列表、礼包领取、礼包码发放。
• 支付成功后的福利触发。

Go 建议：

• internal/module/coupon
• internal/module/gift
• internal/module/welfare

8. MLBB 活动

主要代码：

• controller\mlbb\Mlbb.php
• controller\mlbb\Login.php
• controller\mlbb\Game.php
• controller\mlbb\Activity.php
• controller\mlbb\User.php
• controller\mlbb\Other.php
• service\mlbb\HandleService.php
• library\mlbb\LotteryService.php

职责：

• MLBB 独立活动登录态。
• 活动预约、角色绑定、任务、抽奖、礼包码和代金券发放。
• 活动表以 lr_ 前缀为主。

Go 建议：

• 如果活动仍在运营，单独做 internal/module/mlbb。
• 如果活动已结束，只保留数据查询或后台补发能力，不优先迁移。

9. 第三方和渠道数据 API

主要代码：

• ThreePlatform.php
• v2\DyGameOpen.php
• YqlData.php
• JhApi.php
• RiskControl.php
• v2\PropApi.php
• v2\Huge.php

职责：

• 微信小程序授权/支付。
• 抖音开放平台授权、手机号、角色列表、事件通知。
• YQL 数据、券通知、渠道数据。
• 聚合报表和渠道数据接口。
• 风控登录/注册检查。
• 道具、邮件、充值补单类 API。

Go 建议：

• 做成独立外部集成模块：internal/integration/*。
• 先确认哪些接口仍被使用，再决定迁移顺序。