80 lines
8.6 KiB
Markdown
80 lines
8.6 KiB
Markdown
# 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 的两份文档只表示范围/缺口已预备。
|