ai-engineering-init 1.1.0

package/.claude/docs//346/225/260/346/215/256/345/272/223/350/256/276/350/256/241/350/247/204/350/214/203.md

@@ -0,0 +1,390 @@
+# 数据库设计规范
+
+> **重要提示**: 本项目是 RuoYi-Vue-Plus **纯后端项目**，采用**三层架构**。
+> 数据库设计必须遵循本规范，参考 `ruoyi-demo` 模块的 TestDemo 表。
+
+最后更新: 2026-02-09
+
+---
+
+## 🏗️ 核心规范速查
+
+| 项目 | 规范 |
+|------|------|
+| **包名** | `org.dromara.*` |
+| **Entity 基类** | `TenantEntity`（多租户） |
+| **主键策略** | 雪花 ID（**不用 AUTO_INCREMENT**） |
+| **逻辑删除** | `del_flag CHAR(1) DEFAULT '0'` |
+| **表前缀** | 按模块区分：`sys_`/`test_`/`flow_` 等 |
+
+---
+
+## 📋 表命名规范
+
+### 模块与表前缀对应
+
+| 模块 | 表前缀 | 包路径 | 示例表 |
+|------|--------|--------|--------|
+| **系统管理** | `sys_` | `org.dromara.system` | `sys_user`, `sys_menu`, `sys_role` |
+| **演示模块** | `test_` | `org.dromara.demo` | `test_demo`, `test_tree` |
+| **工作流** | `flow_` | `org.dromara.workflow` | `flow_xxx` |
+| **定时任务** | `sj_` | `org.dromara.job` | `sj_xxx` |
+| **商城业务** | `m_` | `org.dromara.mall` | `m_goods`, `m_order` |
+| **自定义** | `xxx_` | `org.dromara.xxx` | 按业务定义 |
+
+### 命名规则
+
+| 类型 | 规则 | 正确示例 | 错误示例 |
+|------|------|---------|---------|
+| **表名** | 小写 + 下划线 | `sys_user_role` | `SysUserRole` |
+| **字段名** | 小写 + 下划线 | `user_name` | `userName` |
+| **主键** | `id` | `id` | `user_id`（业务表）|
+| **外键** | `关联表_id` | `dept_id` | `deptId` |
+
+---
+
+## 📐 建表模板（MySQL）
+
+### 标准业务表模板
+
+```sql
+CREATE TABLE xxx_table (
+    -- 主键（雪花 ID，不用 AUTO_INCREMENT）
+    id              BIGINT(20)    NOT NULL COMMENT '主键ID',
+
+    -- 多租户字段（必须）
+    tenant_id       VARCHAR(20)   DEFAULT '000000' COMMENT '租户ID',
+
+    -- 业务字段
+    xxx_name        VARCHAR(100)  NOT NULL COMMENT '名称',
+    xxx_code        VARCHAR(64)   DEFAULT NULL COMMENT '编码',
+    status          CHAR(1)       DEFAULT '1' COMMENT '状态(0停用 1正常)',
+    remark          VARCHAR(500)  DEFAULT NULL COMMENT '备注',
+
+    -- 审计字段（必须，继承自 TenantEntity）
+    create_dept     BIGINT(20)    DEFAULT NULL COMMENT '创建部门',
+    create_by       BIGINT(20)    DEFAULT NULL COMMENT '创建人',
+    create_time     DATETIME      DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+    update_by       BIGINT(20)    DEFAULT NULL COMMENT '更新人',
+    update_time     DATETIME      DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+
+    -- 逻辑删除（必须）
+    del_flag        CHAR(1)       DEFAULT '0' COMMENT '删除标志(0正常 1已删除)',
+
+    PRIMARY KEY (id),
+    INDEX idx_tenant_id (tenant_id),
+    INDEX idx_status (status)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='XXX表';
+```
+
+### 树形结构表模板
+
+```sql
+CREATE TABLE xxx_tree (
+    id              BIGINT(20)    NOT NULL COMMENT '主键ID',
+    tenant_id       VARCHAR(20)   DEFAULT '000000' COMMENT '租户ID',
+
+    -- 树形结构字段
+    parent_id       BIGINT(20)    DEFAULT 0 COMMENT '父节点ID',
+    ancestors       VARCHAR(500)  DEFAULT '' COMMENT '祖级列表',
+    order_num       INT(4)        DEFAULT 0 COMMENT '显示顺序',
+
+    -- 业务字段
+    name            VARCHAR(100)  NOT NULL COMMENT '名称',
+    status          CHAR(1)       DEFAULT '1' COMMENT '状态(0停用 1正常)',
+
+    -- 审计字段
+    create_dept     BIGINT(20)    DEFAULT NULL COMMENT '创建部门',
+    create_by       BIGINT(20)    DEFAULT NULL COMMENT '创建人',
+    create_time     DATETIME      DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+    update_by       BIGINT(20)    DEFAULT NULL COMMENT '更新人',
+    update_time     DATETIME      DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+    del_flag        CHAR(1)       DEFAULT '0' COMMENT '删除标志(0正常 1已删除)',
+
+    PRIMARY KEY (id),
+    INDEX idx_parent_id (parent_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='树形表';
+```
+
+---
+
+## 📊 数据类型规范
+
+| 业务场景 | 数据库类型 | Java类型 | 示例 |
+|----------|------------|----------|------|
+| **主键ID** | `BIGINT(20)` | `Long` | `id BIGINT(20) NOT NULL` |
+| **租户ID** | `VARCHAR(20)` | `String` | `tenant_id VARCHAR(20)` |
+| **状态标识** | `CHAR(1)` | `String` | `status CHAR(1) DEFAULT '1'` |
+| **删除标志** | `CHAR(1)` | `String` | `del_flag CHAR(1) DEFAULT '0'` |
+| **短文本** | `VARCHAR(30-100)` | `String` | `user_name VARCHAR(30)` |
+| **长文本** | `VARCHAR(255-500)` | `String` | `remark VARCHAR(500)` |
+| **超长文本** | `TEXT` | `String` | `content TEXT` |
+| **金额** | `DECIMAL(10,2)` | `BigDecimal` | `price DECIMAL(10,2)` |
+| **时间** | `DATETIME` | `Date` | `create_time DATETIME` |
+| **布尔值** | `CHAR(1)` | `String` | `is_xxx CHAR(1) DEFAULT '0'` |
+
+### 布尔值规范
+
+| 字段类型 | 值含义 |
+|----------|--------|
+| **状态 (status)** | `1`=正常, `0`=停用 |
+| **删除标志 (del_flag)** | `0`=正常, `1`=已删除 |
+| **是否字段 (is_xxx)** | `1`=是, `0`=否 |
+
+---
+
+## 🔑 主键设计
+
+### 雪花 ID（项目默认）
+
+```sql
+-- ✅ 正确：不使用 AUTO_INCREMENT
+id BIGINT(20) NOT NULL COMMENT '主键ID',
+
+-- ❌ 错误：使用自增
+id BIGINT(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
+```
+
+### Entity 主键注解
+
+```java
+// ✅ 正确：只指定字段名，使用全局配置的雪花ID
+@TableId(value = "id")
+private Long id;
+
+// ❌ 错误：显式指定自增类型
+@TableId(value = "id", type = IdType.AUTO)
+private Long id;
+```
+
+---
+
+## 📝 必备字段说明
+
+### 审计字段（TenantEntity 已包含）
+
+| 字段 | 类型 | 说明 | 自动填充 |
+|------|------|------|---------|
+| `tenant_id` | VARCHAR(20) | 租户ID | ✅ 是 |
+| `create_dept` | BIGINT(20) | 创建部门 | ✅ 是 |
+| `create_by` | BIGINT(20) | 创建人 | ✅ 是 |
+| `create_time` | DATETIME | 创建时间 | ✅ 是 |
+| `update_by` | BIGINT(20) | 更新人 | ✅ 是 |
+| `update_time` | DATETIME | 更新时间 | ✅ 是 |
+
+### 逻辑删除字段
+
+```sql
+del_flag CHAR(1) DEFAULT '0' COMMENT '删除标志(0正常 1已删除)'
+```
+
+```java
+// Entity 中不需要显式定义，TenantEntity 基类已包含
+// MyBatis-Plus 自动处理：
+// - SELECT: 自动添加 WHERE del_flag = '0'
+// - DELETE: 转换为 UPDATE del_flag = '1'
+```
+
+---
+
+## 📇 索引设计
+
+### 索引类型
+
+```sql
+-- 主键索引（必须）
+PRIMARY KEY (id)
+
+-- 唯一索引（业务唯一字段）
+UNIQUE KEY uk_code (code)
+
+-- 普通索引（频繁查询字段）
+INDEX idx_status (status)
+INDEX idx_create_time (create_time)
+
+-- 复合索引（多条件查询）
+INDEX idx_tenant_status (tenant_id, status)
+```
+
+### 索引设计原则
+
+- **主键必建**：每张表必须有主键索引
+- **外键建索引**：外键字段建议添加索引
+- **租户字段建索引**：`tenant_id` 必须有索引
+- **频繁查询字段建索引**：WHERE 条件中的字段
+- **唯一性约束**：业务上唯一的字段建唯一索引
+- **复合索引遵循最左前缀原则**：`(a,b,c)` 支持 `(a)`, `(a,b)`, `(a,b,c)`
+
+---
+
+## 📖 字典设计规范
+
+### 使用场景
+
+当字段有**固定的几个可选值**时，应使用字典管理：
+- ✅ 状态字段：启用/停用
+- ✅ 类型字段：类型A/类型B/类型C
+- ✅ 性别字段：男/女/未知
+- ❌ 不适合：用户输入的自由文本
+
+### 字典命名规范
+
+| 字典类型 | 命名规则 | 示例 |
+|---------|---------|------|
+| **系统字典** | `sys_` + 功能名 | `sys_user_sex`, `sys_normal_disable` |
+| **业务字典** | 模块前缀 + 字段名 | `demo_xxx_type`, `mall_order_status` |
+
+### 新增字典类型
+
+```sql
+-- 1. 插入字典类型 (sys_dict_type 表)
+INSERT INTO sys_dict_type (dict_id, tenant_id, dict_name, dict_type, create_dept, create_by, create_time, remark)
+VALUES (100, '000000', 'XXX类型', 'demo_xxx_type', 103, 1, sysdate(), 'XXX类型列表');
+
+-- 2. 插入字典数据 (sys_dict_data 表)
+INSERT INTO sys_dict_data (dict_code, tenant_id, dict_sort, dict_label, dict_value, dict_type, css_class, list_class, is_default, create_dept, create_by, create_time, remark)
+VALUES (1001, '000000', 1, '类型A', '1', 'demo_xxx_type', '', 'primary', 'Y', 103, 1, sysdate(), '类型A');
+
+INSERT INTO sys_dict_data (dict_code, tenant_id, dict_sort, dict_label, dict_value, dict_type, css_class, list_class, is_default, create_dept, create_by, create_time, remark)
+VALUES (1002, '000000', 2, '类型B', '2', 'demo_xxx_type', '', 'success', 'N', 103, 1, sysdate(), '类型B');
+```
+
+### VO 中使用字典
+
+```java
+@ExcelProperty(value = "类型")
+@ExcelDictFormat(dictType = "demo_xxx_type")
+private String xxxType;
+```
+
+---
+
+## 🗂️ SQL 文件位置
+
+| 数据库 | 脚本位置 |
+|--------|---------|
+| MySQL | `script/sql/ry_vue_5.X.sql` |
+| PostgreSQL | `script/sql/postgres/` |
+| Oracle | `script/sql/oracle/` |
+| SQL Server | `script/sql/sqlserver/` |
+
+---
+
+## ✅ 设计检查清单
+
+### 表设计检查
+
+- [ ] 表前缀与模块对应（`sys_`/`test_`/`flow_` 等）
+- [ ] 主键使用雪花 ID（不用 AUTO_INCREMENT）
+- [ ] 包含 `tenant_id` 字段
+- [ ] 包含完整的审计字段
+- [ ] 包含逻辑删除字段 `del_flag`
+- [ ] 字段名使用蛇形命名法（`xxx_name` 而非 `xxxName`）
+- [ ] 所有字段都有注释
+- [ ] 状态字段配置了字典
+
+### 索引设计检查
+
+- [ ] 主键索引已建立
+- [ ] 租户字段 `tenant_id` 有索引
+- [ ] 外键字段有索引
+- [ ] 频繁查询字段有索引
+- [ ] 唯一性约束字段有唯一索引
+
+### Entity 检查
+
+- [ ] 继承 `TenantEntity`
+- [ ] `@TableName` 注解指定表名
+- [ ] `@TableId(value = "id")` 注解主键
+- [ ] 字段名与数据库字段对应（驼峰 ↔ 蛇形自动转换）
+
+---
+
+## ❌ 常见错误
+
+### 禁止的写法
+
+```sql
+-- ❌ 错误1: 使用自增 ID
+id BIGINT(20) AUTO_INCREMENT
+
+-- ❌ 错误2: 缺少租户字段
+CREATE TABLE xxx (id BIGINT NOT NULL, name VARCHAR(100))
+
+-- ❌ 错误3: 删除标志字段名错误
+is_deleted CHAR(1)  -- 应该是 del_flag
+
+-- ❌ 错误4: 缺少审计字段
+CREATE TABLE xxx (id BIGINT, name VARCHAR(100))
+
+-- ❌ 错误5: 字段名使用驼峰
+userName VARCHAR(50)  -- 应该是 user_name
+
+-- ❌ 错误6: 缺少字段注释
+name VARCHAR(100)  -- 应该有 COMMENT
+```
+
+### 正确的写法
+
+```sql
+-- ✅ 正确1: 使用雪花 ID
+id BIGINT(20) NOT NULL COMMENT '主键ID'
+
+-- ✅ 正确2: 包含租户字段
+tenant_id VARCHAR(20) DEFAULT '000000' COMMENT '租户ID'
+
+-- ✅ 正确3: 正确的删除标志字段
+del_flag CHAR(1) DEFAULT '0' COMMENT '删除标志(0正常 1已删除)'
+
+-- ✅ 正确4: 包含完整审计字段
+create_dept BIGINT(20) DEFAULT NULL COMMENT '创建部门',
+create_by BIGINT(20) DEFAULT NULL COMMENT '创建人',
+create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+update_by BIGINT(20) DEFAULT NULL COMMENT '更新人',
+update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间'
+
+-- ✅ 正确5: 字段名使用蛇形命名
+user_name VARCHAR(50) COMMENT '用户名'
+
+-- ✅ 正确6: 所有字段都有注释
+name VARCHAR(100) NOT NULL COMMENT '名称'
+```
+
+---
+
+## 📚 参考实现
+
+查看已有的完整实现：
+
+| 类型 | 参考文件 |
+|------|---------|
+| 系统表 | `script/sql/ry_vue_5.X.sql` 中的 `sys_user` 表 |
+| 演示表 | `script/sql/ry_vue_5.X.sql` 中的 `test_demo` 表 |
+| Entity | `org.dromara.demo.domain.TestDemo` |
+
+---
+
+## 🎯 总结
+
+**建表必备字段**：
+
+```sql
+id              BIGINT(20)    NOT NULL COMMENT '主键ID',
+tenant_id       VARCHAR(20)   DEFAULT '000000' COMMENT '租户ID',
+-- 业务字段...
+create_dept     BIGINT(20)    DEFAULT NULL COMMENT '创建部门',
+create_by       BIGINT(20)    DEFAULT NULL COMMENT '创建人',
+create_time     DATETIME      DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+update_by       BIGINT(20)    DEFAULT NULL COMMENT '更新人',
+update_time     DATETIME      DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+del_flag        CHAR(1)       DEFAULT '0' COMMENT '删除标志(0正常 1已删除)',
+PRIMARY KEY (id)
+```
+
+**核心原则**：
+- ✅ 主键使用雪花 ID（不用 AUTO_INCREMENT）
+- ✅ 必须包含 `tenant_id`（多租户隔离）
+- ✅ 必须包含审计字段（create_by、create_time、update_by、update_time）
+- ✅ 必须包含逻辑删除字段 `del_flag`
+- ✅ 字段名使用蛇形命名法
+- ✅ 所有字段都有注释