all-project/docs/设计文档/database

数据库设计目录

目录说明

此目录用于存放项目的数据库设计相关文档和脚本文件。

📁 目录结构

database/
├── README.md                    # 本说明文件
├── hzdyjs_xg.sql               # 完整数据库模型 (当前系统的完整表结构)
├── database_msg.md             # 数据库环境配置信息
├── 数据库设计说明.md             # 整体数据库设计文档
├── ER图设计文档.md               # 实体关系图设计
├── 表结构设计.md                 # 详细表结构和字段说明
├── 数据字典.md                   # 数据字典和编码规范
├── DDL/                         # 数据定义语言脚本
│   ├── system/                  # 系统核心表
│   │   ├── sys_tables.sql       # 系统管理表
│   │   ├── auth_tables.sql      # 权限认证表
│   │   └── tenant_tables.sql    # 多租户表
│   ├── business/                # 业务模块表
│   │   ├── hq_tables.sql        # 后勤管理相关表
│   │   └── custom_tables.sql    # 自定义业务表
│   ├── indexes.sql              # 索引创建脚本
│   └── constraints.sql          # 约束创建脚本
├── DML/                         # 数据操作语言脚本
│   ├── init_data.sql            # 初始化数据脚本
│   ├── dict_data.sql            # 字典数据脚本
│   ├── menu_data.sql            # 菜单权限数据
│   └── test_data.sql            # 测试数据脚本
├── models/                      # 数据模型文件
│   ├── erd/                     # ER图文件
│   │   ├── system_erd.drawio    # 系统模块ER图
│   │   ├── business_erd.drawio  # 业务模块ER图
│   │   └── complete_erd.png     # 完整ER图导出
│   └── schema/                  # 数据库schema文件
│       ├── mysql_schema.sql     # MySQL数据库schema
│       ├── oracle_schema.sql    # Oracle数据库schema
│       └── postgres_schema.sql  # PostgreSQL数据库schema
└── migration/                   # 数据库迁移脚本
    ├── v5.0_to_v5.1/           # 版本升级脚本
    ├── v5.1_to_v5.2/
    └── rollback/                # 回滚脚本

🎯 不同类型数据模型的存放建议

0. 当前完整数据库模型

• 主模型文件: docs/design/database/hzdyjs_xg.sql
• 内容: 当前系统的完整数据库表结构，包含所有业务表和系统表
• 说明: 包含宿舍管理 (bed*, dormitory_)、工作流 (flow__) 等业务模块
• 环境配置: docs/design/database/database_msg.md 包含开发环境数据库连接信息

1. 系统核心数据模型

• 位置: docs/design/database/DDL/system/
• 内容: 系统管理、权限认证、多租户等核心表结构
• 示例: sys_user, sys_role, sys_menu, sys_tenant

2. 业务模块数据模型

• 位置: docs/design/database/DDL/business/
• 内容: 具体业务功能相关的表结构
• 示例: 后勤管理、报告厅预约、满意度调查等

3. 初始化和测试数据

• 位置: docs/design/database/DML/
• 内容: 系统初始化数据、字典数据、测试数据等

4. ER 图和设计文档

• 位置: docs/design/database/models/
• 内容: 数据库设计图表、关系图、设计说明等

5. 版本升级脚本

• 位置: docs/design/database/migration/
• 内容: 数据库版本升级脚本、数据迁移脚本等

🔄 与现有目录的关联

现有 SQL 脚本位置

• 当前完整模型: docs/design/database/hzdyjs_xg.sql → 当前系统的完整数据库模型 (3638 行)
• 环境配置: docs/design/database/database_msg.md → 开发环境数据库连接信息
• 框架主脚本: script/sql/ry_vue_5.X.sql → 参考并拆分到对应模块
• 更新脚本: script/sql/update/ → 整理到 migration 目录
• 业务脚本: docs/requirements/*/ → 移动到 business 目录

同步规则

1. 新表设计: 先在docs/design/database/中设计，再更新到script/sql/
2. 表结构变更: 同时更新设计文档和升级脚本
   • 必须同步更新: docs/design/database/hzdyjs_xg.sql 中的表结构
   • 环境配置变更: 及时更新 docs/design/database/database_msg.md
3. 文档维护: 每次数据库变更都要更新相关设计文档

📝 文件命名规范

DDL 脚本命名

• 系统表: sys_*.sql (如: sys_user.sql)
• 业务表: 模块前缀_*.sql (如: hq_survey.sql)
• 索引脚本: idx_表名.sql (如: idx_sys_user.sql)

文档命名

• 设计文档: 使用中文描述性名称
• ER 图文件: 模块名_erd.drawio
• 导出图片: 模块名_erd.png

⚠️ 注意事项

1. 版本控制: 所有 DDL 变更都要记录版本和变更原因
2. 多数据库支持: 考虑 MySQL、Oracle、PostgreSQL 的兼容性
3. 命名规范: 遵循框架统一的命名规范（下划线命名法）
4. 文档同步: 表结构变更必须同时更新设计文档
   • 关键文件: hzdyjs_xg.sql 必须保持最新的完整表结构
   • 环境安全: database_msg.md 中的密码信息注意安全保护
5. 备份策略: 重要脚本变更前要备份现有版本
6. 当前系统参考: 新增表结构应参考 hzdyjs_xg.sql 中现有表的设计规范

数据库设计说明

📋 文档结构

本目录包含项目数据库设计的核心文档：

• 📊 mysql-database-standard.md - MySQL 数据库建设规范（强制性）
• 🗄️ hzdyjs_xg.sql - 完整数据库模型文件
• 🔧 database_msg.md - 数据库环境配置信息

---

🔴 强制性要求

⚠️ 超级重要：数据库建设强制规范

所有数据库相关的开发工作都必须严格遵循 mysql-database-standard.md 中的规范！

核心强制规范：

1. ✅ 所有业务表必须包含标准基础字段
2. ✅ 统一使用雪花 ID 作为主键
3. ✅ 强制使用逻辑删除，禁止物理删除
4. ✅ 所有表必须支持多租户
5. ✅ 完整的中文注释是必须的

违规后果：

• 不符合规范的表结构将被要求重新设计
• 所有数据库变更都需要经过 Code Review
• 必须与现有数据库模型保持高度一致性

---

🤖 Cursor AI 开发要求

使用 Cursor AI 进行数据库开发时的强制要求：

1. 必须参考规范文档

在进行任何数据库相关开发前，必须：

• 仔细阅读 mysql-database-standard.md 规范
• 参考 hzdyjs_xg.sql 中的现有表结构
• 遵循完全一致的设计模式

2. 强制使用标准模板

• 使用规范文档中提供的建表 SQL 模板
• 所有表必须包含完整的基础字段
• 索引设计必须符合规范要求

3. AI 开发提示词模板

请根据 docs/设计文档/database/mysql-database-standard.md 中的规范，
参考 docs/设计文档/database/hzdyjs_xg.sql 中现有表结构的设计模式，
为 [模块名称] 创建 [表名称] 表。

要求：
1. 严格遵循标准基础字段规范
2. 使用bigint(20)作为主键类型
3. 包含完整的租户支持和逻辑删除
4. 添加完整的中文注释
5. 创建必要的基础索引
6. 使用标准的字段命名规范

请确保生成的SQL与现有表结构风格完全一致。

---

📊 数据库概览

基本信息

• 数据库名称: hzdyjs_xg
• MySQL 版本: 5.7.36+
• 字符集: utf8mb4
• 存储引擎: InnoDB
• 环境配置: 详见 database_msg.md

表数量统计

根据 hzdyjs_xg.sql 统计，数据库包含约 48 个核心表：

核心业务模块

• 工作流模块 (flow_*): 8 个表
• 系统管理模块 (sys_*): 18 个表
• 后勤管理模块 (hq_*): 11 个表
• 代码生成模块 (gen_*): 2 个表
• 任务调度模块 (sj_*): 19 个表
• 测试模块 (test_*): 3 个表

表结构设计模式

标准基础字段（每个业务表必须包含）

`id` bigint(20) NOT NULL COMMENT '主键ID',
`tenant_id` varchar(20) NOT NULL DEFAULT '000000' COMMENT '租户编号',
`create_dept` bigint(20) DEFAULT NULL COMMENT '创建部门',
`create_by` bigint(20) DEFAULT NULL COMMENT '创建者',
`create_time` datetime DEFAULT NULL COMMENT '创建时间',
`update_by` bigint(20) DEFAULT NULL COMMENT '更新者',
`update_time` datetime DEFAULT NULL COMMENT '更新时间',
`deleted` tinyint(1) DEFAULT 0 COMMENT '删除标志（0代表存在 1代表删除）'

关键设计特征

• 主键策略: 雪花 ID (bigint(20))
• 多租户支持: tenant_id 字段
• 逻辑删除: deleted 字段
• 审计追踪: 完整的创建和更新信息
• 索引设计: 租户、状态、时间等关键字段

命名规范

• 表名: 模块前缀 + 下划线 + 业务含义 (如: hq_hall_info)
• 字段名: 下划线命名法 (如: user_name, create_time)
• 索引名: idx*字段名 或 uk*字段名

---

🔧 开发使用指南

建表操作流程

1. 设计前准备

• 阅读 mysql-database-standard.md 规范
• 分析 hzdyjs_xg.sql 中类似表的设计
• 确定表名和字段设计

2. 使用标准模板

• 复制规范文档中的标准模板
• 添加业务字段，保持基础字段不变
• 设计合理的索引结构

3. 代码审查

• 对照检查清单验证表结构
• 确保与现有表风格一致
• 提交前进行团队 Review

表结构修改流程

1. 变更评估

• 评估变更影响范围
• 确保向前兼容性
• 准备数据迁移方案

2. 执行变更

• 使用标准的 ALTER 语句
• 新增字段必须有默认值
• 更新相关文档

3. 验证和部署

• 在测试环境验证
• 准备回滚预案
• 记录变更日志

数据查询规范

必须包含的条件

-- 多租户隔离（必须）
WHERE tenant_id = '当前租户ID'

-- 逻辑删除过滤（建议）
AND deleted = 0

-- 分页查询（大数据量）
ORDER BY create_time DESC
LIMIT 20 OFFSET 0

索引优化查询

-- 利用组合索引
WHERE tenant_id = '000000'
  AND status = '0'
  AND create_time >= '2025-01-01'

---

⚠️ 注意事项

🔴 强制性要求

1. 新建表必须使用标准模板
2. 所有字段必须有中文注释
3. 必须创建租户和删除标志索引
4. 外键字段必须创建索引
5. 禁止使用物理删除

🚫 禁止事项

1. 禁止修改基础字段的类型和含义
2. 禁止删除租户支持相关字段
3. 禁止使用 timestamp 类型
4. 禁止使用 enum 和 set 类型
5. 禁止创建没有注释的字段

✅ 最佳实践

1. 字段长度要合理设置
2. 状态字段统一使用 char(1)
3. 时间字段统一使用 datetime
4. 金额字段使用 decimal 类型
5. 大文本使用 text 类型

---

🔍 快速检查

表结构自检清单

在创建或修改表时，请对照以下清单：

基础字段检查

• id 字段: bigint(20) NOT NULL
• tenant_id 字段: varchar(20) NOT NULL DEFAULT '000000'
• create_*字段: 完整的创建审计字段
• update_*字段: 完整的更新审计字段
• deleted 字段: tinyint(1) DEFAULT 0

业务字段检查

• 字段命名: 下划线命名法
• 数据类型: 符合规范要求
• 默认值: 合理设置
• 注释: 完整的中文说明

索引检查

• 基础索引: tenant_id, deleted, create_time
• 业务索引: 状态、外键、查询字段
• 唯一约束: 包含租户隔离

表定义检查

• 表注释: 清晰的中文说明
• 引擎: InnoDB
• 字符集: utf8mb4
• 命名: 符合模块前缀规范

---

📚 相关资源

📖 核心文档

• MySQL 数据库建设规范 - 必读规范
• 数据库配置信息 - 环境配置
• 完整数据库模型 - 参考示例

🔗 外部资源

• MySQL 8.0 官方文档
• 阿里巴巴 Java 开发手册-数据库规约

📝 变更记录

所有数据库变更必须记录在：docs/变更管理/code-adjust-record.md

---

🎯 目标和愿景

通过严格的数据库设计规范，我们致力于：

1. 🎯 保证数据一致性: 统一的表结构设计
2. ⚡ 提升查询性能: 合理的索引策略
3. 🔒 确保数据安全: 多租户隔离和逻辑删除
4. 📈 支持业务发展: 可扩展的架构设计
5. 🛠️ 降低维护成本: 标准化的开发流程

---

🚨 重要提醒: 数据库是系统的核心，任何不规范的设计都可能对系统造成长期的负面影响。请务必严格遵循规范，确保系统的稳定性和可维护性！

---

最后更新: 2025-01-08
文档维护: 项目技术团队