tkmind_go/documentation/docs/guides/plaza/02-data-model.md

---
sidebar_position: 3
title: 数据模型
sidebar_label: 数据模型
description: Plaza 所有数据库表的完整字段定义、索引策略、约束规则和迁移说明
---

# 数据模型

## 总览

Plaza 新增 **10 张业务表**（`plaza_*` 前缀 + `ops_audit_log`），复用现有 `h5_users` 和 `h5_publish_records`，不创建新的用户体系。

**逻辑名与物理表映射**（与 MindSpace 文档一致）：

| 文档逻辑名 | 物理表 |
| --- | --- |
| users | `h5_users` |
| publications | `h5_publish_records` |

**时间字段约定**：Plaza 新表与现有 H5 库一致，使用 `BIGINT` 毫秒 UTC（`created_at` / `updated_at` / `published_at` 等），不使用 `DATETIME`。

```text
h5_users (现有)
    │
    ├──< plaza_posts          广场帖子（每条对应一个已发布的 publication）
    │       │
    │       ├──< plaza_reactions         点赞 / 收藏 / 分享
    │       ├──< plaza_comments          评论（支持二级回复）
    │       └──< plaza_comment_reactions 评论点赞
    │
    └──< plaza_follows         关注关系（创作者 ↔ 粉丝）

plaza_categories              广场分类（独立配置表）
    └──< plaza_posts

plaza_algorithm_config        热度公式权重（键值表）
plaza_reports                 用户举报
plaza_featured                精选位配置
ops_audit_log                 运营操作审计（追加-only）
```

---

## plaza_posts（广场帖子）

```sql
CREATE TABLE plaza_posts (
    id                CHAR(36)      NOT NULL,
    publication_id    CHAR(36)      NOT NULL,          -- → h5_publish_records.id
    
    user_id           CHAR(36)      NOT NULL,          -- → h5_users.id
    
    -- 快照字段（冗余，避免跨表 JOIN）
    title             VARCHAR(200)  NOT NULL,
    summary           VARCHAR(500)  NOT NULL DEFAULT '',
    cover_url         VARCHAR(500)  NOT NULL DEFAULT '',
    user_slug         VARCHAR(100)  NOT NULL,          -- 快照，发帖时写入
    user_display_name VARCHAR(100)  NOT NULL,
    user_avatar_url   VARCHAR(500)  NOT NULL DEFAULT '',
    
    -- 分类和标签
    category_id       CHAR(36)      NOT NULL,          -- → plaza_categories.id
    tags              JSON          NOT NULL DEFAULT (JSON_ARRAY()),  -- 最多 5 个
    
    -- 状态
    status            ENUM(
                        'pending_review',   -- 待审核（默认）
                        'published',        -- 审核通过，公开展示
                        'hidden',           -- 被运营隐藏或 publication 下线
                        'rejected'          -- 审核拒绝
                      ) NOT NULL DEFAULT 'pending_review',
    
    -- 互动计数（热计数用 Redis，定时同步到这里）
    view_count        INT UNSIGNED  NOT NULL DEFAULT 0,
    like_count        INT UNSIGNED  NOT NULL DEFAULT 0,
    collect_count     INT UNSIGNED  NOT NULL DEFAULT 0,
    comment_count     INT UNSIGNED  NOT NULL DEFAULT 0,
    share_count       INT UNSIGNED  NOT NULL DEFAULT 0,
    
    -- 热度
    hot_score         DOUBLE        NOT NULL DEFAULT 0,
    hot_updated_at    BIGINT        NULL,
    
    -- 设置
    allow_comment     TINYINT(1)    NOT NULL DEFAULT 1,
    
    -- 时间（毫秒 UTC）
    published_at      BIGINT        NOT NULL,
    created_at        BIGINT        NOT NULL,
    updated_at        BIGINT        NOT NULL,
    
    PRIMARY KEY (id),
    UNIQUE KEY uq_publication (publication_id),        -- 每个 publication 只能发一次
    KEY idx_user_status (user_id, status),
    KEY idx_category_hot (category_id, status, hot_score DESC),
    KEY idx_published_at (published_at DESC),
    KEY idx_status_hot (status, hot_score DESC)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

**字段说明：**

- `publication_id` 唯一约束：同一个发布记录只能出现在广场一次，防止重复发布。
- 快照字段（`user_slug` 等）在发帖时写入，此后不随用户改名而变。如果用户改名，需要额外的更新任务，但不影响已有帖子的显示。
- `status = hidden` 覆盖两种场景：运营主动隐藏、publication 被原作者下线。
- `hot_score` 由后台定时任务计算写入，不在每次请求时实时计算。

---

## plaza_reactions（点赞 / 收藏 / 分享）

```sql
CREATE TABLE plaza_reactions (
    id          CHAR(36)     NOT NULL,
    post_id     CHAR(36)     NOT NULL,   -- → plaza_posts.id
    user_id     CHAR(36)     NOT NULL,   -- → h5_users.id
    type        ENUM(
                  'like',
                  'collect',
                  'share'
                ) NOT NULL,
    created_at  BIGINT       NOT NULL,
    
    PRIMARY KEY (id),
    UNIQUE KEY uq_user_post_type (post_id, user_id, type),  -- 同一用户同一帖子同类型只能有一条
    KEY idx_post_type (post_id, type),
    KEY idx_user_type (user_id, type)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

**触发器逻辑（应用层实现，不用数据库触发器）：**

- 插入 reaction → Redis INCR `plaza:post:{id}:like_count`
- 删除 reaction（取消点赞）→ Redis DECR
- 定时任务每 5 分钟将 Redis 计数同步到 `plaza_posts` 对应字段

---

## plaza_comments（评论）

```sql
CREATE TABLE plaza_comments (
    id          CHAR(36)     NOT NULL,
    post_id     CHAR(36)     NOT NULL,   -- → plaza_posts.id
    user_id     CHAR(36)     NOT NULL,   -- → h5_users.id
    parent_id   CHAR(36)     NULL,       -- 二级回复时指向父评论，NULL 表示一级评论
    
    -- 内容
    content     VARCHAR(500) NOT NULL,
    
    -- 状态
    status      ENUM(
                  'visible',
                  'deleted',             -- 用户自己删除（内容替换为空，记录保留）
                  'flagged',             -- 被举报，等待审核
                  'hidden'              -- 运营隐藏
                ) NOT NULL DEFAULT 'visible',
    
    -- 计数
    like_count  INT UNSIGNED NOT NULL DEFAULT 0,
    reply_count INT UNSIGNED NOT NULL DEFAULT 0,  -- 仅一级评论有效
    
    -- 删除人标记
    deleted_by  ENUM('user', 'ops') NULL,
    
    created_at  BIGINT       NOT NULL,
    updated_at  BIGINT       NOT NULL,
    
    PRIMARY KEY (id),
    KEY idx_post_visible (post_id, status, created_at DESC),
    KEY idx_parent (parent_id),
    KEY idx_user (user_id, created_at DESC)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

**规则：**

- 只支持两级：一级评论（`parent_id IS NULL`）和二级回复（`parent_id` 指向一级）。
- 二级回复不再允许继续嵌套，前端也不展示更深的层级。
- 删除评论时不物理删除，将 `content` 设为空字符串，`status` 设为 `deleted`，保留 `reply_count` 用于展示"该评论已删除，有 N 条回复"。
- `post_id` 的 `comment_count` 只计算 `status = visible` 的一级评论数量。

---

## plaza_follows（关注关系）

```sql
CREATE TABLE plaza_follows (
    follower_id CHAR(36)  NOT NULL,   -- 关注者 → h5_users.id
    followee_id CHAR(36)  NOT NULL,   -- 被关注者 → h5_users.id
    created_at  BIGINT    NOT NULL,
    
    PRIMARY KEY (follower_id, followee_id),
    KEY idx_followee (followee_id, created_at DESC)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

**说明：**

- 不允许自己关注自己（应用层校验：`follower_id != followee_id`）。
- `h5_users` 表新增冗余计数字段 `plaza_following_count` 和 `plaza_follower_count`，关注/取关时事务内更新。
- 取关是物理删除行。

---

## plaza_categories（广场分类）

```sql
CREATE TABLE plaza_categories (
    id          CHAR(36)     NOT NULL,
    name        VARCHAR(50)  NOT NULL,
    slug        VARCHAR(50)  NOT NULL,   -- URL 友好，如 work-report
    icon        VARCHAR(10)  NOT NULL DEFAULT '',  -- emoji 或图标代码
    description VARCHAR(200) NOT NULL DEFAULT '',
    sort_order  INT          NOT NULL DEFAULT 0,
    is_active   TINYINT(1)   NOT NULL DEFAULT 1,
    created_at  BIGINT       NOT NULL,
    
    PRIMARY KEY (id),
    UNIQUE KEY uq_slug (slug),
    KEY idx_sort (is_active, sort_order)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

**初始分类数据：**

| name | slug | icon | sort_order |
| --- | --- | --- | --- |
| 职场报告 | work-report | 📊 | 1 |
| 学习笔记 | study-notes | 📚 | 2 |
| 创意作品 | creative | 🎨 | 3 |
| 门店展示 | business | 🏪 | 4 |
| 旅行攻略 | travel | ✈️ | 5 |
| 数据分析 | data-analysis | 📈 | 6 |
| 生活记录 | lifestyle | 🌿 | 7 |
| 其他 | other | 💡 | 99 |

---

## plaza_comment_reactions（评论点赞）

```sql
CREATE TABLE plaza_comment_reactions (
    id          CHAR(36)  NOT NULL,
    comment_id  CHAR(36)  NOT NULL,   -- → plaza_comments.id
    user_id     CHAR(36)  NOT NULL,   -- → h5_users.id
    created_at  BIGINT    NOT NULL,

    PRIMARY KEY (id),
    UNIQUE KEY uq_user_comment (comment_id, user_id),
    KEY idx_comment (comment_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

- 点赞/取消点赞时同步更新 `plaza_comments.like_count`（事务内，不走 Redis）。
- 不提供独立 Redis 键；评论点赞量低于帖子级互动，直接写 MySQL 即可。

---

## plaza_algorithm_config（热度权重）

见 [05-feed-algorithm](./05-feed-algorithm) 中的建表 SQL。Sprint 3 引入。

---

## plaza_reports（举报）

见 [06-ops-platform](./06-ops-platform) 中的建表 SQL。Sprint 5 引入。

---

## plaza_featured（精选位）

见 [06-ops-platform](./06-ops-platform) 中的建表 SQL。Sprint 5 引入。

---

## ops_audit_log（运营审计）

见 [06-ops-platform](./06-ops-platform) 中的建表 SQL。Sprint 5 引入。

---

## h5_users / h5_publish_records 扩展字段

在现有表上通过 `db.mjs` 增量迁移添加：

```sql
ALTER TABLE h5_users
    ADD COLUMN plaza_post_count       INT UNSIGNED NOT NULL DEFAULT 0,
    ADD COLUMN plaza_follower_count   INT UNSIGNED NOT NULL DEFAULT 0,
    ADD COLUMN plaza_following_count  INT UNSIGNED NOT NULL DEFAULT 0,
    ADD COLUMN plaza_verified         TINYINT(1)   NOT NULL DEFAULT 0,
    ADD COLUMN plaza_post_banned      TINYINT(1)   NOT NULL DEFAULT 0,
    ADD COLUMN plaza_comment_banned   TINYINT(1)   NOT NULL DEFAULT 0,
    ADD COLUMN ops_role               ENUM('none','reviewer','editor','ops_admin') NOT NULL DEFAULT 'none';

ALTER TABLE h5_publish_records
    ADD COLUMN plaza_view_count       BIGINT NOT NULL DEFAULT 0,
    ADD COLUMN plaza_like_count       BIGINT NOT NULL DEFAULT 0;
```

**`total_likes`（用户主页 API）**：不单独落库，查询时 `SUM(plaza_posts.like_count) WHERE user_id = ? AND status = 'published'`，或维护 `h5_users.plaza_total_likes` 冗余字段（Sprint 2 可选优化）。

---

## Redis 数据结构

```text
# 实时计数（定时同步到 MySQL）
plaza:post:{post_id}:view_count      STRING  INCR
plaza:post:{post_id}:like_count      STRING  INCR/DECR

# Feed 缓存（TTL 5 分钟）
plaza:feed:hot:{category_id}:page:{n}   STRING  JSON 数组，热门帖子 ID 列表
plaza:feed:new:{category_id}:page:{n}   STRING  JSON 数组，最新帖子 ID 列表

# 用户行为缓存（判断当前用户是否已点赞）
plaza:user:{user_id}:liked              SET    post_id 集合，TTL 30 分钟
```

---

## 索引策略

| 查询场景 | 使用索引 |
| --- | --- |
| 广场首页热门 feed | `idx_status_hot (status, hot_score DESC)` |
| 分类热门 feed | `idx_category_hot (category_id, status, hot_score DESC)` |
| 用户主页帖子列表 | `idx_user_status (user_id, status)` |
| 最新帖子列表 | `idx_published_at (published_at DESC)` |
| 帖子评论列表 | `idx_post_visible (post_id, status, created_at DESC)` |
| 用户关注列表 | `idx_followee (followee_id, created_at DESC)` |

---

## 迁移规范

- 每次 schema 变更：更新 `ui/h5/schema.sql`，并在 `db.mjs` 的 `migrateSchema()` 中做幂等 `ALTER`（与现有 MindSpace 迁移方式一致）。
- 可选归档文件命名：`ui/h5/migrations/V{n}__plaza_{description}.sql`（仅作审计，执行入口仍是 `initSchema`）。
- 新增字段必须有 DEFAULT 值，不允许直接在非空表上添加 NOT NULL 无默认值的列。
- `plaza_posts` 的快照字段（`user_slug` 等）在写入后不自动同步更新，需要独立的后台对账任务。
- 删除字段前先废弃读写代码，确认无流量后再执行 DDL。

---

## 不变量

- 每个 `publication_id` 在 `plaza_posts` 中最多出现一次（更新元数据走 `PATCH`，不换 publication）。
- `plaza_posts.status = hidden` 必须在 `h5_publish_records.status != 'online'` 时下线联动触发（同一事务）。
- `comment_count` 只统计 `status = visible` 的一级评论。
- 所有计数字段不允许出现负数（应用层保证 DECR 前先检查当前值）。
- `plaza_follows` 不允许 `follower_id = followee_id`。