skelet/docs/api.md

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 默认登录流程。