# SQL 脚本目录说明

本目录存放数据库变更脚本，按用途分两个子目录：

```
docs/sql/
├── addsql/    增量脚本：在已有数据库上执行的变更
└── fullsql/   全量脚本：从空库一次性初始化到当前版本
```

## addsql —— 增量脚本

日常开发、迭代产生的数据库变更都放这里，例如：

- 新建表、新增/修改字段、索引
- 字典、菜单、权限等初始化数据
- 数据修复、历史数据补录（如材料价格补采的批量 INSERT）

约定：

1. 文件名用变更日期：`YYYYMMDD.sql`；同一天多次提交用 `YYYYMMDD_02.sql` 递增。
2. 只写本次变更的内容，不要重复写已存在的结构。
3. 优先写成可重复执行的语句（`CREATE TABLE IF NOT EXISTS` 等）。MySQL 的
   `ADD/DROP COLUMN` 不支持 `IF NOT EXISTS`，这类脚本直接写静态 DDL 即可，
   但必须在文件头注明「仅执行一次」，并写清停服/部署顺序。
4. 上线时按文件名日期顺序依次执行，不要跳序；同日多个脚本用 `_02`、`_03` 递增。
5. 大文件（批量数据导入）也放这里，文件头注明数据范围与来源。
6. 清库、重置类脚本（`TRUNCATE` / `DELETE` 全表）会让每次执行都丢数据，
   不要和结构变更混在同一个脚本里，单独成文件并在文件头显著标注影响范围。

## fullsql —— 全量脚本

用于新环境初始化、测试库重建、交付部署。约定：

1. 一个脚本从空库直接建到与当前代码匹配的完整结构（表、索引、基础数据）。
2. 文件名同样用日期：`YYYYMMDD.sql`。
3. 每次结构有变更，除了在 `addsql` 增加量脚本外，要同步更新 `fullsql`，
   保证新环境不需要再逐个补历史增量。

## 通用要求

- 每个脚本文件头写清楚：用途、关联需求/工单、目标库（如 `xg_saas`）。
- 生产环境执行前先备份，执行后核对表结构与数据量。
- 不要把本地调试数据、带真实账号密码的配置写进脚本。