skelet/docs/04-architecture.md

架构设计

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

一、系统结构

游客 / 搜索引擎 / 后台编辑者
  |
  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 和分享：

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

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