yvan
/
kra-new
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
kra-new/docs/OA_MIGRATION_PLAN.md

1356 lines
71 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# OA 到 KRA 完整迁移执行计划
> 计划基线日期：2026-08-21
> 源系统：`oa`
> 目标系统：`kra-new`
> 当前状态：仅完成代码盘点与迁移规划，尚未开始业务迁移
## 1. 目标与结论
目标是在 **不重构现有移动端、PC 端和旧后台调用协议** 的前提下，将 OA 的完整系统能力迁移到 KRA，并最终由 KRA 统一承载：
- 管理后台接口与页面；
- 会长/渠道移动端接口（`/tg`）；
- 玩家及客服端接口（`/imserver`）；
- 对外 SDK 接口（`/sdk`）；
- 游戏、渠道、玩家、订单、扶持、福利、结算、IM、分发、报表等业务；
- 中间件、定时任务、多数据库、Redis、消息队列、对象存储和第三方服务；
- 数据初始化、历史数据迁移、部署和回滚能力。
盘点后的结论是：**KRA 可以承载 OA，但不能直接复制 OA 目录或模型。** 两边虽然都保留了 GVA 风格接口，但后端分层、系统表、鉴权方式和任务机制已经不同。迁移必须以 KRA 的分层、模块目录、系统表和运行时为主，通过 OA 兼容 DTO、兼容中间件和显式数据迁移保持旧客户端协议不变。
## 2. 当前基线
以下数字用于评估工作量，不代表最终有效接口数；正式迁移前仍需从运行时路由和实际客户端请求中去重、排除未注册代码。
| 项目 | OA | KRA 当前状态 |
|---|---:|---:|
| 路由注册语句 | 约 756 | 约 191 |
| System 模型文件 | 32 | 已有完整基础后台模型 |
| Game 模型文件 | 52 | 未迁移 |
| User 玩家模型文件 | 12 | 未迁移 |
| IM 模型文件 | 16 | 仅有通用 WebSocket 基础设施 |
| Issue 模型文件 | 4 | 未迁移 |
| Report 模型文件 | 2 | 未迁移 |
| SW 模型文件 | 4 | 未迁移 |
| OA 管理端 API 文件 | 57 | 仅 KRA 自身后台 API |
OA 路由注册语句按原目录的粗略分布：
| 原路由域 | 注册语句数 | 主要用途 |
|---|---:|---|
| `system` | 198 | 用户、角色、部门、平台、配置、日志、黑名单等 |
| `game` | 303 | 游戏、渠道、订单、扶持、福利、结算、打包等 |
| `user` | 60 | 玩家、角色、补单、发放、协议、短信等 |
| `tg` | 49 | 会长/渠道移动端 |
| `im` | 32 | 管理后台客服 IM |
| `imserver` | 22 | 玩家端 IM 与回调 |
| `sdk` | 18 | 对外签名接口 |
| `issue` | 28 | 分发系统 |
| `report` | 2 | 报表 |
| `sw` | 12 | 商务用户与平台绑定 |
| `common` / `example` | 32 | 公共下载、上传及遗留工具/示例 |
## 3. 不可变更的迁移规则
1. **KRA 是唯一目标代码库。** 不长期保留 OA 与 KRA 两套业务实现。
2. **KRA 系统表优先。** KRA 已有语义等价表时，不再创建 OA 同义系统表；OA 多出的字段增量加入 KRA 表。
3. **OA 独有业务表保留业务语义。** 没有 KRA 对应物的业务表可迁入模块，但必须进入 KRA 的迁移体系和数据层。
4. **旧客户端不改协议。** HTTP 方法、路径、参数来源、字段名、字段类型、默认值、空值形态、响应码、消息、Header 和下载行为均以旧接口契约为准。
5. **后台能力同步迁移。** OA 有而 KRA 没有的管理功能，必须同时迁移后端接口、KRA 后台页面、菜单、按钮权限和 API 权限数据。
6. **接口域不能混用鉴权。** 管理后台、会长端、玩家端、SDK 和第三方回调必须使用各自的 token、签名和上下文。
7. **逐文件核对。** 每一个 OA 源文件必须被标记为“已迁移、被 KRA 替代、确认废弃”之一，不允许无记录遗漏。
8. **逐接口差异测试。** 不以“页面能打开”作为完成标准，必须比较响应字段和业务副作用。
9. **只做显式数据库迁移。** 禁止用无审查的 `AutoMigrate` 修改生产旧表。
10. **迁移定义永久保留。** 已执行的 migration ID 不得从 KRA Catalog 删除或改名。
## 4. 目标模块结构
业务模块建议使用独立目录，并在模块内部继续遵守 KRA 的 `service -> biz -> data` 分层：
```text
internal/modules/<module>/
biz/ # 领域对象、状态机、用例、仓储接口
data/ # PO、GORM 查询、事务、数据转换、迁移
service/ # OA 请求/响应 DTO 与领域对象转换
server/handler/ # Gin handler
server/router/ # 路由与接口域注册
worker/ # 本模块定时任务注册
definition.go # migrations / menus / APIs / default tasks
providers.go # Wire ProviderSet
web/src/modules/<module>/
api/
view/
components/
```
修改 KRA 既有系统表和系统行为的内容仍放在现有 `internal/biz/system`、`internal/data/system`、`internal/service`、`internal/server` 中，避免创建第二套用户、角色、部门和权限系统。
每个业务模块通过 KRA 现有的 `pkg/module` 机制贡献：
- 数据库 migration；
- 后台菜单和 API 元数据；
- HTTP 路由；
- 默认定时任务；
- 运行时任务方法。
## 5. 接口域与鉴权边界
KRA 当前只有公共组和统一私有组，不足以直接表达 OA 的全部鉴权语义。基础阶段需要建立命名清晰的接口域：
| 接口域 | 主要路径 | 客户端 | 必要鉴权/上下文 |
|---|---|---|---|
| Admin Public | `/base/*`、`/init/*`、公共下载 | 后台登录页 | 无登录、验证码、限流 |
| Admin Login | 菜单、用户信息、部分通讯录/IM | 后台端 | KRA/OA 兼容 JWT，不强制 Casbin |
| Admin RBAC | 系统管理和一般业务接口 | 后台端 | JWT + 多角色 Casbin + 操作审计 |
| Admin Business DB | 游戏、渠道、玩家、订单等 | 后台端 | JWT + Casbin + 数据库/平台范围 |
| TG | `/tg/*` | 移动会长端 | 管理用户 JWT + 当前渠道/平台上下文 + 层级权限 |
| IM Player Public | `/imserver/play/register*`、登录、回调 | 移动/PC 玩家端、腾讯回调 | 无登录或回调校验 |
| IM Player Auth | `/imserver/play/*` 登录后接口 | 移动/PC 玩家端 | 玩家专用 JWT，不能复用后台 claims |
| SDK Signed | `/sdk/*` | 游戏 SDK/外部服务 | OA 签名算法、重放保护、调用审计 |
| Callback | IM、支付、打包等回调 | 第三方系统 | 各供应商签名、幂等、原始 ACK |
基础路由改造完成前，不得批量接入业务路由。
## 6. 系统表兼容策略
### 6.1 兼容结论
KRA 与 OA 的核心 GVA 表存在较高重合，可以兼容，但部门、公司、平台和扩展用户字段不能直接照搬。
| OA 表/能力 | KRA 目标 | 处理原则 |
|---|---|---|
| `sys_users` | `sys_users` | 保留 KRA 字段，增加 OA 的实名、主题、IM、注销、用户中心、用户类型等字段 |
| `sys_authorities` | `sys_authorities` | 保留 KRA `data_scope`，增加 OA 的启用、公司管理员、部门范围、JSON 配置等字段 |
| `sys_base_menus` | `sys_base_menus` | KRA ID/父 ID 类型为准；旧接口 DTO 负责输出 OA 需要的字段和类型 |
| `sys_apis` | `sys_apis` | 保留 KRA API 权限模型；补 OA 实际使用的菜单关联等字段 |
| `sys_user_authority` | `sys_user_authority` | 保留多角色；扩展 JWT 和 Casbin 为“任一角色通过即授权” |
| `sys_authority_menus` | `sys_authority_menus` | 使用 KRA 数值菜单 ID，迁移时转换 OA 旧值 |
| `sys_depart` | `sys_departments` | 只保留 KRA 表；`depart_name -> name`，补 OA 组织类别、客服、公司、企业微信等字段 |
| `sys_user_depart` | `sys_user_departments` | 转换表名和外键列名，不保留两套关系表 |
| OA 数据权限关系 | `sys_authority_departments` + KRA `data_scope` | 将 OA 部门/公司范围转换为 KRA 数据范围，同时保留旧接口表现 |
| `sys_operation_records` | `sys_operation_records` | 合并字段并保持 OA 查询响应兼容 |
| 字典表 | KRA 同名表 | 直接映射，核对唯一键、删除语义和返回字段 |
| `sys_config` | `sys_params` / `sys_integration_configs` / 模块配置表 | 按配置用途拆分，旧 `/sysConfig` API 作为兼容门面 |
| OA 独有平台、公司、黑名单、活跃池等表 | KRA 系统扩展表 | 没有等价结构时新增，但由 KRA 模块拥有和迁移 |
### 6.2 数据库迁移硬性要求
KRA 当前的 `CreateMissingTables` 明确不会修改已存在表，因此必须先补充一套经过测试的显式增量 migration 能力：
- `AddColumnIfMissing`；
- `CreateIndexIfMissing`；
- 可审计的数据回填步骤；
- 表名/列名转换脚本；
- 大表分批迁移和断点续传；
- 每个步骤可重复执行且结果一致；
- 迁移前后行数、主键范围、空值数、金额合计和关键关系校验；
- 禁止启动时自动删除列、改列类型或重建大表。
历史数据迁移默认保留原主键。确实不能保留时，必须建立永久 ID 映射表，并同步更新所有外键、缓存键和外部引用。
## 7. 每个模块必须生成的四份清单
每个模块在 `docs/migration/<module>/` 下维护以下文件，缺一不可：
1. `source-ledger.md`：OA 源文件逐一映射到 KRA 目标文件，记录迁移/替代/废弃结论。
2. `schema-map.md`：表、字段、类型、默认值、索引、关系、状态值和历史数据转换规则。
3. `api-contract.md`：方法、路径、接口域、请求字段、响应字段、Header、错误码、消息和副作用。
4. `verification.md`：单测、集成测试、差异测试、前端回归、数据核对结果及获批差异。
## 8. 总体任务阶段
### 阶段 0：基线冻结与自动核对工具
#### MIG-000 源代码与运行时清单冻结
- 从 OA 实际启动后的 `engine.Routes()` 导出有效路由，不能只统计路由文件。
- 扫描 OA 管理端 57 个 API 文件及所有页面调用。
- 收集移动端、PC 端、后台端当前发布版本的请求样本或网关日志。
- 将所有 OA model/api/router/service/middleware/timer/config/frontend 文件登记到总 source ledger。
- 标记未注册路由、注释代码、一次性脚本和 GVA 示例功能，但未经确认不得删除。
完成标准：OA 所有源文件和有效接口均有唯一编号，未分类数量为 0。
#### MIG-001 接口差异测试框架
- 使用同一份脱敏数据分别启动 OA 和 KRA。
- 建立请求语料库，向两边发送相同请求。
- 比较 HTTP 状态、Header、`code/data/msg`、字段存在性、JSON 类型、`null/[]/{}`、排序和分页。
- 对时间、token、随机 ID 等非确定字段只做规则化处理，不允许整段忽略。
- 比较数据库写入、Redis 键、消息队列消息和第三方适配器调用。
- 输出机器可读差异报告和人工批准的 exception ledger。
完成标准：框架能对至少登录、菜单、用户列表、一个业务 CRUD 和一个下载接口出具差异报告。
#### MIG-002 模块脚手架与持续验证
- 建立 OA 业务模块目录和统一 ProviderSet/Definition/Routes/Tasks 接入方式。
- 扩展 `internal/app`、Wire 和 module runtime，使新增模块无需修改系统业务实现。
- 在持续检查中加入 `go test ./...`、`go vet ./...`、`go build ./...`、前端 lint/build 和契约测试。
- 增加路由冲突、migration ID 冲突、菜单/API 重复和跨层 import 检查。
完成标准：空示例模块可独立贡献表、路由、菜单和定时任务，并通过完整构建。
### 阶段 1：KRA 兼容底座
#### FND-001 显式增量数据库迁移
- 实现第 6.2 节的增列、索引、回填和校验工具。
- 增加 MySQL、PostgreSQL、SQL Server、Oracle、SQLite 的方言测试；生产实际使用的数据库优先达到完整覆盖。
- 增加 dry-run/检查模式和失败后的恢复说明。
#### FND-002 OA 请求与响应兼容层
- 支持 OA `PageResult` 和 `OaPageResult`，包括 `maxCount`、`fialData`、`extend` 等历史字段。
- 保持旧接口成功/失败 `code`、`msg` 和 HTTP 状态。
- 兼容 `new-token`、`new-expires-at`、文件下载 Header 和 OA 上传响应。
- 固化时间格式、金额精度、布尔/整数状态、空集合和软删除字段的 JSON 表现。
- 共享路径发生 KRA/OA 契约冲突时，以仍在使用的旧客户端契约为准，并登记 KRA 侧调整。
#### FND-003 多接口域与中间件
- 建立第 5 节的命名路由域。
- 扩展后台 JWT claims：多角色、手机号、公司、管理员标识等 OA 必需上下文。
- Casbin 改为多角色任一命中；保留 `888` 超级管理员旁路。
- 迁移/重写 `DbHandler`、`TgAuth`、`SignAuth`、操作记录、错误审计、限流、CORS 和初始化保护。
- 对签名和回调增加时间窗、nonce/幂等键，保持旧签名算法输入输出不变。
#### FND-004 多数据库、公司、平台上下文
- 复用 KRA `database_list`，统一按 alias 获取业务库。
- 将 OA 请求体中的 `dbName`、当前公司、当前平台和角色可见数据库解析为显式 request context。
- 禁止业务层读取全局 DB 或直接从 Gin Context 取值。
- 对单库、跨库查询、批量多库请求和无权限库建立测试。
#### FND-005 外部集成基础设施
- 直接复用 KRA 已有 Redis/cache、对象存储、邮件、支付、WebSocket 能力。
- 补齐 RabbitMQ AMQP 运行时客户端；KRA 当前只有 RabbitMQ 配置定义，没有 OA 客服队列所需的完整 AMQP 生命周期实现。
- 新增腾讯 IM、用户中心、短信、OCR、游戏业务站、PC 分包、契约/企业签及各 CP 扶持接口适配器。
- 所有客户端放入 `internal/integration`，业务模块只依赖接口，不复制 OA 的全局单例和 `utils` 网络调用。
- 所有密钥从安全配置注入，禁止复制 OA 配置文件中的明文凭据；上线前完成旧凭据轮换。
#### FND-006 历史数据迁移程序
- 建立独立迁移命令，支持源 OA 库到目标 KRA 库的结构检查、分批导入、续跑和校验。
- 支持主系统库及 `db-list` 中各业务库。
- 所有转换规则来源于各模块 `schema-map.md`。
- 迁移日志不得打印密码、身份证、token、签名密钥等敏感值。
### 阶段 2：KRA 系统能力合并
#### SYS-001 用户、登录与账号生命周期
范围：账号密码登录、手机号登录、会长登录、注册、忘记密码、用户列表、个人信息、多角色、部门、公司子账号、切换公司、黑名单、注销、实名认证、常用菜单和 IM 客服字段。
子任务：
- `SYS-001-A`：扩展 KRA `sys_users` DO/PO/repo 和显式 migration。
- `SYS-001-B`：迁移 OA 登录、注册、用户中心同步、JWT claims 和 token 刷新行为。
- `SYS-001-C`：补齐所有 `/base/*`、`/user/*` 兼容接口。
- `SYS-001-D`：迁移 KRA 后台用户页面缺少的字段、筛选、批量操作和公司账户功能。
- `SYS-001-E`：逐文件对照 OA `sys_user` model/request/response/api/service/router 及相关中间件。
#### SYS-002 角色、菜单、API、按钮和数据权限
- 合并 OA 角色扩展字段和多角色鉴权。
- 对齐菜单树、默认路由、参数、按钮权限、API 权限和 Casbin 策略。
- 迁移角色与平台、角色与部门/公司范围关系。
- 验证超级管理员、普通角色、冻结角色、多角色用户和无菜单用户。
- 同步 KRA 后台角色、菜单、API、按钮和成员分配页面。
#### SYS-003 部门、公司、岗位和通讯录
- 将 `sys_depart` 数据转换到 `sys_departments`，补齐 OA 字段。
- 将 `sys_user_depart` 转换到 `sys_user_departments`。
- 明确 OA 的角色、岗位、部门三种概念，禁止再次混用。
- 迁移部门树、顶级公司、子公司、客服部门、账号数量、批量分配和通讯录接口。
- 验证移动/删除部门后的祖先链、公司范围和孤儿关系。
#### SYS-004 系统配置、日志、文件、导出与遗留工具
- 迁移 `sysConfig` 兼容门面、操作日志、用户行为日志、黑名单、上传下载和 Excel 导出。
- 复用 KRA 安全配置、登录日志、错误日志、数据访问日志、媒体库和附件分类。
- 逐项评估 OA 代码生成器、断点续传、客户示例等遗留功能：仍被菜单/API/用户使用则迁移；确认不再使用后才进入废弃清单。
- 对 OA 有而 KRA 没有的后台入口补齐菜单、API 元数据、按钮权限和页面。
### 阶段 3：平台、游戏与渠道主数据
#### PLT-001 联运平台、公司与商务身份
范围：`sys_platform`、角色平台关系、公司关系、CP session/support/gift、SW 用户/角色/偏好/平台绑定、商务用户管理。
依赖：`SYS-001`、`SYS-002`、`SYS-003`、`FND-004`。
#### GAM-001 游戏目录与基础配置
范围：`tab_game`、游戏类型、CP、游戏设置、原包、区服、合服、互通、禁用配置、改名日志、APP、平台配置、支付配置、系统选项和企业签日志。
重点验收：
- 游戏改名涉及的所有冗余字段和日志；
- 配置 JSON、状态值和金额字段；
- 业务库选择；
- 后台列表筛选、详情、导出、配置页和按钮权限；
- OA 游戏相关源文件逐一完成 ledger。
#### CHN-001 渠道、商务、合同与公告
范围：`tab_promote`、商务归属、推广配置、登录记录、合同、公告、押金、平台币、渠道状态和上下级关系。
重点验收：渠道审核、驳回、商务改派、结算周期修改、不可推广游戏、层级关系、锁定/解锁和冗余快照更新。
#### PKG-001 渠道申请与多端打包
范围：`tab_promote_apply`、`tab_promote_app`、Android/iOS/H5/超级签/PC 打包、快手抖音配置、分享显示和隐藏游戏。
依赖：`GAM-001`、`CHN-001`、外部分包适配器。
重点验收：
- `-1/0/1/2/3` 打包状态机；
- 原包与渠道申请关系；
- PC 异步提交、轮询、失败恢复和幂等；
- 旧移动端/PC 端下载 URL 和响应字段；
- KRA 后台打包管理页面。
### 阶段 4：玩家、订单、扶持与财务
#### PLY-001 玩家、角色与账号关联
范围：`tab_user`、登录记录、角色、角色详情、补链、补单、协议、短信日志、批量玩家、敏感字段查看和脱敏。
重点验收：渠道归因、跨库查询、敏感信息权限/审计、余额修改、补链跨表更新和导出字段。
#### ORD-001 充值、绑币、平台币与交易记录
范围：`tab_spend`、`tab_spend_bind`、`tab_spend_provide`、余额、渠道币、订单绑定、补单、支付/游戏通知状态、企业签日志和代金券记录。
依赖：`PLY-001`、`GAM-001`、`CHN-001`。
重点验收：金额精度、订单唯一性、重复回调、补单幂等、游戏到账、渠道归因、结算明细生成和导出。
#### SUP-001 扶持、福利与 CP 发放
范围：扶持申请、渠道扶持、禁止扶持、倍数/清零、福利配置/道具/记录、CP 礼包、自动审核与自动发放。
依赖：`PLY-001`、`GAM-001`、`CHN-001`。
重点验收：审核状态机、实际到账、失败补偿、外部 CP 调用、批量发放、周/月卡重复执行保护和后台审核页面。
#### FIN-001 结算、提现、代充与预支
范围：渠道结算、结算时间、周期单、提现、押金、代充折扣、绑币订单、预支白名单/游戏/额度/还款及相关日志。
依赖：`ORD-001`、`CHN-001`。
重点验收：结算汇总、周期确认、余额扣增、重复付款防护、跨表事务边界、提现状态和预支额度恢复。
### 阶段 5：移动端、PC 端、IM 与外部接口
#### TG-001 会长/渠道移动端完整接口
范围：全部 `/tg/promote`、`/tg/app`、`/tg/promoteApply`、`/tg/support` 接口。
依赖：`GAM-001`、`CHN-001`、`PKG-001`、`PLY-001`、`ORD-001`、`SUP-001`、`FIN-001`。
重点验收：平台切换、渠道层级菜单限制、首页统计、结算确认、提现、代充、福利、预支和移动端字段类型。
#### IM-001 管理后台客服 IM
范围：群组、会话、联系记录、收藏、标签、快捷语、客服转接/退出、客服状态和会话容量。
依赖：`SYS-001`、`PLT-001`、腾讯 IM、RabbitMQ。
#### IM-002 玩家端与 SDK IM
范围：全部 `/imserver`、`/sdk/im`、腾讯 IM callback、玩家注册登录、平台绑定、入群、会话、评价、未读数和 OCR。
重点验收：
- 后台 JWT 与玩家 JWT 完全隔离；
- 腾讯回调原始 body、签名、ACK 和幂等；
- RabbitMQ reject/requeue/ack 语义；
- 客服并发分配和 `im_current_session` 原子更新；
- 移动端与 PC 端现有接口逐字段回归。
#### SDK-001 扶持及其他签名 SDK
范围：`/sdk/support/*` 及除 IM 外的签名接口。
重点验收：旧签名算法、字段排序、空值参与规则、错误响应和重放保护。
### 阶段 6：分发与报表
#### ISS-001 Issue 分发系统
范围：Issue 玩家、补单、充值、角色和数据接口，以及相应 KRA 后台页面。
依赖：`PLY-001`、`ORD-001`。
#### REP-001 运营报表
范围：Top PID、每日 PID 及 OA 中由动态 SQL/跨库聚合产生的报表。
依赖：主业务写入模块稳定后执行。
重点验收：时间边界、时区、去重口径、金额合计、跨库汇总、分页和导出结果。
### 阶段 7：定时任务与运行保障
#### OPS-001 OA 定时任务迁移
OA 当前至少包含以下运行任务，必须逐个归属到对应模块并注册到 KRA 任务中心：
| OA 任务 | 目标模块 |
|---|---|
| `ClearDB` | System |
| `CloseChat` | IM |
| `UnsubscribeSysUser` | System/User |
| `AutoSendSupport` | Support |
| `AutoSendGift` | Support |
| `PromoteActivePoolScan` | Platform/Channel |
| `PcRepackageScan` | Packaging |
| `LockChannelOverThreeMonth` | Channel |
| `AutoSendFuliRecord` | Welfare |
| `AutoSendWeekCard` | Welfare |
| `AutoBuLianInactiveUsers` | Player |
| `AutoAuditSupport` | Support |
每个任务必须验证：默认 cron、秒级模式、启停配置、手动触发、并发防重、超时、失败重试、执行日志、告警、跨库范围和重复实例运行风险。
#### OPS-002 可观测性与故障恢复
- 为所有外部调用增加 request ID、耗时、结果码和脱敏错误日志。
- 为订单、发放、提现、打包、IM 回调增加幂等键和补偿查询入口。
- 增加任务积压、消息队列连接、第三方失败率、数据库连接和慢查询指标。
- 编写常见故障恢复手册，覆盖 OA 维护文档中的主要故障场景。
### 阶段 8：全量回归、数据演练与切换
#### CUT-001 全量接口与后台回归
- 有效 OA 路由覆盖率 100%，或存在书面批准的废弃记录。
- 旧前端 API 调用覆盖率 100%。
- KRA 新增后台菜单、页面、按钮和权限均可按角色访问。
- 逐接口差异报告无未批准差异。
#### CUT-002 数据迁移演练
- 使用生产结构副本和脱敏数据至少完成两次全量演练。
- 核对行数、主键、外键、软删除、金额、状态分布和关键业务抽样。
- 记录每张表迁移耗时、锁影响、失败恢复和增量追平方式。
#### CUT-003 灰度与正式切换
- 先影子读/流量回放，再灰度只读接口，最后灰度写接口。
- 写接口切换前冻结或增量同步 OA 数据，防止双主写入。
- 回调、定时任务和消费者在任一时刻只能有一套系统实际执行。
- 保留可执行回滚方案、回滚数据点和外部回调切回步骤。
## 9. 单个模块的执行模板
每个模块都按以下顺序执行，不允许跳过最后两步：
1. **盘点**：登记 OA model/request/response/api/router/service/frontend/timer/config 文件。
2. **契约**：冻结路径、鉴权、请求、响应、Header、错误和副作用。
3. **数据**：完成 schema map、migration、历史转换和校验脚本。
4. **领域**：实现 KRA DO、状态机、用例和仓储接口。
5. **数据层**：实现 PO、查询、事务、跨库访问和外部仓储。
6. **接口层**：实现兼容 DTO、handler、路由和中间件绑定。
7. **后台端**：迁移 API 文件、页面、菜单、按钮和权限种子。
8. **任务/集成**：接入本模块定时任务、消息和第三方服务。
9. **自动验证**：单测、集成测试、契约差异、前端构建和页面回归。
10. **逐文件复核**：对 source ledger 每一项签署结论，生成 verification 报告。
## 10. 模块完成标准
模块只有同时满足以下条件才能标记完成：
- source ledger 中无未处理文件；
- schema map 中无待定字段、状态或索引；
- 有效接口全部注册且鉴权域正确；
- 请求与响应字段、类型、消息、Header 和分页结构一致；
- 查询条件、Join、排序、默认值、软删除和事务行为一致；
- Redis/MQ/第三方调用及失败处理一致；
- KRA 后台页面、菜单、按钮权限完整；
- 单元测试、集成测试、差异测试、后端构建、前端 lint/build 全部通过；
- 历史数据转换通过自动校验和业务抽样；
- 所有差异均有书面原因和批准记录。
## 11. 推荐执行顺序与并行关系
```text
MIG-000/001/002
|
FND-001..006
|
SYS-001..004
|
PLT-001 ---- GAM-001 ---- CHN-001
| | |
| +---- PKG-001-+
| |
+---- PLY-001 ---- ORD-001-+
| | |
+-- SUP-001+-- FIN-001
|
TG-001 / IM-001 / IM-002 / SDK-001
|
ISS-001 / REP-001
|
OPS-001 / OPS-002
|
CUT-001..003
```
可并行原则：
- 基础阶段结束后，平台、游戏基础、玩家基础和 IM 适配器可由不同任务并行。
- 同一张 KRA 系统表只允许一个任务负责 schema 和核心 repo，其他模块通过接口依赖。
- 管理端页面可在接口契约冻结后并行迁移，但不得自行改变接口字段。
- 定时任务代码随所属模块实现，最终在 `OPS-001` 统一做重复执行和调度验证。
## 12. 当前已识别的高风险点
1. OA 的有效接口数量远高于 KRA，且部分路由只在特定路由组注册，必须以运行时为准。
2. KRA 当前私有路由统一经过 Casbin，而 OA 存在“仅登录即可访问”的接口，路由域必须先拆开。
3. OA JWT 支持多角色和公司上下文，KRA 当前 claims 主要是单角色。
4. OA 未登录响应与 KRA 当前 HTTP 401/错误码行为存在差异。
5. OA 部门表与 KRA 表名、字段和关系表不同，不能双表共存作为长期方案。
6. KRA 当前 migration 不会为旧表自动加列，系统字段扩展必须显式实现。
7. OA 多数据库和跨库写入没有统一事务，迁移时要保持现有结果并补充幂等/补偿。
8. OA 大量业务查询使用动态 map 和冗余快照字段，不能简单改为关联表实时查询。
9. `sys_user` 服务混合了登录、IM、注销和多个 CP 发放适配，迁移时必须拆分但保持调用顺序和结果。
10. RabbitMQ、腾讯 IM、PC 分包、用户中心、短信、OCR 和多个 CP 接口是完整迁移的外部阻塞项。
11. 移动端和 PC 端源码不在当前两个仓库中时，必须用发布包、请求日志或抓包补齐契约基线。
12. 回调消费者、定时任务和自动发放在双系统并行期间存在重复执行风险。
## 13. 第一批建议启动任务
正式编码时建议先只启动以下任务，完成后再大规模并行：
- `MIG-000`：生成完整 source ledger 和有效路由清单；
- `MIG-001`：建立 OA/KRA 接口差异测试框架；
- `MIG-002`：建立第一个可插拔 OA 模块样板；
- `FND-001`：实现显式增量数据库 migration；
- `FND-002`：冻结兼容响应和分页结构；
- `FND-003`：拆分接口域和鉴权中间件；
- `SYS-001-A`：完成 `sys_users` 字段映射草案与 migration 评审；
- `SYS-003`：完成部门/公司/岗位映射草案，禁止在映射确定前导入用户关系数据。
这一批完成后，才具备安全拆分多个业务模块任务并行迁移的条件。
## 14. 细化执行目录
本节是对前面阶段任务的可执行拆分。编号规则如下：
- `MIG/FND/SYS/...-主编号`：模块级里程碑；
- `...-主编号-A/B/C`：工作包，可单独分派给一个开发任务；
- `...-主编号-A1/A2`：同一工作包内的文件、接口或验收批次；
- 工作包没有通过自己的验收标准时，不得标记所属模块完成。
每个工作包默认包含四类动作：代码实现、数据库/配置变更、测试、文档更新。若某项不适用，必须在任务记录中写明“确认不适用”，不能留空。
### 14.1 任务状态和门禁
| 状态 | 含义 | 进入条件 | 退出条件 |
|---|---|---|---|
| `READY` | 可以开始 | 前置任务已完成，输入文件已冻结 | 开发者接单 |
| `DOING` | 开发中 | 已建立分支和任务目录 | 代码、迁移、测试全部提交 |
| `REVIEW` | 待复核 | source/schema/api/verification 四份清单已更新 | 通过代码和契约复核 |
| `BLOCKED` | 被阻塞 | 外部服务、客户端样本、数据权限或字段含义缺失 | 阻塞原因解除并补充证据 |
| `DONE` | 已完成 | 所有工作包验收通过 | 进入后续依赖 |
| `DEFERRED` | 明确延期 | 经过负责人确认不影响当前切换范围 | 重新评估，不视为完成 |
阶段门禁：
1. `MIG` 门禁：所有 OA 路由、前端 API、页面入口、配置和任务均已编号。
2. `FND` 门禁：KRA 能表达 OA 的响应、鉴权、多库、外部调用和增量迁移。
3. `SYS` 门禁：管理后台登录、用户、权限、部门、菜单和数据范围稳定。
4. `业务主数据` 门禁：游戏、平台、渠道、玩家主键关系稳定。
5. `交易与资金` 门禁：订单、扶持、结算和提现具备幂等及补偿能力。
6. `端能力` 门禁：后台、TG、玩家端、PC/移动端和 SDK 契约全部通过。
7. `CUT` 门禁：数据演练、流量回放、回滚和运维交接全部完成。
### 14.2 每个工作包的固定交付物
每个工作包至少交付以下内容，文件名可按模块替换 `<module>`：
```text
docs/migration/<module>/<task-id>-source-ledger.md
docs/migration/<module>/<task-id>-schema-map.md
docs/migration/<module>/<task-id>-api-contract.md
docs/migration/<module>/<task-id>-verification.md
```
代码交付至少应覆盖：
- KRA `biz`：DO、状态常量、仓储接口和业务错误；
- KRA `data`：PO、转换函数、查询、事务和 migration；
- KRA `service`：请求 DTO、响应 DTO、字段转换和分页转换；
- KRA `server`：handler、router、中间件绑定和权限元数据；
- KRA `web`：API 封装、页面、菜单、按钮和路由；
- `*_test.go`：领域、数据、接口和回归测试；
- 配置/任务/集成：只在工作包确实拥有该能力时加入。
### 14.3 任务执行时的统一拆分动作
一个工作包不得直接从 OA 文件复制到 KRA。必须按以下 12 个子动作逐项销项：
| 子动作 | 内容 | 产出 |
|---|---|---|
| `P01` 源文件登记 | model/request/response/api/service/router/web/config/timer 全量登记 | source ledger |
| `P02` 路由冻结 | 方法、路径、路由组、中间件、是否公开 | api-contract |
| `P03` 请求冻结 | JSON/form/query/header、必填、默认值、兼容别名 | api-contract |
| `P04` 响应冻结 | code/data/msg、字段、类型、空值、分页、下载 Header | api-contract |
| `P05` 数据表冻结 | 表、列、类型、默认值、索引、软删除、主键 | schema-map |
| `P06` 状态机冻结 | 状态值、允许转换、重复请求、失败回退 | schema-map |
| `P07` 领域实现 | DO、用例、错误和仓储接口 | KRA biz |
| `P08` 数据实现 | PO、查询、事务、跨库和外部仓储 | KRA data |
| `P09` 兼容接口实现 | DTO、handler、route、旧响应适配 | KRA service/server |
| `P10` 前端/后台实现 | API、页面、菜单、按钮、权限 | KRA web + seed |
| `P11` 对照验证 | OA/KRA 相同输入、相同数据、相同副作用 | verification |
| `P12` 文件签收 | 每个源文件写明迁移、替代或废弃理由 | signed ledger |
## 15. 阶段 0 细化：盘点和工具
### MIG-000 源代码与运行时清单冻结
| 工作包 | 范围 | 主要 OA 输入 | KRA 产出 | 依赖 | 并行 |
|---|---|---|---|---|---|
| `MIG-000-A` | 后端文件清单 | `server/model`、`api/v1`、`service`、`router` | 总 source ledger | 无 | 可与 B/C 并行 |
| `MIG-000-B` | 前端调用清单 | `web/src/api`、`web/src/view`、`router` | API-to-page 映射表 | 无 | 可与 A/C 并行 |
| `MIG-000-C` | 路由运行时清单 | `initialize/router.go`、所有 `router/*` | 有效方法/路径/中间件清单 | OA 可启动环境 | 可与 A/B 并行 |
| `MIG-000-D` | 数据表清单 | `model/**/*.go`、初始化/建表逻辑 | 表字段/索引/关系目录 | A | 不与 schema 改造并行 |
| `MIG-000-E` | 定时任务清单 | `initialize/timer.go`、配置 | 任务/cron/依赖/副作用表 | A | 可与 D 并行 |
| `MIG-000-F` | 外部依赖清单 | IM、MQ、短信、UC、OCR、OSS、分包、CP 调用 | 外部服务矩阵 | A | 可与 D/E 并行 |
| `MIG-000-G` | 客户端样本冻结 | 后台页面、移动端、PC 端请求日志/抓包 | 脱敏请求语料库 | B/C | C 完成后进行 |
| `MIG-000-H` | 遗留代码归类 | 注释路由、测试、脚本、示例 | 保留/废弃审批表 | A/B | 可与 G 并行 |
完成标准：A-H 全部 `DONE`，总清单中的 OA 文件、有效路由、页面 API、任务和外部依赖均有编号。
### MIG-001 接口差异测试框架
| 工作包 | 细化内容 | 最小验收 |
|---|---|---|
| `MIG-001-A` | 测试环境、数据库快照、脱敏种子 | OA/KRA 可用同一业务数据启动 |
| `MIG-001-B` | 请求重放器，支持 JSON/form/query/header/file | 可重放登录、列表、详情、写入 |
| `MIG-001-C` | 响应规范化，处理 token/时间/随机 ID | 不掩盖字段、类型和消息差异 |
| `MIG-001-D` | 数据库副作用快照 | 能比较新增、更新、删除、状态和金额 |
| `MIG-001-E` | Redis/MQ/外部调用断言 | 能检查 key、topic、ack、调用参数 |
| `MIG-001-F` | 差异报告和例外清单 | 每个差异有路径、字段、原因和审批人 |
| `MIG-001-G` | 端到端基线用例 | 登录、菜单、用户列表、业务 CRUD、下载各 1 组 |
### MIG-002 模块脚手架与持续验证
| 工作包 | 细化内容 |
|---|---|
| `MIG-002-A` | 建立模块 Definition、Catalog、ProviderSet、RouteRegistrar、Task Contributor 样板 |
| `MIG-002-B` | 建立 module migration、菜单、API、定时任务注册样板 |
| `MIG-002-C` | 建立跨层依赖检查和路由冲突检查 |
| `MIG-002-D` | 建立 Go/前端/契约/数据校验 CI 入口 |
| `MIG-002-E` | 用空模块完成 Wire、构建、启动和初始化演练 |
## 16. 阶段 1 细化：KRA 兼容底座
### FND-001 显式增量数据库迁移
| 工作包 | 细化内容 | 关键文件/产出 |
|---|---|---|
| `FND-001-A` | 表/列/索引存在性检查 | `pkg/database/migration` 工具和测试 |
| `FND-001-B` | MySQL 增列/索引/默认值方言 | 方言测试和 dry-run 输出 |
| `FND-001-C` | PostgreSQL/SQL Server/Oracle/SQLite 方言 | 各方言兼容测试 |
| `FND-001-D` | 批量回填、断点、限速、进度 | migration runner 扩展 |
| `FND-001-E` | 迁移前后校验、失败恢复 | checksum/校验报告 |
| `FND-001-F` | 禁止破坏性变更的静态检查 | 删除列/改类型/无 ID 检查 |
| `FND-001-G` | 用 `sys_users` 和 `sys_departments` 做演练 | 可重复执行、已有数据不丢失 |
### FND-002 OA 请求与响应兼容层
| 工作包 | 细化内容 |
|---|---|
| `FND-002-A` | `{code,data,msg}` 基础响应和错误码 | 成功、失败、未登录、过期、权限不足 |
| `FND-002-B` | `PageResult`/`OaPageResult` 分页转换 | `list/total/page/pageSize/maxCount/fialData/extend` |
| `FND-002-C` | 字段类型和空值规则 | int/bool/string、null/[]/{}、时间和金额 |
| `FND-002-D` | token/Header/Cookie 兼容 | `x-token`、`new-token`、`new-expires-at` |
| `FND-002-E` | 上传、`common/download`、下载、导出和文件名兼容 | Content-Type、Content-Disposition、文件流 |
| `FND-002-F` | 全局错误和消息映射 | OA 原消息与 KRA 错误的固定映射表 |
| `FND-002-G` | 兼容层基线测试 | 至少 20 个典型接口通过差异测试 |
### FND-003 多接口域与中间件
| 工作包 | 细化内容 |
|---|---|
| `FND-003-A` | Public/Admin Login/Admin RBAC/Admin DB 路由组 | 路由注册和中间件顺序固定 |
| `FND-003-B` | 后台 JWT claims 与多角色 | `Authorities`、公司、手机号、管理员标识 |
| `FND-003-C` | Casbin 多角色和超级管理员 | 任一角色命中、888 旁路、冻结角色 |
| `FND-003-D` | OA 未登录/过期/非法 token 行为 | code、HTTP 状态、reload 字段和 Header |
| `FND-003-E` | `DbHandler` 和数据范围 | body 四种 `dbName` 结构、跨库权限 |
| `FND-003-F` | `TgAuth` 平台切换和层级 | Redis 当前平台、渠道层级和登录记录 |
| `FND-003-G` | `SignAuth` 签名 | 参数排序、空值、重放、错误返回 |
| `FND-003-H` | 操作日志/错误审计/限流/CORS | 成功、失败、未授权请求的记录边界 |
| `FND-003-I` | `sys_captcha`、`sys_initdb`、初始化保护和健康检查 | `/base/captcha`、`/health`、`/init/checkdb`、`/init/initdb` |
### FND-004 多数据库、公司、平台上下文
| 工作包 | 细化内容 |
|---|---|
| `FND-004-A` | OA `db-list` 到 KRA `database_list` 映射 | alias、连接、显示名、业务 URL |
| `FND-004-B` | 请求体 `dbName` 统一解析 | string/list/ids/data 四种结构 |
| `FND-004-C` | 当前公司/平台上下文 | Redis key、JWT、request context |
| `FND-004-D` | 多库只读查询 | 并发、超时、部分失败、结果合并 |
| `FND-004-E` | 多库写入和补偿 | 无跨库事务时的幂等、重试、补偿记录 |
| `FND-004-F` | 无权限库和不存在库 | 统一错误消息和审计 |
### FND-005 外部集成基础设施
| 工作包 | 细化内容 | 依赖 |
|---|---|---|
| `FND-005-A` | RabbitMQ AMQP 连接、声明、发布、消费、ack/requeue | MQ 配置 |
| `FND-005-B` | 腾讯 IM client、UserSig、回调签名和请求封装 | 腾讯配置 |
| `FND-005-C` | 用户中心 UC 注册、登录、加密和短信接口 | UC 配置 |
| `FND-005-D` | 阿里云短信发送、验证码存储和限流 | 短信配置 |
| `FND-005-E` | OCR 身份证/营业执照适配器 | OCR 配置 |
| `FND-005-F` | 游戏业务站/CP 发放 HTTP client | 外部业务站矩阵 |
| `FND-005-G` | PC 重打包适配器和轮询 | 分包服务协议 |
| `FND-005-H` | 企业签/契约/支付扩展适配器 | 第三方协议 |
| `FND-005-I` | 所有适配器的超时、重试、脱敏和 mock | A-H |
### FND-006 历史数据迁移程序
| 工作包 | 细化内容 |
|---|---|
| `FND-006-A` | 迁移命令、配置、dry-run、断点和日志 | 独立命令入口 |
| `FND-006-B` | 主系统表迁移 | 用户、角色、菜单、API、部门、字典、日志 |
| `FND-006-C` | 系统扩展表迁移 | 公司、平台、黑名单、活跃池、CP 配置 |
| `FND-006-D` | 业务库表迁移 | 按 db alias 分批迁移 |
| `FND-006-E` | 主键/外键/关系表校验 | 映射表和孤儿检查 |
| `FND-006-F` | 金额/状态/时间/软删除校验 | 汇总及抽样报告 |
| `FND-006-G` | 增量追平和回滚演练 | 两次以上完整演练 |
## 17. 阶段 2 细化：系统能力合并
### SYS-001 用户、登录与账号生命周期
| 工作包 | OA 文件/能力范围 | 依赖 |
|---|---|---|
| `SYS-001-A` | `model/system/sys_user.go`、用户 PO/DO 字段扩展 | FND-001 |
| `SYS-001-B` | 用户扩展列 migration、索引、默认值、回填 | A |
| `SYS-001-C` | `/base/login` 账号密码登录 | FND-002/003 |
| `SYS-001-D` | `/base/register`、`/base/phoneLogin`、短信验证码 | FND-005-C/D |
| `SYS-001-E` | `/base/tgPhoneLogin` 会长登录及用户状态 | FND-003-F |
| `SYS-001-F` | `/base/forgetOnChangePassword`、重置/修改密码 | C |
| `SYS-001-G` | `/user/getUserInfo`、个人资料、主题、头像 | A/C |
| `SYS-001-H` | 用户列表、筛选、导出、批量角色/部门 | SYS-002/003 |
| `SYS-001-I` | 公司子账号、公司切换、公司用户列表 | SYS-003 |
| `SYS-001-J` | `sys_user_blacklist`、注销、实名认证、敏感字段 | FND-003-H、FND-005-E |
| `SYS-001-K` | IM 客服字段、状态、容量和会话数 | IM-001 前置接口先定义 |
| `SYS-001-L` | `sys_user_menus_often`、管理后台用户页面与按钮权限 | C-H |
| `SYS-001-M` | 用户全量差异回归和数据迁移验收 | A-L |
### SYS-002 角色、菜单、API、按钮和数据权限
| 工作包 | OA 文件/能力范围 | 依赖 |
|---|---|---|
| `SYS-002-A` | `sys_authority` 字段和角色状态 | FND-001 |
| `SYS-002-B` | 角色 CRUD、树、复制、默认路由 | A |
| `SYS-002-C` | 多角色关联和 JWT authority 列表 | SYS-001-C |
| `SYS-002-D` | 菜单树、菜单参数、`sys_menu_btn`、动态路由 | FND-002 |
| `SYS-002-E` | API 表、运行时路由同步、API 分组 | MIG-000-C |
| `SYS-002-F` | `sys_casbin`、Casbin 策略、`sys_authority_btn`、按钮权限、角色菜单 | C-E |
| `SYS-002-G` | 角色平台关系和数据范围 | SYS-003、PLT-001 |
| `SYS-002-H` | KRA 后台角色/菜单/API/按钮页面 | B-F |
| `SYS-002-I` | 超管/普通角色/多角色/无权限回归 | B-G |
### SYS-003 部门、公司、岗位和通讯录
| 工作包 | OA 文件/能力范围 | 依赖 |
|---|---|---|
| `SYS-003-A` | OA `sys_depart` 与 KRA `sys_departments` 字段映射 | FND-001 |
| `SYS-003-B` | 部门扩展列 migration 和祖先链回填 | A |
| `SYS-003-C` | `sys_user_depart` 到 `sys_user_departments` 关系转换 | A/B |
| `SYS-003-D` | 公司/顶级部门/子部门树和范围 | B |
| `SYS-003-E` | 岗位和用户岗位关系 | KRA position |
| `SYS-003-F` | 部门 CRUD、移动、删除、批量分配 | C-E |
| `SYS-003-G` | 通讯录、客服部门、账号数量、企业微信字段 | D-F |
| `SYS-003-H` | 部门/公司/岗位后台页面 | F/G |
| `SYS-003-I` | 祖先链、孤儿关系、公司权限和用户查询回归 | A-H |
### SYS-004 系统配置、日志、文件、导出与遗留工具
| 工作包 | 范围 | 依赖 |
|---|---|---|
| `SYS-004-A` | `sysConfig`/`sys_system` 兼容门面、参数和集成配置映射 | FND-002 |
| `SYS-004-B` | 操作记录、`sys_user_action_log`、登录日志 | FND-003-H |
| `SYS-004-C` | `sys_jwt_blacklist`、`sys_member_blacklist`、`sys_member_blacklist_pay` | SYS-001 |
| `SYS-004-D` | 文件上传下载、断点续传、媒体库、附件分类 | FND-005 |
| `SYS-004-E` | Excel 导入导出和模板 | FND-002-E |
| `SYS-004-F` | `sys_auto_code`、`sys_auto_code_history`、`sys_autocode_history` 和生成器使用性评估 | MIG-000-H |
| `SYS-004-G` | `exa_breakpoint_continue`、`exa_customer`、`exa_file_upload_download`、GitHub/example/test 页面使用性评估 | MIG-000-H |
| `SYS-004-H` | `sys_dictionary`、`sys_dictionary_detail` 兼容复核及后台监控、日志、媒体和配置入口 | A-E |
## 18. 阶段 3 细化：平台、游戏、渠道和打包
### PLT-001 联运平台、公司和商务身份
| 工作包 | OA 表/文件范围 | 依赖 |
|---|---|---|
| `PLT-001-A` | `sys_platform` 平台主数据 | SYS-003 |
| `PLT-001-B` | `sys_authority_platform` 角色平台关系 | SYS-002 |
| `PLT-001-C` | `sys_user_company` 公司关系 | SYS-001/003 |
| `PLT-001-D` | `sys_platform_cp_session`、`sys_platform_cp_support`、`sys_platform_cp_gift_config`、gift 记录 | A |
| `PLT-001-E` | SW `business_user_api`、`sys_user_role`、`sys_user_preference`、`sys_user_bind_platform` | SYS-001 |
| `PLT-001-F` | 平台/公司/商务后台页面和权限 | A-E |
| `PLT-001-G` | `sys_platform_promote_active_pool`、`sys_promote_active_pool_batch*` 和当前平台/业务库映射回归 | FND-004 |
### GAM-001 游戏目录与基础配置拆分
| 工作包 | OA 表/文件范围 | 主要接口/页面 |
|---|---|---|
| `GAM-001-A` | `tab_game_type` | 游戏类型 CRUD |
| `GAM-001-B` | `tab_game_cp` | CP 商 CRUD |
| `GAM-001-C` | `tab_game` 基础字段 | 游戏 CRUD、列表、详情 |
| `GAM-001-D` | 游戏状态、配置 JSON、数据字段 | `changeStatus`、`setGameConfig`、`setGameDataField` |
| `GAM-001-E` | 游戏改名和 `tab_game_change_name_log` | 改名、历史引用、日志 |
| `GAM-001-F` | `tab_game_set`、`tab_game_source` | 对接设置、原包管理 |
| `GAM-001-G` | `tab_game_server`、`tab_game_server_merge` | 区服、合服 |
| `GAM-001-H` | `tab_game_interflow` | 互通关联和跨游戏关系 |
| `GAM-001-I` | `tab_game_ban_set`、`tab_game_ban_support` | 禁推/禁扶持 |
| `GAM-001-J` | `tab_app`、`tab_platform_config` | APP 包和平台配置 |
| `GAM-001-K` | `tab_pay_config`、`sys_option` | 支付配置和系统选项 |
| `GAM-001-L` | `tab_platform_qys_pay_log`、`tab_platform_qys_consume_log`、`art_opus_index_order` | 企业签日志、排序 |
| `GAM-001-M` | 游戏后台页面、菜单、按钮和导出 | A-L |
| `GAM-001-N` | 游戏表迁移、状态机和跨表回归 | A-M |
每个 `GAM-001-*` 工作包必须独立完成 P01-P12；`GAM-001-C` 和 `GAM-001-D` 不允许并行修改同一个 `tab_game` PO、migration 或状态常量。
### CHN-001 渠道、商务、合同和公告拆分
| 工作包 | OA 表/文件范围 | 主要业务 |
|---|---|---|
| `CHN-001-A` | `tab_promote` 主表和层级关系 | 渠道 CRUD、上下级、状态 |
| `CHN-001-B` | 渠道审核、驳回、冻结、解冻 | 状态机和审计 |
| `CHN-001-C` | `tab_promote_business` | 商务归属、批量改派 |
| `CHN-001-D` | `tab_promote_config` | 渠道推广配置 |
| `CHN-001-E` | `tab_promote_login_record` | 登录记录和连续未登录 |
| `CHN-001-F` | `tab_promote_contract` | 合同列表、签署、状态 |
| `CHN-001-G` | `tab_promote_notice` | 渠道公告 |
| `CHN-001-H` | `tab_promote_deposit`、`tab_promote_coin`、平台币/渠道币 | 押金、余额和币种 |
| `CHN-001-I` | 渠道导出、后台页面和权限 | 前端全量迁移 |
| `CHN-001-J` | 层级、商务、状态和快照回归 | 全量差异测试 |
### PKG-001 渠道申请与多端打包拆分
| 工作包 | OA 表/文件范围 | 主要业务 |
|---|---|---|
| `PKG-001-A` | `tab_promote_apply` 基础申请 | 申请 CRUD、审核基础字段 |
| `PKG-001-B` | 申请审核、分成比例、可见性 | 审核、比例、隐藏游戏 |
| `PKG-001-C` | Android 普通包状态机 | `allPackage`、下载、失败重试 |
| `PKG-001-D` | PC 重打包状态机 | `allPcPackage`、外部任务、轮询 |
| `PKG-001-E` | H5/超级签/免分包 | URL、分享显示、渠道参数 |
| `PKG-001-F` | `tab_promote_app` 包自定义 | 图标、名称、启动图 |
| `PKG-001-G` | 快手/抖音配置 | 保存、查询、校验 |
| `PKG-001-H` | 打包下载、删除、导出 | 文件和权限 |
| `PKG-001-I` | 后台打包管理页面和任务中心入口 | 页面、按钮、进度 |
| `PKG-001-J` | 状态机、幂等、异步失败和下载回归 | 全量验收 |
## 19. 阶段 4 细化：玩家、订单、扶持和财务
### PLY-001 玩家、角色和账号关联拆分
| 工作包 | OA 表/文件范围 | 主要业务 |
|---|---|---|
| `PLY-001-A` | `tab_user` 玩家主表 | 玩家列表、详情、编辑 |
| `PLY-001-B` | 玩家注册归因、设备、IP、补链 | 渠道归因和 `buLian` |
| `PLY-001-C` | `tab_user_play`、`tab_user_play_info` | 角色列表、角色详情 |
| `PLY-001-D` | `tab_user_login_record` | 玩家登录历史和导出 |
| `PLY-001-E` | 玩家补单 `tab_user_mend` | 补单申请、处理和状态 |
| `PLY-001-F` | `tab_user_agree_record`、`tab_sms_log` | 协议记录、短信查询 |
| `PLY-001-G` | 敏感信息脱敏和 reveal | 权限、审计、字段展示 |
| `PLY-001-H` | 玩家批量添加、导出和小号 | 批量导入、列表导出 |
| `PLY-001-I` | `tab_user_deduct_bind`、余额调整 | 绑币回收、平台币余额 |
| `PLY-001-J` | 玩家后台页面、筛选、按钮 | 前端全量迁移 |
| `PLY-001-K` | 归因、补链、角色和敏感字段回归 | 数据/接口验收 |
### ORD-001 充值、绑币、平台币和交易记录拆分
| 工作包 | OA 表/文件范围 | 主要业务 |
|---|---|---|
| `ORD-001-A` | `tab_spend` 订单主表 | 列表、详情、CRUD |
| `ORD-001-B` | 支付状态和游戏通知状态 | 状态机、回调、查询 |
| `ORD-001-C` | 订单绑定和补单 | `bind`、`repair`、幂等 |
| `ORD-001-D` | `tab_spend_bind`、`tab_promote_bind_update_record` | 绑币充值、换绑和变更记录 |
| `ORD-001-E` | `tab_spend_provide` | 平台币发放 |
| `ORD-001-F` | `tab_spend_balance`、`tab_spend_promote_coin` | 余额/渠道币变更 |
| `ORD-001-G` | 代金券记录和 QYS 交易日志 | `tab_coupon_record`、企业签 |
| `ORD-001-H` | 支付适配器与回调兼容 | 支付渠道、签名、ACK |
| `ORD-001-I` | 订单导出、后台页面、权限 | 前端和导出 |
| `ORD-001-J` | 金额、唯一性、回调、补单、到账回归 | 全量验收 |
### SUP-001 扶持、福利和 CP 发放拆分
| 工作包 | OA 表/文件范围 | 主要业务 |
|---|---|---|
| `SUP-001-A` | `tab_support` | 扶持申请、审核、状态 |
| `SUP-001-B` | `tab_promote_support` | 渠道扶持 |
| `SUP-001-C` | `tab_support_beishu`、`tab_support_zero_log` | 倍数、清零、日志 |
| `SUP-001-D` | `tab_fuli_config`、`tab_fuli_prop` | 福利配置、道具 |
| `SUP-001-E` | `tab_fuli_record` | 福利记录、批量审核、发放 |
| `SUP-001-F` | CP 礼包配置和发放 | `sys_platform_cp_gift*` |
| `SUP-001-G` | CP 外部发放适配器 | 996、盛和等业务站 |
| `SUP-001-H` | 自动审核、自动扶持、自动福利 | 任务和幂等 |
| `SUP-001-I` | 扶持/福利后台页面和权限 | 前端全量迁移 |
| `SUP-001-J` | 到账、失败、补偿、重复发放回归 | 全量验收 |
### FIN-001 结算、提现、代充和预支拆分
| 工作包 | OA 表/文件范围 | 主要业务 |
|---|---|---|
| `FIN-001-A` | `tab_promote_settlement_time` | 结算时间配置 |
| `FIN-001-B` | `tab_promote_settlement` | 结算单、汇总、确认 |
| `FIN-001-C` | `tab_promote_settlement_period` | 周期单和详情 |
| `FIN-001-D` | `tab_promote_withdraw`、`tab_promote_withdraw_ip`、`tab_user_hzb_withdraw` | 渠道/玩家提现、风控、状态 |
| `FIN-001-E` | `tab_promote_agent`、`tab_promote_bind` | 代充折扣、绑币订单 |
| `FIN-001-F` | `tab_promote_advance_whitelist`、`tab_promote_advance_game` | 预支白名单和游戏 |
| `FIN-001-G` | `tab_promote_advance_limit_log`、`tab_promote_advance_return_log` | 预支额度、还款、限额和返还日志 |
| `FIN-001-H` | 余额、结算、提现后台页面和权限 | 前端全量迁移 |
| `FIN-001-I` | 金额、状态、重复付款、额度恢复回归 | 全量验收 |
## 20. 阶段 5 细化：TG、IM、SDK 和客户端
### TG-001 会长/渠道移动端拆分
| 工作包 | API 族 | 依赖 |
|---|---|---|
| `TG-001-A` | `/tg/promote/info`、`base_info`、`update` | SYS-001、CHN-001 |
| `TG-001-B` | `/tg/promote/getAll`、`switch`、当前平台 | FND-003-F、PLT-001 |
| `TG-001-C` | `data_index`、`summary`、统计口径 | GAM/CHN/PLY/ORD |
| `TG-001-D` | `period`、`confirmPeriod`、`showDetail` | FIN-001-B/C |
| `TG-001-E` | `withdraw`、`withdraw_info`、`bank` | FIN-001-D |
| `TG-001-F` | `profit`、`profitRecord`、`recharge`、`register` | ORD/FIN |
| `TG-001-G` | `bindPay*`、预支代充 | FIN-001-E/F/G |
| `TG-001-H` | 福利、扶持和申请接口 | SUP-001、PKG-001 |
| `TG-001-I` | `tab_promote_sms`、TG 菜单、层级限制、短信和错误返回 | FND-003-F |
| `TG-001-J` | 移动端全量请求回放和字段回归 | A-I |
### IM-001 管理后台客服 IM 拆分
| 工作包 | OA 表/API 族 | 主要业务 |
|---|---|---|
| `IM-001-A` | `im_group`、`im_group_member`、群组 CRUD | 后台群组和成员管理 |
| `IM-001-B` | `im_groups`、`im_messages`、`im_messages_content` | 客服群、消息、平台和玩家关系 |
| `IM-001-C` | `im_groups_contact`、`im_robots` | 会话联系、机器人和状态 |
| `IM-001-D` | 客服分配、转接、结束 | 用户 IM 字段和并发计数 |
| `IM-001-E` | `im_collect`、`im_collect_tag`、`im_collect_rel_tag`、`im_shortcut`、`im_shortcut_group` | 收藏、标签、快捷语和分组 |
| `IM-001-F` | RabbitMQ 入群队列 | 发布、消费、ack/requeue |
| `IM-001-G` | 腾讯 IM 同步、群事件和消息 | 第三方适配器 |
| `IM-001-H` | 后台 IM 页面、WebSocket、权限 | 前端和实时通信 |
| `IM-001-I` | 并发分配、断线、转接和会话回归 | 全量验收 |
### IM-002 玩家端和 SDK IM 拆分
| 工作包 | API 族 | 主要业务 |
|---|---|---|
| `IM-002-A` | 玩家注册、注册登录、账号登录 | 玩家 JWT |
| `IM-002-B` | 玩家密码、登出、userinfo | 玩家会话 |
| `IM-002-C` | `im_play_users`、`im_play_users_bind_platform` | 平台账号绑定/解绑/列表 |
| `IM-002-D` | `im_play_group`、`im_play_group_tag`、游戏/角色/绑定列表 | 玩家群和跨业务库查询 |
| `IM-002-E` | enterGroup、enterContact、评价 | 客服会话 |
| `IM-002-F` | `im_call_back`、腾讯 IM callback | 消息/群事件/ACK/幂等 |
| `IM-002-G` | `/sdk/im/saveUser`、`userSig` | SDK 基础接口 |
| `IM-002-H` | SDK 群组成员和群主操作 | create/add/del/change |
| `IM-002-I` | SDK 消息修改、未读数、评价 | 消息能力 |
| `IM-002-J` | OCR 和 SDK 错误兼容 | 签名、敏感数据 |
| `IM-002-K` | 移动端/PC 端请求回放 | A-J |
### SDK-001 其他签名 SDK
| 工作包 | API 族 | 依赖 |
|---|---|---|
| `SDK-001-A` | `/sdk/support/list` | SUP-001 |
| `SDK-001-B` | `/sdk/support/update` | SUP-001 |
| `SDK-001-C` | 旧签名算法和字段排序 | FND-003-G |
| `SDK-001-D` | 幂等、重放、错误和审计 | A-C |
| `SDK-001-E` | 外部客户端回放 | D |
## 21. 阶段 6 细化：Issue 和报表
### ISS-001 Issue 分发系统
| 工作包 | OA 文件/表范围 | 主要业务 |
|---|---|---|
| `ISS-001-A` | `tab_issue_user` | 分发玩家 |
| `ISS-001-B` | `sys_issue_user_mend` | 分发补单 |
| `ISS-001-C` | `tab_issue_spend` | 分发充值 |
| `ISS-001-D` | `tab_issue_user_play_role` | 分发角色 |
| `ISS-001-E` | `tab_issue_data` | 数据分发和导出 |
| `ISS-001-F` | 后台页面、权限和接口回归 | A-E |
### REP-001 报表
| 工作包 | OA 文件/表范围 | 主要业务 |
|---|---|---|
| `REP-001-A` | `tab_datareport_top_pid` | Top PID |
| `REP-001-B` | `tab_datareport_every_pid` | 每日 PID |
| `REP-001-C` | 动态 SQL、跨库聚合和时间边界 | 报表查询引擎 |
| `REP-001-D` | 报表页面、导出、权限和差异回归 | 全量验收 |
## 22. 阶段 7 细化：定时任务、运维和切换
### OPS-001 定时任务逐项迁移
每个任务都独立建工作包，不能把所有 cron 放在一个提交中：
| 工作包 | OA 任务 | 目标模块 | 关键验收 |
|---|---|---|---|
| `OPS-001-A` | `ClearDB` | System | 操作日志/JWT/任务日志清理范围一致 |
| `OPS-001-B` | `CloseChat` | IM | 超 30 分钟会话、计数和状态 |
| `OPS-001-C` | `UnsubscribeSysUser` | System | 15 天注销窗口、软删除和回滚 |
| `OPS-001-D` | `AutoSendSupport` | Support | 多业务库、外部发放、失败重试 |
| `OPS-001-E` | `AutoSendGift` | Support | 礼包状态和重复发放 |
| `OPS-001-F` | `PromoteActivePoolScan` | Platform/Channel | 活跃池扫描和渠道状态 |
| `OPS-001-G` | `PcRepackageScan` | Packaging | 外部任务轮询和失败回收 |
| `OPS-001-H` | `LockChannelOverThreeMonth` | Channel | 登录时间、上下级锁定和原因 |
| `OPS-001-I` | `AutoSendFuliRecord` | Welfare | 审核/待发放记录和幂等 |
| `OPS-001-J` | `AutoSendWeekCard` | Welfare | 周卡/月卡周期和重复执行 |
| `OPS-001-K` | `AutoBuLianInactiveUsers` | Player | inactive 条件、补链目标和跨库 |
| `OPS-001-L` | `AutoAuditSupport` | Support | dbNames、limit、审核状态和日志 |
| `OPS-001-M` | 调度总体验收 | Worker | 启停、手动触发、并发防重、告警 |
### OPS-002 可观测性与故障恢复
| 工作包 | 细化内容 |
|---|---|
| `OPS-002-A` | 请求、任务、外部调用和消息统一 request/trace ID |
| `OPS-002-B` | 订单、发放、提现、打包、IM 回调幂等查询 |
| `OPS-002-C` | MQ、第三方、数据库、任务积压监控 |
| `OPS-002-D` | 敏感字段脱敏和审计检查 |
| `OPS-002-E` | OA 维护文档故障场景逐项演练 |
| `OPS-002-F` | 运维手册、告警阈值和应急联系人交接 |
### CUT-001 全量接口和后台回归
| 工作包 | 细化内容 |
|---|---|
| `CUT-001-A` | 后台公共/登录/RBAC/多库接口全量回归 |
| `CUT-001-B` | 游戏/渠道/玩家/订单/扶持/财务接口全量回归 |
| `CUT-001-C` | TG 移动端全量回放 |
| `CUT-001-D` | IM 玩家端、客服端和 SDK 全量回放 |
| `CUT-001-E` | PC/Android/iOS/H5 下载、打包和回调回归 |
| `CUT-001-F` | KRA 后台页面、菜单、按钮、角色回归 |
| `CUT-001-G` | 未注册/未迁移/已批准废弃项审计 |
### CUT-002 数据迁移演练
| 工作包 | 细化内容 |
|---|---|
| `CUT-002-A` | 主系统库全量迁移演练 |
| `CUT-002-B` | 各业务库全量迁移演练 |
| `CUT-002-C` | 增量追平、停写窗口和耗时测量 |
| `CUT-002-D` | 行数、金额、状态、关系、软删除抽样 |
| `CUT-002-E` | 失败恢复、断点续跑和回滚演练 |
### CUT-003 灰度与正式切换
| 工作包 | 细化内容 |
|---|---|
| `CUT-003-A` | 影子读和请求回放，不产生业务写入 |
| `CUT-003-B` | 只读接口灰度和差异阈值 |
| `CUT-003-C` | 管理后台写接口灰度 |
| `CUT-003-D` | TG/玩家/SDK/回调写接口灰度 |
| `CUT-003-E` | 停止 OA 定时任务、消费者和外部回调入口 |
| `CUT-003-F` | KRA 正式切换、DNS/网关/配置切换 |
| `CUT-003-G` | 回滚到 OA 的数据点、路由和外部系统切换 |
| `CUT-003-H` | 切换后 24 小时、72 小时和 7 天观察 |
## 23. 后台页面与 API 迁移批次
后台页面必须和接口工作包绑定，不能只迁后端。以下批次是 KRA 后台新增页面的建议交付顺序：
| 批次 | OA 页面/API 族 | 绑定任务 | 页面交付 |
|---|---|---|---|
| `WEB-001` | 用户、角色、菜单、API、按钮、部门、岗位 | SYS-001/002/003 | 登录后基础管理闭环 |
| `WEB-002` | 平台、公司、商务、黑名单、配置、日志 | SYS-004/PLT-001/CHN-001 | 系统运维闭环 |
| `WEB-003` | 游戏类型、CP、游戏、设置、原包、区服、合服 | GAM-001-A-H | 游戏主数据闭环 |
| `WEB-004` | 游戏禁推、APP、平台配置、支付、企业签日志 | GAM-001-I-L | 游戏扩展闭环 |
| `WEB-005` | 渠道、商务、推广配置、合同、公告、登录记录 | CHN-001 | 渠道主数据闭环 |
| `WEB-006` | 渠道申请、打包、APP 包、快手抖音 | PKG-001 | 打包闭环 |
| `WEB-007` | 玩家、角色、补单、协议、短信、敏感信息 | PLY-001 | 玩家运营闭环 |
| `WEB-008` | 订单、绑币、平台币、代金券、支付日志 | ORD-001 | 交易闭环 |
| `WEB-009` | 扶持、福利、CP 礼包、自动审核 | SUP-001 | 发放闭环 |
| `WEB-010` | 结算、周期、提现、代充、预支 | FIN-001 | 财务闭环 |
| `WEB-011` | 后台客服 IM、收藏、快捷语、会话 | IM-001 | 客服闭环 |
| `WEB-012` | Issue、报表和导出 | ISS-001/REP-001 | 分析闭环 |
| `WEB-013` | 定时任务、运行日志、错误日志、版本和集成配置 | SYS-004/OPS-001/002 | 运维闭环 |
每个 WEB 批次必须同时完成：API 文件、页面组件、动态菜单、按钮权限、列表/表单/详情/导出/批量操作、loading/空态/错误态和角色权限验证。
## 24. 推荐的任务分派方式
为了避免多个任务互相覆盖，建议按以下角色边界分派：
| 角色 | 负责范围 | 不应直接修改 |
|---|---|---|
| 基础设施任务 | FND、MIG、公共响应、认证、多库、迁移工具 | 业务模块状态机 |
| 系统任务 | SYS、平台、用户权限和后台基础页面 | 游戏/订单业务表 |
| 主数据任务 | 游戏、平台、渠道、打包 | 玩家余额和结算核心逻辑 |
| 玩家任务 | 玩家、角色、补链、敏感字段 | 渠道结算状态机 |
| 交易任务 | 订单、支付、绑币、余额 | IM 会话分配 |
| 发放财务任务 | 扶持、福利、结算、提现、预支 | 登录和权限核心表 |
| 端适配任务 | TG、玩家端、SDK、PC/移动端兼容 | KRA 系统表 schema |
| IM 集成任务 | 腾讯 IM、RabbitMQ、WebSocket、客服 | 订单金额计算 |
| 运维切换任务 | 定时任务、观测、数据演练、灰度 | 未经模块负责人确认的业务代码 |
同一文件、同一 PO、同一 migration、同一状态常量只能有一个任务负责人。跨任务修改必须先登记依赖变更，不允许通过后续冲突解决“顺手合并”。
## 25. 细化后的验收批次
每完成一个工作包，按以下批次保存证据：
| 批次 | 验收内容 | 必须回答的问题 |
|---|---|---|
| `V-A` 文件 | OA 文件是否逐一处理 | 是否还有未归类文件？是否误删逻辑？ |
| `V-B` Schema | 表和字段是否兼容 | 是否保留主键、索引、默认值、软删除和状态？ |
| `V-C` Request | 请求是否兼容 | 方法、路径、参数位置、必填、别名是否一致？ |
| `V-D` Response | 响应是否兼容 | code、msg、字段、类型、空值、分页和 Header 是否一致？ |
| `V-E` Logic | 业务是否一致 | 状态转换、事务、幂等、跨表更新是否一致？ |
| `V-F` Side Effect | 副作用是否一致 | Redis、MQ、第三方调用、日志和任务是否一致？ |
| `V-G` Web | 后台是否完整 | 菜单、按钮、列表、表单、导出和权限是否完整？ |
| `V-H` Data | 历史数据是否正确 | 行数、金额、状态、关系、抽样是否通过？ |
| `V-I` Ops | 能否运行和恢复 | 监控、告警、重试、补偿、回滚是否可执行？ |
只有 `V-A` 到 `V-I` 全部有证据，工作包才可以进入 `REVIEW`。
## 26. 细化后的并行规则
### 允许并行
- `MIG-000-A/B/C/E/F` 可以并行；`MIG-000-D` 在文件清单稳定后开始。
- `FND-005-A/B/C/D/E` 可由不同集成任务并行，但共享的配置加载和错误规范由一个负责人维护。
- `GAM-001-A/B` 可并行；`GAM-001-C/D/E` 必须按游戏主表、状态、改名顺序执行。
- `CHN-001-C/D/E/F/G` 可在 `CHN-001-A` 的主键和状态冻结后并行。
- `PLY-001-C/D/F` 可在玩家主表冻结后并行。
- `WEB-001` 之后，各业务 WEB 批次可在相应 API 契约冻结后并行开发。
### 禁止并行
- 不允许同时修改同一张表的 migration 和历史迁移脚本。
- 不允许同时修改同一个 API 的旧响应 DTO 和前端调用封装。
- 不允许在 `SYS-001/002/003` 未完成前迁移用户、角色、部门关系数据。
- 不允许在 `GAM-001-C` 未完成前迁移渠道申请、玩家归因和订单外键。
- 不允许在 `ORD-001` 未完成前迁移结算、提现、预支金额数据。
- 不允许在 `IM-001-F/G` 未完成前启用真实 RabbitMQ 消费和腾讯 IM 回调。
- 不允许在 `CUT-003-E` 完成前关闭 OA 的任务/消费者，也不允许双系统同时处理同一回调。
## 27. 细化后的第一轮实际执行顺序
第一轮不要直接进入全部业务，按以下 20 个工作包顺序执行：
1. `MIG-000-A` 后端源文件登记。
2. `MIG-000-B` 前端 API/页面登记。
3. `MIG-000-C` 运行时路由导出。
4. `MIG-000-D` 数据表字段目录。
5. `MIG-000-G` 移动端/PC/后台请求样本冻结。
6. `MIG-001-A/B/C` 差异测试基础框架。
7. `MIG-002-A/B/E` 模块接入样板。
8. `FND-001-A/B/G` 增量迁移最小闭环。
9. `FND-002-A/B/C/D` 响应和 token 兼容闭环。
10. `FND-003-A/B/C/D` 后台路由和 JWT/Casbin 闭环。
11. `FND-004-A/B/C` 多库和平台上下文闭环。
12. `SYS-001-A/B` 用户表扩展和 migration 评审。
13. `SYS-003-A/B/C` 部门表和关系表映射评审。
14. `SYS-002-A/C/D/E` 角色、多角色、菜单和 API 关系。
15. `SYS-001-C/G` 登录和个人信息兼容接口。
16. `SYS-003-D/F` 公司/部门接口。
17. `WEB-001` 系统基础后台页面。
18. `MIG-001-G` 登录、菜单、用户、部门差异回归。
19. `FND-006-B` 主系统表迁移演练。
20. 阶段门禁评审，确认是否进入 `PLT/GAM/CHN` 并行开发。
## 28. 任务记录模板
后续每个任务建议按以下格式记录，避免只提交代码而没有迁移证据：
```markdown
# <TASK-ID> <任务名称>
## 任务状态
- 状态：READY / DOING / REVIEW / BLOCKED / DONE
- 负责人：
- 评审人：
- 前置任务：
- 影响任务：
## 范围
- OA 文件：
- OA 路由/API：
- OA 表：
- KRA 目标文件：
- KRA 后台页面：
## 实施清单
- [ ] P01 源文件登记
- [ ] P02 路由冻结
- [ ] P03 请求冻结
- [ ] P04 响应冻结
- [ ] P05 数据表冻结
- [ ] P06 状态机冻结
- [ ] P07 领域实现
- [ ] P08 数据实现
- [ ] P09 兼容接口实现
- [ ] P10 前端/后台实现
- [ ] P11 对照验证
- [ ] P12 文件签收
## 验收证据
- [ ] V-A 文件
- [ ] V-B Schema
- [ ] V-C Request
- [ ] V-D Response
- [ ] V-E Logic
- [ ] V-F Side Effect
- [ ] V-G Web
- [ ] V-H Data
- [ ] V-I Ops
## 已知差异与批准
| 差异 | 原因 | 影响 | 批准人 | 是否阻塞 |
|---|---|---|---|---|
```
## 29. OA 前端 API 和页面精确归属索引
本索引用于 `MIG-000-B` 的初始归类。最终仍以实际 import、页面调用和运行时请求为准；同名 API 文件不能仅凭文件名判断已完成。
### 29.1 系统基础前端
| OA `web/src/api` 文件 | 目标任务 | 目标页面/说明 |
|---|---|---|
| `user.js` | SYS-001 | 用户、登录和个人信息 |
| `jwt.js` | SYS-001 / FND-003 | 登出、黑名单和 token |
| `authority.js` | SYS-002 | 角色管理 |
| `authorityBtn.js` | SYS-002 | 按钮权限 |
| `menu.js` | SYS-002 | 菜单与动态路由 |
| `api.js` | SYS-002 | API 管理 |
| `casbin.js` | SYS-002 | Casbin 策略 |
| `sysDepart.js` | SYS-003 | OA 部门兼容接口 |
| `sysUserDepart.js` | SYS-003 | 用户部门关系 |
| `sysUserMenusOften.js` | SYS-001-L | 常用菜单 |
| `sysDictionary.js` | SYS-004-H | 字典 |
| `sysDictionaryDetail.js` | SYS-004-H | 字典项 |
| `sysOperationRecord.js` | SYS-004-B | 操作记录 |
| `sysUserActionLog.js` | SYS-004-B | 用户行为日志 |
| `sysUserBlacklist.js` | SYS-001-J / SYS-004-C | 用户黑名单 |
| `system.js` | SYS-004-A | 系统配置兼容门面 |
| `initdb.js` | FND-003-I | 数据库初始化 |
对应 OA 页面目录：`login`、`person`、`superAdmin`、`sysDepart`、`sysUserDepart`、`sysUserMenusOften`、`sysUserActionLog`、`sysUserBlacklist`、`system`、`systemTools`。
### 29.2 平台和公司前端
| OA `web/src/api` 文件 | 目标任务 | 目标页面目录 |
|---|---|---|
| `sysPlatform.js` | PLT-001-A | `sysPlatform` |
| `sysAuthorityPlatform.js` | PLT-001-B | `sysAuthorityPlatform` |
| `sysPlatformCpSession.js` | PLT-001-D | `sysPlatformCpSession` |
| `sysPlatformCpSupport.js` | PLT-001-D | `sysPlatformCpSupport` |
### 29.3 游戏主数据前端
| OA `web/src/api` 文件 | 目标任务 | 目标页面目录 |
|---|---|---|
| `tabGameType.js` | GAM-001-A | `tabGameType` |
| `tabGameCp.js` | GAM-001-B | `tabGameCp` |
| `tabGame.js` | GAM-001-C/D/E | `tabGame` |
| `tabGameSet.js` | GAM-001-F | `tabGameSet` |
| `tabGameSource.js` | GAM-001-F | `tabGameSource` |
| `tabGameServer.js` | GAM-001-G | `tabGameServer` |
| `tabGameServerMerge.js` | GAM-001-G | `tabGameServerMerge` |
| `tabGameBanSet.js` | GAM-001-I | `tabGameBanSet` |
| `tabGameChangeNameLog.js` | GAM-001-E | `tabGameChangeNameLog` |
| `tabApp.js` | GAM-001-J / PKG-001-F | `tabApp` |
| `tabPlatformConfig.js` | GAM-001-J | `tabPlatformConfig` |
| `tabPlatformQysPayLog.js` | GAM-001-L / ORD-001-G | `tabPlatformQysPayLog` |
| `tabPlatformQysConsumeLog.js` | GAM-001-L / ORD-001-G | `tabPlatformQysConsumeLog` |
### 29.4 渠道、打包和财务前端
| OA `web/src/api` 文件 | 目标任务 | 目标页面目录 |
|---|---|---|
| `tabPromote.js` | CHN-001-A/B/H | `tabPromote` |
| `tabPromoteBusiness.js` | CHN-001-C | `tabPromoteBusiness` |
| `tabPromoteConfig.js` | CHN-001-D | `tabPromoteConfig` |
| `tabPromoteLoginRecord.js` | CHN-001-E | `tabPromoteLoginRecord` |
| `tabPromoteContract.js` | CHN-001-F | `tabPromoteContract` |
| `tabPromoteApply.js` | PKG-001 | `tabPromoteApply` |
| `tabPromoteSettlement.js` | FIN-001-B | `tabPromoteSettlement` |
| `tabPromoteSettlementTime.js` | FIN-001-A | `tabPromoteSettlementTime` |
| `tabPromoteSupport.js` | SUP-001-B | `tabPromoteSupport` |
### 29.5 玩家、订单和扶持前端
| OA `web/src/api` 文件 | 目标任务 | 目标页面目录 |
|---|---|---|
| `tabUser.js` | PLY-001-A/B/G/H | `tabUser` |
| `tabUserMend.js` | PLY-001-E | `tabUserMend` |
| `tabUserPlayInfo.js` | PLY-001-C | `tabUserPlayInfo` |
| `tabSmsLog.js` | PLY-001-F | `tabSmsLog` |
| `tabSpend.js` | ORD-001-A/B/C/I | `tabSpend` |
| `tabCouponRecord.js` | ORD-001-G | `tabCouponRecord` |
| `tabSupport.js` | SUP-001-A | `tabSupport` |
### 29.6 IM、公共能力和遗留前端
| OA `web/src/api` 文件 | 目标任务 | 处理原则 |
|---|---|---|
| `imGroupMember.js` | IM-001-A | 迁移接口和 `imGroupMember` 页面 |
| `fileUploadAndDownload.js` | SYS-004-D | 对接 KRA 媒体库并保持旧协议 |
| `breakpoint.js` | SYS-004-D / SYS-004-G | 有调用则迁移，未调用则审批废弃 |
| `email.js` | SYS-004-A | 复用 KRA 邮件模块，保持旧 API |
| `autoCode.js` | SYS-004-F | 使用性评估后迁移或废弃 |
| `customer.js` | SYS-004-G | 使用性评估后迁移或废弃 |
| `github.js` | SYS-004-G | 使用性评估后迁移或废弃 |
### 29.7 无独立 OA 页面但仍必须迁移的接口
以下能力不能因为当前 `web/src/view` 中没有对应目录而漏迁：
- `/tg/*`：移动会长端使用，归 `TG-001`；
- `/imserver/*`：移动/PC 玩家端使用，归 `IM-002`；
- `/sdk/*`：游戏 SDK 和外部服务使用，归 `IM-002`、`SDK-001`；
- Issue 全部接口：可能由外部后台或独立页面使用，归 `ISS-001`；
- Report 全部接口：归 `REP-001`；
- SW 商务用户接口：归 `PLT-001-E`；
- OA 当前未展示页面的 Game/User/System 接口：仍按运行时路由和调用日志迁移。
## 30. OA 后端源文件覆盖检查规则
为了保证“逐文件确认”可以自动执行，在 `MIG-000-A` 中增加以下检查：
1. 扫描 `server/model/<domain>/*.go`，每个文件基名必须出现在 source ledger 或本计划的任务归属中。
2. 扫描 `server/model/<domain>/request/*.go` 和 `response/*.go`，必须关联至少一个 API contract。
3. 扫描 `server/api/v1/<domain>/*.go`，必须关联 handler 工作包或批准废弃项。
4. 扫描 `server/router/<domain>/*.go`，必须关联运行时有效路由或明确未注册。
5. 扫描 `server/service/<domain>/*.go`，必须关联业务用例、集成适配器或批准废弃项。
6. 扫描 `web/src/api/*.js`，必须关联页面、外部客户端或批准废弃项。
7. 扫描 `web/src/view/**`，必须关联一个 `WEB-*` 批次或批准废弃项。
8. 扫描配置、中间件、定时任务和第三方工具目录，必须关联 `FND-*`、`OPS-*` 或业务任务。
自动检查输出至少包含：
```text
source_path
source_type
domain
owner_task_id
target_path
decision=migrate|replace|retire
contract_ids
verification_status
```
合并门禁：`owner_task_id`、`decision`、`target_path` 或 `verification_status` 任何一项为空，迁移覆盖检查失败。
Reference in New Issue View Git Blame Copy Permalink