TanWenyan/leaudit-platform-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: refine sql operations handbook

Browse Source
This commit is contained in:
wren
2026-05-10 20:14:05 +08:00
parent ae89eec3b9
commit 601811f957
2 changed files with 137 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files
scripts/创建sql/README.md
+135 -39
View File
@@ -1,8 +1,10 @@
# SQL 脚本目录说明
# SQL 上线操作手册
本目录统一存放数据库相关 SQL，避免根目录下脚本分散。
本目录统一存放数据库相关 SQL。
## 命名约定
目标不是只告诉你“文件在哪”，而是让开发、DBA、运维拿到后可以直接按顺序执行、验收、排查。
## 目录约定
- `schema_*`：建表、补字段、补索引、结构补丁
- `seed_*`：初始化数据、菜单、权限、路由种子
@@ -11,33 +13,121 @@
- `*_patch.sql`：补丁脚本
- `*_audit.sql`：审计/巡检类脚本
## 推荐执行方式
## 通用执行规范
执行生产脚本时建议统一带上 `ON_ERROR_STOP=1`：
### 1. 推荐命令
生产执行时统一带 `ON_ERROR_STOP=1`：
```bash
psql -h <host> -U <user> -d <db_name> -v ON_ERROR_STOP=1 -f scripts/创建sql/<file>.sql
```
## 按模块分类
### 2. 执行前要求
- 先确认目标库是测试库、预发库还是正式库
- 先备份，尤其是 `schema_*` 和 `migrate_*`
- 先看脚本头部注释，确认依赖关系
- 先跑 `precheck_*`，再跑 `migrate_*`
- 生产环境优先按“单脚本执行 -> 验收 -> 下一步”推进，不要一把梭
### 3. 执行后要求
- 记录执行人、执行时间、执行环境
- 保存关键查询结果或截图
- 若脚本涉及后端新接口，执行后重启对应服务
## 快速场景索引
### 新环境最小起步
1. `user_rbac_schema_patch.sql`
2. `user_rbac_seed.sql`
3. `schema_v2_add_evaluation_tables.sql`
4. `seed_home_entry_modules.sql`
### 系统使用统计上线
1. `schema_add_usage_stats.sql`
2. `seed_usage_stats_rbac.sql`
### 评查点分组迁移
1. `precheck_rule_group_migration.sql`
2. `migrate_rule_groups_to_business_roots.sql`
3. `seed_rule_groups_rbac.sql`
4. `seed_evaluation_points_rbac.sql`
### 交叉评查一期上线
1. `schema_v3_add_cross_review_phase1.sql`
2. `seed_cross_review_phase1_permissions.sql`
### RAG 能力上线
1. `schema_add_rag_chat.sql`
2. 视环境决定是否补跑 `user_rbac_seed.sql`
## 按模块说明
### 一、系统使用统计
- `schema_add_usage_stats.sql`
- 用途：补齐系统使用统计需要的库结构
- 主要内容：新增 `usage_login_events`、给 `sso_users` 增加 `last_login_at`、补 `leaudit_audit_runs.trigger_user_id` 统计索引
- 场景：上线“系统使用统计”后端接口前必跑
- 执行时机：上线“系统使用统计”接口前必跑
- `seed_usage_stats_rbac.sql`
- 用途：补齐“系统使用统计”菜单、权限点、角色授权
- 主要内容：新增 `/usage-stats` 路由、`usage_stats:*` 权限、给 `super_admin` / `provincial_admin` / `admin` 赋权
- 场景：库结构准备完成后执行
- 执行时机：库结构完成后执行
推荐顺序：
#### 上线顺序
1. `schema_add_usage_stats.sql`
2. `seed_usage_stats_rbac.sql`
#### 标准执行命令
```bash
psql -h <host> -U <user> -d <db_name> -v ON_ERROR_STOP=1 -f scripts/创建sql/schema_add_usage_stats.sql
psql -h <host> -U <user> -d <db_name> -v ON_ERROR_STOP=1 -f scripts/创建sql/seed_usage_stats_rbac.sql
```
#### 执行后验收
```sql
SELECT column_name
FROM information_schema.columns
WHERE table_name = 'sso_users'
AND column_name = 'last_login_at';
SELECT to_regclass('public.usage_login_events');
SELECT route_path, route_title
FROM sys_routes
WHERE route_path = '/usage-stats'
AND deleted_at IS NULL;
SELECT permission_key
FROM permissions
WHERE permission_key LIKE 'usage_stats:%'
ORDER BY permission_key;
```
#### 业务验证
- 管理员登录一次，检查 `usage_login_events`
- 上传一个文档，检查上传统计是否可计数
- 发起一次评查，检查 `leaudit_audit_runs.trigger_user_id`
- 用地区管理员账号访问统计接口，确认只能看到本地区数据
#### 失败排查
- `schema_add_usage_stats.sql` 失败：先停，不要继续跑 seed
- `seed_usage_stats_rbac.sql` 失败：先查 `/settings` 路由、`roles` 是否存在
- 统计接口 500：重点检查 `sso_users`、`leaudit_audit_runs`、`usage_login_events`
### 二、用户 / RBAC / 地区权限
- `user_rbac_schema_patch.sql`
@@ -55,12 +145,12 @@ psql -h <host> -U <user> -d <db_name> -v ON_ERROR_STOP=1 -f scripts/创建sql/<f
- 用途：老系统迁移前数据审计
- 场景：检查空地区、脏角色、重复账号、无角色用户等风险
常见顺序：
#### 常见顺序
1. `user_rbac_schema_patch.sql`
2. `user_rbac_seed.sql`
3. `user_rbac_comments_patch.sql`
4. `user_rbac_migration_audit.sql`（按需执行）
4. `user_rbac_migration_audit.sql`
### 三、首页入口 / 文档类型 / 前端路由
@@ -73,7 +163,7 @@ psql -h <host> -U <user> -d <db_name> -v ON_ERROR_STOP=1 -f scripts/创建sql/<f
- `seed_frontend_route_scope.sql`
- 用途：补齐前端真实菜单树仍需暴露的路由范围
常见顺序：
#### 常见顺序
1. `schema_v2_add_evaluation_tables.sql`
2. `seed_home_entry_modules.sql`
@@ -99,13 +189,19 @@ psql -h <host> -U <user> -d <db_name> -v ON_ERROR_STOP=1 -f scripts/创建sql/<f
- `seed_evaluation_points_rbac.sql`
- 用途：补齐规则/评查点相关权限点
推荐顺序：
#### 推荐顺序
1. `precheck_rule_group_migration.sql`
2. `migrate_rule_groups_to_business_roots.sql`
3. `seed_rule_groups_rbac.sql`
4. `seed_evaluation_points_rbac.sql`
#### 操作建议
- 先在测试库做全量演练
- 先导出旧表备份
- 迁移完成后重点验收：文档类型绑定页、规则组页、上传页、评查执行链路
### 五、旧绑定下线检查
- `precheck_drop_legacy_rule_type_bindings.sql`
@@ -120,7 +216,7 @@ psql -h <host> -U <user> -d <db_name> -v ON_ERROR_STOP=1 -f scripts/创建sql/<f
- `seed_cross_review_phase1_permissions.sql`
- 用途：交叉评查第一阶段权限种子
推荐顺序：
#### 推荐顺序
1. `schema_v3_add_cross_review_phase1.sql`
2. `seed_cross_review_phase1_permissions.sql`
@@ -129,6 +225,7 @@ psql -h <host> -U <user> -d <db_name> -v ON_ERROR_STOP=1 -f scripts/创建sql/<f
- `schema_add_rag_chat.sql`
- 用途：RAG 数据集、会话等相关结构初始化/补充
- 说明：若环境还没补齐 RBAC 菜单/权限，联动检查 `user_rbac_seed.sql`
### 八、文档版本管理
@@ -136,34 +233,33 @@ psql -h <host> -U <user> -d <db_name> -v ON_ERROR_STOP=1 -f scripts/创建sql/<f
- 用途：给 `leaudit_documents` 补齐版本归档能力
- 主要内容：增加版本链字段、归一化名称、历史数据回填
## 快速索引
## 生产环境最小执行清单
### 新环境最小起步
### 通用模板
1. `user_rbac_schema_patch.sql`
2. `user_rbac_seed.sql`
3. `schema_v2_add_evaluation_tables.sql`
4. `seed_home_entry_modules.sql`
1. 确认目标库
2. 备份
3. 跑 `precheck_*` 或确认依赖
4. 执行 1 个脚本
5. 做 1 轮验收
6. 再执行下一个脚本
7. 重启相关服务
8. 做接口与业务验证
### 系统使用统计上线
### 系统使用统计模板
1. `schema_add_usage_stats.sql`
2. `seed_usage_stats_rbac.sql`
1. 备份 `sso_users`、`sys_routes`、`permissions`、`role_permissions`、`role_route`、`leaudit_audit_runs`
2. 执行 `schema_add_usage_stats.sql`
3. 执行结构验收 SQL
4. 执行 `seed_usage_stats_rbac.sql`
5. 执行菜单/权限验收 SQL
6. 重启后端服务
7. 登录一次、上传一次、评查一次
8. 用超级管理员和地区管理员分别验证接口返回范围
### 评查点分组迁移
## 维护规则
1. `precheck_rule_group_migration.sql`
2. `migrate_rule_groups_to_business_roots.sql`
3. `seed_rule_groups_rbac.sql`
### 交叉评查一期上线
1. `schema_v3_add_cross_review_phase1.sql`
2. `seed_cross_review_phase1_permissions.sql`
## 注意事项
- 生产执行前先备份，尤其是 `migrate_*` 和 `schema_*` 脚本
- `precheck_*` 为只读脚本，适合上线前先跑一遍
- `seed_*` 通常按幂等方式写，但仍建议先在测试/预发验证
- 当前仓库文档和脚本引用已统一迁移到 `scripts/创建sql/`，后续新增 SQL 也请继续放这里
- 新增 SQL 一律放 `scripts/创建sql/`
- 新增脚本时同步补本 README
- 若脚本执行顺序变化，优先更新这里，再更新业务文档
- 若脚本已废弃，保留文件时必须在头部写明“已废弃”和替代脚本