@nebula-skills/nebula-code-standards 0.1.0

package/skill/db-standards.md

@@ -0,0 +1,232 @@
+# 数据库设计规范
+
+> 适用于所有 Nebula 框架业务项目的数据库脚本编写规范。
+
+## 一、Flyway 版本文件命名
+
+脚本存放路径：`{项目}-server/src/main/resources/db/migration/`
+
+命名格式：`V{大版本}.{小版本}.{补丁}__{描述}.sql`
+
+```
+V1.0.0__init_t_demo.sql          # 建表 DDL
+V1.0.1__add_column_xxx.sql       # 字段变更（新增列、修改注释等）
+V1.0.2__init_demo_menu_data.sql  # 菜单/字典初始化 DML
+V1.0.3__alter_t_demo_index.sql   # 索引调整
+```
+
+**规则：**
+- 版本号必须严格递增，**已提交的脚本文件绝对不可修改**
+- 双下划线 `__` 分隔版本号与描述
+- 描述用英文蛇形命名，简洁说明变更内容
+- 一次发布对应一个文件，不拆分多文件（除非必要）
+
+---
+
+## 二、DDL 建表规范
+
+### 2.1 表命名
+
+- 格式：`t_{业务名蛇形}`
+- 示例：`t_demo`、`t_customer`、`t_order_detail`
+- 系统表使用 `sys_` 前缀（如 `sys_user`、`sys_menu`）
+
+### 2.2 公共字段（必须包含，顺序固定）
+
+每张业务表必须包含来自 `BaseEntity` 的 **11 个公共字段**，**顺序固定，且全部集中置于业务字段之前**（不可与业务字段交错排列）。
+
+**11 个公共字段快速对照（建表前逐一检查，带 ⚠️ 的是高频遗漏项）：**
+
+| # | 列名 | 类型约束 | 易遗漏 |
+|---|------|---------|--------|
+| 1 | `id` | `BIGINT NOT NULL` | — |
+| 2 | `tenant_id` | `BIGINT DEFAULT NULL` | — |
+| 3 | `create_user_id` | `BIGINT DEFAULT NULL` | — |
+| 4 | `creator` | `VARCHAR(128) DEFAULT NULL` | — |
+| 5 | `create_time` | `DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6)` | — |
+| 6 | `modify_user_id` | `BIGINT DEFAULT NULL` | — |
+| 7 | `updater` | `VARCHAR(128) DEFAULT NULL` | — |
+| 8 | `modify_time` | `DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6)` | — |
+| 9 | `delete_flag` | `INT NOT NULL DEFAULT 0` | — |
+| 10 | `remark` | `VARCHAR(500) DEFAULT NULL` | ⚠️ 容易遗漏 |
+| 11 | `custom_fields` | `TEXT DEFAULT NULL` | ⚠️ 容易遗漏 |
+
+> **常见错误**：只写到 `delete_flag` 就结束，漏掉 `remark` 和 `custom_fields`。这会导致 MyBatis-Plus 自动填充时找不到列，运行时报错。
+
+```sql
+CREATE TABLE IF NOT EXISTS `t_demo`
+(
+    -- ========== 公共字段（对应 BaseEntity，顺序固定，不可省略） ==========
+    `id`             BIGINT       NOT NULL COMMENT '主键（雪花算法）',
+    `tenant_id`      BIGINT                DEFAULT NULL COMMENT '租户ID（多租户行级隔离）',
+    `create_user_id` BIGINT                DEFAULT NULL COMMENT '创建人ID',
+    `creator`        VARCHAR(128)          DEFAULT NULL COMMENT '创建人用户名',
+    `create_time`    DATETIME(6)  NOT NULL DEFAULT CURRENT_TIMESTAMP(6) COMMENT '创建时间',
+    `modify_user_id` BIGINT                DEFAULT NULL COMMENT '最后修改人ID',
+    `updater`        VARCHAR(128)          DEFAULT NULL COMMENT '最后修改人用户名',
+    `modify_time`    DATETIME(6)  NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6) COMMENT '最后修改时间',
+    `delete_flag`    INT          NOT NULL DEFAULT 0 COMMENT '逻辑删除（0:未删除 1:已删除）',
+    `remark`         VARCHAR(500)          DEFAULT NULL COMMENT '备注',         -- ⚠️ 不可省略
+    `custom_fields`  TEXT                  DEFAULT NULL COMMENT '自定义扩展字段（JSON）', -- ⚠️ 不可省略
+
+    -- ========== 业务字段（放公共字段之后） ==========
+    `demo_name`      VARCHAR(100) NOT NULL COMMENT '示例名称',
+    `demo_code`      VARCHAR(50)  NOT NULL COMMENT '示例编码（租户内唯一）',
+    `demo_type`      VARCHAR(20)           DEFAULT NULL COMMENT '示例类型（A:类型A B:类型B）',
+    `status`         INT          NOT NULL DEFAULT 0 COMMENT '状态（0:正常 1:禁用）',
+
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_tenant_demo_code` (`tenant_id`, `demo_code`),
+    KEY `idx_demo_name` (`demo_name`),
+    KEY `idx_status` (`status`)
+) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT ='示例表';
+```
+
+### 2.3 公共字段 Java 映射（BaseEntity 自动填充）
+
+| SQL 字段 | Java 属性 | 填充时机 | 说明 |
+|---------|-----------|---------|------|
+| `id` | `id` | INSERT | 雪花算法，无需手动赋值 |
+| `tenant_id` | `tenantId` | INSERT | 从 TenantContext 自动获取 |
+| `create_user_id` | `createUserId` | INSERT | 自动填充 |
+| `creator` | `creator` | INSERT | 创建人用户名，自动填充 |
+| `create_time` | `createTime` | INSERT | 自动填充 |
+| `modify_user_id` | `modifyUserId` | INSERT+UPDATE | 自动填充 |
+| `updater` | `updater` | INSERT+UPDATE | 最后修改人，自动填充 |
+| `modify_time` | `modifyTime` | INSERT+UPDATE | 自动填充 |
+| `delete_flag` | `deleteFlag` | 逻辑删除标记 | `@TableLogic`，查询自动追加 `AND delete_flag=0` |
+| `remark` | `remark` | 手动赋值 | 通用备注 |
+| `custom_fields` | `customFields` | 手动赋值 | JSON 扩展字段，配合表单设计器 |
+
+---
+
+## 三、字段设计规范
+
+### 3.1 字段类型映射
+
+| 数据库类型 | Java 类型 | 适用场景 |
+|-----------|-----------|---------|
+| `VARCHAR(N)` | `String` | 字符串，N 根据业务设定 |
+| `TEXT` | `String` | 长文本（> 500 字符）|
+| `INT` | `Integer` | 整数（状态、数量等）|
+| `BIGINT` | `Long` | 主键、ID、大整数 |
+| `DATETIME` | `LocalDateTime` | 日期时间 |
+| `DATE` | `LocalDate` | 仅日期 |
+| `DECIMAL(M,D)` | `BigDecimal` | 金额、精确小数（禁止用 Double）|
+| `TINYINT(1)` | `Boolean` | 布尔值（可选，也可用 INT）|
+
+### 3.2 字段命名
+
+- 数据库列：蛇形命名，如 `demo_name`、`create_time`
+- Java 字段：驼峰命名，如 `demoName`、`createTime`
+- MyBatis-Plus 全局开启 `camel-case-column-map`，自动完成两者映射
+
+### 3.3 枚举值约定
+
+枚举值使用整数存储，字段注释中说明含义：
+
+```sql
+`status` INT NOT NULL DEFAULT 0 COMMENT '状态（0:正常 1:禁用）',
+`order_type` INT DEFAULT NULL COMMENT '订单类型（1:普通订单 2:定制订单 3:补单）',
+```
+
+### 3.4 状态字段
+
+- 通用状态字段名：`status`
+- 约定：`0` 为正常/启用，`1` 为禁用/停用
+
+---
+
+## 四、索引设计规范
+
+| 索引类型 | 命名格式 | 示例 |
+|---------|---------|------|
+| 主键 | `PRIMARY KEY (id)` | — |
+| 唯一键 | `uk_{表简称}_{列名}` | `uk_tenant_demo_code` |
+| 普通索引 | `idx_{列名}` | `idx_demo_name`、`idx_status` |
+| 联合索引 | `idx_{列1}_{列2}` | `idx_tenant_status` |
+
+**多租户唯一键必须包含 `tenant_id`：**
+```sql
+UNIQUE KEY `uk_tenant_demo_code` (`tenant_id`, `demo_code`)
+```
+
+---
+
+## 五、菜单与字典 DML 规范
+
+### 5.1 存放位置
+
+**菜单和字典 DML 维护在 `nebula-system` 项目的迁移脚本中**，不放在业务服务的迁移脚本里：
+```
+nebula-system-server/src/main/resources/db/migration/
+```
+
+### 5.2 菜单插入模板
+
+```sql
+-- 一级目录菜单（{业务中文名}：替换为当前项目名，{domain} 替换为业务域）
+INSERT INTO sys_menu (id, parent_id, menu_type, menu_name, perms, path, component, sort_order, visible, status)
+VALUES (40000, 0, 'M', '{业务中文名}', '', '/{domain}app', '', 10, 1, 1);
+
+-- 二级功能菜单
+INSERT INTO sys_menu (id, parent_id, menu_type, menu_name, perms, path, component, sort_order, visible, status)
+VALUES (40001, 40000, 'C', '示例管理', '{domain}:demo:query', '/{domain}app/demo', '{domain}app/demo', 1, 1, 1);
+
+-- 权限按钮（menu_type = 'F'）
+INSERT INTO sys_menu (id, parent_id, menu_type, menu_name, perms, sort_order)
+VALUES (40010, 40001, 'F', '新增', '{domain}:demo:create', 1);
+
+INSERT INTO sys_menu (id, parent_id, menu_type, menu_name, perms, sort_order)
+VALUES (40011, 40001, 'F', '修改', '{domain}:demo:update', 2);
+
+INSERT INTO sys_menu (id, parent_id, menu_type, menu_name, perms, sort_order)
+VALUES (40012, 40001, 'F', '删除', '{domain}:demo:delete', 3);
+```
+
+**权限标识格式：** `{业务域}:{资源}:{操作}`
+
+常用操作：`query`（查询）、`create`（新增）、`update`（修改）、`delete`（删除）、`export`（导出）
+
+### 5.3 字典插入模板
+
+```sql
+-- 字典类型
+INSERT INTO sys_dict_type (id, dict_name, type_code, status, remark)
+VALUES (100, '示例类型', 'demo_type', 0, '示例模块使用的类型字典');
+
+-- 字典项
+INSERT INTO sys_dict_item (dict_type_id, item_label, item_value, sort_order, status)
+VALUES (100, '类型A', 'A', 1, 0);
+
+INSERT INTO sys_dict_item (dict_type_id, item_label, item_value, sort_order, status)
+VALUES (100, '类型B', 'B', 2, 0);
+```
+
+---
+
+## 六、字段变更脚本规范
+
+```sql
+-- 新增列（安全，不影响现有数据）
+ALTER TABLE `t_demo`
+    ADD COLUMN `new_field` VARCHAR(100) DEFAULT NULL COMMENT '新字段说明'
+    AFTER `demo_code`;   -- 指定插入位置
+
+-- 修改列注释（不修改类型，最安全）
+ALTER TABLE `t_demo`
+    MODIFY COLUMN `status` INT NOT NULL DEFAULT 0 COMMENT '状态（0:正常 1:禁用 2:待审核）';
+
+-- 新增索引
+ALTER TABLE `t_demo`
+    ADD INDEX `idx_new_field` (`new_field`);
+
+-- 新增唯一键
+ALTER TABLE `t_demo`
+    ADD UNIQUE KEY `uk_tenant_new_field` (`tenant_id`, `new_field`);
+```
+
+**注意：**
+- 生产环境禁止 DROP COLUMN / DROP TABLE（需单独审批）
+- 不允许修改已提交的 Flyway 脚本，必须新建版本文件来变更
+- 字段变更后对应更新 Java DO 类和相关 VO 类