# 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/*`。 - 先确认哪些接口仍被使用，再决定迁移顺序。