docs: 添加项目文档和 AgentSkills

- 添加架构文档 (ARCHITECTURE.md) - 添加 API 文档 (API.md) - 添加文档索引 (docs/README.md) - 添加部署技能 (skills/city-manual-deploy/SKILL.md) - 添加测试技能 (skills/city-manual-test/SKILL.md) - 添加内容管理技能 (skills/city-manual-content/SKILL.md)
2026-04-12 13:36:21 +00:00
parent 572a06a12c
commit 81632c1b35
6 changed files with 1772 additions and 0 deletions
--- a/city-manual/docs/API.md
+++ b/city-manual/docs/API.md
@@ -0,0 +1,541 @@
+# 城市手册 - API 文档
+
+## 1. API 概述
+
+### 1.1 基础信息
+
+- **Base URL:** `http://localhost:8000/api`
+- **认证方式:** JWT Bearer Token
+- **数据格式:** JSON
+- **GraphQL 端点:** `http://localhost:8000/graphql/`
+
+### 1.2 认证
+
+所有需要认证的接口需要在 Header 中携带 JWT Token：
+
+```
+Authorization: Bearer <access_token>
+```
+
+### 1.3 错误响应
+
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "错误描述",
+    "details": {}
+  }
+}
+```
+
+## 2. 用户认证 API
+
+### 2.1 用户注册
+
+**POST** `/api/users/`
+
+**请求：**
+```json
+{
+  "username": "string",
+  "email": "string",
+  "password": "string",
+  "phone": "string"
+}
+```
+
+**响应：**
+```json
+{
+  "id": 1,
+  "username": "string",
+  "email": "string",
+  "phone": "string",
+  "role": "user",
+  "created_at": "2026-04-12T00:00:00Z"
+}
+```
+
+### 2.2 用户登录
+
+**POST** `/api/auth/token/`
+
+**请求：**
+```json
+{
+  "username": "string",
+  "password": "string"
+}
+```
+
+**响应：**
+```json
+{
+  "access": "eyJ0eXAiOiJKV1QiLCJhbGc...",
+  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
+}
+```
+
+### 2.3 刷新令牌
+
+**POST** `/api/auth/token/refresh/`
+
+**请求：**
+```json
+{
+  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
+}
+```
+
+**响应：**
+```json
+{
+  "access": "eyJ0eXAiOiJKV1QiLCJhbGc..."
+}
+```
+
+### 2.4 获取当前用户信息
+
+**GET** `/api/users/me/`
+
+**Headers:**
+```
+Authorization: Bearer <access_token>
+```
+
+**响应：**
+```json
+{
+  "id": 1,
+  "username": "string",
+  "email": "string",
+  "phone": "string",
+  "role": "user",
+  "avatar": "url",
+  "created_at": "2026-04-12T00:00:00Z"
+}
+```
+
+### 2.5 更新用户信息
+
+**PUT** `/api/users/me/`
+
+**请求：**
+```json
+{
+  "username": "string",
+  "email": "string",
+  "phone": "string",
+  "avatar": "url"
+}
+```
+
+## 3. 版块管理 API
+
+### 3.1 获取版块列表
+
+**GET** `/api/regions/`
+
+**查询参数：**
+- `level` - 版块级别（province/city/county/town/village）
+- `parent` - 上级版块 ID
+- `search` - 搜索关键词
+
+**响应：**
+```json
+{
+  "count": 100,
+  "next": "url",
+  "previous": "url",
+  "results": [
+    {
+      "id": 1,
+      "name": "广东省",
+      "level": "province",
+      "parent": null,
+      "children": [],
+      "moderator_count": 5,
+      "article_count": 100
+    }
+  ]
+}
+```
+
+### 3.2 获取版块详情
+
+**GET** `/api/regions/{id}/`
+
+**响应：**
+```json
+{
+  "id": 1,
+  "name": "深圳市",
+  "level": "city",
+  "parent": {
+    "id": 1,
+    "name": "广东省"
+  },
+  "children": [
+    {"id": 2, "name": "南山区"},
+    {"id": 3, "name": "福田区"}
+  ],
+  "description": "description",
+  "moderator_count": 3,
+  "article_count": 50,
+  "service_count": 20,
+  "created_at": "2026-04-12T00:00:00Z"
+}
+```
+
+### 3.3 创建版块
+
+**POST** `/api/regions/`
+
+**权限：** 管理员
+
+**请求：**
+```json
+{
+  "name": "string",
+  "level": "city",
+  "parent": 1,
+  "description": "string"
+}
+```
+
+## 4. 内容管理 API
+
+### 4.1 获取文章列表
+
+**GET** `/api/articles/`
+
+**查询参数：**
+- `region` - 版块 ID
+- `category` - 分类（history/culture/practical/life）
+- `status` - 状态（draft/pending/published/rejected）
+- `search` - 搜索关键词
+
+**响应：**
+```json
+{
+  "count": 100,
+  "results": [
+    {
+      "id": 1,
+      "title": "深圳历史",
+      "region": {"id": 1, "name": "深圳市"},
+      "category": "history",
+      "author": {"id": 1, "username": "author"},
+      "status": "published",
+      "view_count": 1000,
+      "like_count": 50,
+      "comment_count": 10,
+      "created_at": "2026-04-12T00:00:00Z",
+      "updated_at": "2026-04-12T00:00:00Z"
+    }
+  ]
+}
+```
+
+### 4.2 获取文章详情
+
+**GET** `/api/articles/{id}/`
+
+**响应：**
+```json
+{
+  "id": 1,
+  "title": "深圳历史",
+  "content": "markdown content",
+  "region": {"id": 1, "name": "深圳市"},
+  "category": "history",
+  "author": {"id": 1, "username": "author"},
+  "status": "published",
+  "view_count": 1000,
+  "like_count": 50,
+  "comment_count": 10,
+  "tags": ["历史", "文化"],
+  "created_at": "2026-04-12T00:00:00Z",
+  "updated_at": "2026-04-12T00:00:00Z"
+}
+```
+
+### 4.3 创建文章
+
+**POST** `/api/articles/`
+
+**权限：** 认证用户
+
+**请求：**
+```json
+{
+  "title": "string",
+  "content": "markdown content",
+  "region": 1,
+  "category": "history",
+  "tags": ["tag1", "tag2"]
+}
+```
+
+### 4.4 更新文章
+
+**PUT** `/api/articles/{id}/`
+
+**权限：** 作者或版主或管理员
+
+**请求：**
+```json
+{
+  "title": "string",
+  "content": "markdown content",
+  "category": "history",
+  "tags": ["tag1", "tag2"]
+}
+```
+
+### 4.5 删除文章
+
+**DELETE** `/api/articles/{id}/`
+
+**权限：** 作者或版主或管理员
+
+## 5. 特色服务 API
+
+### 5.1 获取特色服务列表
+
+**GET** `/api/services/`
+
+**查询参数：**
+- `region` - 版块 ID
+- `category` - 分类（clothing/food/accommodation/transportation/entertainment/tourism/culture）
+- `status` - 状态
+
+**响应：**
+```json
+{
+  "count": 100,
+  "results": [
+    {
+      "id": 1,
+      "name": "深圳湾公园",
+      "region": {"id": 1, "name": "深圳市"},
+      "category": "tourism",
+      "description": "description",
+      "rating": 4.5,
+      "rating_count": 100,
+      "status": "published",
+      "created_at": "2026-04-12T00:00:00Z"
+    }
+  ]
+}
+```
+
+### 5.2 获取特色服务详情
+
+**GET** `/api/services/{id}/`
+
+**响应：**
+```json
+{
+  "id": 1,
+  "name": "深圳湾公园",
+  "description": "description",
+  "region": {"id": 1, "name": "深圳市"},
+  "category": "tourism",
+  "address": "地址",
+  "contact": "联系方式",
+  "images": ["url1", "url2"],
+  "rating": 4.5,
+  "rating_count": 100,
+  "status": "published",
+  "author": {"id": 1, "username": "author"},
+  "created_at": "2026-04-12T00:00:00Z"
+}
+```
+
+### 5.3 创建特色服务
+
+**POST** `/api/services/`
+
+**请求：**
+```json
+{
+  "name": "string",
+  "description": "string",
+  "region": 1,
+  "category": "tourism",
+  "address": "string",
+  "contact": "string",
+  "images": ["url1", "url2"]
+}
+```
+
+## 6. 互动功能 API
+
+### 6.1 评论
+
+**GET** `/api/comments/`
+
+查询参数：
+- `object_type` - 对象类型（article/service）
+- `object_id` - 对象 ID
+
+**POST** `/api/comments/`
+
+**请求：**
+```json
+{
+  "content": "string",
+  "object_type": "article",
+  "object_id": 1
+}
+```
+
+### 6.2 评分
+
+**POST** `/api/ratings/`
+
+**请求：**
+```json
+{
+  "score": 5,
+  "object_type": "service",
+  "object_id": 1
+}
+```
+
+### 6.3 点赞
+
+**POST** `/api/likes/`
+
+**请求：**
+```json
+{
+  "object_type": "article",
+  "object_id": 1
+}
+```
+
+### 6.4 收藏
+
+**POST** `/api/favorites/`
+
+**请求：**
+```json
+{
+  "object_type": "region",
+  "object_id": 1
+}
+```
+
+**GET** `/api/favorites/`
+
+获取当前用户的收藏列表
+
+## 7. 版主管理 API
+
+### 7.1 申请版主
+
+**POST** `/api/moderator-applications/`
+
+**请求：**
+```json
+{
+  "region": 1,
+  "reason": "申请理由"
+}
+```
+
+### 7.2 获取版主申请列表
+
+**GET** `/api/moderator-applications/`
+
+**权限：** 管理员
+
+### 7.3 审核版主申请
+
+**POST** `/api/moderator-applications/{id}/review/`
+
+**权限：** 管理员
+
+**请求：**
+```json
+{
+  "status": "approved",
+  "reason": "审核意见"
+}
+```
+
+### 7.4 获取版主权限
+
+**GET** `/api/moderator-permissions/`
+
+**权限：** 版主
+
+## 8. GraphQL API
+
+### 8.1 查询示例
+
+```graphql
+query {
+  region(id: 1) {
+    id
+    name
+    level
+    children {
+      id
+      name
+    }
+    articles {
+      id
+      title
+      author {
+        username
+      }
+    }
+  }
+}
+```
+
+### 8.2 变更示例
+
+```graphql
+mutation {
+  createArticle(input: {
+    title: "深圳历史"
+    content: "内容"
+    region: 1
+    category: HISTORY
+  }) {
+    article {
+      id
+      title
+      status
+    }
+  }
+}
+```
+
+## 9. 错误码
+
+| 错误码 | 说明 |
+|--------|------|
+| `AUTH_FAILED` | 认证失败 |
+| `PERMISSION_DENIED` | 权限不足 |
+| `NOT_FOUND` | 资源不存在 |
+| `VALIDATION_ERROR` | 参数验证错误 |
+| `DUPLICATE` | 重复资源 |
+| `INVALID_STATUS` | 无效状态 |
+
+## 10. 速率限制
+
+- 未认证用户：100 请求/小时
+- 认证用户：1000 请求/小时
+- 管理员：无限制
+
+## 11. 版本控制
+
+当前 API 版本：`v1`
+
+版本格式：`/api/v1/`