mirror of
https://gitcode.com/ageerle/ruoyi-ai.git
synced 2026-03-13 20:53:42 +08:00
159 lines
4.5 KiB
Markdown
159 lines
4.5 KiB
Markdown
# 数据库开发规范
|
||
|
||
|
||
## 1. 建表规约
|
||
|
||
### 1.1 表命名规范
|
||
|
||
**【强制】** 表名、字段名必须使用小写字母或数字，禁止出现数字开头，禁止两个下划线中间只出现数字。
|
||
|
||
**【强制】** 表名采用 `业务-模块-功能` 的命名方式，使用下划线分隔。
|
||
|
||
**正例：**
|
||
```sql
|
||
-- 聊天业务-配置模块-配置功能
|
||
chat_config
|
||
|
||
-- 聊天业务-消息模块-消息功能
|
||
chat_message
|
||
|
||
-- 聊天业务-模型模块-模型功能
|
||
chat_model
|
||
|
||
-- 系统业务-用户模块-用户功能
|
||
sys_user
|
||
|
||
-- 系统业务-角色模块-角色功能
|
||
sys_role
|
||
|
||
-- 知识库业务-角色模块-角色功能
|
||
knowledge_role
|
||
```
|
||
|
||
**反例：**
|
||
```sql
|
||
-- 不规范的命名
|
||
chatConfig
|
||
ChatMessage
|
||
chat-model
|
||
user1
|
||
2user
|
||
user__info
|
||
```
|
||
|
||
### 1.2 字段命名规范
|
||
|
||
**【强制】** 字段名必须使用小写字母或数字，使用下划线分隔。
|
||
|
||
**【推荐】** 表达是与否概念的字段，必须使用 `is_xxx` 的方式命名，数据类型是 `char(1)`，1 表示是，0 表示否。
|
||
|
||
**正例：** `is_deleted`、`is_enabled`
|
||
|
||
## 2. 公共字段规范
|
||
|
||
### 2.1 必备公共字段
|
||
|
||
|
||
**【推荐】** 表增加以下公共字段：
|
||
|
||
| 字段名 | 类型 | 默认值 | 说明 | 是否必须 |
|
||
|--------|------|--------|------|----------|
|
||
| `id` | `bigint(20)` | AUTO_INCREMENT | 主键ID | 是 |
|
||
| `create_time` | `datetime` | NULL | 创建时间 | 是 |
|
||
| `update_time` | `datetime` | NULL | 更新时间 | 是 |
|
||
| `create_by` | `bigint(20)` | NULL | 创建者ID | 是 |
|
||
| `update_by` | `bigint(20)` | NULL | 更新者ID | 是 |
|
||
| `create_dept` | `bigint(20)` | NULL | 创建部门ID | 是 |
|
||
| `del_flag` | `char(1)` | '0' | 删除标志（0存在 1删除） | 推荐 |
|
||
| `tenant_id` | `varchar(20)` | '000000' | 租户编号 | 多租户必须 |
|
||
| `remark` | `varchar(500)` | NULL | 备注 | 是 |
|
||
| `version` | `int(11)` | NULL | 版本号（乐观锁） | 可选 |
|
||
|
||
### 2.2 公共字段说明
|
||
|
||
- **`id`**: 主键，使用雪花算法生成的 bigint 类型
|
||
- **`create_time`**: 记录创建时间，便于数据追踪和审计
|
||
- **`update_time`**: 记录最后更新时间，便于数据同步和缓存失效
|
||
- **`create_by`**: 创建者用户ID，便于权限控制和数据追溯
|
||
- **`update_by`**: 更新者用户ID，便于操作审计
|
||
- **`del_flag`**: 逻辑删除标志，0表示正常，1表示删除
|
||
- **`tenant_id`**: 租户隔离字段，支持多租户架构
|
||
- **`remark`**: 备注信息，便于业务说明
|
||
|
||
## 3. SQL 更新管理规范
|
||
|
||
### 3.1 目录结构
|
||
|
||
```
|
||
script/
|
||
├── sql/
|
||
│ ├── ruoyi-ai.sql # 初始化SQL文件
|
||
│ └── update/ # 增量更新SQL目录
|
||
│ ├── 2024-05-24-chat-message-billing-type.sql
|
||
│ ├── 2024-07-13-chat-model-priority.sql
|
||
│ └── 2024-08-15-knowledge-role-bak.sql
|
||
└── deploy/
|
||
└── deploy/
|
||
└── mysql-init/
|
||
└── ruoyi-ai.sql # Docker初始化SQL（与主文件同步）
|
||
```
|
||
|
||
### 3.2 更新SQL规范
|
||
|
||
**【强制】** 增量更新SQL文件必须放在 `script/sql/update/` 目录下。
|
||
|
||
**【强制】** 更新SQL文件命名格式：`YYYY-MM-DD-功能描述.sql`
|
||
|
||
**正例：**
|
||
```
|
||
2024-05-24-chat-message-billing-type.sql
|
||
2024-07-13-chat-model-priority.sql
|
||
2024-08-15-knowledge-role-backup.sql
|
||
```
|
||
|
||
**【强制】** 每个更新SQL文件必须包含：
|
||
- 文件头部注释说明变更内容
|
||
- 变更日期和负责人
|
||
- 具体的DDL/DML语句
|
||
|
||
**正例：**
|
||
```sql
|
||
-- 为 chat_message 表添加 billing_type 字段
|
||
-- 变更日期: 2024-05-24
|
||
-- 负责人: 张三
|
||
-- 说明: 支持消息计费类型区分
|
||
|
||
ALTER TABLE chat_message
|
||
ADD COLUMN billing_type char NULL COMMENT '计费类型（1-token计费，2-次数计费，null-普通消息）';
|
||
```
|
||
|
||
### 3.3 部署流程
|
||
|
||
#### 3.3.1 首次部署
|
||
|
||
**【强制】** 首次初始化项目只需要执行：
|
||
```bash
|
||
mysql -u root -p database_name < script/sql/ruoyi-ai.sql
|
||
```
|
||
|
||
#### 3.3.2 增量更新
|
||
|
||
**【强制】** 代码更新时，按日期顺序执行 `script/sql/update/` 下的补丁SQL：
|
||
|
||
```bash
|
||
# 按文件名日期顺序执行
|
||
mysql -u root -p database_name < script/sql/update/2024-05-24-chat-message-billing-type.sql
|
||
mysql -u root -p database_name < script/sql/update/2024-07-13-chat-model-priority.sql
|
||
```
|
||
|
||
#### 3.3.3 同步更新
|
||
|
||
**【强制】** 当数据库发生变化时，必须同时完成以下操作：
|
||
|
||
1. 在 `script/sql/update/` 下添加增量SQL补丁
|
||
2. 将变更同步更新到初始化文件 `script/sql/ruoyi-ai.sql`
|
||
|
||
---
|
||
>
|
||
> 最后更新时间：2025-11-07
|