diff --git a/.gitignore b/.gitignore index c108be9..3c9c4b7 100644 --- a/.gitignore +++ b/.gitignore @@ -46,3 +46,6 @@ web/node_modules/ # Local reference sources and desktop-only tooling state /gva/ /.claude/settings.local.json + +# Migration credentials, database snapshots and raw request recordings stay local. +/docs/migration/private/ diff --git a/docs/OA_MIGRATION_PLAN.md b/docs/OA_MIGRATION_PLAN.md index 772c114..d2b1216 100644 --- a/docs/OA_MIGRATION_PLAN.md +++ b/docs/OA_MIGRATION_PLAN.md @@ -1,1355 +1,79 @@ -# OA 到 KRA 完整迁移执行计划 +# OA 到 oa-new 迁移执行计划 -> 计划基线日期：2026-08-21 -> 源系统：`oa` -> 目标系统：`kra-new` -> 当前状态：仅完成代码盘点与迁移规划，尚未开始业务迁移 +> 基线日期：2026-09-28。源：本仓库 `oa-old/server`、`oa-old/web`；目标：当前 oa-new。本文替代旧计划中的表优先、嵌套分层及跨模块并行决策。 +> 当前只实施 M00；M01–M18 均未开始。进度以 [迁移入口](migration/README.md) 和 [progress.json](migration/progress.json) 为准。没有任何模块已获用户确认。 -## 1. 目标与结论 +## 迁移原则 -目标是在 **不重构现有移动端、PC 端和旧后台调用协议** 的前提下，将 OA 的完整系统能力迁移到 KRA，并最终由 KRA 统一承载： +1. **OA 是业务唯一依据，KRA 提供架构。** 同一路径的登录、参数、校验、错误、返回类型及业务行为冲突时修改 oa-new；最终运行一套业务实现。禁止按客户端、开关或模式保留 OA/KRA 两套业务行为。 +2. **旧契约只能增加，不能减少。** 方法、路径、请求来源、名称、类型、默认值、空值、响应字段和值、业务码、消息、Header、下载及回调 ACK 均逐项对照旧源码和请求结果。新增字段不得改变旧字段含义。 +3. **表和模型不预设 KRA 优先。** 先证明实体语义、键、关联、约束及数据口径等价，再选择统一持久化模型；通过明确增量字段/迁移兼容 OA，禁止仅把不同字段改名后认作等价。 +4. **遵守根 AGENTS.md 的分层。** DTO 在 `internal/service/dto`，适配器在 `internal/service/`，DO/用例/仓储接口在 `internal/biz/`，PO/仓储实现和迁移在 `internal/data/`；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；保留已有暂存/未暂存改动。后续数据库变更必须有可审查脚本、数据演练及回滚说明，不用启动时自动迁移替代审查。 -- 管理后台接口与页面； -- 会长/渠道移动端接口（`/tg`）； -- 玩家及客服端接口（`/imserver`）； -- 对外 SDK 接口（`/sdk`）； -- 游戏、渠道、玩家、订单、扶持、福利、结算、IM、分发、报表等业务； -- 中间件、定时任务、多数据库、Redis、消息队列、对象存储和第三方服务； -- 数据初始化、历史数据迁移、部署和回滚能力。 +## 19 批顺序与边界 -盘点后的结论是：**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// - 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// - 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//` 下维护以下文件，缺一不可： - -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 任务 | 目标模块 | +| 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 | 请求 | |---|---| -| `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 | +| 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 | -每个任务必须验证：默认 cron、秒级模式、启停配置、手动触发、并发防重、超时、失败重试、执行日志、告警、跨库范围和重复实例运行风险。 +导入导出、回调、任务和消息消费者必须随所属业务一起验收；M18 是遗漏核查，不是把它们统一延后实现。13 个旧定时注册点按业务归属登记；仅有源码但无实际注册的插件单列待核实，不虚增运行功能。 -#### OPS-002 可观测性与故障恢复 +## 执行与逐接口验收 -- 为所有外部调用增加 request ID、耗时、结果码和脱敏错误日志。 -- 为订单、发放、提现、打包、IM 回调增加幂等键和补偿查询入口。 -- 增加任务积压、消息队列连接、第三方失败率、数据库连接和慢查询指标。 -- 编写常见故障恢复手册，覆盖 OA 维护文档中的主要故障场景。 +每批按“冻结范围 → 补契约/数据样本 → 实现 → 逐接口核对 → 修复差异 → 用户确认”推进。M00 只冻结清单和工具，不将静态已盘点记成已迁移。 -### 阶段 8：全量回归、数据演练与切换 +- 用相同请求和相同初始数据分别调用旧、新服务。读接口比较完整响应；写接口在两个隔离数据副本执行，比较响应及最终关联数据、计数、余额、权限或消息效果。不得向生产双写。 +- 覆盖成功、缺参/错类型、无权限、无记录、重复操作及接口实际存在的分支。精确检查 null/空数组/空对象、字符串/数字、排序、分页、金额和时间单位。 +- token、验证码、随机 ID 等动态值必须先登记具体 JSON 路径与规则再比对；比较其类型、结构、claims/有效期或后续使用结果。默认不得整体忽略 data、时间、金额或业务字段。 +- 第三方 SDK/回调/MQ 使用本地替身或隔离依赖核对协议和副作用；模拟通过只证明该测试范围，不冒充真实外部系统验证。原始 ACK、文件流、导出 URL 和表格内容使用适用的比较方式。 +- 后端按受影响层运行测试/检查；新 Web 运行相应构建与接口消费检查。**模块确认依据是逐接口请求一致，不设桌面端 E2E 门槛。** +- 已实现、静态核对、请求一致、用户确认分开记录。请求无真实可运行基线时保持 pending-runtime；未完成项不得静默豁免。 -#### CUT-001 全量接口与后台回归 +每个确认包至少包含：模块/API 状态表、旧新请求与响应证据、差异和 KRA 修改记录、字段/数据映射、测试结果及限制、待用户确认清单。证据不得包含真实口令、token、密钥或原配置文件。 -- 有效 OA 路由覆盖率 100%，或存在书面批准的废弃记录。 -- 旧前端 API 调用覆盖率 100%。 -- KRA 新增后台菜单、页面、按钮和权限均可按角色访问。 -- 逐接口差异报告无未批准差异。 +## 状态、恢复与当前关卡 -#### CUT-002 数据迁移演练 +状态依次为 `not_started → in_progress → awaiting_confirmation → confirmed`。中途缺依赖时保留本批状态并追加 blocker；不是自动确认或自动切换下一批的理由。 -- 使用生产结构副本和脱敏数据至少完成两次全量演练。 -- 核对行数、主键、外键、软删除、金额、状态分布和关键业务抽样。 -- 记录每张表迁移耗时、锁影响、失败恢复和增量追平方式。 +恢复时先读 [迁移入口](migration/README.md)、[progress.json](migration/progress.json)、本批 verification/environment，再检查 Git 状态及源码指纹，恢复最后一条未完成 case。若代码或配置基线变化，先重建受影响证据。 -#### 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 每个工作包的固定交付物 - -每个工作包至少交付以下内容，文件名可按模块替换 ``： - -```text -docs/migration//-source-ledger.md -docs/migration//-schema-map.md -docs/migration//-api-contract.md -docs/migration//-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 -# <任务名称> - -## 任务状态 -- 状态：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//*.go`，每个文件基名必须出现在 source ledger 或本计划的任务归属中。 -2. 扫描 `server/model//request/*.go` 和 `response/*.go`，必须关联至少一个 API contract。 -3. 扫描 `server/api/v1//*.go`，必须关联 handler 工作包或批准废弃项。 -4. 扫描 `server/router//*.go`，必须关联运行时有效路由或明确未注册。 -5. 扫描 `server/service//*.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` 任何一项为空，迁移覆盖检查失败。 +当前关卡是 M00： +- 当前旧源码 `oa-old/` 尚未纳入 Git，须保存清单与内容指纹；保留 `docs/code-review-issues.md` 已暂存删除。 +- 环境探测已报告本机 MySQL 可监听但账号认证 1045；Redis 无监听。连接状态、实际构建命令与证据由执行记录补齐。 +- 空库或新建空容器不能视作旧 OA 数据快照；数据库认证恢复后还须验证表、样本、权限与克隆隔离。 +- M00 基础文档与工具完成后交用户确认，**确认前不开始 M01 实现**。M01 的两份文档只表示范围/缺口已预备。 diff --git a/docs/code-review-issues.md b/docs/code-review-issues.md deleted file mode 100644 index 48e8b33..0000000 --- a/docs/code-review-issues.md +++ /dev/null @@ -1,78 +0,0 @@ -# 代码审查问题清单（internal + pkg） - -- 审查日期：2026-08-27 ~ 2026-08-28，共十一轮全量审查。第十一轮（2026-08-28）：核查第十轮划线项（22 项）+ 全新视角回归审查；`go build ./...` 编译验证通过 -- 文档结构：只保留待修复问题，按**类型**归类；每条标注发现轮次与处置状态（专项待修/待修）；已修复并经复查确认的、经评估决定保留的、用户决策不修的直接删除 -- gva/ 目录是遗留参考库（独立 module 不参与 kra 编译），不在审查范围 -- 依赖方向合规：pkg 无 import internal；integration 不 import data/service；data 不 import integration/payment；无循环依赖 -- 第十一轮总评：核心分层契约、日志防循环、CleanupStale 顺序反转、调度器重试、微文件合并等历轮修复验收干净；当前风险集中在**边缘入口的防护不对称**——公开写接口无治理、TTL 语义错位、停机路径无超时、前端凭证存储薄弱 - ---- - -## 一、安全与正确性缺陷 - -### 专项设计待修（用户已确认需专项处理） - -| # | 问题 | 位置 | 状态 | -|---|------|------|------| -| ~~V-39~~ | ~~公开无限流写接口 `/sysError/createSysError`~~：已移入鉴权路由组、纳入安全限流，并限制 `Info` 最大长度 | ~~server/router/audit.go；middleware/rate_limit.go；service/dto/audit.go~~ | ~~十一轮~~ | -| V-33 | 支付指纹严格相等校验对存量订单幂等重放的冲突风险（initialized/pending 存量订单重放报参数冲突而非幂等短路）——修复需兼容旧指纹、区分订单状态、覆盖并发重放，直接放宽会削弱防篡改 | biz/payment/payment.go:645-657 | 十轮发现，专项 | -| V-24 | Delete↔Create 竞态窗口仍开（锁仅覆盖 Delete，秒传/上传/Complete 的 CreateMedia 路径不持锁）；多副本需数据库/分布式锁 | biz/system/media.go:50,111-143；media_upload.go:100-107,262 | 八轮发现，专项 | -| V-13b | swagger：空 env fail-open（gin.go:68 仍注册）；gin 白名单 vs main.go 黑名单双清单不一致（qa/uat 时日志谎报）；env 门禁零测试——需统一单一判定函数+环境矩阵测试 | server/gin.go:64-70；cmd/main.go:105-126,171 | 七轮发现，专项 | -| V-27 | redis_list 仍按下标回退（configuration.go:439-441，database_list 已修✓）；别名匹配失败时哨兵字面量落盘无拒绝校验——需重新定义配置项稳定标识与密钥继承规则 | internal/initialize/configuration.go:427-446 | 九轮发现，专项 | -| V-20 | 前端 token 拼入 URL（完整 JWT 拼二维码 URL）——需后端一次性短时效票据+扫码协议迁移 | web/src/components/upload/QR-code.vue:55 | 六轮发现，专项 | -| V-15 | **envelope 净化剩余三洞**（全角冒号已修✓——response.go:53 分隔符已扩 ["失败:","失败："]）：① 17 处无冒号/紧贴拼接调用截断不可命中（api.go:137,156、authority.go 9 处、menu.go:170,178,198、user.go:150），非黑名单错误原样透出；② **CodeError data 通道完全无净化**——payment TestProvider Stages[].Message 原始 err 随 data 到前端；③ 净化静默无日志（"不泄露也不可排障"）。另有误伤：宽泛词 marker+约 45 处截断吞 biz 可读提示——需统一错误模型+结构化 Data 脱敏+日志策略 | server/httpx/response.go:32-59；data/payment/payment.go:79-139 | 六轮发现，专项 | -| V-19 | **证书别名缺口仍在（三层同源✓但键表未补别名——"已纳入键表"声称不实）**：app_cert_content/root_cert_content/pkcs12_content/cert_content/key_content/cert_path 等仍不命中 IsIntegrationSecretKey（后缀表无 *_content/*_path 项，integration_config.go:402-413）→ API 直连提交明文落库并回显，日志 resp_data 同泄；修法：剥后缀匹配词干或显式枚举（勿用裸 content/path 后缀防误伤） | biz/integration/integration_config.go:402-413,329-332,427-435 | 六轮发现，十轮部分+十一轮复核未闭合 | -| ~~V-30~~ | ~~douyin `platform_serial_no` required 标记与别名校验不一致~~：字段已标记 required，支付 required 校验同时识别 `platform_cert_serial` 别名 | ~~biz/integration/integration_config_definition.go；integration_config.go~~ | ~~十一轮复核~~ | -| V-38 | 媒体域裸错误（ErrMediaTooLarge/ErrUploadSessionNotFound）vs AGENTS typed errors 契约——需连同错误码表与 HTTP 映射一起迁移 | biz/system/media.go:52、media_upload.go:21 | 十轮发现，专项 | - -### 待修（正确性缺陷） - -| # | 问题 | 位置 | 状态 | -|---|------|------|------| -| ~~V-40~~ | ~~上传会话 TTL 未按最后活动时间刷新~~：每次分片写入后同步更新上传会话 `updated_at` | ~~data/system/media_upload.go~~ | ~~十一轮~~ | -| V-41 | （新发现，中低）merging 仅 1h 宽限（data:129），远程存储 Compose 超 1h 的合法合并被清理并整体失败（有回滚无泄漏，功能误杀） | data/system/media_upload.go:129 | 十一轮 | -| V-42 | **（新发现，中）dataScopeAuditWriter.Close 无超时且 MySQL DSN 无网络超时**：Close 无限期 `<-w.done`（:67-73）、flush 用 context.Background 无 deadline（:88）、DSN 无 readTimeout/writeTimeout（config.yaml:9,15）——DB 故障时 cleanup 链（data.go:191-198 先 auditLog.Close 后关 DB）被挂起 flush 永久阻塞，进程无法优雅退出 | data/data_scope_audit.go:67-73,88；configs/config.yaml:9,15 | 十一轮 | -| V-43 | **（新发现，中）前端 token 存 localStorage（7 天长期凭证 XSS 可窃）+ 401 登出回调可被并发弹窗吞掉**（application/index.vue:16 已有弹窗时 show-error 被忽略、handleClose 置 null cb 不执行 → 401 后 token 残留循环） | web/src/pinia/modules/user.js:23；components/application/index.vue:16；utils/request.js:231-241 | 十一轮 | -| ~~V-44~~ | ~~V-36 词表收窄导致“导出token无效或已过期”不再命中~~：已补充 `token无效` 匹配 | ~~middleware/error_audit.go~~ | ~~十一轮~~ | -| ~~V-45~~ | ~~sysError 写路径失败无日志~~：创建失败时已记录结构化错误日志 | ~~server/handler/audit.go~~ | ~~十一轮~~ | -| V-46 | （新发现，低）调度器启动重试无上限无退避：永久性错误（cron 解析失败整批 return err，task_scheduler.go:204-207）会每 5s 重试永不成功+刷 Warn 日志（约 720 条/小时）——需区分永久/暂时性错误 | worker/task_scheduler.go:93-112,204-207 | 十一轮（V-35 修复残留） | -| V-47 | （新发现，低）PersistRuntimeConfig 三段写非原子（先 storage 再 email 再 config，任一失败返回）——前面已写的集成配置与未替换的 runtime 出现不一致窗口 | data/initialization_backend.go:74-83 | 十一轮 | -| V-31 残留 | UpdateMediaName 仍透传 gorm 原文（404 语义丢失） | data/system/media.go:125-127 | 九轮，部分修复 | - -## 二、死代码与碎屑 - -| # | 问题 | 位置 | 状态 | -|---|------|------|------| -| Z-15 | 软删字段死重量（4 个 PO 的 DeletedAt+索引在删除路径全 Unscoped 后成死配置）——存量表结构清理需迁移与回滚策略，待数据库迁移窗口 | data/system/media.go:16,34；media_upload.go:17,35,104 | 九轮，专项 | -| Z-9 | audit.go:76/83 ctxRespTextKey/ctxRespTruncatedKey 消费分支生产链路不可达（后置键）；access_log 先对截断体完整脱敏再覆盖（白做功）——需连同响应捕获链路整体重构 | server/middleware/audit.go:76-85；access_log.go:110-121 | 八轮，专项 | -| Z-13 残留 | cors.go:13-14 逗号空格、audit.go:104 单行 13 字段、audit.go:46-47 空 else-if——纯格式问题（用户评估：格式化工具统一处理） | server/middleware/ | 八轮，评估暂缓 | -| Z-17 | scanUpload.vue 空 catch 吞路由就绪异常——需统一前端错误上报 | web/src/view/media/scanUpload.vue:115-116 | 九轮，专项 | -| Z-22 | （新发现）Z-19 清理后前端死代码残留：image.js:32-35 空 if 块+未使用 newImgSize；global.js:51,54 未使用 allKeys+悬空比较表达式；另 3 处已注释 console 代码（cropper.vue:198、upload.vue:363、menus.vue:302） | web/src/utils/image.js:32-35；core/global.js:51,54 | 十一轮 | -| ~~Z-23~~ | ~~douyin 别名分支放错校验器~~：已移除通信校验器中的不可达分支，别名逻辑归入支付校验器 | ~~biz/integration/integration_config.go~~ | ~~十一轮~~ | -| Z-24 | （新发现）秒传分支变量名 `copy` 遮蔽内置函数（可读性） | biz/system/media_upload.go:100 | 十一轮 | - -## 三、重复实现 / 双轨残留 - -| # | 问题 | 位置 | 状态 | -|---|------|------|------| -| Y-7 | 掩码三套实现+键表多层漂移（data Secret∪IsIntegrationSecretKey / service 仅后者 / redact.go 第四张表）；哨兵双轨（****** vs ***）——需先定义跨层协议（专项） | data/integration:225-245；service/integration:69-96；redact.go:18-27 | 九轮，专项 | -| Y-12 | **（新发现，中低）redact 键表误伤非机密标识符，审计记录失去回放价值**：redact.go:22 精确项 "key"、:24-25 platformserialno/webhookid 是序列号/ID 非秘密——实证误伤 dto/menu.go:26,90（菜单路由 key）、dto/media.go:15,76（存储 key）、settings.go:45,56,117、version.go:39，这些写接口的操作审计响应中 key 全为 `***`，菜单/媒体/设置类审计基本无法回放排障（安全无泄漏，可用性受损） | server/middleware/redact.go:22,24-25；dto/menu.go:26 等 | 十一轮 | -| Y-5 | 集成配置校验双重执行（biz 层对掩码值总通过半失效）——用户评估：分层防线保留 | biz/integration:122-129 | 八轮，评估保留 | -| Y-2 剩余 | capture.go JSON 成功路径先 marshal 后判超限（超长白做）——用户评估：安全优先保留现状 | middleware/capture.go:49-76 | 六轮，评估保留 | -| Y-10 | 前端两套动态路由注册逻辑（登录整树 vs 守卫扁平化+redirect）——需先补路由矩阵测试 | web/src/pinia/modules/user.js:85-87；permission.js:78-146 | 十轮，专项 | - -## 四、文档漂移 - -| # | 问题 | 位置 | 状态 | -|---|------|------|------| -| F-37 | **CLAUDE.md:19 integration 描述仍为 "(cache, email, payment, storage)" 4 项（"已同步"声称不实——实际目录 8 个模块，AGENTS.md 版本已含全部）** | CLAUDE.md:19 | 十轮发现，声称不实 | -| F-39 | （新，微）根 README.md:7-18 目录树缺 internal/{integration,modules,paymentkit,routecatalog,logging,utils} 与 pkg/（AGENTS.md 为权威无错，README 属简化版） | README.md:7-18 | 十一轮 | - -## 处置建议（按优先级） - -1. **V-39 公开写接口治理**（限流覆盖/长度 binding/或移入鉴权组——安全优先）+ **V-44/V-45 ErrorAudit 噪音与盲区**（词表补导出 token 文案或改 4xx；CreateError 失败补日志） -2. **V-40 TTL 改活动时间**（UpsertChunk touch 会话 updated_at——一行修复）+ **V-42 Close/DSN 超时** + **V-46 重试上限/退避** -3. **V-19 键表补别名**（剥后缀匹配词干——一处三层受益；连带 Z-23 死分支归位）+ **V-30 douyin required**（通用循环感知别名后置 true） -4. **V-43 前端凭证**（401 回调修复+token 存储评估）+ **F-37 一行同步**（本轮声称不实项） -5. **V-41/V-47/V-31 残留 + Z-22/23/24 碎屑 + Y-12 redact 误伤面收敛**（与 Y-7 专项一并设计） -6. **专项批次**：V-15 错误模型统一、V-33 指纹兼容窗口、V-24 分布式锁、V-13b 单一判定函数、V-27 稳定标识、V-20 短时票据、V-38 错误码迁移、Z-15 迁移窗口、Z-9 响应链重构、Y-7 跨层协议、Y-10 路由矩阵