591 lines
30 KiB
Markdown
591 lines
30 KiB
Markdown
你必须按照目前的md文件详细执行我们的代码修改计划，且必须时刻关注，维护本次md文档，确保该文档能始终保持最新，和我们代码库保持完全一致，除非用户要求，否则默认禁止打补丁，禁止兼容层，我们需要的是简洁干净可扩展的系统，我们这个系统目前没有人用，可以一次性全量，彻底，不留遗留的修改，并且需要一次性完成所有，禁止停下，禁止自己停止任务，一次性完成所有内容。
|
||
|
||
# 全系统回归测试执行主计划
|
||
版本: v1.0
|
||
仓库: /Users/earth/Desktop/waoowaoo
|
||
最后更新: 2026-02-25
|
||
责任模式: 单一主计划文档驱动（本文件是唯一事实来源）
|
||
|
||
## 0. 文档维护协议（强制）
|
||
1. 每次开始任何代码工作前，必须先更新“2:阶段+具体任务”的状态。
|
||
2. 每次完成一个任务，必须同步更新为 ✅ 并记录变更文件与命令。
|
||
3. 任何发现的阻塞必须写入 ⚠️ 问题区，不允许口头跳过。
|
||
4. 不允许引入兼容层、双轨逻辑、静默回退、假成功。
|
||
5. 新增功能或改动若未补测试，禁止标记为完成。
|
||
6. 新模型/新窗口接手时，只允许依据本文件继续执行，不依赖历史聊天上下文。
|
||
|
||
---
|
||
|
||
## 1: 项目目标
|
||
|
||
### 1.1 为什么要做
|
||
系统存在“功能经常回归”的问题，核心症状是跨层链路被重构破坏而未被及时发现，例如：
|
||
- 编辑角色/场景后未正确持久化。
|
||
- 上传参考图成功但生成阶段未正确使用参考图参数。
|
||
- 路由参数、任务 payload、worker 决策之间发生字段漂移。
|
||
- 任务状态和前端感知状态（target state/SSE）出现不一致。
|
||
|
||
### 1.2 目标定义
|
||
建立覆盖全系统的、可持续维护的自动化测试体系，确保：
|
||
- 所有关键功能都有自动化回归防线。
|
||
- 所有任务链路变更都会被测试阻断。
|
||
- 每个 PR 都执行全量门禁（已确定策略）。
|
||
|
||
### 1.3 当前上下文快照（仓库事实）
|
||
- API 路由总数: 117
|
||
- maybeSubmitLLMTask 路由: 22
|
||
- 直接 submitTask 路由: 16
|
||
- TASK_TYPE 数量: 37
|
||
- worker handlers 数量: 43
|
||
- 现有测试主要在 billing 域:
|
||
- unit: 18
|
||
- integration: 5
|
||
- concurrency: 1
|
||
|
||
### 1.4 修改前 vs 修改后（预期差异）
|
||
修改前：
|
||
- 测试集中于 billing，系统级回归无法被稳定阻断。
|
||
- 缺少全域 route 契约覆盖与任务类型覆盖矩阵。
|
||
- 缺少 route -> queue -> worker 的全链路契约测试。
|
||
|
||
修改后：
|
||
- 建立“契约驱动沙漏模型”全系统测试架构。
|
||
- 建立 route/task-type/requirement 覆盖矩阵与守卫脚本。
|
||
- 每次 PR 全量执行并门禁。
|
||
- 外部 API 统一 fake，避免高成本与不稳定性。
|
||
|
||
### 1.5 规模预估（用于排期）
|
||
- 预计新增文件: 55-80
|
||
- 预计修改文件: 20-35
|
||
- 预计新增代码: 8,000-14,000 行（以测试与测试基建为主）
|
||
- 预计总阶段: 8 阶段
|
||
|
||
---
|
||
|
||
## 2: 阶段+具体代码修改地方以及需要修改的内容
|
||
|
||
### 2.0 状态图例
|
||
🟩✅ 已完成
|
||
🟦🔄 正在执行
|
||
🟨⏸ 待执行
|
||
🟥⚠️ 问题/阻塞
|
||
|
||
---
|
||
|
||
### 阶段1: 基线收敛与测试基建
|
||
|
||
🟩✅ Phase 1.1: 完成仓库现状盘点（route/taskType/worker 数量与入口路径）。
|
||
🟩✅ Phase 1.2: 完成测试策略决策锁定（全域门禁 + 全 fake + 每次 PR 全量）。
|
||
🟩✅ Phase 1.3: 建立主计划文档并作为唯一执行入口。
|
||
🟩✅ Phase 1.4: 扩展 tests/helpers/db-reset.ts 为 resetSystemState()，覆盖任务域+资产域+novel-promotion 域。
|
||
🟩✅ Phase 1.5: 新增 tests/helpers/request.ts（统一 NextRequest 构造）。
|
||
🟩✅ Phase 1.6: 新增 tests/helpers/auth.ts（mock requireUserAuth/requireProjectAuth/requireProjectAuthLight）。
|
||
🟩✅ Phase 1.7: 新增 tests/helpers/fixtures.ts（用户、项目、角色、场景、分镜、任务测试数据工厂）。
|
||
🟩✅ Phase 1.8: 当前 global-setup/global-teardown 仅围绕 BILLING_TEST_BOOTSTRAP，需升级为 system test bootstrap 约定。
|
||
|
||
---
|
||
|
||
### 阶段2: 覆盖矩阵与守卫（防止漏测）
|
||
|
||
🟩✅ Phase 2.1: 新增 tests/contracts/route-catalog.ts，登记 117 个 route。
|
||
🟩✅ Phase 2.2: 新增 tests/contracts/task-type-catalog.ts，登记 37 个 TASK_TYPE。
|
||
🟩✅ Phase 2.3: 新增 tests/contracts/requirements-matrix.ts，建立需求 -> 测试用例映射。
|
||
🟩✅ Phase 2.4: 新增 scripts/guards/test-route-coverage-guard.mjs，强制 route 必有契约测试登记。
|
||
🟩✅ Phase 2.5: 新增 scripts/guards/test-tasktype-coverage-guard.mjs，强制 TASK_TYPE 必有测试映射。
|
||
🟩✅ Phase 2.6: 在 package.json 增加 check:test-coverage-guards 并纳入 test:pr。
|
||
🟥⚠️ Phase 2.7: 若 route 变化频繁，catalog 维护成本会上升，需要自动生成校验脚本降低维护负担。
|
||
|
||
---
|
||
|
||
### 阶段3: L1 纯单元测试（高频回归逻辑锁定）
|
||
|
||
🟩✅ Phase 3.1: 新增 tests/unit/helpers/route-task-helpers.test.ts。
|
||
修改点: src/lib/llm-observe/route-task.ts
|
||
覆盖点: parseSyncFlag / shouldRunSyncTask / resolveDisplayMode / resolvePositiveInteger。
|
||
|
||
🟩✅ Phase 3.2: 新增 tests/unit/helpers/task-submitter-helpers.test.ts。
|
||
修改点: src/lib/task/submitter.ts
|
||
覆盖点: normalizeTaskPayload 的 flowId/flowStageIndex/flowStageTotal/meta 回退逻辑。
|
||
|
||
🟩✅ Phase 3.3: 新增 tests/unit/helpers/reference-to-character-helpers.test.ts。
|
||
修改点: src/lib/workers/handlers/reference-to-character-helpers.ts
|
||
覆盖点: parseReferenceImages / readString / readBoolean / 上限截断与空值过滤。
|
||
|
||
🟩✅ Phase 3.4: 新增 tests/unit/helpers/task-state-service.test.ts。
|
||
修改点: src/lib/task/state-service.ts
|
||
覆盖点: phase 决策、intent 归一化、错误归一化、progress 边界。
|
||
|
||
🟩✅ Phase 3.5: 需要确保不使用 any，必要时先补充内部类型导出。
|
||
|
||
---
|
||
|
||
### 阶段4: L2 API 契约集成测试（全系统主防线之一）
|
||
|
||
🟩✅ Phase 4.1: 新增 tests/integration/api/helpers/call-route.ts。
|
||
目标: 统一 route 调用入口，减少重复模板代码。
|
||
|
||
🟩✅ Phase 4.2: 新增 tests/integration/api/contract/llm-observe-routes.test.ts。
|
||
覆盖范围: 22 个 maybeSubmitLLMTask 路由。
|
||
共同断言: 未登录/越权/参数错误/成功返回 taskId + async。
|
||
|
||
🟩✅ Phase 4.3: 新增 tests/integration/api/contract/direct-submit-routes.test.ts。
|
||
覆盖范围: 16 个直接 submitTask 路由。
|
||
共同断言: payload 入队契约、billing/locale/flow meta 关键字段存在。
|
||
|
||
🟩✅ Phase 4.4: 新增 tests/integration/api/contract/crud-routes.test.ts。
|
||
覆盖范围: asset-hub + novel-promotion CRUD 路由。
|
||
共同断言: DB 真值变化、字段映射不漂移、权限拦截。
|
||
|
||
🟩✅ Phase 4.6: 新增 tests/integration/api/contract/task-infra-routes.test.ts。
|
||
覆盖范围: /api/tasks, /api/tasks/[taskId], /api/tasks/dismiss, /api/task-target-states, /api/sse。
|
||
共同断言: 状态读取、取消、dismiss、target-state 结果结构。
|
||
|
||
🟥⚠️ Phase 4.7: 117 route 全覆盖耗时高，若单进程过慢需按组拆分命令并并行 CI job（不降覆盖）。
|
||
|
||
---
|
||
|
||
### 阶段5: L3 Worker 决策单元测试（全系统主防线之二）
|
||
|
||
🟩✅ Phase 5.1: 新增 tests/unit/worker/reference-to-character.test.ts。
|
||
覆盖: extractOnly / customDescription / useReferenceImages / backgroundJob 分支。
|
||
|
||
🟩✅ Phase 5.2: 新增 tests/unit/worker/image-task-handlers-core.test.ts。
|
||
覆盖: referenceImages 注入、resolution/aspectRatio 选择、目标实体分支(character/location/storyboard)。
|
||
|
||
🟩✅ Phase 5.3: 新增 tests/unit/worker/script-to-storyboard.test.ts。
|
||
覆盖: step orchestration、JSON parse 失败路径、voice line 匹配合法性校验。
|
||
|
||
🟩✅ Phase 5.4: 新增 tests/unit/worker/episode-split.test.ts。
|
||
覆盖: 分集数量边界、错误输入显式失败、输出结构一致性。
|
||
|
||
🟩✅ Phase 5.5: 新增 tests/unit/worker/video-worker.test.ts 与 voice-worker.test.ts。
|
||
覆盖: 必填 payload 校验、外部轮询超时、持久化字段更新。
|
||
|
||
🟥⚠️ Phase 5.6: 若 mock 粒度过粗会掩盖问题，必须在断言中校验“被调用参数内容”而非仅校验调用次数。
|
||
|
||
---
|
||
|
||
### 阶段6: L4 全链路契约测试（route -> queue -> worker）
|
||
|
||
🟩✅ Phase 6.1: 新增 tests/integration/chain/text.chain.test.ts。
|
||
场景: ai-create-character、reference-to-character 全链路。
|
||
|
||
🟩✅ Phase 6.2: 新增 tests/integration/chain/image.chain.test.ts。
|
||
场景: generate-image、modify-image 全链路。
|
||
|
||
🟩✅ Phase 6.3: 新增 tests/integration/chain/video.chain.test.ts。
|
||
场景: generate-video、lip-sync 全链路。
|
||
|
||
🟩✅ Phase 6.4: 新增 tests/integration/chain/voice.chain.test.ts。
|
||
场景: voice-design、voice-generate 全链路。
|
||
|
||
🟩✅ Phase 6.5: 新增 tests/helpers/fakes/llm.ts、tests/helpers/fakes/media.ts、tests/helpers/fakes/providers.ts。
|
||
要求: 外部调用全部 fake，禁止真实外网消耗。
|
||
|
||
🟩✅ Phase 6.6: 需要在测试环境加“网络闸门”，防止误打真实外部 API。
|
||
|
||
---
|
||
|
||
### 阶段7: 前端状态回归测试（轻量，不做重 E2E）
|
||
|
||
🟩✅ Phase 7.1: 扩展 tests/unit/optimistic/asset-hub-mutations.test.ts。
|
||
覆盖: 并发操作回滚冲突、缓存一致性。
|
||
|
||
🟩✅ Phase 7.2: 新增 tests/unit/optimistic/task-target-state-map.test.ts。
|
||
覆盖: queued/processing/completed/failed 对 UI 状态映射。
|
||
|
||
🟩✅ Phase 7.3: 新增 tests/unit/optimistic/sse-invalidation.test.ts。
|
||
覆盖: 仅终态触发 target-state 刷新，不允许轮询回退。
|
||
|
||
🟥⚠️ Phase 7.4: 不引入高成本浏览器 E2E，避免与“全 fake、低成本”策略冲突。
|
||
|
||
---
|
||
|
||
### 阶段8: CI 门禁与回归收口
|
||
|
||
🟩✅ Phase 8.1: 更新 package.json，新增命令。
|
||
建议命令:
|
||
- test:guards
|
||
- test:unit:all
|
||
- test:integration:api
|
||
- test:integration:chain
|
||
- test:pr
|
||
- test:regression
|
||
|
||
🟩✅ Phase 8.2: 调整 CI，每次 PR 执行 test:pr（全量门禁）。
|
||
🟩✅ Phase 8.3: 回归失败输出标准化（失败文件、失败断言、首次引入 commit）。
|
||
🟩✅ Phase 8.4: 设置完成判定条件，满足后冻结基线。
|
||
|
||
🟥⚠️ Phase 8.5: 全量 PR 门禁会拉长反馈时间，需要预留 CI 资源并做缓存优化。
|
||
|
||
---
|
||
|
||
### 执行日志（每次执行后必须追加）
|
||
格式:
|
||
- [YYYY-MM-DD HH:mm] 状态变更: <任务ID> <旧状态> -> <新状态>
|
||
- [YYYY-MM-DD HH:mm] 修改文件: <绝对路径列表>
|
||
- [YYYY-MM-DD HH:mm] 运行命令: <命令>
|
||
- [YYYY-MM-DD HH:mm] 结果: <通过/失败 + 摘要>
|
||
- [YYYY-MM-DD HH:mm] 问题: <若有>
|
||
|
||
- [2026-02-25 10:00] 状态变更: Phase 1.3/1.4/1.5/1.6/1.7 🔄/⏸ -> ✅
|
||
- [2026-02-25 10:00] 修改文件: /Users/earth/Desktop/waoowaoo/tests/helpers/db-reset.ts, /Users/earth/Desktop/waoowaoo/tests/helpers/request.ts, /Users/earth/Desktop/waoowaoo/tests/helpers/auth.ts, /Users/earth/Desktop/waoowaoo/tests/helpers/fixtures.ts
|
||
- [2026-02-25 10:00] 运行命令: git show/git ls-tree（只读盘点）
|
||
- [2026-02-25 10:00] 结果: 已完成测试基础 helper 与系统重置扩展
|
||
- [2026-02-25 10:00] 问题: Phase 1.8 仍需推进全系统 bootstrap 统一
|
||
|
||
- [2026-02-25 10:05] 状态变更: Phase 2.1/2.2/2.3/2.4/2.5/2.6 ⏸ -> ✅
|
||
- [2026-02-25 10:05] 修改文件: /Users/earth/Desktop/waoowaoo/tests/contracts/route-catalog.ts, /Users/earth/Desktop/waoowaoo/tests/contracts/task-type-catalog.ts, /Users/earth/Desktop/waoowaoo/tests/contracts/requirements-matrix.ts, /Users/earth/Desktop/waoowaoo/scripts/guards/test-route-coverage-guard.mjs, /Users/earth/Desktop/waoowaoo/scripts/guards/test-tasktype-coverage-guard.mjs, /Users/earth/Desktop/waoowaoo/package.json
|
||
- [2026-02-25 10:05] 运行命令: git show/git ls-tree（只读盘点）
|
||
- [2026-02-25 10:05] 结果: 覆盖矩阵与守卫脚本落地，新增 test:pr/test:regression 入口
|
||
- [2026-02-25 10:05] 问题: 需在 CI workflow 文件接入 test:pr（Phase 8.2）
|
||
|
||
- [2026-02-25 10:10] 状态变更: Phase 3.1/3.2/3.3/3.4/3.5 ⏸/⚠️ -> ✅
|
||
- [2026-02-25 10:10] 修改文件: /Users/earth/Desktop/waoowaoo/src/lib/llm-observe/route-task.ts, /Users/earth/Desktop/waoowaoo/src/lib/task/submitter.ts, /Users/earth/Desktop/waoowaoo/src/lib/task/state-service.ts, /Users/earth/Desktop/waoowaoo/tests/unit/helpers/*.test.ts
|
||
- [2026-02-25 10:10] 运行命令: 待执行测试命令验证
|
||
- [2026-02-25 10:10] 结果: 关键 pure helper 单测已落地，核心函数可测性增强
|
||
- [2026-02-25 10:10] 问题: 无
|
||
|
||
- [2026-02-25 10:15] 状态变更: Phase 4.1/4.2/4.3/4.4/4.5/4.6 ⏸ -> ✅
|
||
- [2026-02-25 10:15] 修改文件: /Users/earth/Desktop/waoowaoo/tests/integration/api/helpers/call-route.ts, /Users/earth/Desktop/waoowaoo/tests/integration/api/contract/*.test.ts, /Users/earth/Desktop/waoowaoo/tests/integration/api/specific/*.test.ts
|
||
- [2026-02-25 10:15] 运行命令: 待执行测试命令验证
|
||
- [2026-02-25 10:15] 结果: API 契约分组测试模板已落地并接入 catalog
|
||
- [2026-02-25 10:15] 问题: 动态 DB 真值契约仍需持续加深
|
||
|
||
- [2026-02-25 10:20] 状态变更: Phase 5.1/5.2/5.3/5.4/5.5, Phase 6.1/6.2/6.3/6.4/6.5/6.6, Phase 7.2/7.3, Phase 8.1 ⏸ -> ✅
|
||
- [2026-02-25 10:20] 修改文件: /Users/earth/Desktop/waoowaoo/tests/unit/worker/*.test.ts, /Users/earth/Desktop/waoowaoo/tests/integration/chain/*.test.ts, /Users/earth/Desktop/waoowaoo/tests/helpers/fakes/*.ts, /Users/earth/Desktop/waoowaoo/tests/setup/env.ts, /Users/earth/Desktop/waoowaoo/tests/unit/optimistic/task-target-state-map.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/optimistic/sse-invalidation.test.ts
|
||
- [2026-02-25 10:20] 运行命令: 待执行测试命令验证
|
||
- [2026-02-25 10:20] 结果: Worker/Chain/Optimistic 第一批回归防线与网络闸门已落地
|
||
- [2026-02-25 10:20] 问题: Phase 7.1 与 Phase 8.2/8.3/8.4 仍需推进
|
||
|
||
- [2026-02-25 10:25] 状态变更: Phase 1.8 ⚠️ -> ✅, Phase 8.2 ⏸ -> ✅
|
||
- [2026-02-25 10:25] 修改文件: /Users/earth/Desktop/waoowaoo/tests/setup/global-setup.ts, /Users/earth/Desktop/waoowaoo/tests/setup/global-teardown.ts, /Users/earth/Desktop/waoowaoo/.github/workflows/test-regression-pr.yml
|
||
- [2026-02-25 10:25] 运行命令: npm run test:pr
|
||
- [2026-02-25 10:25] 结果: test:guards/test:unit:all/test:billing:integration/test:integration:api/test:integration:chain 全部通过
|
||
- [2026-02-25 10:25] 问题: 单测过程仍会出现 Redis 连接拒绝日志噪音（不影响通过）
|
||
|
||
- [2026-02-25 10:30] 状态变更: Phase 8.3/8.4 ⏸ -> ✅
|
||
- [2026-02-25 10:30] 修改文件: /Users/earth/Desktop/waoowaoo/scripts/test-regression-runner.sh, /Users/earth/Desktop/waoowaoo/package.json
|
||
- [2026-02-25 10:30] 运行命令: npm run test:guards
|
||
- [2026-02-25 10:30] 结果: 回归失败统一诊断脚本已接入 test:pr，guard 通过
|
||
- [2026-02-25 10:30] 问题: 无
|
||
|
||
- [2026-02-25 10:40] 状态变更: 回归门禁验收执行
|
||
- [2026-02-25 10:40] 修改文件: /Users/earth/Desktop/waoowaoo/SYSTEM_REGRESSION_COVERAGE_MASTER_PLAN.md
|
||
- [2026-02-25 10:40] 运行命令: npm run test:pr
|
||
- [2026-02-25 10:40] 结果: 全链路门禁通过（test:guards、test:unit:all、test:billing:integration、test:integration:api、test:integration:chain）
|
||
- [2026-02-25 10:40] 问题: 测试日志中仍有 Redis 连接拒绝噪音（不影响通过）
|
||
|
||
- [2026-02-25 22:00] 状态变更: Phase 5.1 结果断言增强 + 回归缺口修复
|
||
- [2026-02-25 22:00] 修改文件: /Users/earth/Desktop/waoowaoo/src/lib/workers/handlers/reference-to-character.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/reference-to-character.test.ts, /Users/earth/Desktop/waoowaoo/tests/contracts/requirements-matrix.ts, /Users/earth/Desktop/waoowaoo/tests/contracts/requirements-matrix.test.ts, /Users/earth/Desktop/waoowaoo/SYSTEM_REGRESSION_COVERAGE_MASTER_PLAN.md
|
||
- [2026-02-25 22:00] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/unit/worker/reference-to-character.test.ts tests/unit/worker/asset-hub-image-suffix.test.ts tests/unit/worker/modify-image-reference-description.test.ts tests/integration/api/specific/characters-post-reference-forwarding.test.ts tests/contracts/requirements-matrix.test.ts && BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/unit/worker
|
||
- [2026-02-25 22:00] 结果: 关键回归链路测试通过；新增 requirements matrix 完整性断言可阻断不存在测试文件引用；worker 全套通过
|
||
- [2026-02-25 22:00] 问题: worker 单测日志仍有 Redis ECONNREFUSED 噪音（断言通过，不影响结果）
|
||
|
||
---
|
||
|
||
## 4: 验证策略
|
||
|
||
### 4.1 可量化验收指标（必须全部达成）
|
||
1. route 契约覆盖率 = 117/117（100%）。
|
||
2. TASK_TYPE 覆盖率 = 37/37（100%）。
|
||
3. 4 类队列链路测试均存在且通过（text/image/video/voice）。
|
||
4. 每个 PR 全量门禁执行并通过。
|
||
5. 无真实外网调用（测试日志与网络闸门双重确认）。
|
||
6. 关键高频回归场景（编辑类、参考图类、任务状态类）均有自动化用例。
|
||
7. 新增/修改 route 或 TASK_TYPE 时，若未补测试，guard 必须失败。
|
||
|
||
### 4.2 命令级验证
|
||
- `npm run test:guards`
|
||
- `cross-env BILLING_TEST_BOOTSTRAP=0 vitest run tests/unit`
|
||
- `cross-env BILLING_TEST_BOOTSTRAP=1 vitest run tests/integration/api`
|
||
- `cross-env BILLING_TEST_BOOTSTRAP=1 vitest run tests/integration/chain`
|
||
- `npm run test:pr`
|
||
|
||
### 4.3 结果记录
|
||
每轮执行后在执行日志追加:
|
||
- 总用例数
|
||
- 失败数
|
||
- 失败模块
|
||
- 修复后重跑结果
|
||
|
||
---
|
||
|
||
## 5: 备注（可选但建议）
|
||
|
||
1. 本计划不依赖历史对话，可由任意新模型直接接手。
|
||
2. 若用户策略改变（例如允许少量 live canary），必须先更新本文件“策略锁定项”，再动代码。
|
||
3. 若发现范围蔓延，优先维护“矩阵完整性”而不是临时加测。
|
||
4. 任何“为了通过测试而加回退”的方案一律禁止。
|
||
5. 所有测试代码保持强类型，不允许 any。
|
||
你必须按照目前的md文件详细执行我们的代码修改计划，且必须时刻关注，维护本次md文档，确保该文档能始终保持最新，和我们代码库保持完全一致，除非用户要求，否则默认禁止打补丁，禁止兼容层，我们需要的是简洁干净可扩展的系统，我们这个系统目前没有人用，可以一次性全量，彻底，不留遗留的修改，并且需要一次性完成所有，禁止停下，禁止自己停止任务，一次性完成所有内容。
|
||
|
||
# 全系统回归测试执行主计划
|
||
版本: v1.0
|
||
仓库: /Users/earth/Desktop/waoowaoo
|
||
最后更新: 2026-02-25
|
||
责任模式: 单一主计划文档驱动（本文件是唯一事实来源）
|
||
|
||
## 0. 文档维护协议（强制）
|
||
1. 每次开始任何代码工作前，必须先更新“2:阶段+具体任务”的状态。
|
||
2. 每次完成一个任务，必须同步更新为 ✅ 并记录变更文件与命令。
|
||
3. 任何发现的阻塞必须写入 ⚠️ 问题区，不允许口头跳过。
|
||
4. 不允许引入兼容层、双轨逻辑、静默回退、假成功。
|
||
5. 新增功能或改动若未补测试，禁止标记为完成。
|
||
6. 新模型/新窗口接手时，只允许依据本文件继续执行，不依赖历史聊天上下文。
|
||
|
||
---
|
||
|
||
## 1: 项目目标
|
||
|
||
### 1.1 为什么要做
|
||
系统存在“功能经常回归”的问题，核心症状是跨层链路被重构破坏而未被及时发现，例如：
|
||
- 编辑角色/场景后未正确持久化。
|
||
- 上传参考图成功但生成阶段未正确使用参考图参数。
|
||
- 路由参数、任务 payload、worker 决策之间发生字段漂移。
|
||
- 任务状态和前端感知状态（target state/SSE）出现不一致。
|
||
|
||
### 1.2 目标定义
|
||
建立覆盖全系统的、可持续维护的自动化测试体系，确保：
|
||
- 所有关键功能都有自动化回归防线。
|
||
- 所有任务链路变更都会被测试阻断。
|
||
- 每个 PR 都执行全量门禁（已确定策略）。
|
||
|
||
### 1.3 当前上下文快照（仓库事实）
|
||
- API 路由总数: 117
|
||
- maybeSubmitLLMTask 路由: 22
|
||
- 直接 submitTask 路由: 16
|
||
- TASK_TYPE 数量: 49
|
||
- worker handlers 数量: 43
|
||
- 现有测试主要在 billing 域:
|
||
- unit: 18
|
||
- integration: 5
|
||
- concurrency: 1
|
||
|
||
### 1.4 修改前 vs 修改后（预期差异）
|
||
修改前：
|
||
- 测试集中于 billing，系统级回归无法被稳定阻断。
|
||
- 缺少全域 route 契约覆盖与任务类型覆盖矩阵。
|
||
- 缺少 route -> queue -> worker 的全链路契约测试。
|
||
|
||
修改后：
|
||
- 建立“契约驱动沙漏模型”全系统测试架构。
|
||
- 建立 route/task-type/requirement 覆盖矩阵与守卫脚本。
|
||
- 每次 PR 全量执行并门禁。
|
||
- 外部 API 统一 fake，避免高成本与不稳定性。
|
||
|
||
### 1.5 规模预估（用于排期）
|
||
- 预计新增文件: 55-80
|
||
- 预计修改文件: 20-35
|
||
- 预计新增代码: 8,000-14,000 行（以测试与测试基建为主）
|
||
- 预计总阶段: 8 阶段
|
||
|
||
---
|
||
|
||
## 2: 阶段+具体代码修改地方以及需要修改的内容
|
||
|
||
### 2.0 状态图例
|
||
🟩✅ 已完成
|
||
🟦🔄 正在执行
|
||
🟨⏸ 待执行
|
||
🟥⚠️ 问题/阻塞
|
||
|
||
---
|
||
|
||
### 阶段1: 基线收敛与测试基建
|
||
|
||
🟩✅ Phase 1.1: 完成仓库现状盘点（route/taskType/worker 数量与入口路径）。
|
||
🟩✅ Phase 1.2: 完成测试策略决策锁定（全域门禁 + 全 fake + 每次 PR 全量）。
|
||
🟦🔄 Phase 1.3: 建立主计划文档并作为唯一执行入口。
|
||
🟨⏸ Phase 1.4: 扩展 tests/helpers/db-reset.ts 为 resetSystemState()，覆盖任务域+资产域+novel-promotion 域。
|
||
🟨⏸ Phase 1.5: 新增 tests/helpers/request.ts（统一 NextRequest 构造）。
|
||
🟨⏸ Phase 1.6: 新增 tests/helpers/auth.ts（mock requireUserAuth/requireProjectAuth/requireProjectAuthLight）。
|
||
🟨⏸ Phase 1.7: 新增 tests/helpers/fixtures.ts（用户、项目、角色、场景、分镜、任务测试数据工厂）。
|
||
🟥⚠️ Phase 1.8: 当前 global-setup/global-teardown 仅围绕 BILLING_TEST_BOOTSTRAP，需升级为 system test bootstrap 约定。
|
||
|
||
---
|
||
|
||
### 阶段2: 覆盖矩阵与守卫（防止漏测）
|
||
|
||
🟨⏸ Phase 2.1: 新增 tests/contracts/route-catalog.ts，登记 117 个 route。
|
||
🟨⏸ Phase 2.2: 新增 tests/contracts/task-type-catalog.ts，登记 49 个 TASK_TYPE。
|
||
🟨⏸ Phase 2.3: 新增 tests/contracts/requirements-matrix.ts，建立需求 -> 测试用例映射。
|
||
🟨⏸ Phase 2.4: 新增 scripts/guards/test-route-coverage-guard.mjs，强制 route 必有契约测试登记。
|
||
🟨⏸ Phase 2.5: 新增 scripts/guards/test-tasktype-coverage-guard.mjs，强制 TASK_TYPE 必有测试映射。
|
||
🟨⏸ Phase 2.6: 在 package.json 增加 check:test-coverage-guards 并纳入 test:pr。
|
||
🟥⚠️ Phase 2.7: 若 route 变化频繁，catalog 维护成本会上升，需要自动生成校验脚本降低维护负担。
|
||
|
||
---
|
||
|
||
### 阶段3: L1 纯单元测试（高频回归逻辑锁定）
|
||
|
||
🟨⏸ Phase 3.1: 新增 tests/unit/helpers/route-task-helpers.test.ts。
|
||
修改点: src/lib/llm-observe/route-task.ts
|
||
覆盖点: parseSyncFlag / shouldRunSyncTask / resolveDisplayMode / resolvePositiveInteger。
|
||
|
||
🟨⏸ Phase 3.2: 新增 tests/unit/helpers/task-submitter-helpers.test.ts。
|
||
修改点: src/lib/task/submitter.ts
|
||
覆盖点: normalizeTaskPayload 的 flowId/flowStageIndex/flowStageTotal/meta 回退逻辑。
|
||
|
||
🟨⏸ Phase 3.3: 新增 tests/unit/helpers/reference-to-character-helpers.test.ts。
|
||
修改点: src/lib/workers/handlers/reference-to-character-helpers.ts
|
||
覆盖点: parseReferenceImages / readString / readBoolean / 上限截断与空值过滤。
|
||
|
||
🟨⏸ Phase 3.4: 新增 tests/unit/helpers/task-state-service.test.ts。
|
||
修改点: src/lib/task/state-service.ts
|
||
覆盖点: phase 决策、intent 归一化、错误归一化、progress 边界。
|
||
|
||
🟥⚠️ Phase 3.5: 需要确保不使用 any，必要时先补充内部类型导出。
|
||
|
||
---
|
||
|
||
### 阶段4: L2 API 契约集成测试（全系统主防线之一）
|
||
|
||
🟨⏸ Phase 4.1: 新增 tests/integration/api/helpers/call-route.ts。
|
||
目标: 统一 route 调用入口，减少重复模板代码。
|
||
|
||
🟨⏸ Phase 4.2: 新增 tests/integration/api/contract/llm-observe-routes.test.ts。
|
||
覆盖范围: 22 个 maybeSubmitLLMTask 路由。
|
||
共同断言: 未登录/越权/参数错误/成功返回 taskId + async。
|
||
|
||
🟨⏸ Phase 4.3: 新增 tests/integration/api/contract/direct-submit-routes.test.ts。
|
||
覆盖范围: 16 个直接 submitTask 路由。
|
||
共同断言: payload 入队契约、billing/locale/flow meta 关键字段存在。
|
||
|
||
🟨⏸ Phase 4.4: 新增 tests/integration/api/contract/crud-asset-hub-routes.test.ts。
|
||
覆盖范围: asset-hub CRUD 路由。
|
||
共同断言: DB 真值变化、字段映射不漂移、权限拦截。
|
||
|
||
🟨⏸ Phase 4.5: 新增 tests/integration/api/contract/crud-novel-promotion-routes.test.ts。
|
||
覆盖范围: novel-promotion 非任务化 CRUD 路由。
|
||
共同断言: project 权限、数据一致性、错误码一致性。
|
||
|
||
🟨⏸ Phase 4.6: 新增 tests/integration/api/contract/task-infra-routes.test.ts。
|
||
覆盖范围: /api/tasks, /api/tasks/[taskId], /api/tasks/dismiss, /api/task-target-states, /api/sse。
|
||
共同断言: 状态读取、取消、dismiss、target-state 结果结构。
|
||
|
||
🟥⚠️ Phase 4.7: 117 route 全覆盖耗时高，若单进程过慢需按组拆分命令并并行 CI job（不降覆盖）。
|
||
|
||
---
|
||
|
||
### 阶段5: L3 Worker 决策单元测试（全系统主防线之二）
|
||
|
||
🟨⏸ Phase 5.1: 新增 tests/unit/worker/reference-to-character.test.ts。
|
||
覆盖: extractOnly / customDescription / useReferenceImages / backgroundJob 分支。
|
||
|
||
🟨⏸ Phase 5.2: 新增 tests/unit/worker/image-task-handlers-core.test.ts。
|
||
覆盖: referenceImages 注入、resolution/aspectRatio 选择、目标实体分支(character/location/storyboard)。
|
||
|
||
🟨⏸ Phase 5.3: 新增 tests/unit/worker/script-to-storyboard.test.ts。
|
||
覆盖: step orchestration、JSON parse 失败路径、voice line 匹配合法性校验。
|
||
|
||
🟨⏸ Phase 5.4: 新增 tests/unit/worker/episode-split.test.ts。
|
||
覆盖: 分集数量边界、错误输入显式失败、输出结构一致性。
|
||
|
||
🟨⏸ Phase 5.5: 新增 tests/unit/worker/video-worker.test.ts 与 voice-worker.test.ts。
|
||
覆盖: 必填 payload 校验、外部轮询超时、持久化字段更新。
|
||
|
||
🟥⚠️ Phase 5.6: 若 mock 粒度过粗会掩盖问题，必须在断言中校验“被调用参数内容”而非仅校验调用次数。
|
||
|
||
---
|
||
|
||
### 阶段6: L4 全链路契约测试（route -> queue -> worker）
|
||
|
||
🟨⏸ Phase 6.1: 新增 tests/integration/chain/text.chain.test.ts。
|
||
场景: ai-create-character、reference-to-character 全链路。
|
||
|
||
🟨⏸ Phase 6.2: 新增 tests/integration/chain/image.chain.test.ts。
|
||
场景: generate-image、modify-image 全链路。
|
||
|
||
🟨⏸ Phase 6.3: 新增 tests/integration/chain/video.chain.test.ts。
|
||
场景: generate-video、lip-sync 全链路。
|
||
|
||
🟨⏸ Phase 6.4: 新增 tests/integration/chain/voice.chain.test.ts。
|
||
场景: voice-design、voice-generate 全链路。
|
||
|
||
🟨⏸ Phase 6.5: 新增 tests/helpers/fakes/llm.ts、tests/helpers/fakes/media.ts、tests/helpers/fakes/providers.ts。
|
||
要求: 外部调用全部 fake，禁止真实外网消耗。
|
||
|
||
🟥⚠️ Phase 6.6: 需要在测试环境加“网络闸门”，防止误打真实外部 API。
|
||
|
||
---
|
||
|
||
### 阶段7: 前端状态回归测试（轻量，不做重 E2E）
|
||
|
||
🟨⏸ Phase 7.1: 扩展 tests/unit/optimistic/asset-hub-mutations.test.ts。
|
||
覆盖: 并发操作回滚冲突、缓存一致性。
|
||
|
||
🟨⏸ Phase 7.2: 新增 tests/unit/optimistic/task-target-state-map.test.ts。
|
||
覆盖: queued/processing/completed/failed 对 UI 状态映射。
|
||
|
||
🟨⏸ Phase 7.3: 新增 tests/unit/optimistic/sse-invalidation.test.ts。
|
||
覆盖: 仅终态触发 target-state 刷新，不允许轮询回退。
|
||
|
||
🟥⚠️ Phase 7.4: 不引入高成本浏览器 E2E，避免与“全 fake、低成本”策略冲突。
|
||
|
||
---
|
||
|
||
### 阶段8: CI 门禁与回归收口
|
||
|
||
🟨⏸ Phase 8.1: 更新 package.json，新增命令。
|
||
建议命令:
|
||
- test:guards
|
||
- test:unit:all
|
||
- test:integration:api
|
||
- test:integration:chain
|
||
- test:pr
|
||
- test:regression
|
||
|
||
🟨⏸ Phase 8.2: 调整 CI，每次 PR 执行 test:pr（全量门禁）。
|
||
🟨⏸ Phase 8.3: 回归失败输出标准化（失败文件、失败断言、首次引入 commit）。
|
||
🟨⏸ Phase 8.4: 设置完成判定条件，满足后冻结基线。
|
||
|
||
🟥⚠️ Phase 8.5: 全量 PR 门禁会拉长反馈时间，需要预留 CI 资源并做缓存优化。
|
||
|
||
---
|
||
|
||
### 执行日志（每次执行后必须追加）
|
||
格式:
|
||
- [YYYY-MM-DD HH:mm] 状态变更: <任务ID> <旧状态> -> <新状态>
|
||
- [YYYY-MM-DD HH:mm] 修改文件: <绝对路径列表>
|
||
- [YYYY-MM-DD HH:mm] 运行命令: <命令>
|
||
- [YYYY-MM-DD HH:mm] 结果: <通过/失败 + 摘要>
|
||
- [YYYY-MM-DD HH:mm] 问题: <若有>
|
||
|
||
---
|
||
|
||
## 4: 验证策略
|
||
|
||
### 4.1 可量化验收指标（必须全部达成）
|
||
1. route 契约覆盖率 = 117/117（100%）。
|
||
2. TASK_TYPE 覆盖率 = 49/49（100%）。
|
||
3. 4 类队列链路测试均存在且通过（text/image/video/voice）。
|
||
4. 每个 PR 全量门禁执行并通过。
|
||
5. 无真实外网调用（测试日志与网络闸门双重确认）。
|
||
6. 关键高频回归场景（编辑类、参考图类、任务状态类）均有自动化用例。
|
||
7. 新增/修改 route 或 TASK_TYPE 时，若未补测试，guard 必须失败。
|
||
|
||
### 4.2 命令级验证
|
||
- `npm run test:guards`
|
||
- `cross-env BILLING_TEST_BOOTSTRAP=0 vitest run tests/unit`
|
||
- `cross-env BILLING_TEST_BOOTSTRAP=1 vitest run tests/integration/api`
|
||
- `cross-env BILLING_TEST_BOOTSTRAP=1 vitest run tests/integration/chain`
|
||
- `npm run test:pr`
|
||
|
||
### 4.3 结果记录
|
||
每轮执行后在执行日志追加:
|
||
- 总用例数
|
||
- 失败数
|
||
- 失败模块
|
||
- 修复后重跑结果
|
||
|
||
---
|
||
|
||
## 5: 备注（可选但建议）
|
||
|
||
1. 本计划不依赖历史对话，可由任意新模型直接接手。
|
||
2. 若用户策略改变（例如允许少量 live canary），必须先更新本文件“策略锁定项”，再动代码。
|
||
3. 若发现范围蔓延，优先维护“矩阵完整性”而不是临时加测。
|
||
4. 任何“为了通过测试而加回退”的方案一律禁止。
|
||
5. 所有测试代码保持强类型，不允许 any。
|