# 专题内容数据表与 API 结构

适用专题：`2026年内蒙古自治区旅游发展大会`

## 本地启动

在目录 `C:\Users\Administrator\Documents\Codex\2026-07-08\wo\outputs\inner-mongolia-tourism-topic` 中执行：

```powershell
pnpm install
node .\server.js
```

启动后可访问：

- 前台专题页：`http://127.0.0.1:3086/index.html`
- 后台发布页：`http://127.0.0.1:3086/admin.html`
- 健康检查：`http://127.0.0.1:3086/api/health`

## 环境变量

### 1. 本地文件模式

默认不配环境变量即可运行：

```powershell
$env:DATA_DRIVER="file"
```

### 2. MySQL / RDS 模式

切到阿里云 RDS 时，配置：

```powershell
$env:DATA_DRIVER="mysql"
$env:MYSQL_URL="mysql://user:password@rm-xxxx.mysql.rds.aliyuncs.com:3306/zhuanti_db"
```

然后先执行 [mysql-schema.sql](/C:/Users/Administrator/Documents/Codex/2026-07-08/wo/outputs/inner-mongolia-tourism-topic/mysql-schema.sql) 建表。

### 3. OSS 上传模式

后台图片和视频直传需要这些环境变量：

```powershell
$env:OSS_BUCKET="your-bucket"
$env:OSS_REGION="cn-hongkong"
$env:OSS_ACCESS_KEY_ID="LTAI..."
$env:OSS_ACCESS_KEY_SECRET="your-secret"
$env:OSS_DIR_PREFIX="topics"
$env:OSS_PUBLIC_BASE_URL="https://your-bucket.oss-cn-hongkong.aliyuncs.com"
```

---

## 1. 数据表建议

### `topics`

用途：保存专题级配置与前台展示基础信息。

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | varchar(64) | 专题主键 |
| `title` | varchar(255) | 专题标题 |
| `summary` | text | 首屏导语 |
| `brief` | text | 专题摘要 |
| `status` | varchar(32) | 预热中 / 进行中 / 已归档 |
| `status_label` | varchar(64) | 前台状态文案 |
| `phase` | varchar(64) | 会前 / 会中 / 会后 |
| `scene` | varchar(128) | 使用场景 |
| `shift` | varchar(128) | 值班说明 |
| `hero_image` | varchar(255) | 主视觉地址 |
| `seo_title` | varchar(255) | SEO 标题 |
| `seo_description` | varchar(255) | SEO 描述 |
| `updated_at` | datetime | 最近更新时间 |
| `created_at` | datetime | 创建时间 |

### `topic_contents`

用途：专题内容主表，图文、视频、直播、外链统一落在这里。

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | varchar(64) | 内容主键 |
| `topic_id` | varchar(64) | 所属专题 |
| `title` | varchar(255) | 标题 |
| `summary` | text | 摘要 |
| `content_type` | varchar(32) | `article / video / live / link` |
| `source_type` | varchar(32) | `official / media / video / social` |
| `display_column` | varchar(64) | 前台展示栏目 |
| `verify_status` | varchar(32) | 待审 / 已审核 / 后台发布 / 直播中 |
| `publish_time` | datetime | 对外发布时间 |
| `featured` | tinyint(1) | 是否进入焦点位 |
| `sort_order` | int | 前台排序 |
| `origin_url` | varchar(512) | 原文链接 |
| `cover_image` | varchar(255) | 封面图地址 |
| `media_url` | varchar(512) | 视频 / 直播 / 媒体地址 |
| `body_json` | json | 正文结构化内容 |
| `created_by` | varchar(64) | 发布人 |
| `created_at` | datetime | 创建时间 |
| `updated_at` | datetime | 更新时间 |

### `review_queue`

用途：外链、视频切片、社交内容等进入专题前的审核队列。

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | varchar(64) | 主键 |
| `topic_id` | varchar(64) | 所属专题 |
| `queue_type` | varchar(32) | `article / video / live / link` |
| `title` | varchar(255) | 队列标题 |
| `meta` | varchar(255) | 来源与状态摘要 |
| `status` | varchar(32) | `pending / approved / rejected` |
| `origin_url` | varchar(512) | 原始链接 |
| `reviewed_by` | varchar(64) | 审核人 |
| `reviewed_at` | datetime | 审核时间 |

### `topic_timeline_nodes`

用途：专题时间线节点与事件阶段管理。

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | varchar(64) | 主键 |
| `topic_id` | varchar(64) | 所属专题 |
| `content_id` | varchar(64) | 关联内容，可为空 |
| `timeline_type` | varchar(32) | `latest / context` |
| `time_label` | varchar(64) | 前台时间文本 |
| `title` | varchar(255) | 节点标题 |
| `summary` | text | 节点说明 |
| `sort_order` | int | 排序 |
| `created_at` | datetime | 创建时间 |

---

## 2. 已实现接口

### 专题配置

- `GET /api/topics/:topicId`
  获取专题基础信息与统计。
- `PATCH /api/topics/:topicId`
  更新标题、导语、状态、SEO 等配置。
- `GET /api/topics/:topicId/dashboard`
  一次返回前台和后台所需的聚合数据。

### 内容表 `topic_contents`

- `GET /api/topics/:topicId/contents`
  支持筛选参数：
  - `type`
  - `sourceType`
  - `featured`
  - `keyword`
- `POST /api/topics/:topicId/contents`
  新建一条专题内容，并自动补入最新时间线。
- `PATCH /api/topics/:topicId/contents/:contentId`
  修改内容标题、摘要、来源、排序、焦点状态等。
- `DELETE /api/topics/:topicId/contents/:contentId`
  删除内容，并联动移除关联的时间线节点。

### 时间线 `topic_timeline_nodes`

- `GET /api/topics/:topicId/timeline`
  返回 `latest` 与 `context` 两组时间线。
- `POST /api/topics/:topicId/timeline`
  新建时间线节点，可关联已有内容。
- `PATCH /api/topics/:topicId/timeline/:nodeId`
  修改时间标签、节点文案、排序或时间线类型。

### 审核队列 `review_queue`

- `GET /api/topics/:topicId/review-queue`
  获取待审队列，支持 `status` 查询。
- `POST /api/topics/:topicId/review-queue/:queueId/approve`
  审核通过并转成正式内容，同时写入最新时间线。
- `POST /api/topics/:topicId/review-queue/:queueId/reject`
  驳回待审内容，并记录审核信息。

### 外链导入

- `POST /api/import/link`
  输入外部链接，解析为待审队列项。

### OSS 上传

- `POST /api/uploads/policy`
  获取阿里云 OSS 直传策略，用于后台直接上传图片和视频。

### 开发辅助

- `GET /api/health`
  健康检查。
- `POST /api/dev/reset`
  把模拟数据库重置回种子状态。

---

## 3. 示例请求

### 获取专题看板

```http
GET /api/topics/topic-2026-nmg-travel-conference/dashboard
```

### 新增一条内容

```json
{
  "title": "大会现场视频更新",
  "summary": "新增一条视频类内容",
  "contentType": "video",
  "sourceType": "official",
  "displayColumn": "大会现场",
  "featured": true
}
```

### 审核通过一条队列内容

```json
{
  "displayColumn": "审核入库",
  "verifyStatus": "已审核"
}
```

### 手动新增时间线节点

```json
{
  "timelineType": "context",
  "timeLabel": "会后",
  "title": "成果沉淀与专题归档",
  "summary": "把重点报道、视频集锦和图集整理成长期可访问的归档页"
}
```

---

## 4. 当前实现边界

这一版已经完成：

1. `topics / topic_contents / review_queue / topic_timeline_nodes` 的真实接口映射
2. 前台从 `localStorage` 切换为 API 请求
3. 后台的发布、审核、焦点切换、时间线写入走同一套接口
4. 支持 `file / mysql` 双数据驱动切换
5. 后台支持 OSS 直传策略与上传回填

下一步最自然的是：

1. 接入真实数据库，例如 MySQL / RDS
2. 增加后台登录与操作日志
3. 补内容正文编辑、图片上传、批量排序