# User Migration Delivery Plan ## 背景 当前 `feat-overseas-user-migration` worktree 已经完成海外用户迁移主链路实现,并补齐了: - 模型层迁移表与状态机 - 海外内部迁移接口 - 国内管理端迁移 API - 迁移中心前端 - 单元测试 / 控制器测试 / 路由测试 - API E2E - Playwright UI E2E 本计划的目标不是继续扩功能,而是把当前能力收口到“可交付、可审阅、可部署”的状态。 ## 当前已验证通过的内容 以下能力已经通过真实测试验证: - `go test ./service/user_migration/... -v` - `go test ./controller -run "Test.*Migration|Test.*Synced" -v` - `go test ./model -run "Test.*Migration|Test.*Synced" -v` - `go test ./router -run "TestUserMigrationRoutes" -v` - `go test -v ./test/e2e -count=1` - `cd web && bunx playwright test e2e/user-migration.spec.ts` - `powershell -NoProfile -ExecutionPolicy Bypass -File scripts/run-user-migration-e2e.ps1 -All` 这些验证已经覆盖: - 扫描层冲突分析 - create_new / merge / skip - fast path 恢复与 drift - root-only 访问控制 - verify 聚合结果 - 内部迁移 API 边界 - UI 迁移中心主流程 ## 剩余工作目标 把当前 worktree 收敛为: 1. 改动范围清晰 2. 非主线噪音最小 3. 文档完整 4. 提交路径明确 ## 需要处理的剩余事项 ### 1. 清理非主线前端脏 diff 当前与迁移主线无强耦合、但会影响审阅质量的内容: - `web/src/i18n/locales/en.json` - `web/src/pages/Setting/Ratio/ModelRationNotSetEditor.jsx` 目标: - 只保留本轮确有必要的改动 - 避免大面积格式化/编码噪音 - 确保 `bun run build` 继续通过 ### 2. 产出测试覆盖矩阵文档 新增一份文档,明确: - 迁移功能需求点 - 对应自动化测试名 - 测试层级(unit / controller / router / api-e2e / ui-e2e) 建议文件: - `docs/testing/user-migration-test-matrix.md` ### 3. 收敛提交范围 建议把当前 worktree 的改动按下面 3 组看待: #### A. 核心后端与测试 - `model/*migration*` - `service/user_migration/*` - `controller/internal_user_migration*` - `controller/user_migration*` - `router/user_migration_router_test.go` #### B. 前端迁移中心 - `web/src/components/table/users/migration/*` - `web/src/hooks/users/useUserMigrationData.jsx` - `web/src/pages/User/index.jsx` - `web/e2e/*` - `web/playwright.config.ts` #### C. E2E 基础设施与文档 - `test/e2e/*` - `scripts/run-user-migration-e2e.ps1` - `docs/testing/*` ### 4. 最终交付前整体验证 在准备提交前至少再次执行: ```bash go test ./service/user_migration/... -v go test ./controller -run "Test.*Migration|Test.*Synced" -v go test ./model -run "Test.*Migration|Test.*Synced" -v go test ./router -run "TestUserMigrationRoutes" -v go test -v ./test/e2e -count=1 cd web && bun run build cd web && bunx playwright test e2e/user-migration.spec.ts ``` ## 建议执行顺序 1. 清理 `en.json` 和 `ModelRationNotSetEditor.jsx` 2. 产出测试覆盖矩阵文档 3. 再跑一轮最终回归 4. 审查 `git diff --stat` 5. 进入提交阶段 ## 完成标准 只有同时满足以下条件,才算本轮迁移能力真正收尾: - 迁移主链路代码无新增功能性缺口 - Go 测试、API E2E、UI E2E 全绿 - worktree 中无明显无关脏改动 - 测试覆盖矩阵可供审阅 - 提交范围已经可清晰切分