create-table

name	create-table
description	数据库建表规范。创建新表 SQL 时必须遵循；SQL 建完后必须继续阅读 table-config skill 来生成 {mod}.ts 配置

建表规范

重要：本 skill 只管 SQL 建表。SQL 写完后，必须继续阅读 ../table-config/SKILL.md 来生成对应的 {mod}.ts 表配置文件。两者是串联流程，不可跳过。

按下面顺序执行，避免漏规则：

1. 先确认表路径和表名是否符合本页规范。
2. 再按业务场景选择字段组：主显示字段、审计字段、软删除、字典字段、外键、地址字段、自动编码字段。
3. SQL 写完后逐项自检：字段名不能重复；同一语义不要并存两套命名；字典字段、布尔字段、外键字段必须满足本页的命名和类型规则。
4. 如果需求要求本文未覆盖、且仓库里也没有先例的数据类型、默认值或索引写法，先明确指出冲突并等待确认，不要自行猜测。

表路径

codegen/src/tables/{mod}/{mod}.sql

表名格式

{mod}_{table} 小写下划线，如 base_usr

部分约定字段

-- 主键
`id` varchar(22) NOT NULL COMMENT 'ID',

-- 显示标签
`lbl` varchar(45) NOT NULL DEFAULT '' COMMENT '名称',

-- 审计字段（按需选用，非全部必须）
`create_usr_id` varchar(22) NOT NULL DEFAULT '' COMMENT '创建人',
`create_usr_id_lbl` varchar(45) NOT NULL DEFAULT '' COMMENT '创建人',
`create_time` datetime DEFAULT NULL COMMENT '创建时间',
`update_usr_id` varchar(22) NOT NULL DEFAULT '' COMMENT '更新人',
`update_usr_id_lbl` varchar(45) NOT NULL DEFAULT '' COMMENT '更新人',
`update_time` datetime DEFAULT NULL COMMENT '更新时间',

-- 软删除
`is_deleted` tinyint unsigned NOT NULL DEFAULT 0 COMMENT '删除,dict:is_deleted',
`delete_usr_id` varchar(22) NOT NULL DEFAULT '' COMMENT '删除人',
`delete_usr_id_lbl` varchar(45) NOT NULL DEFAULT '' COMMENT '删除人',
`delete_time` datetime DEFAULT NULL COMMENT '删除时间',

• 创建/修改审计字段（create_*、update_*）只在需要记录“谁创建/修改、何时创建/修改”时成组添加；纯中间表、一次性临时表、无需追踪责任人的表可以省略
• 软删除字段（is_deleted、delete_*、delete_time）只在记录需要逻辑删除、保留历史或支持恢复时成组添加；允许直接物理删除的表不要添加
• tenant_id 只在该表数据需要按租户隔离、过滤或鉴权时添加；单租户表、系统全局表不要添加
• lbl 是绝大多数业务主表的基础显示字段；纯中间表、日志表、令牌表这类不面向业务展示的表可以没有 lbl
• 如果出现字段重名、字段语义冲突，或现有字段类型与本页规则冲突，先返回明确错误点，不要继续拼接 SQL

字典字段

-- 业务字典: COMMENT 中用 dictbiz: 标注
`status` varchar(20) NOT NULL DEFAULT '' COMMENT '状态,dictbiz:ec_order_status',

-- 系统字典: COMMENT 中用 dict: 标注
`is_locked` tinyint unsigned NOT NULL DEFAULT 0 COMMENT '锁定,dict:is_locked',

• 有 dict: 或 dictbiz: 标注的字段，若字典配置了 is_sys=1，则该字段必定是 ENUM 类型（codegen 会自动生成枚举类型）
• 字典的详细配置规则见 dict/SKILL.md

可选系统字段

字段	用途
tenant_id	租户隔离
org_id + org_id_lbl	组织隔离
is_locked	锁定功能
is_enabled	启用/禁用
order_by	手动排序（聚合表子表时必须要有，否则子表无法排序）
rem	备注
is_hidden	隐藏记录
parent_id	树形结构

布尔字段

`is_enabled` tinyint unsigned NOT NULL DEFAULT 1 COMMENT '启用,dict:is_enabled',

• 命名必须以 is_ 开头，如 is_xxx
• 类型必须为 tinyint unsigned
• 默认值为 0 或 1

外键

`usr_id` varchar(22) NOT NULL DEFAULT '' COMMENT '用户',
`usr_id_lbl` varchar(45) NOT NULL DEFAULT '' COMMENT '用户',

• 外键命名：{foreignTable}_id（不带模块名 {mod}_ 前缀），如 usr_id
• 冗余标签命名：{foreignTable}_id_lbl，如 usr_id_lbl
• 冗余标签字段按需添加，一般业务表都需要

多对多中间表

-- 表名: {mod}_{table1}_{table2}
CREATE TABLE `base_usr_role` (
  `id` varchar(22) NOT NULL COMMENT 'ID',
  `usr_id` varchar(22) NOT NULL DEFAULT '' COMMENT '用户',
  `role_id` varchar(22) NOT NULL DEFAULT '' COMMENT '角色',
  -- ... 审计字段
);

表索引

INDEX (`tenant_id`, `is_deleted`, `lbl`),

• 通常有唯一性或查询过滤需求的字段才需要加索引
• 注意不要建唯一索引，而是普通索引

城市地址字段

地址字段固定一组，命名规则为 *_province_code、*_province_lbl、*_city_code、*_city_lbl、*_county_code、*_county_lbl、*_address。无前缀的 province_code 等也可识别。

`province_code` varchar(10) NOT NULL DEFAULT '' COMMENT '省份编码',
`province_lbl` varchar(10) NOT NULL DEFAULT '' COMMENT '省份',
`city_code` varchar(15) NOT NULL DEFAULT '' COMMENT '城市编码',
`city_lbl` varchar(15) NOT NULL DEFAULT '' COMMENT '城市',
`county_code` varchar(20) NOT NULL DEFAULT '' COMMENT '区县编码',
`county_lbl` varchar(20) NOT NULL DEFAULT '' COMMENT '区县',
`address` varchar(100) NOT NULL DEFAULT '' COMMENT '详细地址',

自动编码字段

`code_seq` int unsigned NOT NULL DEFAULT 0 COMMENT '编码-序列号',
`code` varchar(45) NOT NULL DEFAULT '' COMMENT '编码',
-- 日期序列（可选）
`date_seq` date NOT NULL DEFAULT (CURRENT_DATE) COMMENT '日期-序列号',

• 如果表中已有 lbl 字段，序列字段命名为 code_seq / code；否则为 lbl_seq / code

完整示例

DROP TABLE IF EXISTS `base_example`;
CREATE TABLE `base_example` (
  `id` varchar(22) NOT NULL COMMENT 'ID',
  `lbl` varchar(45) NOT NULL DEFAULT '' COMMENT '名称',
  `usr_id` varchar(22) NOT NULL DEFAULT '' COMMENT '用户',
  `usr_id_lbl` varchar(45) NOT NULL DEFAULT '' COMMENT '用户',
  `is_enabled` tinyint unsigned NOT NULL DEFAULT 1 COMMENT '启用,dict:is_enabled',
  `order_by` int unsigned NOT NULL DEFAULT 1 COMMENT '排序',
  `tenant_id` varchar(22) NOT NULL DEFAULT '' COMMENT '租户',
  `create_usr_id` varchar(22) NOT NULL DEFAULT '' COMMENT '创建人',
  `create_usr_id_lbl` varchar(45) NOT NULL DEFAULT '' COMMENT '创建人',
  `create_time` datetime DEFAULT NULL COMMENT '创建时间',
  `update_usr_id` varchar(22) NOT NULL DEFAULT '' COMMENT '更新人',
  `update_usr_id_lbl` varchar(45) NOT NULL DEFAULT '' COMMENT '更新人',
  `update_time` datetime DEFAULT NULL COMMENT '更新时间',
  `is_deleted` tinyint unsigned NOT NULL DEFAULT 0 COMMENT '删除,dict:is_deleted',
  `delete_usr_id` varchar(22) NOT NULL DEFAULT '' COMMENT '删除人',
  `delete_usr_id_lbl` varchar(45) NOT NULL DEFAULT '' COMMENT '删除人',
  `delete_time` datetime DEFAULT NULL COMMENT '删除时间',
  INDEX (`tenant_id`, `is_deleted`, `lbl`),
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_as_cs COMMENT='示例';