skelet/docs/04-architecture.md

# 架构设计

> 本文讲“怎么把技术栈搭起来”：系统结构、职责划分、数据模型、技术难点、开发顺序。

## 一、系统结构

```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 服务。 |
| `SkeletonProjectPage` | Page | 骨架项目详情页。 |
| `ArticleIndexPage` | Page | 文章列表。 |
| `ArticlePage` | Page | 评测、对比、避坑指南等内容文章。 |

### 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` | AI 友好度评分维度定义。 |
| `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 | 是否赞助展示，必须前台标识。 |

**评分模型纪律（唯一权威定义）**：

- AI Coding 友好度评分维度以上表 6 个 0-5 分项为唯一权威：目录结构、文档完整度、测试可用性、示例模块、依赖克制度、增量开发难度。
- **总分不单独录入**，由 6 个分项计算得出（总和 0-30，前台可换算为百分制展示），用模型 property 或注解实现，避免人工维护时总分和分项对不上。
- `business/` 下的文档引用本节，不得自行维护另一份维度清单。
- 每个项目除分数外必须有一句评语：为什么适合 / 不适合 AI coding。

### 3.4 URL 与筛选

筛选条件必须可以通过 URL 表达，便于 SEO 和分享：

```text
/scenarios/saas/
/scenarios/saas/?language=python
/projects/?framework=wagtail&database=sqlite
```

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 初始化后目标结构：

```text
skelet/
├── docs/
├── manage.py
├── requirements.txt
├── skelet/
│   ├── settings/
│   ├── urls.py
│   └── wsgi.py
├── core/
│   ├── models.py
│   ├── templates/
│   └── static/
├── tests/
├── media/
└── README.md
```

实际路径以初始化后的 Wagtail 项目为准；初始化完成后必须更新本文和 `current-state.md`。

## 七、架构纪律

- 业务事实和 schema 变化必须同步更新本文。
- 不在代码里发明文档没有的接口、字段和状态。
- 不把静态内容、用户数据、缓存数据混在一个模型里。
- 高风险模块先单独验证，再接入完整页面或流程。