chengshishouce/city-manual/docs/API.md

# 城市手册 - 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/`