diff --git a/docs/02-requirements.md b/docs/02-requirements.md index 139ac6e..cc0e8d0 100644 --- a/docs/02-requirements.md +++ b/docs/02-requirements.md @@ -56,7 +56,7 @@ - **首页与场景导航**：访问 `/` 时能看到场景入口、推荐项目区和最新文章入口。 - **骨架项目列表**：访问场景页时能看到该场景下已发布项目；无项目时显示空状态。 -- **筛选与基础搜索**：选择语言或框架筛选后，列表只展示匹配项目；筛选条件可被 URL 表示。 +- **筛选与基础搜索**：选择语言或框架筛选后，列表只展示匹配项目；筛选条件可被 URL 表示（参数契约见 [`04-architecture.md`](04-architecture.md) §3.4）。 - **骨架详情页**：详情页展示名称、简介、官网 / GitHub 链接、技术栈、适用场景、不适用场景、AI 友好度评分、维护状态和推荐理由。 - **后台内容管理**：管理员能在 Wagtail 后台新增项目、分类、语言、框架和评分，并发布后在前台可见。 - **SEO 基础**：核心公开页面有稳定 slug、页面标题、meta description，并可生成 sitemap。 diff --git a/docs/03-tech-stack.md b/docs/03-tech-stack.md index 041d7ae..1935844 100644 --- a/docs/03-tech-stack.md +++ b/docs/03-tech-stack.md @@ -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 | 已定 | 第一版以内容站为主，避免引入前后端分离复杂度。 | diff --git a/docs/04-architecture.md b/docs/04-architecture.md index 95d8b76..ed953ce 100644 --- a/docs/04-architecture.md +++ b/docs/04-architecture.md @@ -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`。 ## 七、架构纪律 diff --git a/docs/06-tasks.md b/docs/06-tasks.md index 12e7296..5bc5a7b 100644 --- a/docs/06-tasks.md +++ b/docs/06-tasks.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` 含 ``；纯 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；首页响应含 `