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>
This commit is contained in:
Claude Fable 5
+81
-4
@@ -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 验证通过后再扩展。
|
||||
|
||||
Reference in New Issue
Block a user