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:
+43
-11
@@ -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`。
|
||||
|
||||
## 七、架构纪律
|
||||
|
||||
Reference in New Issue
Block a user