# API / 模块合约

> MVP 是服务端渲染内容站，不提供公开业务 API。本文记录 Wagtail/Django 边界和后续 API 扩展原则。

## 通用约定

- 前台页面：Django / Wagtail 服务端渲染 HTML。
- 后台管理：Wagtail Admin Session。
- MVP 公开 API：无。
- 时间格式：后台和数据库使用 Django 默认时区配置；前台展示按站点配置格式化。
- 未登录访问后台：由 Wagtail Admin 重定向到登录页。

## MVP 页面输入合约

MVP 的“接口”主要是 URL 参数。

### `GET /projects/`

查询参数：

| 参数 | 说明 |
| --- | --- |
| `scenario` | 场景 slug，可选。 |
| `language` | 语言 slug，可选。 |
| `framework` | 框架 slug，可选。 |
| `database` | 数据库 slug，可选。 |
| `min_ai_score` | AI 友好度最低分，可选。 |
| `q` | 基础搜索关键词，可选。 |

响应：HTML 页面，展示匹配项目列表、当前筛选条件和空状态。

### `GET /projects/{slug}/`

响应：HTML 页面，展示骨架项目详情。

必须包含：

- 项目名称和简介。
- GitHub / 官网链接。
- 技术栈。
- 适合场景和不适合场景。
- AI 友好度评分和评分理由。
- 维护状态。
- 推荐理由。
- Sponsored 标识，如适用。

## 后台内容边界

后台使用 Wagtail Admin，不单独开发自定义管理 API。

管理员可维护：

- `SkeletonProjectPage`
- `ScenarioPage`
- `ArticlePage`
- `Language`
- `Framework`
- `DatabaseOption`
- `SkeletonFeature`

## 后续 API 原则

只有出现以下需求时才新增 API：

- 前台异步筛选必须无刷新更新。
- 用户提交骨架项目。
- 外部系统读取项目数据库。
- GitHub 数据同步任务需要内部端点。

新增 API 前必须先更新本文，至少写清路径、鉴权方式、请求字段、响应字段、错误码、幂等性和频率限制。

## 错误与降级

- 筛选无结果：展示空状态，不返回 500。
- slug 不存在：返回 404 页面。
- 外部链接为空：不展示链接按钮。
- Sponsored 项目：必须展示赞助标识。
- 后台未登录：使用 Wagtail 默认登录流程。