Harden task board and specs for weaker coding agents

- 06-tasks: add per-task detail sheets for Phase 0/1 (concrete init commands, BLOCKED preconditions, verification commands with expected results) and a constraint/verification quick table for Phase 2/3; replace subjective acceptance wording with checkable items - 04-architecture: promote 3.4 to an authoritative filter-param contract (names, values, AND combination, invalid-value handling); add required/optional/default field annex with 0-5 validators to 3.3; state AiCodingScore is not a model in MVP; record structure decision (keep wagtail-start home/search apps, business models in new core app, no Dockerfile) - 03-tech-stack: add version-pinning policy row for T-001 - routes/02-requirements: point filter wording back to the 3.4 contract instead of maintaining copies - T-104: human-input boundary - seed projects, scores and verdicts must be user-confirmed; BLOCKED without a confirmed list - current-state snapshot updated; maintenance record appended to progress.md Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-06 16:11:54 +08:00
parent d98bfb7531
commit 678d081124
7 changed files with 147 additions and 21 deletions
@@ -56,7 +56,7 @@

 - **首页与场景导航**：访问 `/` 时能看到场景入口、推荐项目区和最新文章入口。
 - **骨架项目列表**：访问场景页时能看到该场景下已发布项目；无项目时显示空状态。
- **筛选与基础搜索**：选择语言或框架筛选后，列表只展示匹配项目；筛选条件可被 URL 表示。
+- **筛选与基础搜索**：选择语言或框架筛选后，列表只展示匹配项目；筛选条件可被 URL 表示（参数契约见 [`04-architecture.md`](04-architecture.md) §3.4）。
 - **骨架详情页**：详情页展示名称、简介、官网 / GitHub 链接、技术栈、适用场景、不适用场景、AI 友好度评分、维护状态和推荐理由。
 - **后台内容管理**：管理员能在 Wagtail 后台新增项目、分类、语言、框架和评分，并发布后在前台可见。
 - **SEO 基础**：核心公开页面有稳定 slug、页面标题、meta description，并可生成 sitemap。
@@ -8,6 +8,7 @@
 | --- | --- | --- | --- |
 | CMS / Web 框架 | Wagtail + Django | 已定 | 内容模型、后台、页面、SEO、搜索和后续扩展都适合目录评测站。 |
 | Python | Python 3.12 | 已定 | Wagtail 当前支持 Python 3.12；部署环境更稳。 |
+| 版本钉死 | `requirements.txt` 按实际安装版本 pin | T-001 落实 | 初始化时安装 pip 当前稳定版 Wagtail，用 `pip show wagtail` 确认版本后写成 `wagtail==X.Y.Z`，并回写本表。 |
 | 数据库 | SQLite with JSON1 | 已定 | 开发和第一版上线成本低；MVP 写入少。 |
 | 后续数据库 | PostgreSQL | 条件触发 | 出现用户写入、高并发、后台多人编辑、锁冲突或会员功能后迁移。 |
 | 前端模板 | Django Templates / Wagtail Templates | 已定 | 第一版以内容站为主，避免引入前后端分离复杂度。 |
@@ -65,6 +65,8 @@ SQLite db.sqlite3
 | `ArticleIndexPage` | Page | 文章列表。 |
 | `ArticlePage` | Page | 评测、对比、避坑指南等内容文章。 |

+模型归属：`HomePage` 在 `home` app（`wagtail start` 生成，沿用不改名）；其余 Page、Snippet 和文章模型集中在 `core` app（见本文第六节）。
+
 ### 3.2 Snippet / 辅助模型

 | 模型 | 说明 |
@@ -73,7 +75,7 @@ SQLite db.sqlite3
 | `Framework` | Wagtail、Django、FastAPI、Next.js、Laravel 等。 |
 | `DatabaseOption` | SQLite、PostgreSQL、MySQL、MongoDB 等。 |
 | `SkeletonFeature` | Auth、Admin、Payment、SEO、Docker、Tests 等功能标签。 |
-| `AiCodingScore` | AI 友好度评分维度定义。 |
+| `AiCodingScore` | **MVP 不建此模型**：评分维度即 `SkeletonProjectPage` 的 6 个分数字段（见 3.3），避免两处维护同一套维度。 |
 | `SponsorSlot` | 后续赞助展示位置，MVP 可先不启用。 |
 | `AffiliateLink` | 后续返佣链接，MVP 可先不启用。 |

@@ -105,6 +107,13 @@ SQLite db.sqlite3
 | `is_featured` | Boolean | 是否首页推荐。 |
 | `is_sponsored` | Boolean | 是否赞助展示，必须前台标识。 |

+**必填 / 可空 / 默认（后台校验以此为准，实现不得自行猜测）**：
+
+- 必填：`title`、`summary`、`github_url`、`scenarios`（至少 1 个）、`languages`（至少 1 个）、`maturity`、6 个评分字段、`recommended_for`。
+- 可空：`official_url`、`license_name`、`frameworks`、`databases`、`features`、`not_recommended_for`、`review_notes`。
+- 默认：`maintenance_status='unknown'`、`is_featured=False`、`is_sponsored=False`。
+- 6 个评分字段使用 `MinValueValidator(0)` / `MaxValueValidator(5)`。
+
 **评分模型纪律（唯一权威定义）**：

 - AI Coding 友好度评分维度以上表 6 个 0-5 分项为唯一权威：目录结构、文档完整度、测试可用性、示例模块、依赖克制度、增量开发难度。
@@ -112,17 +121,36 @@ SQLite db.sqlite3
 - `business/` 下的文档引用本节，不得自行维护另一份维度清单。
 - 每个项目除分数外必须有一句评语：为什么适合 / 不适合 AI coding。

-### 3.4 URL 与筛选
+### 3.4 URL 与筛选参数契约（唯一权威）

-筛选条件必须可以通过 URL 表达，便于 SEO 和分享：
+筛选条件必须可以通过 URL 表达，便于 SEO 和分享。列表页查询参数按下表实现，视图、模板和其他文档不得另造参数名或语义：
+
+| 参数 | 取值 | 语义 |
+| --- | --- | --- |
+| `language` | `Language.slug`，单值 | 项目 `languages` 包含该语言 |
+| `framework` | `Framework.slug`，单值 | 项目 `frameworks` 包含该框架 |
+| `database` | `DatabaseOption.slug`，单值 | 项目 `databases` 包含该数据库 |
+| `min_score` | 0-30 整数 | `total_score`（6 分项之和）≥ 该值 |
+| `q` | 关键词字符串 | `title` 或 `summary` 不区分大小写包含（ORM `icontains`，MVP 不接搜索后端） |
+| `page` | ≥1 整数 | 分页页码，每页 20 条 |
+
+组合规则：
+
+- 参数均可选，多个参数同时出现时按 AND 组合。
+- MVP 每个参数只取单值；同名参数重复出现时取第一个。
+- `min_score` / `page` 无法解析为合法整数时忽略该参数，不报错。
+- 未知 slug 正常参与过滤，自然得到空列表并渲染空状态。
+
+示例：

 ```text
 /scenarios/saas/
 /scenarios/saas/?language=python
-/projects/?framework=wagtail&database=sqlite
+/projects/?framework=wagtail&database=sqlite&min_score=18
+/projects/?q=admin&page=2
 ```

-MVP 可以使用服务端查询和分页，不做前端复杂状态管理。
+MVP 使用服务端查询和分页，不做前端复杂状态管理。

 ## 四、关键技术难点

@@ -146,26 +174,30 @@ MVP 可以使用服务端查询和分页，不做前端复杂状态管理。

 ## 六、项目结构建议

-T-001 初始化后目标结构：
+T-001 初始化后目标结构（与 `wagtail start skelet .` 的实际输出对齐）：

 ```text
 skelet/
 ├── docs/
 ├── manage.py
 ├── requirements.txt
-├── skelet/
-│   ├── settings/
+├── skelet/            # wagtail start 生成的配置包
+│   ├── settings/      # base.py / dev.py / production.py
 │   ├── urls.py
 │   └── wsgi.py
-├── core/
+├── home/              # wagtail start 生成，保留，承载 HomePage
+├── search/            # wagtail start 生成，保留
+├── core/              # 新建业务 app：Snippet、场景页、项目页、文章模型
 │   ├── models.py
 │   ├── templates/
-│   └── static/
-├── tests/
+│   ├── static/
+│   └── tests.py
 ├── media/
 └── README.md
 ```

+**结构决策**：保留 `wagtail start` 生成的 `home` 和 `search` app，不重命名（手改默认迁移容易出错）；业务模型全部放在新建的 `core` app；测试放各 app 的 `tests.py`，暂不建独立 `tests/` 目录；生成的 `Dockerfile` 删除（第一版不用 Docker，见 `03-tech-stack.md`）。
+
 实际路径以初始化后的 Wagtail 项目为准；初始化完成后必须更新本文和 `current-state.md`。

 ## 七、架构纪律
@@ -9,6 +9,7 @@
 3. 完成后跑验证，把证据追加到 [`../progress.md`](../progress.md)，再改成 `DONE`。
 4. 同步更新 [`current-state.md`](current-state.md)。
 5. 不实现 Backlog 或后续阶段功能，除非任务已明确要求。
+6. 任务表只是索引；有「任务详单」的任务，实现指引和验证命令以详单为准。

 ## 状态图例

@@ -30,18 +31,18 @@
 | ID | 任务 | 依赖 | 验收要点 | 状态 |
 | --- | --- | --- | --- | --- |
 | T-101 | 建立场景、语言、框架、数据库、功能标签模型 | T-003 | Wagtail 后台可维护这些 Snippet；迁移文件生成并通过 migrate | TODO |
-| T-102 | 建立骨架项目详情模型 | T-101 | `SkeletonProjectPage` 包含架构文档中的 MVP 字段；后台编辑分组清晰；字段校验合理 | TODO |
+| T-102 | 建立骨架项目详情模型 | T-101 | `SkeletonProjectPage` 严格按 `04-architecture.md` §3.3 表和必填/默认附注实现；评分字段带 0-5 校验器；总分由分项计算 | TODO |
 | T-103 | 建立文章模型 | T-101 | 可维护文章列表和详情；文章可链接骨架项目 | TODO |
-| T-104 | 准备首批种子内容 | T-102, T-103 | 至少有 3 个场景、5 个骨架项目、2 篇文章；数据来源和人工录入方式记录清楚 | TODO |
+| T-104 | 准备首批种子内容 | T-102, T-103 | 至少有 3 个场景、5 个骨架项目、2 篇文章；候选项目、评分和评语须经人工确认，禁止模型编造（见详单） | TODO |

 ## Phase 2 · 前台 MVP

 | ID | 任务 | 依赖 | 验收要点 | 状态 |
 | --- | --- | --- | --- | --- |
-| T-201 | 实现基础页面框架 | T-104 | `base.html`、导航、页脚、基础样式可用；移动端不溢出 | TODO |
+| T-201 | 实现基础页面框架 | T-104 | `base.html`、导航、页脚、纯 CSS 基础样式；含 viewport meta；无超过视口的固定宽度容器 | TODO |
 | T-202 | 实现首页 | T-201 | 首页展示场景入口、推荐骨架和最新文章 | TODO |
 | T-203 | 实现场景页和项目列表页 | T-202 | 场景页展示对应项目；项目列表支持分页和空状态 | TODO |
-| T-204 | 实现筛选与基础搜索 | T-203 | URL 参数可筛选语言、框架、数据库、AI 分数和关键词 | TODO |
+| T-204 | 实现筛选与基础搜索 | T-203 | 严格按 `04-architecture.md` §3.4 参数契约实现筛选和关键词搜索 | TODO |
 | T-205 | 实现骨架详情页 | T-204 | 展示需求文档要求的详情字段、评分、推荐理由和 Sponsored 标识 | TODO |
 | T-206 | 实现文章列表和文章详情 | T-203 | 文章可访问，可链接项目详情 | TODO |

@@ -55,6 +56,82 @@
 | T-305 | 接入轻量访问统计与外链点击记录 | T-301 | Plausible / Umami 或等价方案接入；外部链接点击可统计；不引入重量级分析 SDK；这是里程碑 M3（SEO 验证）和 M4（Affiliate）的数据前置 | TODO |
 | T-304 | MVP 完整验收 | T-303, T-305 | `02-requirements.md` 的 P0 验收全部通过，验证命令和结果写入 `progress.md` | TODO |

+## 任务详单
+
+> 本节给出实现指引、验收核对项和验证命令，弥补任务表一行放不下的细节。验证命令的输出一律追加到 [`../progress.md`](../progress.md) 作为完成证据。
+
+### T-001 初始化 Wagtail 项目骨架
+
+前置：`python3.12 --version` 可用。不可用则任务标 `BLOCKED` 并在 `progress.md` 记录缺口，**不要改用其他 Python 版本**。
+
+步骤：
+
+1. `python3.12 -m venv .venv && .venv/bin/pip install --upgrade pip`
+2. `.venv/bin/pip install wagtail`（当前稳定版）
+3. `.venv/bin/wagtail start skelet .`（在仓库根目录生成 `manage.py`、`skelet/` 配置包、`home/`、`search/`）
+4. `.venv/bin/python manage.py startapp core` 并加入 `INSTALLED_APPS`；保留 `home` / `search`，不重命名（结构决策见 `04-architecture.md` §六）
+5. 删除生成的 `Dockerfile`；`requirements.txt` 按 `.venv/bin/pip show wagtail` 的实际版本钉死 `wagtail==X.Y.Z`
+6. `.venv/bin/python manage.py migrate && .venv/bin/python manage.py createsuperuser`
+7. 替换 `init.sh` 顶部三个命令变量；回写 `03-tech-stack.md` §一/§三、`04-architecture.md` §六、`current-state.md`
+
+验证（括号内为预期结果）：
+
+- `.venv/bin/python manage.py check`（System check identified no issues）
+- `runserver` 后另开终端 `curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8000/`（200）；同法访问 `/admin/login/`（200）
+
+### T-002 基础配置与环境样例
+
+- `skelet/settings/` 保持 base/dev/production 拆分；`SECRET_KEY`、`DEBUG`、`ALLOWED_HOSTS` 从环境变量读取，dev 环境给安全默认值。
+- 新建 `.env.example`：只含占位值（如 `SECRET_KEY=replace-me`），逐项注释用途；真实 `.env` 已被 `.gitignore` 忽略。
+- 验证：`grep -riE "secret|token|password" .env.example` 只出现占位值；`manage.py check` 无错误。
+
+### T-003 最小验证基线
+
+- 在 `home/tests.py` 写一个 smoke 测试：test client 访问 `/`，断言状态码 200。
+- 验证：`.venv/bin/python manage.py test`（至少 1 个测试通过）。
+- 完成后同步 `05-coding-rules.md` §7 的真实命令和 `init.sh` 的 `VERIFY_CMD`。
+
+### T-101 分类与标签模型
+
+- 场景不是 Snippet：建 `ScenarioIndexPage` / `ScenarioPage`（`core` app，Page 类型，本轮只建模型，不做模板）。
+- Snippet 共 4 个：`Language`、`Framework`、`DatabaseOption`、`SkeletonFeature`；字段一律 `name`（Char，unique）+ `slug`（unique，作 URL 筛选参数值），注册为 Wagtail Snippet。
+- 不建 `AiCodingScore` 模型（见 `04-architecture.md` §3.2）。
+- 验证：`makemigrations` + `migrate` 成功；每个 Snippet 一个单元测试（创建对象、slug 重复时抛错）；`manage.py test` 全部通过。
+
+### T-102 骨架项目详情模型
+
+- `SkeletonProjectPage`（`core` app）：字段、必填/可空/默认严格按 `04-architecture.md` §3.3 表和附注实现，不增不减。
+- 6 个评分字段带 `MinValueValidator(0)` / `MaxValueValidator(5)`；`total_score` 为 property（6 项之和，0-30）。
+- 后台按 5 组分面板：基本信息 / 分类标签 / 评分 / 评测内容 / 展示控制。
+- 验证单元测试至少 3 个：合法对象 `full_clean()` 通过；某评分设为 6 时 `full_clean()` 抛 `ValidationError`；`total_score` 等于 6 项之和。`manage.py test` 全部通过。
+
+### T-103 文章模型
+
+- `ArticleIndexPage` + `ArticlePage`（`core` app）；正文用 RichTextField 或 StreamField；文章到骨架项目用可空多对多关联。
+- 验证：`migrate` 成功；单元测试创建文章并关联一个项目；`manage.py test` 全部通过。
+
+### T-104 首批种子内容（人工输入边界）
+
+- **候选项目、评分和评语必须来自用户提供或经用户逐条确认**，来源方法见 [`../business/research-sourcing-strategy.md`](../business/research-sourcing-strategy.md)；agent 不得凭记忆编造项目名、GitHub 地址或评分。
+- 仓库内没有人工确认的清单时，本任务标 `BLOCKED`，在 `progress.md` 记录"等待首批项目清单"，不要往下做。
+- 有清单后：按 SaaS、内容站/CMS 两个场景录入 ≥3 个场景页、≥5 个项目、≥2 篇文章（后台录入或 fixture，方式记入 `progress.md`）。
+- 验证：`manage.py shell -c` 分别输出场景、项目、文章的 count（≥3 / ≥5 / ≥2）。
+
+### Phase 2 / Phase 3 关键约束与验证速查
+
+| 任务 | 关键实现约束 | 验证 |
+| --- | --- | --- |
+| T-201 | `base.html` 含 `<meta name="viewport">`；纯 CSS 无构建链路；无超视口固定宽度容器 | `curl /` 返回 200；各页面模板均继承 `base.html` |
+| T-202 | 首页三区块全部来自数据库查询（`is_featured`、最新文章），不硬编码内容 | 测试断言 featured 项目标题出现在 `/` 响应中 |
+| T-203 | 场景页只列已发布（live）项目；分页每页 20；空场景渲染 `empty_state.html` | 测试两用例：有项目场景（200 且含项目名）、空场景（200 且含空状态文案） |
+| T-204 | 严格按 `04-architecture.md` §3.4 契约；搜索用 ORM `icontains` | 测试 4 用例：`language` 过滤、`min_score` 过滤、`q` 搜索、非法参数被忽略 |
+| T-205 | 展示 §3.3 全部展示字段；`is_sponsored=True` 时渲染 `sponsored_badge.html` | 测试断言详情页含评分、推荐理由；赞助用例含 Sponsored 标识 |
+| T-206 | 文章详情可点击进入关联项目详情页 | 测试断言文章页响应含项目详情链接 |
+| T-301 | title/description 用 Wagtail 自带 `seo_title` / `search_description`；sitemap 用 `wagtail.contrib.sitemaps` | `curl /sitemap.xml` 返回 200 且含项目 URL；首页响应含 `<meta name="description"` |
+| T-302 | 部署文档以 [`deployment/environment-assessment.md`](deployment/environment-assessment.md) 的结论为基线 | 文档内命令逐条可复制执行 |
+| T-303 | JSON1 验证、WAL、备份、PostgreSQL 迁移触发条件写入部署文档 | 服务器上 `PRAGMA journal_mode;` 输出 `wal` 的证据记入 `progress.md` |
+| T-305 | Plausible / Umami 轻量脚本；外链带点击事件；不引入重 SDK | 页面响应含统计脚本域名；外链元素带事件属性 |
+
 ## Backlog

 - 首批内容库建设（原 `business/research-sourcing-strategy.md` 建议的 T-105~T-109，收敛为先做 2 个场景）：建立候选清单，完成 SaaS、内容站/CMS 两个场景各 10 个项目的初评；管理后台和 API 服务场景在 M3 验证通过后再扩展。
@@ -11,7 +11,7 @@
 ## 当前快照

 - 日期：2026-07-06
- 阶段：MVP 起步前，harness 文档已初始化并完成瘦身（元文档合并为 `90-harness-reference.md`，入口统一为 `AGENTS.md`）
+- 阶段：MVP 起步前，harness 文档已初始化并完成瘦身（元文档合并为 `90-harness-reference.md`，入口统一为 `AGENTS.md`）；任务看板已加固（任务详单、验证命令、筛选参数契约、字段必填/默认附注）
 - 开发环境：WSL2 / Linux，仓库根目录 `/mnt/d/opc_project/skelet`，bash 为标准命令形态
 - git：已初始化，主分支 `main`；`.gitignore` 已生效（`deploy/` 及凭证类文件不入库），`.gitattributes` 统一 LF 行尾
 - 技术栈：目标为 Wagtail + Django + Python 3.12 + SQLite；第一版英文单语言站点
@@ -36,9 +36,10 @@
 | `init.ps1` / `init.sh` | 已有，占位 | T-001 初始化生产代码后替换真实命令。 |
 | `manage.py` | 待建 | Wagtail/Django 入口。 |
 | `requirements.txt` | 待建 | Python 依赖。 |
-| `skelet/` | 待建 | Django 项目配置。 |
-| `core/` | 待建 | Wagtail 页面模型、模板和静态资源。 |
-| `tests/` | 待建 | 测试目录。 |
+| `skelet/` | 待建 | Django 配置包（`wagtail start` 生成 base/dev/production settings）。 |
+| `home/` / `search/` | 待建 | `wagtail start` 默认 app，保留不改名；`HomePage` 在 `home`。 |
+| `core/` | 待建 | 业务 app：Snippet、场景页、项目页、文章模型、模板和静态资源。 |
+| 各 app `tests.py` | 待建 | smoke 与模型测试（T-003 起），暂不建独立 `tests/` 目录。 |

 ## 任务看板状态

@@ -37,7 +37,7 @@

 - 展示所有已发布骨架项目。
 - 支持按语言、框架、数据库、AI 分数、关键词筛选。
- 筛选条件体现在 URL 查询参数中。
+- 筛选条件体现在 URL 查询参数中；参数名、取值和组合规则以 [`04-architecture.md`](04-architecture.md) §3.4 契约表为唯一权威，本文不重复维护。
 - 展示当前筛选条件和清除筛选入口。

 ### 项目详情页
@@ -65,3 +65,18 @@
 - 决策：`deploy/` 整目录不入库，部署凭证只保留在本机；行尾规范定为 LF（与 WSL2/Linux 标准开发环境一致）。
 - 下一步：T-001 初始化 Wagtail 项目骨架。

+## 2026-07-06 任务看板加固（面向执行能力较弱的模型）
+
+- 状态：DONE
+- 变更：
+  - `docs/06-tasks.md`：新增「任务详单」一节。Phase 0/1 每任务给出实现指引、前置检查和带预期结果的验证命令（T-001 含 `wagtail start` 逐步命令和 BLOCKED 条件）；Phase 2/3 给出关键实现约束与验证速查表。表格中的主观验收措辞（"字段校验合理""移动端不溢出"等）替换为可勾选项。
+  - `docs/04-architecture.md`：§3.4 升级为筛选参数契约表（唯一权威：`language`/`framework`/`database`/`min_score`/`q`/`page`，单值、AND 组合、非法值处理规则）；§3.3 表下新增必填/可空/默认附注和评分校验器要求；§3.2 明确 `AiCodingScore` MVP 不建模型；§一/§六记录结构决策：保留 `wagtail start` 生成的 `home`/`search` app，业务模型集中在新建 `core` app，测试放各 app `tests.py`，删除生成的 Dockerfile。
+  - `docs/03-tech-stack.md`：新增版本钉死策略行（T-001 时按 pip 实装稳定版 pin `wagtail==X.Y.Z` 并回写）。
+  - `docs/routes.md`、`docs/02-requirements.md`：筛选相关表述指回 §3.4 契约，不再各自维护。
+  - `docs/current-state.md`：快照与目录要点同步上述结构决策。
+  - T-104 明确人工输入边界：候选项目、评分、评语必须经用户确认，无清单时标 BLOCKED，禁止模型编造。
+- 验证：`grep` 检查 §3.4 引用一致（routes、requirements、06-tasks 均指向 04-architecture）；人工核对任务详单命令与 03-tech-stack §三目标命令形态一致。
+- 阻塞：无。
+- 决策：筛选参数契约以 `04-architecture.md` §3.4 为唯一权威；`home`/`search` app 保留不改名；`AiCodingScore` 不建模型；种子内容评分必须人工确认。
+- 下一步：T-001 初始化 Wagtail 项目骨架（详单已可直接照做）。
+