Add harness coding documentation

docs/api.md

@@ -0,0 +1,78 @@
+# 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 默认登录流程。