帮助文章分类枚举表设计

背景

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

一、表结构设计

1. 分类主表 `sys_help_category`

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

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 外键。

-- 新增 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 枚举，全量初始化：

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	公告/通知（预留，后续扩展）

四、业务查询示例

查询帮助中心所有启用分类（供下拉选择）

SELECT id, code, name_zh, name_en
FROM sys_help_category
WHERE status = 1 AND scene = 'HELP'
ORDER BY sort DESC;

查询指定协议类型的文章（如服务条款，支持多语言）

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;

查询协议页所有分类及其文章（一次性加载）

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;

五、后续扩展方式

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

-- 示例：新增"新手指南"分类（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）或物理删除

sys_help_category_design.md 7.2 KB Istoric Crud