229 lines
10 KiB
Markdown
229 lines
10 KiB
Markdown
# 架构设计
|
||
|
||
> 本文讲“怎么把技术栈搭起来”：系统结构、职责划分、数据模型、技术难点、开发顺序。
|
||
|
||
## 一、系统结构
|
||
|
||
```text
|
||
游客 / 搜索引擎 / 后台编辑者
|
||
|
|
||
v
|
||
Nginx
|
||
|
|
||
v
|
||
Gunicorn
|
||
|
|
||
v
|
||
Django + Wagtail
|
||
|
|
||
+--> Wagtail Pages / Snippets / Admin
|
||
+--> Templates / Static / Media
|
||
|
|
||
v
|
||
SQLite db.sqlite3
|
||
```
|
||
|
||
第一版没有独立前端应用，也没有公开业务 API。页面由 Wagtail/Django 渲染。
|
||
|
||
## 二、职责划分
|
||
|
||
**Wagtail / Django**
|
||
|
||
- 管理页面、骨架项目、分类、标签、评分和文章。
|
||
- 提供后台编辑、草稿、发布、slug、SEO 字段。
|
||
- 渲染公开页面。
|
||
- 提供基础搜索和筛选。
|
||
|
||
**模板层**
|
||
|
||
- 首页、场景页、语言页、框架页、骨架详情页、文章页。
|
||
- 展示筛选状态、空状态、评分、推荐理由、外部链接。
|
||
- 不承载业务规则和数据修正逻辑。
|
||
|
||
**数据层**
|
||
|
||
- SQLite 保存 Wagtail 内容、用户、权限、页面树、项目条目和评分。
|
||
- `media/` 保存上传图片。
|
||
- 不在数据库保存真实密钥、token 或第三方平台凭证。
|
||
|
||
**部署层**
|
||
|
||
- Nginx 处理 HTTPS、静态文件、媒体文件和反向代理。
|
||
- Gunicorn 运行 Django。
|
||
- SQLite 文件和 media 目录必须纳入备份。
|
||
|
||
## 三、数据模型
|
||
|
||
### 3.1 Wagtail Page 类型
|
||
|
||
| 模型 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `HomePage` | Page | 首页，展示场景入口、推荐骨架、最新文章。 |
|
||
| `ScenarioIndexPage` | Page | 场景总览页。 |
|
||
| `ScenarioPage` | Page | 单个场景页，如 SaaS、管理后台、API 服务。 |
|
||
| `ProjectIndexPage` | Page | 项目列表页（`/projects/`），承载筛选与分页。 |
|
||
| `SkeletonProjectPage` | Page | 骨架项目详情页。 |
|
||
| `ArticleIndexPage` | Page | 文章列表。 |
|
||
| `ArticlePage` | Page | 评测、对比、避坑指南等内容文章。 |
|
||
|
||
模型归属：`HomePage` 在 `home` app（`wagtail start` 生成，沿用不改名）；其余 Page、Snippet 和文章模型集中在 `core` app（见本文第六节）。
|
||
|
||
**页面树结构（唯一权威）**：
|
||
|
||
```text
|
||
HomePage (/)
|
||
├── ScenarioIndexPage (/scenarios/)
|
||
│ └── ScenarioPage (/scenarios/{slug}/)
|
||
├── ProjectIndexPage (/projects/)
|
||
│ └── SkeletonProjectPage (/projects/{slug}/)
|
||
└── ArticleIndexPage (/articles/)
|
||
└── ArticlePage (/articles/{slug}/)
|
||
```
|
||
|
||
- 项目详情页统一挂在 `ProjectIndexPage` 下，**不挂在场景页下**：一个项目属于多个场景（多对多），而页面树上只能有一个父节点。
|
||
- `ScenarioPage` 没有子项目页；它通过查询 `SkeletonProjectPage.objects.live().filter(scenarios=...)` 渲染本场景的项目列表。
|
||
- 列表筛选与分页在 `ProjectIndexPage.get_context()` 中做服务端查询实现（参数契约见 3.4），**不另建独立 Django view**。
|
||
- `/languages/{slug}/`、`/frameworks/{slug}/` MVP 由筛选参数替代，不建 Page（见 `routes.md`）。
|
||
|
||
**Wagtail 实现注意**：Page 模型上的多对多字段（`scenarios`、`languages`、`frameworks`、`databases`、`features`）必须用 modelcluster 的 `ParentalManyToManyField`，不能用 Django 普通 `ManyToManyField`，否则后台编辑、草稿和预览会出错。
|
||
|
||
### 3.2 Snippet / 辅助模型
|
||
|
||
| 模型 | 说明 |
|
||
| --- | --- |
|
||
| `Language` | Python、TypeScript、Go、Java、PHP 等。 |
|
||
| `Framework` | Wagtail、Django、FastAPI、Next.js、Laravel 等。 |
|
||
| `DatabaseOption` | SQLite、PostgreSQL、MySQL、MongoDB 等。 |
|
||
| `SkeletonFeature` | Auth、Admin、Payment、SEO、Docker、Tests 等功能标签。 |
|
||
| `AiCodingScore` | **MVP 不建此模型**：评分维度即 `SkeletonProjectPage` 的 6 个分数字段（见 3.3），避免两处维护同一套维度。 |
|
||
| `SponsorSlot` | 后续赞助展示位置，MVP 可先不启用。 |
|
||
| `AffiliateLink` | 后续返佣链接，MVP 可先不启用。 |
|
||
|
||
### 3.3 `SkeletonProjectPage` 核心字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `title` | Wagtail Page title | 项目名称。 |
|
||
| `summary` | Text | 一句话简介。 |
|
||
| `github_url` | URL | GitHub 地址。 |
|
||
| `official_url` | URL，可空 | 官网或文档。 |
|
||
| `license_name` | Char | 开源协议。 |
|
||
| `scenarios` | 多对多 | 适合场景。一个骨架常同时适合多个场景（如 SaaS 和管理后台），必须按多对多实现，避免上线后再迁移。 |
|
||
| `languages` | 多选 | 使用语言。 |
|
||
| `frameworks` | 多选 | 使用框架。 |
|
||
| `databases` | 多选 | 支持数据库。 |
|
||
| `features` | 多选 | 功能标签。 |
|
||
| `maturity` | Choice | experimental / stable / mature。 |
|
||
| `maintenance_status` | Choice | active / slow / unknown / archived。 |
|
||
| `structure_score` | Integer 0-5 | 目录结构清晰度。 |
|
||
| `docs_score` | Integer 0-5 | 文档完整度。 |
|
||
| `tests_score` | Integer 0-5 | 测试可用性。 |
|
||
| `example_score` | Integer 0-5 | 示例模块完整度。 |
|
||
| `dependency_score` | Integer 0-5 | 依赖克制度。 |
|
||
| `incremental_score` | Integer 0-5 | 增量开发难度（agent 在既有模式中添加功能是否有清晰落点；含任务切片友好度）。 |
|
||
| `recommended_for` | RichText / StreamField | 适合什么情况。 |
|
||
| `not_recommended_for` | RichText / StreamField | 不适合什么情况。 |
|
||
| `review_notes` | RichText / StreamField | 编辑评测。 |
|
||
| `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 分项为唯一权威：目录结构、文档完整度、测试可用性、示例模块、依赖克制度、增量开发难度。
|
||
- **总分不单独录入**，由 6 个分项计算得出（总和 0-30，前台可换算为百分制展示），用模型 property 或注解实现，避免人工维护时总分和分项对不上。
|
||
- `business/` 下的文档引用本节，不得自行维护另一份维度清单。
|
||
- 每个项目除分数外必须有一句评语：为什么适合 / 不适合 AI coding。
|
||
|
||
### 3.4 URL 与筛选参数契约（唯一权威）
|
||
|
||
筛选条件必须可以通过 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&min_score=18
|
||
/projects/?q=admin&page=2
|
||
```
|
||
|
||
MVP 使用服务端查询和分页，不做前端复杂状态管理。
|
||
|
||
## 四、关键技术难点
|
||
|
||
| 难点 | 说明 | 应对 |
|
||
| --- | --- | --- |
|
||
| Wagtail 内容模型设计 | Page 和 Snippet 边界如果设计错，后续迁移成本高。 | 先实现最小字段，避免过度抽象；模型变化同步文档。 |
|
||
| SQLite 上线 | 读多写少可行，但并发写有限。 | MVP 不做前台写入；启用 WAL；设置迁移 PostgreSQL 条件。 |
|
||
| 筛选与 SEO | 筛选如果只靠前端状态，不利于搜索引擎和分享。 | 使用服务端查询和可分享 URL。 |
|
||
| 评分可信度 | AI 友好度评分容易主观。 | 固定评分维度，详情页展示评分理由。 |
|
||
| 赞助与推荐冲突 | 商业化会损害信任。 | Sponsored 必须显式标识，和编辑推荐分离。 |
|
||
|
||
## 五、推荐开发顺序
|
||
|
||
1. 初始化 Wagtail 项目骨架，确认 Python 3.12 + SQLite 可运行。
|
||
2. 建立基础 Page / Snippet 模型和迁移。
|
||
3. 在后台录入首批示例数据。
|
||
4. 实现首页、场景页、列表页、详情页。
|
||
5. 实现筛选、基础搜索、空状态。
|
||
6. 补 SEO、sitemap、robots、部署说明。
|
||
7. 上线前配置 SQLite WAL、备份策略、Nginx/Gunicorn。
|
||
|
||
## 六、项目结构建议
|
||
|
||
T-001 初始化后目标结构（与 `wagtail start skelet .` 的实际输出对齐）：
|
||
|
||
```text
|
||
skelet/
|
||
├── docs/
|
||
├── manage.py
|
||
├── requirements.txt
|
||
├── skelet/ # wagtail start 生成的配置包
|
||
│ ├── settings/ # base.py / dev.py / production.py
|
||
│ ├── urls.py
|
||
│ └── wsgi.py
|
||
├── home/ # wagtail start 生成，保留，承载 HomePage
|
||
├── search/ # wagtail start 生成，保留
|
||
├── core/ # 新建业务 app：Snippet、场景页、项目页、文章模型
|
||
│ ├── models.py
|
||
│ ├── templates/
|
||
│ ├── static/
|
||
│ └── tests.py
|
||
├── media/
|
||
└── README.md
|
||
```
|
||
|
||
**结构决策**：保留 `wagtail start` 生成的 `home` 和 `search` app；业务模型全部放在新建的 `core` app；测试放各 app 的 `tests.py`，暂不建独立 `tests/` 目录；`Dockerfile` 已删除。
|
||
|
||
已初始化：Wagtail 7.4.2 + Django 6.0.6，SQLite 可用，superuser `admin` 已创建。
|
||
|
||
## 七、架构纪律
|
||
|
||
- 业务事实和 schema 变化必须同步更新本文。
|
||
- 不在代码里发明文档没有的接口、字段和状态。
|
||
- 不把静态内容、用户数据、缓存数据混在一个模型里。
|
||
- 高风险模块先单独验证，再接入完整页面或流程。
|