tkmind_go/documentation/docs/guides/plaza/04-backend-api.md

---
sidebar_position: 5
title: 后端 API 契约
sidebar_label: 后端 API
description: Plaza 和运营后台所有 API 的路由、请求/响应结构、权限规则和错误码
---

# 后端 API 契约

## 通用规范

- 所有路由前缀：`/api/plaza/v1/`
- 运营路由前缀：`/api/ops/v1/`
- 请求体格式：`application/json`
- 响应格式：`{ "data": ... }` 或 `{ "error": { "code": "...", "message": "..." } }`
- 分页：游标分页，参数 `cursor`（上一页最后一条的 `id`）和 `limit`（默认 20，最大 50）
- 所有写接口需要登录，读接口游客可访问
- 所有接口携带 `X-Request-ID` 响应头

---

## Plaza 公开 API

### GET /api/plaza/v1/feed

获取广场 Feed 列表（热门或最新）。

**权限**：无需登录

**Query 参数**：

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `sort` | `hot` \| `new` | `hot` | 排序方式 |
| `category` | string | - | 分类 slug，不传则全部 |
| `cursor` | string | - | 游标翻页 |
| `limit` | number | 20 | 每页数量 |

**响应**：

```json
{
  "data": {
    "posts": [ ... ],
    "featured": {
      "homepage_banner": [ ... ],
      "trending": [ ... ]
    },
    "next_cursor": "post_yyy",
    "has_more": true
  }
}
```

**精选与 Feed 合并规则**（Sprint 5 起）：

1. `featured.homepage_banner`：单独返回，前端渲染在 Feed 上方轮播，**不参与** `posts` 游标分页。
2. `featured.trending`：在 `sort=hot` 且 `cursor` 为空时，插入 `posts` 列表前 10 位（按 `plaza_featured.sort_order`），去重后其余位按 `hot_score` 填充。
3. Sprint 1–4：`featured` 字段为 `{ "homepage_banner": [], "trending": [] }`。

**单条 post 对象字段**（`posts` 数组元素、`GET /posts/:id` 同构）：

```json
{
  "id": "post_xxx",
  "title": "2025年Q2项目复盘报告",
  "summary": "本季度核心指标完成情况与下季度规划",
  "cover_url": "https://assets.go.tkmind.cn/...",
  "category": { "id": "cat_xxx", "name": "职场报告", "slug": "work-report" },
  "tags": ["复盘", "季度报告"],
  "author": {
    "user_id": "user_xxx",
    "slug": "zhangsan",
    "display_name": "张三",
    "avatar_url": "https://..."
  },
  "stats": {
    "view_count": 1234,
    "like_count": 89,
    "collect_count": 23,
    "comment_count": 15
  },
  "viewer_reacted": { "liked": false, "collected": true },
  "published_at": "2025-06-12T10:30:00Z"
}
```

`viewer_reacted` 仅登录用户返回，游客为 `null`。

---

### GET /api/plaza/v1/posts/:id

获取单个帖子详情。

**权限**：无需登录

**响应**：同 feed 中的单条 post 对象，额外包含：

```json
{
  "data": {
    "post": {
      ...上方字段...,
      "publication_url": "https://go.tkmind.cn/u/zhangsan/pages/q2-report",
      "allow_comment": true
    }
  }
}
```

---

### POST /api/plaza/v1/posts

将已发布的 MindSpace 页面发布到广场。

**权限**：需要登录，`publication_id` 必须归属当前用户

**请求体**：

```json
{
  "publication_id": "pub_xxx",
  "category_id": "cat_xxx",
  "tags": ["复盘", "季度报告"],
  "cover_url": "https://...",     // 可选，不传则用 publication 的封面
  "allow_comment": true
}
```

**业务校验**：

1. `publication_id` 对应的 publication `status = online`，否则返回 `PUBLICATION_NOT_ONLINE`。
2. 该 `publication_id` 在 `plaza_posts` 中已存在 → 返回 `409 ALREADY_PUBLISHED`（**创建接口不支持更新**，更新走 `PATCH`）。
3. 当前用户未被运营封禁发帖权限，否则返回 `POST_PERMISSION_DENIED`。
4. 执行内容二次安全扫描（异步），帖子先以 `status = pending_review` 入库；扫描通过且（人工或自动）审核通过后变为 `published`。

**Feed 可见性**：仅 `status = published` 的帖子出现在公开 Feed；`pending_review` 仅作者本人在 MindSpace「我的广场帖」可见（Sprint 1 可暂不实现作者视图，但不得出现在 `/plaza`）。

---

### PATCH /api/plaza/v1/posts/:id

更新已发布到广场的帖子元数据（分类、标签、封面、是否允许评论）。

**权限**：需要登录，只能操作自己的帖子

**请求体**（字段均可选，至少传一项）：

```json
{
  "category_id": "cat_xxx",
  "tags": ["复盘"],
  "cover_url": "https://...",
  "allow_comment": false
}
```

**约束**：不可更换 `publication_id`；若帖子 `status = rejected`，PATCH 后重新进入 `pending_review`。

**响应**：

```json
{
  "data": {
    "post": {
      "id": "post_xxx",
      "status": "pending_review"
    }
  }
}
```

---

### DELETE /api/plaza/v1/posts/:id

将帖子从广场撤回（仅 status 改为 hidden，不物理删除）。

**权限**：需要登录，只能操作自己的帖子

---

### POST /api/plaza/v1/posts/:id/reports

举报帖子。

**权限**：需要登录

**请求体**：`{ "reason": "spam", "detail": "可选说明" }`（`reason` 枚举见 [06-ops-platform](./06-ops-platform)）

**响应**：`201`

---

### POST /api/plaza/v1/comments/:id/reports

举报评论。

**权限**：需要登录

**请求体**：同帖子举报 `{ "reason": "spam", "detail": "可选说明" }`

**响应**：`201`

---

### GET /api/plaza/v1/categories

获取所有分类列表。

**权限**：无需登录

**响应**：

```json
{
  "data": {
    "categories": [
      {
        "id": "cat_xxx",
        "name": "职场报告",
        "slug": "work-report",
        "icon": "📊",
        "post_count": 1234
      }
    ]
  }
}
```

---

### GET /api/plaza/v1/users/:slug

获取用户广场主页信息。

**权限**：无需登录

`stats.total_likes`：对该用户所有 `status = published` 帖子的 `like_count` 求和（见 [02-data-model](./02-data-model)）。

**响应**：

```json
{
  "data": {
    "user": {
      "user_id": "user_xxx",
      "slug": "zhangsan",
      "display_name": "张三",
      "avatar_url": "https://...",
      "bio": "数据分析师，喜欢用 AI 做报告",
      "stats": {
        "post_count": 12,
        "follower_count": 234,
        "following_count": 56,
        "total_likes": 1890
      },
      "viewer_following": false
    },
    "recent_posts": [ ...最新 6 篇帖子... ]
  }
}
```

---

### GET /api/plaza/v1/users/:slug/posts

获取用户发布的帖子列表（分页）。

**权限**：无需登录

---

## 互动 API

### POST /api/plaza/v1/posts/:id/reactions

点赞、收藏或标记分享。

**权限**：需要登录

**请求体**：

```json
{ "type": "like" }   // like | collect | share
```

**幂等**：同一用户同一帖子同类型重复请求返回 200，不报错。

---

### DELETE /api/plaza/v1/posts/:id/reactions/:type

取消点赞或收藏。

**权限**：需要登录，只能取消自己的 reaction

---

### GET /api/plaza/v1/posts/:id/comments

获取帖子评论列表。

**权限**：无需登录

**Query 参数**：`cursor`、`limit`、`parent_id`（获取某条评论的回复时传入）

**响应**：

```json
{
  "data": {
    "comments": [
      {
        "id": "cmt_xxx",
        "content": "写得很好！",
        "author": {
          "user_id": "user_xxx",
          "slug": "lisi",
          "display_name": "李四",
          "avatar_url": "https://..."
        },
        "like_count": 5,
        "reply_count": 2,
        "viewer_liked": false,
        "created_at": "2025-06-12T11:00:00Z",
        "status": "visible"
      }
    ],
    "next_cursor": "cmt_yyy",
    "has_more": false
  }
}
```

---

### POST /api/plaza/v1/posts/:id/comments

发表评论。

**权限**：需要登录

**请求体**：

```json
{
  "content": "写得很好！",
  "parent_id": null      // 回复二级时传一级评论 ID
}
```

**校验**：

- `content` 不能为空，最长 500 字符。
- `parent_id` 如果传入，必须是该帖子的一级评论（`parent_id IS NULL`），不允许三级嵌套。
- `plaza_posts.allow_comment = 1` 才允许评论，否则返回 `COMMENT_DISABLED`。

---

### DELETE /api/plaza/v1/comments/:id

删除自己的评论（软删除）。

**权限**：需要登录，只能删除自己的评论

---

### POST /api/plaza/v1/comments/:id/reactions

点赞评论。

**权限**：需要登录

---

## 关注 API

### POST /api/plaza/v1/users/:slug/follow

关注用户。

**权限**：需要登录，不能关注自己

---

### DELETE /api/plaza/v1/users/:slug/follow

取消关注。

**权限**：需要登录

---

## 运营 API（/api/ops/v1/）

所有运营 API 需要 `ops_role` 为 `reviewer`、`editor` 或 `ops_admin` 的用户。平台 `role = admin` **不等于** `ops_admin`，需在 `h5_users.ops_role` 单独分配。

> **双审核入口**：Sprint 1 保留 `/admin-api/plaza/posts/:id/review`（`requireAdmin`）；Sprint 5 起运营主路径为 `/api/ops/v1/review/*`。两路径均写入 `ops_audit_log`（admin 路径由服务端桥接 `reviewPostAsOps`）。

### GET /api/ops/v1/review/queue

获取待审核帖子队列。

**Query 参数**：`status`（默认 `pending_review`）、`cursor`、`limit`

---

### POST /api/ops/v1/review/posts/:id

审核单个帖子。

**请求体**：

```json
{
  "action": "approve",           // approve | reject | hide
  "reason": "内容违规：含广告"   // reject/hide 时必填
}
```

**副作用**：
- `approve` → `plaza_posts.status = published`，写入 `ops_audit_log`
- `reject` → `plaza_posts.status = rejected`，通知发布者，写入日志
- `hide` → `plaza_posts.status = hidden`，写入日志

---

### POST /api/ops/v1/review/batch

批量审核帖子（`editor` 及以上）。

**请求体**：

```json
{
  "post_ids": ["post_a", "post_b"],
  "action": "approve",
  "reason": null
}
```

**响应**：`{ "data": { "posts": [ { "id": "...", "status": "published" } ] } }`

---

### POST /api/ops/v1/featured

设置精选内容。

**请求体**：

```json
{
  "post_id": "post_xxx",
  "position": "homepage_banner",   // homepage_banner | category_top | trending
  "expires_at": "2025-06-20T00:00:00Z"
}
```

---

### GET /api/ops/v1/analytics/overview

广场数据概览（日/周数据）。

**响应**字段：新帖数、发布转化率、日活、分类分布、TOP 创作者、违规比率。

---

## 错误码

| 错误码 | HTTP 状态 | 含义 |
| --- | --- | --- |
| `PUBLICATION_NOT_ONLINE` | 422 | 发布源不是在线状态 |
| `ALREADY_PUBLISHED` | 409 | 该 publication 已发布到广场 |
| `POST_NOT_FOUND` | 404 | 帖子不存在或已隐藏 |
| `POST_PERMISSION_DENIED` | 403 | 无发帖权限（被封禁） |
| `COMMENT_DISABLED` | 422 | 该帖子已关闭评论 |
| `COMMENT_TOO_LONG` | 422 | 评论超出 500 字符 |
| `REPLY_DEPTH_EXCEEDED` | 422 | 不允许三级嵌套回复 |
| `SELF_FOLLOW` | 422 | 不能关注自己 |
| `OPS_PERMISSION_DENIED` | 403 | 非运营角色访问运营接口 |

---

## 与 MindSpace 的联动

### publication 下线时自动隐藏广场帖子

在现有 MindSpace 下线 publication 的事务中，增加：

```sql
UPDATE plaza_posts
SET status = 'hidden', updated_at = :now_ms
WHERE publication_id = :publication_id
  AND status != 'hidden';
```

实现位置：`ui/h5/mindspace-publications.mjs` 的 offline 流程，与现有事件写入同一连接事务。

### 广场互动数据回写 MindSpace

通过后台定时任务（每小时），在同一 MySQL 实例内将广场计数汇总到 `h5_publish_records`：

```sql
UPDATE h5_publish_records p
JOIN plaza_posts pp ON pp.publication_id = p.id
SET p.plaza_view_count = pp.view_count,
    p.plaza_like_count = pp.like_count
WHERE pp.updated_at > :last_sync_time;
```

- **不**调用 MindSpace service 函数；字段定义与迁移由 MindSpace/Plaza 共用 `db.mjs` 维护。
- 回写失败不影响广场读写，下次任务重试。