# 帮助文章分类枚举表设计

## 背景

当前 `SysHelpClassification` 是 Java 硬编码枚举，新增分类需要改代码重新部署。
改为数据库字典表后，管理后台直接维护分类，各业务模块通过 `category_code` 查询对应内容，无需改代码。

---

## 一、表结构设计

### 1. 分类主表 `sys_help_category`

存储所有分类/协议类型，管理后台从此表读取下拉选项。

```sql
CREATE TABLE `sys_help_category` (
  `id`          BIGINT       NOT NULL AUTO_INCREMENT COMMENT '主键',
  `code`        VARCHAR(50)  NOT NULL                COMMENT '分类编码（英文唯一标识，业务方使用此字段查询）',
  `name_zh`     VARCHAR(100) NOT NULL                COMMENT '中文名称',
  `name_en`     VARCHAR(100) NOT NULL                COMMENT '英文名称',
  `scene`       VARCHAR(50)  NOT NULL DEFAULT 'HELP' COMMENT '适用场景: HELP=帮助中心, PROTOCOL=协议展示, NOTICE=公告',
  `sort`        INT          NOT NULL DEFAULT 0       COMMENT '排序值，越大越靠前',
  `status`      TINYINT      NOT NULL DEFAULT 1       COMMENT '状态: 1=启用, 0=禁用',
  `remark`      VARCHAR(255)          DEFAULT NULL   COMMENT '备注（说明该分类的用途）',
  `create_time` DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_code` (`code`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='帮助文章分类枚举表';
```

### 2. `sys_help` 表调整

将原来的硬编码枚举字段替换为分类 code 外键。

```sql
-- 新增 category_code 字段，替代原 sys_help_classification 枚举字段
ALTER TABLE `sys_help`
  ADD COLUMN `category_code` VARCHAR(50) NOT NULL DEFAULT '' COMMENT '分类编码，关联 sys_help_category.code' AFTER `title`,
  ADD INDEX `idx_category_code` (`category_code`);
```

> **迁移说明**：上线时先写入初始数据（见下方），再执行字段迁移，将旧枚举 ordinal 映射到对应 code。

---

## 二、初始数据

对应现有 `SysHelpClassification` 枚举，全量初始化：

```sql
INSERT INTO `sys_help_category` (`code`, `name_zh`, `name_en`, `scene`, `sort`, `status`, `remark`) VALUES
('HELP',            '新手入门',   'Getting Started',   'HELP',     100, 1, '注册、下载、基础操作等新手引导'),
('FAQ',             '常见问题',   'FAQ',               'HELP',     90,  1, '用户高频问题汇总'),
('EXCHANGE',        '交易指南',   'Trading Guide',     'HELP',     80,  1, '现货/合约交易操作说明'),
('COININFO',        '币种资料',   'Coin Info',         'HELP',     70,  1, '各币种项目介绍'),
('ANALYSIS',        '行情技术',   'Market Analysis',   'HELP',     60,  1, '技术分析、行情解读'),
('FOLLOW_PROTOCOL', '交易员条款', 'Trader Agreement',  'PROTOCOL', 55,  1, '带单交易员服务协议'),
('PRIVACY',         '隐私条款',   'Privacy Policy',    'PROTOCOL', 50,  1, '用户隐私政策'),
('DISCLAIMER',      '免责声明',   'Disclaimer',        'PROTOCOL', 45,  1, '平台免责声明'),
('PROTOCOL',        '条款协议',   'Terms of Service',  'PROTOCOL', 40,  1, '用户服务协议/利用规约'),
('QR_CODE',         'APP二维码',  'APP QR Code',       'HELP',     10,  1, '应用下载二维码展示页'),
('OTHER',           '其他',       'Other',             'HELP',     0,   1, '未归类内容');
```

---

## 三、字段说明

### `sys_help_category` 字段

| 字段        | 类型         | 必填 | 说明                                                              |
|-------------|--------------|------|-------------------------------------------------------------------|
| id          | bigint       | 是   | 主键，自增                                                        |
| code        | varchar(50)  | 是   | 唯一编码，**业务方通过此字段查询**，如 `PROTOCOL`、`PRIVACY`    |
| name_zh     | varchar(100) | 是   | 中文名称，管理后台下拉显示                                        |
| name_en     | varchar(100) | 是   | 英文名称，前端多语言使用                                          |
| scene       | varchar(50)  | 是   | 适用场景，用于前端分区展示，见场景枚举说明                        |
| sort        | int          | 是   | 排序值，越大越靠前，默认 0                                        |
| status      | tinyint      | 是   | 1=启用，0=禁用；禁用后该分类不再出现在下拉中                     |
| remark      | varchar(255) | 否   | 备注，说明该分类的业务用途                                        |
| create_time | datetime     | 是   | 创建时间                                                          |
| update_time | datetime     | 是   | 最后修改时间                                                      |

### `scene` 场景枚举值

| 值       | 说明                                         |
|----------|----------------------------------------------|
| HELP     | 帮助中心展示（新手指南、FAQ、交易指南等）    |
| PROTOCOL | 协议页面展示（服务条款、隐私政策、免责等）   |
| NOTICE   | 公告/通知（预留，后续扩展）                  |

---

## 四、业务查询示例

### 查询帮助中心所有启用分类（供下拉选择）
```sql
SELECT id, code, name_zh, name_en
FROM sys_help_category
WHERE status = 1 AND scene = 'HELP'
ORDER BY sort DESC;
```

### 查询指定协议类型的文章（如服务条款，支持多语言）
```sql
SELECT h.id, h.title, h.content, h.lang
FROM sys_help h
WHERE h.category_code = 'PROTOCOL'
  AND h.status = 1       -- CommonStatus.NORMAL
  AND h.lang = 'EN'
ORDER BY h.is_top ASC, h.sort DESC;
```

### 查询协议页所有分类及其文章（一次性加载）
```sql
SELECT c.code, c.name_zh, h.title, h.content, h.lang
FROM sys_help_category c
LEFT JOIN sys_help h ON h.category_code = c.code AND h.status = 1
WHERE c.scene = 'PROTOCOL' AND c.status = 1
ORDER BY c.sort DESC, h.sort DESC;
```

---

## 五、后续扩展方式

新增分类时，**只需在管理后台插入一行**，无需改代码：

```sql
-- 示例：新增"新手指南"分类（APP端新手流程）
INSERT INTO `sys_help_category` (`code`, `name_zh`, `name_en`, `scene`, `sort`, `remark`)
VALUES ('BEGINNER_GUIDE', '新手指南', 'Beginner Guide', 'HELP', 95, 'APP端新手引导流程专用');
```

前端/API 按 `code` 字段拉取对应分类的文章，`code` 值与业务约定后保持不变，新增分类不影响现有业务。

---

## 六、管理后台接口建议

| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 分类列表（下拉用） | GET | `/cms/help-category/list` | 返回所有启用分类，按 scene 过滤 |
| 分类分页查询 | POST | `/cms/help-category/page-query` | 管理列表，支持 scene/status 筛选 |
| 新增分类 | POST | `/cms/help-category/create` | 新增一个分类 |
| 修改分类 | POST | `/cms/help-category/update` | 修改名称、排序、状态等 |
| 删除分类 | POST | `/cms/help-category/deletes` | 软删除（status=0）或物理删除 |