kra-new/docs/OA_MIGRATION_PLAN.md

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 分层：

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. 推荐执行顺序与并行关系

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>：

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 分页转换
FND-002-C	字段类型和空值规则
FND-002-D	token/Header/Cookie 兼容
FND-002-E	上传、common/download、下载、导出和文件名兼容
FND-002-F	全局错误和消息映射
FND-002-G	兼容层基线测试

FND-003 多接口域与中间件

工作包	细化内容
FND-003-A	Public/Admin Login/Admin RBAC/Admin DB 路由组
FND-003-B	后台 JWT claims 与多角色
FND-003-C	Casbin 多角色和超级管理员
FND-003-D	OA 未登录/过期/非法 token 行为
FND-003-E	DbHandler 和数据范围
FND-003-F	TgAuth 平台切换和层级
FND-003-G	SignAuth 签名
FND-003-H	操作日志/错误审计/限流/CORS
FND-003-I	sys_captcha、sys_initdb、初始化保护和健康检查

FND-004 多数据库、公司、平台上下文

工作包	细化内容
FND-004-A	OA db-list 到 KRA database_list 映射
FND-004-B	请求体 dbName 统一解析
FND-004-C	当前公司/平台上下文
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	主系统表迁移
FND-006-C	系统扩展表迁移
FND-006-D	业务库表迁移
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. 任务记录模板

后续每个任务建议按以下格式记录，避免只提交代码而没有迁移证据：

# <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-* 或业务任务。

自动检查输出至少包含：

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 任何一项为空，迁移覆盖检查失败。