kra-oa/docs/OA_MIGRATION_PLAN.md

OA 到 oa-new 迁移执行计划

基线日期：2026-09-28。源：本仓库 oa-old/server、oa-old/web；目标：当前 oa-new。本文替代旧计划中的表优先、嵌套分层及跨模块并行决策。 当前只实施 M00；M01–M18 均未开始。进度以 迁移入口 和 progress.json 为准。没有任何模块已获用户确认。

迁移原则

1. OA 是业务唯一依据，KRA 提供架构。 同一路径的登录、参数、校验、错误、返回类型及业务行为冲突时修改 oa-new；最终运行一套业务实现。禁止按客户端、开关或模式保留 OA/KRA 两套业务行为。
2. 旧契约只能增加，不能减少。 方法、路径、请求来源、名称、类型、默认值、空值、响应字段和值、业务码、消息、Header、下载及回调 ACK 均逐项对照旧源码和请求结果。新增字段不得改变旧字段含义。
3. 表和模型不预设 KRA 优先。 先证明实体语义、键、关联、约束及数据口径等价，再选择统一持久化模型；通过明确增量字段/迁移兼容 OA，禁止仅把不同字段改名后认作等价。
4. 遵守根 AGENTS.md 的分层。 DTO 在 internal/service/dto，适配器在 internal/service/<domain>，DO/用例/仓储接口在 internal/biz/<domain>，PO/仓储实现和迁移在 internal/data/<domain>；HTTP 在 server，外部 I/O 在 integration，任务运行在 worker。modules 仅承载模块声明、schema/seed/menu/API/task 贡献，cmd 负责 Wire。不得在 modules 下再建完整 biz/data/service 层。
5. 同步修改新 Web。 按旧接口修改 API、表单、store、菜单和权限依赖。用户最新要求是逐接口请求结果一致即可确认；外部 OA 桌面端源码、抓包及桌面端 E2E 不是迁移门槛，不因缺少它们停止接口核对。
6. 每批完成后等待用户确认。 可在本批内部并行盘点、开发和验证；不得提前实现下一批。用户确认记录必须来自实际用户消息，不得由测试成功、文档创建或 agent 自行代填。
7. 可恢复、可审查。 每条接口与每项 KRA 修改都有 ID、状态和证据。未知或缺环境标 pending，不能标一致。旧缺陷和性能优化单独登记，未经评估不得混入迁移掩盖行为差异。
8. 只实施已授权范围。 M00 不改登录、业务表、生产配置或旧源码，不执行优化 SQL；保留已有暂存/未暂存改动。后续数据库变更必须有可审查脚本、数据演练及回滚说明，不用启动时自动迁移替代审查。

19 批顺序与边界

批次	模块	纳入本批的能力
M00	基线环境台账	源码指纹、实际路由清单、冲突清单、核对工具、环境与恢复入口；仅预备 M01 契约
M01	密码登录会话核心	下列固定 8 条接口；登录所需 UC、设备/冻结/企业/角色读取及 token 上下文一并核对，不提前实现其管理 CRUD
M02	其他认证账号生命周期	其余 base 接口，含 register、phoneLogin、tgPhoneLogin、sendSms 的全部 reg 分支、忘记密码、注销和实名
M03	用户企业组织架构	用户、企业、部门、组织层级、账号/公司/部门关联及 OA 扩展字段
M04	角色资源权限	角色、菜单、API、按钮、多角色、数据范围、常用菜单；统一 M01 会话所需读取逻辑
M05	安全管理	设备、冻结、规则、黑名单、追踪、安全日志和对应启动/退出处理
M06	公共基础配置字典文件日志	配置、字典、文件、断点续传、平台上传、静态下载、客户端版本数据、邮件/短信适配及通用日志
M07	平台 CP 商务	平台/CP 资料、商务账号、平台绑定审核和冲突、相关授权
M08	游戏基础资料	游戏、关联游戏、默认分佣、区服、合服/互通、CP/来源/类型、禁言禁充等配置
M09	推广渠道合同活跃池	渠道/商务/代理、合同公告、活跃/绑定池、锁定和归属变更
M10	申请分包	游戏申请、渠道包、盒子、多端打包、PC 分包任务及回调
M11	玩家角色	玩家、角色、登录记录、账号关联、换绑/补链、协议与相关记录
M12	订单充值	充值、补单、绑币/扣绑、平台币/余额交易、发放、支付配置及外部支付协议
M13	扶持礼包福利	扶持及审核、CP 发放、礼包、福利、周/月卡；自动审核/发放任务和 SDK 发放结果
M14	结算资金	结算/周期、提现、保证金、渠道币、代充、预支额度/白名单/还款及交易状态
M15	TG 业务	/tg 身份及平台切换、层级限制、统计、申请、福利、资金接口，复用已确认的业务实现
M16	IM 客服 SDK	后台客服、玩家专用会话、群/成员/消息/已读/评价/OCR、SDK、腾讯回调、kefu 队列和会话任务
M17	发行报表	Issue 玩家/充值/补单/角色/换绑、日报、渠道汇总、千游社/艺术订单等统计及导出
M18	工具全量收尾	旧工具/示例逐项归属或确认处置；未归属路由/任务/静态资源清零、全量回归、数据演练和切换准备

M01 固定范围：

ID	请求
M01-API-001	POST /base/captcha
M01-API-002	POST /base/login
M01-API-003	GET /user/getUserInfo
M01-API-004	POST /menu/getMenu
M01-API-005	POST /user/getUserMenus
M01-API-006	POST /user/setUserAuthority
M01-API-007	POST /user/companySwitch
M01-API-008	POST /jwt/jsonInBlacklist

导入导出、回调、任务和消息消费者必须随所属业务一起验收；M18 是遗漏核查，不是把它们统一延后实现。13 个旧定时注册点按业务归属登记；仅有源码但无实际注册的插件单列待核实，不虚增运行功能。

执行与逐接口验收

每批按“冻结范围 → 补契约/数据样本 → 实现 → 逐接口核对 → 修复差异 → 用户确认”推进。M00 只冻结清单和工具，不将静态已盘点记成已迁移。

• 用相同请求和相同初始数据分别调用旧、新服务。读接口比较完整响应；写接口在两个隔离数据副本执行，比较响应及最终关联数据、计数、余额、权限或消息效果。不得向生产双写。
• 覆盖成功、缺参/错类型、无权限、无记录、重复操作及接口实际存在的分支。精确检查 null/空数组/空对象、字符串/数字、排序、分页、金额和时间单位。
• token、验证码、随机 ID 等动态值必须先登记具体 JSON 路径与规则再比对；比较其类型、结构、claims/有效期或后续使用结果。默认不得整体忽略 data、时间、金额或业务字段。
• 第三方 SDK/回调/MQ 使用本地替身或隔离依赖核对协议和副作用；模拟通过只证明该测试范围，不冒充真实外部系统验证。原始 ACK、文件流、导出 URL 和表格内容使用适用的比较方式。
• 后端按受影响层运行测试/检查；新 Web 运行相应构建与接口消费检查。模块确认依据是逐接口请求一致，不设桌面端 E2E 门槛。
• 已实现、静态核对、请求一致、用户确认分开记录。请求无真实可运行基线时保持 pending-runtime；未完成项不得静默豁免。

每个确认包至少包含：模块/API 状态表、旧新请求与响应证据、差异和 KRA 修改记录、字段/数据映射、测试结果及限制、待用户确认清单。证据不得包含真实口令、token、密钥或原配置文件。

状态、恢复与当前关卡

状态依次为 not_started → in_progress → awaiting_confirmation → confirmed。中途缺依赖时保留本批状态并追加 blocker；不是自动确认或自动切换下一批的理由。

恢复时先读 迁移入口、progress.json、本批 verification/environment，再检查 Git 状态及源码指纹，恢复最后一条未完成 case。若代码或配置基线变化，先重建受影响证据。

当前关卡是 M00：

• 当前旧源码 oa-old/ 尚未纳入 Git，须保存清单与内容指纹；保留 docs/code-review-issues.md 已暂存删除。
• 环境探测已报告本机 MySQL 可监听但账号认证 1045；Redis 无监听。连接状态、实际构建命令与证据由执行记录补齐。
• 空库或新建空容器不能视作旧 OA 数据快照；数据库认证恢复后还须验证表、样本、权限与克隆隔离。
• M00 基础文档与工具完成后交用户确认，确认前不开始 M01 实现。M01 的两份文档只表示范围/缺口已预备。