79 lines
2.1 KiB
Markdown
79 lines
2.1 KiB
Markdown
|
# 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 默认登录流程。
|