skelet/docs/review/phase1-review.md

Phase 1 评审

评审日期：2026-07-06
评审视角：全栈开发工程师
评审范围：T-101 至 T-104 的内容模型、迁移、测试、任务状态和当前文档同步。

结论

Phase 1 尚未完全达标。

T-101、T-103 基本达标；T-102 主体模型已建立，但 SkeletonProjectPage 的必填多对多约束没有被实际校验；T-104 标为 BLOCKED 是合理的，因为当前仓库没有人工确认的首批种子内容清单。

当前不能把 Phase 1 视为完整完成。最低需要先修复：

1. SkeletonProjectPage.scenarios / languages 至少 1 个的校验。
2. 相关单元测试，覆盖缺少场景 / 缺少语言时抛 ValidationError。
3. AGENTS.md 当前阶段和下一步任务，与 docs/06-tasks.md、docs/current-state.md 同步。

Findings

1. High：scenarios / languages 必填约束未真正生效

架构文档明确要求：

• docs/04-architecture.md §3.3：scenarios 至少 1 个，languages 至少 1 个。
• docs/06-tasks.md T-102：SkeletonProjectPage 必须严格按 04-architecture.md §3.3 表和必填 / 默认附注实现。

当前模型只写了：

scenarios = ParentalManyToManyField("core.ScenarioPage", blank=False)
languages = ParentalManyToManyField("core.Language", blank=False)

位置：core/models.py。

但实测 blank=False 不会让 SkeletonProjectPage.full_clean() 拦截空多对多。临时创建正确页面树后分别验证：

no_m2m PASS_NO_ERROR
language_only PASS_NO_ERROR
scenario_only PASS_NO_ERROR

这意味着项目可以没有场景、没有语言，仍通过模型校验。后续筛选、场景页列表和内容质量都会受影响。

建议修复：

• 在 SkeletonProjectPage.clean() 中检查：
  • 已保存对象：self.scenarios.exists() / self.languages.exists()。
  • Wagtail 编辑流程中如果使用 unsaved cluster relation，需要确认 ParentalManyToManyField 的表单数据能被正确校验。
• 或实现 Wagtail admin form / panel 层校验，确保后台编辑保存时无法为空。
• 增加单元测试：
  • 缺 scenarios 时抛 ValidationError。
  • 缺 languages 时抛 ValidationError。
  • 两者都有时 full_clean() 通过。

2. Medium：T-102 的测试没有覆盖正确页面树和必填场景

core/tests.py 中 test_valid_project_full_clean 把 SkeletonProjectPage 直接加到 root 下：

root = Page.get_first_root_node()
root.add_child(instance=project)

但模型声明和架构要求是：

HomePage
└── ProjectIndexPage
    └── SkeletonProjectPage

SkeletonProjectPage.parent_page_types = ["core.ProjectIndexPage"]，直接挂 root 在真实 Wagtail 页面创建流程里是不允许的。

实测：

can_create_project_under_root False
can_create_article_under_root False
can_create_scenario_under_root False

当前测试绕过了真实父子页面约束，也没有给项目添加 scenario，因此无法证明 T-102 的核心编辑路径可用。

建议修复：

• 测试中创建 HomePage -> ProjectIndexPage -> SkeletonProjectPage。
• 为合法项目同时添加 scenario 和 language。
• 文章测试中创建 HomePage -> ArticleIndexPage -> ArticlePage。

3. Medium：AGENTS.md 当前阶段已过期

docs/06-tasks.md 显示：

T-101 DONE
T-102 DONE
T-103 DONE
T-104 BLOCKED

docs/current-state.md 也写：

下一个可领取任务：T-104（BLOCKED，等待人工确认种子内容）

但 AGENTS.md 仍写：

下一步 ... T-101：建立场景、语言、框架、数据库、功能标签模型。

这会误导下一轮 agent 重复领取已完成任务，违反任务状态变化同步 current-state.md 和入口文档的工作规则。

建议修复：

• AGENTS.md 改为 Phase 1 局部完成：T-101/T-102/T-103 已完成，T-104 BLOCKED。
• 下一步写清楚：等待人工确认种子内容；未解除阻塞前不要进入 Phase 2。

逐任务评审

T-101 建立场景、语言、框架、数据库、功能标签模型

状态：基本达标。

已确认：

• ScenarioIndexPage / ScenarioPage 是 Page，不是 Snippet。
• Language、Framework、DatabaseOption、SkeletonFeature 是 Snippet，并使用 @register_snippet 注册。
• 4 个 Snippet 都有 name unique + slug unique。
• 没有实现 AiCodingScore 模型，符合 MVP 决策。
• 迁移 core/migrations/0001_initial.py 存在并已应用。
• 测试覆盖创建对象和 slug 唯一性。

遗留风险：

• 测试只验证数据库唯一约束抛 IntegrityError，没有验证 Wagtail 后台表单体验；但对 T-101 当前验收不是阻断。

T-102 建立骨架项目详情模型

状态：未完全达标。

已确认：

• ProjectIndexPage 和 SkeletonProjectPage 已建立。
• SkeletonProjectPage 字段基本覆盖 04-architecture.md §3.3。
• scenarios、languages、frameworks、databases、features 使用 ParentalManyToManyField。
• 6 个评分字段有 MinValueValidator(0) / MaxValueValidator(5)。
• total_score 是 property，计算 6 项总分。
• 后台面板分为 5 组。
• 迁移 0002_projectindexpage_skeletonprojectpage.py 存在并已应用。

未达标点：

• scenarios / languages 至少 1 个没有实际校验。
• 合法对象测试没有创建正确页面树，也没有添加 scenario。
• 缺少针对空 scenarios / 空 languages 的失败测试。

T-103 建立文章模型

状态：基本达标。

已确认：

• ArticleIndexPage 和 ArticlePage 已建立。
• ArticlePage.body 使用 RichTextField。
• related_projects 是可空多对多，指向 SkeletonProjectPage。
• 迁移 0003_articleindexpage_articlepage.py 存在并已应用。
• 测试覆盖文章关联项目。

遗留风险：

• 当前测试把 ArticlePage 直接挂 root，没有按 ArticleIndexPage -> ArticlePage 的真实页面树创建。建议随 T-102 测试一起修正。

T-104 准备首批种子内容

状态：BLOCKED 合理。

已确认：

• 当前数据库中 ScenarioPage / SkeletonProjectPage / ArticlePage count 均为 0。
• 当前没有人工确认的首批项目清单、评分和评语。
• docs/06-tasks.md 明确要求无清单时标 BLOCKED，禁止模型编造。
• progress.md 已记录 T-104 因缺少人工确认清单而 BLOCKED。

因此 T-104 不能标 DONE，但当前 BLOCKED 状态符合规则。

验证命令

本次评审运行：

bash -lc '.venv/bin/python3.12.exe manage.py check'
bash -lc '.venv/bin/python3.12.exe manage.py test'
bash -lc '.venv/bin/python3.12.exe manage.py makemigrations --check --dry-run'
bash -lc '.venv/bin/python3.12.exe manage.py showmigrations core'

结果：

• manage.py check：0 errors，9 个 treebeard 兼容 warning。
• manage.py test：17 tests passed。
• makemigrations --check --dry-run：No changes detected。
• showmigrations core：0001_initial、0002_projectindexpage_skeletonprojectpage、0003_articleindexpage_articlepage 已应用。

补充行为检查：

snippets ['DatabaseOption', 'Framework', 'Language', 'SkeletonFeature']
project parents ['core.ProjectIndexPage']
article parents ['core.ArticleIndexPage']
can_create_project_under_root False
can_create_article_under_root False
can_create_scenario_under_root False
no_m2m PASS_NO_ERROR
language_only PASS_NO_ERROR
scenario_only PASS_NO_ERROR

是否允许进入 Phase 2

不允许。

原因：

• T-104 仍处于 BLOCKED，依赖未满足。
• T-102 仍有必填多对多校验缺口。

建议下一步：

1. 修复 SkeletonProjectPage 的 scenarios / languages 至少 1 个校验。
2. 修正 T-102 / T-103 测试的页面树创建方式。
3. 更新 AGENTS.md 当前阶段和下一步任务。
4. 等待用户提供人工确认的种子内容后，再继续 T-104。