1

2026-09-30 10:28:10 +08:00
parent f6a9581666
commit 13c5b90e92
3 changed files with 0 additions and 79 deletions
@@ -1,79 +0,0 @@
 # OA 到 oa-new 迁移执行计划
 > 基线日期：2026-09-28。源：本仓库 `oa-old/server`、`oa-old/web`；目标：当前 oa-new。本文替代旧计划中的表优先、嵌套分层及跨模块并行决策。
 > 当前只实施 M00；M01–M18 均未开始。进度以 [迁移入口](migration/README.md) 和 [progress.json](migration/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；不是自动确认或自动切换下一批的理由。
 恢复时先读 [迁移入口](migration/README.md)、[progress.json](migration/progress.json)、本批 verification/environment，再检查 Git 状态及源码指纹，恢复最后一条未完成 case。若代码或配置基线变化，先重建受影响证据。
 当前关卡是 M00：
 - 当前旧源码 `oa-old/` 尚未纳入 Git，须保存清单与内容指纹；保留 `docs/code-review-issues.md` 已暂存删除。
 - 环境探测已报告本机 MySQL 可监听但账号认证 1045；Redis 无监听。连接状态、实际构建命令与证据由执行记录补齐。
 - 空库或新建空容器不能视作旧 OA 数据快照；数据库认证恢复后还须验证表、样本、权限与克隆隔离。
 - M00 基础文档与工具完成后交用户确认，**确认前不开始 M01 实现**。M01 的两份文档只表示范围/缺口已预备。