CMate 后台 API 文档

# CMate 后台 API 文档

- 基础路径：`/api`
- 内容类型：`application/json`
- 认证方式：部分接口需要在请求头携带 `Authorization: Bearer <token>`（见 `src/middlewares/auth.ts:1-18`）
- 速率限制：服务端开启全局限流（见 `src/app.ts:14-18`），具体数值由环境变量配置

## 通用响应格式
- 成功：`{ "success": true, "data": <数据> }`
- 失败：`{ "success": false, "error": <错误码> }`
- 常见错误码：`invalid_body`、`email_exists`、`invalid_credentials`、`unauthorized`、`not_found`、`internal_error`

---

## 认证 Auth
- 路由前缀：`/api/auth`（见 `src/routes/index.ts:8-12` 与 `src/modules/auth/routes.ts:9-12`）

### 注册
- 方法与路径：`POST /api/auth/register`
- 请求体：
  ```json
  { "username": "string(>=2)", "email": "email", "password": "string(>=6)" }
  ```
- 成功响应：`200`
  ```json
  {
    "success": true,
    "data": {
      "user": { "id": "string", "username": "string", "email": "string" },
      "token": "JWT"
    }
  }
  ```
- 可能错误：`400 invalid_body`、`409 email_exists`、`500 internal_error`

### 登录
- 方法与路径：`POST /api/auth/login`
- 请求体：
  ```json
  { "email": "email", "password": "string(>=6)" }
  ```
- 成功响应：`200`（结构同注册）
- 可能错误：`400 invalid_body`、`401 invalid_credentials`、`500 internal_error`

---

## 微信小程序 WeChat Mini Program
- 路由前缀：`/api/wechat`

### 登录（code2Session）
- 方法与路径：`POST /api/wechat/login`
- 请求体：
  ```json
  { "code": "wx.login() 返回的 js_code" }
  ```
- 成功响应：`200`
  ```json
  {
    "success": true,
    "data": {
      "user": { "id": "string", "username": "string" },
      "token": "JWT"
    }
  }
  ```
- 说明：服务端使用 `WX_APPID` 和 `WX_SECRET` 调用微信 `jscode2session`，绑定/创建用户并签发 JWT；后续受保护接口使用该 `token`。

### 实时消息流（SSE，Web 客户端）
- 方法与路径：`GET /api/messages/stream?token=<JWT>`
- 事件：`message.receive`、`message.read`（详见“帖子 Posts/关系 Relationships/消息 Messages”模块）
- 说明：微信小程序推荐使用 WebSocket（`wx.connectSocket`）；当前服务端已提供 SSE，Web 管理端可直接使用。

## 用户 Users
- 路由前缀：`/api/users`（见 `src/routes/index.ts:9-12` 与 `src/modules/users/routes.ts:9-12`）

### 获取用户资料
- 方法与路径：`GET /api/users/:id`
- 成功响应：`200`
  ```json
  {
    "success": true,
    "data": { "id": "string", "username": "string", "email": "string", "createdAt": "ISODate" }
  }
  ```
- 可能错误：`404 not_found`、`500 internal_error`

### 获取粉丝列表
- 方法与路径：`GET /api/users/:id/followers`
- 成功响应：`200`
  ```json
  {
    "success": true,
    "data": [ { "id": "string", "username": "string", "email": "string", "createdAt": "ISODate" } ]
  }
  ```

### 获取关注列表
- 方法与路径：`GET /api/users/:id/following`
- 成功响应：`200`
  ```json
  {
    "success": true,
    "data": [ { "id": "string", "username": "string", "email": "string", "createdAt": "ISODate" } ]
  }
  ```

---

## 关系 Relationships
- 路由前缀：`/api/relationships`（见 `src/routes/index.ts:10-12` 与 `src/modules/relationships/routes.ts:9-12`）
- 认证：需要 `Authorization: Bearer <token>`（见 `src/middlewares/auth.ts:6-18`）

### 关注用户
- 方法与路径：`POST /api/relationships/users/:id/follow`
- 成功响应：`204`（无响应体）
- 可能错误：`400 invalid_target`、`401 unauthorized`、`500 internal_error`

### 取消关注
- 方法与路径：`DELETE /api/relationships/users/:id/follow`
- 成功响应：`204`（无响应体）
- 可能错误：`401 unauthorized`

---

## 帖子 Posts
- 路由前缀：`/api/posts`（见 `src/routes/index.ts:11-12` 与 `src/modules/posts/routes.ts:10-18`）

### 列表
- 方法与路径：`GET /api/posts`
- 成功响应：`200`
  ```json
  {
    "success": true,
    "data": [
      {
        "id": "string",
        "authorId": "string",
        "content": "string",
        "createdAt": "ISODate",
        "author": { "id": "string", "username": "string" }
      }
    ]
  }
  ```

### 创建（需认证）
- 方法与路径：`POST /api/posts`
- 认证：`Authorization: Bearer <token>`
- 请求体：
  ```json
  { "content": "string(1..1024)" }
  ```
- 成功响应：`201`
  ```json
  {
    "success": true,
    "data": {
      "id": "string",
      "authorId": "string",
      "content": "string",
      "createdAt": "ISODate",
      "author": { "id": "string", "username": "string" }
    }
  }
  ```
- 可能错误：`400 invalid_body`、`401 unauthorized`

### 获取详情
- 方法与路径：`GET /api/posts/:id`
- 成功响应：`200`（结构同创建返回的 `data`）
- 可能错误：`404 not_found`

### 添加评论（需认证）
- 方法与路径：`POST /api/posts/:id/comments`
- 请求体：
  ```json
  { "content": "string(1..512)" }
  ```
- 成功响应：`201`
  ```json
  {
    "success": true,
    "data": { "id": "string", "postId": "string", "authorId": "string", "content": "string", "createdAt": "ISODate" }
  }
  ```
- 可能错误：`400 invalid_body`、`401 unauthorized`

### 评论列表
- 方法与路径：`GET /api/posts/:id/comments`
- 成功响应：`200`
  ```json
  {
    "success": true,
    "data": [ { "id": "string", "postId": "string", "authorId": "string", "content": "string", "createdAt": "ISODate" } ]
  }
  ```

### 点赞（需认证）
- 方法与路径：`POST /api/posts/:id/likes`
- 成功响应：`204`（无响应体；重复点赞也返回 `204`）
- 可能错误：`401 unauthorized`

### 取消点赞（需认证）
- 方法与路径：`DELETE /api/posts/:id/likes`
- 成功响应：`204`（无响应体）
- 可能错误：`401 unauthorized`

### 点赞数量
- 方法与路径：`GET /api/posts/:id/likes/count`
- 成功响应：`200`
  ```json
  { "success": true, "data": { "count": 0 } }
  ```

---

## 示例流程
```http
POST /api/auth/register
Authorization: (无)
Content-Type: application/json

{ "username": "bob", "email": "bob@example.com", "password": "secret123" }
```
```http
POST /api/posts
Authorization: Bearer <token>
Content-Type: application/json

{ "content": "hello from bob" }
```

> 参考实现：`src/modules/*/controller.ts`、`src/modules/*/routes.ts`、`src/middlewares/auth.ts`