docs(scripts): organize sql files under 创建sql

2026-05-10 19:56:31 +08:00
parent be41863099
commit ae89eec3b9
26 changed files with 206 additions and 37 deletions
@@ -218,9 +218,9 @@
 ### 11. 规则组迁移方案文档与脚本已经补齐

 已补充：
- `scripts/precheck_rule_group_migration.sql`
- `scripts/migrate_rule_groups_to_business_roots.sql`
- `scripts/migrate_rule_groups_to_doc_type_roots.sql`
+- `scripts/创建sql/precheck_rule_group_migration.sql`
+- `scripts/创建sql/migrate_rule_groups_to_business_roots.sql`
+- `scripts/创建sql/migrate_rule_groups_to_doc_type_roots.sql`
 - `docs/评查点分组/评查点分组迁移执行前检查清单.md`

 说明：
@@ -318,12 +318,12 @@
 | 位置 | 作用 |
 |------|------|
 | `rules/contract_loan/rules.yaml` | 借款合同规则集修复点 |
-| `scripts/seed_frontend_route_scope.sql` | 前端真实路由范围 seed |
-| `scripts/user_rbac_seed.sql` | RBAC 基础 seed |
-| `scripts/seed_home_entry_modules.sql` | 首页入口模块 seed |
-| `scripts/precheck_rule_group_migration.sql` | 分组迁移前检查 |
-| `scripts/migrate_rule_groups_to_business_roots.sql` | 按业务根迁移分组 |
-| `scripts/migrate_rule_groups_to_doc_type_roots.sql` | 按文档类型根迁移分组 |
+| `scripts/创建sql/seed_frontend_route_scope.sql` | 前端真实路由范围 seed |
+| `scripts/创建sql/user_rbac_seed.sql` | RBAC 基础 seed |
+| `scripts/创建sql/seed_home_entry_modules.sql` | 首页入口模块 seed |
+| `scripts/创建sql/precheck_rule_group_migration.sql` | 分组迁移前检查 |
+| `scripts/创建sql/migrate_rule_groups_to_business_roots.sql` | 按业务根迁移分组 |
+| `scripts/创建sql/migrate_rule_groups_to_doc_type_roots.sql` | 按文档类型根迁移分组 |
 | `docs/接口/` | 当前有效接口主文档 |

 ---
@@ -10,8 +10,8 @@
  - `fastapi_modules/fastapi_leaudit/controllers/ragChatController.py`
  - `fastapi_modules/fastapi_leaudit/services/impl/ragChatServiceImpl.py`
  - `fastapi_modules/fastapi_leaudit/services/impl/ragDatasetServiceImpl.py`
-  - `scripts/schema_add_rag_chat.sql`
-  - `scripts/user_rbac_seed.sql`
+  - `scripts/创建sql/schema_add_rag_chat.sql`
+  - `scripts/创建sql/user_rbac_seed.sql`
  - `pyproject.toml` 已加入 `chromadb`
 - 发布分支已经合并到目标部署分支。
 - 数据库备份已完成，至少备份：
@@ -138,7 +138,7 @@ pip install chromadb
 ```bash
 psql -v ON_ERROR_STOP=1 \
  -h <DB_HOST> -p <DB_PORT> -U <DB_USER> -d <DB_NAME> \
-  -f scripts/schema_add_rag_chat.sql
+  -f scripts/创建sql/schema_add_rag_chat.sql
 ```

 作用：
@@ -150,7 +150,7 @@ psql -v ON_ERROR_STOP=1 \
 ```bash
 psql -v ON_ERROR_STOP=1 \
  -h <DB_HOST> -p <DB_PORT> -U <DB_USER> -d <DB_NAME> \
-  -f scripts/user_rbac_seed.sql
+  -f scripts/创建sql/user_rbac_seed.sql
 ```

 作用：
@@ -192,8 +192,8 @@ pip install -e .

 按“第 5 节”的先后顺序执行：

-1. `scripts/schema_add_rag_chat.sql`
-2. `scripts/user_rbac_seed.sql`
+1. `scripts/创建sql/schema_add_rag_chat.sql`
+2. `scripts/创建sql/user_rbac_seed.sql`

 ### 步骤 4：重启 FastAPI 主服务

@@ -302,8 +302,8 @@ ORDER BY r.role_key;
 1. 备份数据库
 2. `git pull`
 3. `source .venv/bin/activate && pip install -e .`
-4. 执行 `scripts/schema_add_rag_chat.sql`
-5. 执行 `scripts/user_rbac_seed.sql`
+4. 执行 `scripts/创建sql/schema_add_rag_chat.sql`
+5. 执行 `scripts/创建sql/user_rbac_seed.sql`
 6. 重启 FastAPI 主服务
 7. 重启 `scripts/start_worker.sh`
 8. 验证 `/api/v3/rag/apps` 和 `/api/v3/rag/chat/messages`
@@ -71,7 +71,7 @@ LeAudit 有一套自己的 SQLAlchemy ORM 表（`storage/models/`）。**leaudit
 | 17 | `leaudit_evaluation_points` | 规则点/评查点元数据 | ✅ 已创建 |

 > 所有表均含 `create_time` / `update_time` / `delete_time` 三时间戳 + 中文列注释。  
-> 详细建表 SQL 见 `scripts/schema_v2_add_evaluation_tables.sql`。
+> 详细建表 SQL 见 `scripts/创建sql/schema_v2_add_evaluation_tables.sql`。

 ---

@@ -28,7 +28,7 @@
 执行：

 ```bash
-psql ... -f scripts/precheck_drop_legacy_rule_type_bindings.sql
+psql ... -f scripts/创建sql/precheck_drop_legacy_rule_type_bindings.sql
 ```

 重点看：
@@ -4,11 +4,11 @@

 ## 1. 目标

-本清单用于在正式执行 `scripts/migrate_rule_groups_to_doc_type_roots.sql` 之前，先把当前库里的旧数据、兼容态数据和潜在冲突点查清楚。
+本清单用于在正式执行 `scripts/创建sql/migrate_rule_groups_to_doc_type_roots.sql` 之前，先把当前库里的旧数据、兼容态数据和潜在冲突点查清楚。

 如果希望直接执行一份只读巡检 SQL，可使用：

- `scripts/precheck_rule_group_migration.sql`
+- `scripts/创建sql/precheck_rule_group_migration.sql`

 本次迁移的目标仍然是：

@@ -272,7 +272,7 @@ ORDER BY rs.id;

 字段补完后，重新执行：

- `scripts/precheck_rule_group_migration.sql`
+- `scripts/创建sql/precheck_rule_group_migration.sql`

 确认：

@@ -283,11 +283,11 @@ ORDER BY rs.id;

 再执行：

- `scripts/migrate_rule_groups_to_business_roots.sql`
+- `scripts/创建sql/migrate_rule_groups_to_business_roots.sql`

 说明：

- 旧脚本 `scripts/migrate_rule_groups_to_doc_type_roots.sql` 仅保留兼容历史引用
+- 旧脚本 `scripts/创建sql/migrate_rule_groups_to_doc_type_roots.sql` 仅保留兼容历史引用
 - 不建议继续作为正式迁移脚本使用

 ### 步骤 5：迁后验证 4 个页面
@@ -3,7 +3,7 @@
 这份说明对应两个文件：

 - `scripts/migrate_legacy_users.py`
- `scripts/user_rbac_migration_audit.sql`
+- `scripts/创建sql/user_rbac_migration_audit.sql`

 目标很明确：

@@ -129,7 +129,7 @@ python3 scripts/migrate_legacy_users.py --apply
 如果你想先单独跑审计，用这个：

 ```bash
-psql -h 172.16.0.81 -p 54302 -U docauditai_admin -d docauditai -f scripts/user_rbac_migration_audit.sql
+psql -h 172.16.0.81 -p 54302 -U docauditai_admin -d docauditai -f scripts/创建sql/user_rbac_migration_audit.sql
 ```

 它会检查：
@@ -172,9 +172,9 @@ psql -h 172.16.0.81 -p 54302 -U docauditai_admin -d docauditai -f scripts/user_r

 建议严格按这个顺序：

-1. 确认 `scripts/user_rbac_schema_patch.sql` 已执行
-2. 确认 `scripts/user_rbac_seed.sql` 已执行
-3. 先跑 `scripts/user_rbac_migration_audit.sql`
+1. 确认 `scripts/创建sql/user_rbac_schema_patch.sql` 已执行
+2. 确认 `scripts/创建sql/user_rbac_seed.sql` 已执行
+3. 先跑 `scripts/创建sql/user_rbac_migration_audit.sql`
 4. 再跑 `python3 scripts/migrate_legacy_users.py` 做 dry-run
 5. 最后跑 `python3 scripts/migrate_legacy_users.py --apply`

@@ -0,0 +1,169 @@
+# SQL 脚本目录说明
+
+本目录统一存放数据库相关 SQL，避免根目录下脚本分散。
+
+## 命名约定
+
+- `schema_*`：建表、补字段、补索引、结构补丁
+- `seed_*`：初始化数据、菜单、权限、路由种子
+- `precheck_*`：正式迁移/删表前的只读巡检脚本
+- `migrate_*`：数据迁移、历史结构升级
+- `*_patch.sql`：补丁脚本
+- `*_audit.sql`：审计/巡检类脚本
+
+## 推荐执行方式
+
+执行生产脚本时建议统一带上 `ON_ERROR_STOP=1`：
+
+```bash
+psql -h <host> -U <user> -d <db_name> -v ON_ERROR_STOP=1 -f scripts/创建sql/<file>.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`
+
+### 二、用户 / RBAC / 地区权限
+
+- `user_rbac_schema_patch.sql`
+  - 用途：补齐用户、角色、权限、路由核心表结构
+  - 场景：新库初始化或旧库尚未具备 RBAC 基础表时
+
+- `user_rbac_seed.sql`
+  - 用途：初始化基础角色、权限、路由种子
+  - 依赖：`user_rbac_schema_patch.sql`
+
+- `user_rbac_comments_patch.sql`
+  - 用途：补充 RBAC 相关表和字段中文注释
+
+- `user_rbac_migration_audit.sql`
+  - 用途：老系统迁移前数据审计
+  - 场景：检查空地区、脏角色、重复账号、无角色用户等风险
+
+常见顺序：
+
+1. `user_rbac_schema_patch.sql`
+2. `user_rbac_seed.sql`
+3. `user_rbac_comments_patch.sql`
+4. `user_rbac_migration_audit.sql`（按需执行）
+
+### 三、首页入口 / 文档类型 / 前端路由
+
+- `schema_v2_add_evaluation_tables.sql`
+  - 用途：补充入口模块、文档类型及相关结构
+
+- `seed_home_entry_modules.sql`
+  - 用途：初始化首页入口模块并绑定既有文档类型
+
+- `seed_frontend_route_scope.sql`
+  - 用途：补齐前端真实菜单树仍需暴露的路由范围
+
+常见顺序：
+
+1. `schema_v2_add_evaluation_tables.sql`
+2. `seed_home_entry_modules.sql`
+3. `seed_frontend_route_scope.sql`
+
+### 四、评查点分组迁移
+
+- `precheck_rule_group_migration.sql`
+  - 用途：正式迁移前巡检当前分组树、规则集绑定、入口模块映射
+  - 特点：只读，不改数据
+
+- `migrate_rule_groups_to_business_roots.sql`
+  - 用途：按“业务大类根”做正式迁移
+  - 说明：当前正式迁移入口脚本
+
+- `migrate_rule_groups_to_doc_type_roots.sql`
+  - 用途：历史草案保留
+  - 说明：已废弃，仅兼容历史引用，请改用 `migrate_rule_groups_to_business_roots.sql`
+
+- `seed_rule_groups_rbac.sql`
+  - 用途：补齐评查点分组页面与接口的 RBAC 权限
+
+- `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`
+  - 用途：删除 `leaudit_rule_type_bindings` 前做覆盖率和风险检查
+  - 特点：只读，不删除数据
+
+### 六、交叉评查
+
+- `schema_v3_add_cross_review_phase1.sql`
+  - 用途：交叉评查第一阶段表结构
+
+- `seed_cross_review_phase1_permissions.sql`
+  - 用途：交叉评查第一阶段权限种子
+
+推荐顺序：
+
+1. `schema_v3_add_cross_review_phase1.sql`
+2. `seed_cross_review_phase1_permissions.sql`
+
+### 七、RAG
+
+- `schema_add_rag_chat.sql`
+  - 用途：RAG 数据集、会话等相关结构初始化/补充
+
+### 八、文档版本管理
+
+- `migrate_20260429_document_versioning.sql`
+  - 用途：给 `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. `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`
+
+### 交叉评查一期上线
+
+1. `schema_v3_add_cross_review_phase1.sql`
+2. `seed_cross_review_phase1_permissions.sql`
+
+## 注意事项
+
+- 生产执行前先备份，尤其是 `migrate_*` 和 `schema_*` 脚本
+- `precheck_*` 为只读脚本，适合上线前先跑一遍
+- `seed_*` 通常按幂等方式写，但仍建议先在测试/预发验证
+- 当前仓库文档和脚本引用已统一迁移到 `scripts/创建sql/`，后续新增 SQL 也请继续放这里
@@ -11,7 +11,7 @@
 --      - 已存在新一级业务根 root.contract / root.casefile
 --      - 已存在默认二级分组 *.default / 通用
 -- 2. 执行前必须先跑：
--      scripts/precheck_rule_group_migration.sql
+--      scripts/创建sql/precheck_rule_group_migration.sql
 -- 3. 必须先备份：
 --      leaudit_evaluation_point_groups
 --      leaudit_rule_group_bindings
@@ -1,5 +1,5 @@
 -- 已废弃：文件名保留仅为兼容历史引用，请改用：
--   scripts/migrate_rule_groups_to_business_roots.sql
+--   scripts/创建sql/migrate_rule_groups_to_business_roots.sql
 --
 -- 评查点分组迁移草案（产品新口径）
 -- 目标结构：
@@ -1,6 +1,6 @@
 -- 删除 leaudit_rule_type_bindings 前的检查 SQL（仅检查，不执行删除）
 -- 使用方式：
--   psql ... -f scripts/precheck_drop_legacy_rule_type_bindings.sql
+--   psql ... -f scripts/创建sql/precheck_drop_legacy_rule_type_bindings.sql

 \echo '=== 1. 文档类型总量 / 新旧绑定覆盖情况 ==='
 WITH doc_types AS (
@@ -4,7 +4,7 @@
 -- 2. 本脚本只做查询，不修改任何数据
 --
 -- 推荐执行方式：
-- psql "$DATABASE_URL" -f scripts/precheck_rule_group_migration.sql
+-- psql "$DATABASE_URL" -f scripts/创建sql/precheck_rule_group_migration.sql

 -- =========================================================
 -- 0. 文档类型与入口模块映射总览
@@ -72,7 +72,7 @@ VALUES
    ('/contract-template/search', 'contract-template.search', 'contract-template.search', (SELECT id FROM template_root), '模板搜索', 'ri-search-line', 1, FALSE, TRUE, '{"group":"contract"}'::jsonb, 0, NOW(), NOW(), NULL),
    ('/contract-template/list', 'contract-template.list', 'contract-template.list', (SELECT id FROM template_root), '模板列表', 'ri-folder-line', 2, FALSE, TRUE, '{"group":"contract"}'::jsonb, 0, NOW(), NOW(), NULL),
    ('/cross-checking/upload', 'cross-checking.upload', 'cross-checking.upload', (SELECT id FROM cross_root), '创建任务', 'ri-upload-cloud-line', 1, FALSE, TRUE, '{"group":"cross-review"}'::jsonb, 0, NOW(), NOW(), NULL),
-    ('/cross-checking/result', 'cross-checking.result', 'cross-checking.result', (SELECT id FROM cross_root), '评查结果', 'ri-file-list-3-line', 2, FALSE, TRUE, '{"group":"cross-review"}'::jsonb, 0, NOW(), NOW(), NULL)
+    ('/cross-checking/result', 'cross-checking.result', 'cross-checking.result', (SELECT id FROM cross_root), '评查任务列表', 'ri-file-list-3-line', 2, FALSE, TRUE, '{"group":"cross-review"}'::jsonb, 0, NOW(), NOW(), NULL)
 ON CONFLICT (route_path) WHERE deleted_at IS NULL
 DO UPDATE SET
    route_name = EXCLUDED.route_name,
@@ -96,7 +96,7 @@ SET
        WHEN child.route_path = '/contract-template/search' THEN '模板搜索'
        WHEN child.route_path = '/contract-template/list' THEN '模板列表'
        WHEN child.route_path = '/cross-checking/upload' THEN '创建任务'
-        WHEN child.route_path = '/cross-checking/result' THEN '评查结果'
+        WHEN child.route_path = '/cross-checking/result' THEN '评查任务列表'
        ELSE child.route_title
    END,
    updated_at = NOW()
@@ -1,7 +1,7 @@
 -- ==========================================================================
 -- LeAudit Platform RBAC / User Seed
 -- 说明：
--   1. 本文件依赖 scripts/user_rbac_schema_patch.sql 已执行
+--   1. 本文件依赖 scripts/创建sql/user_rbac_schema_patch.sql 已执行
 --   2. 权限键统一采用 module:resource:action 风格
 --   3. 当前只初始化新系统当前开发真正需要的最小权限集
 -- ============================================================================
@@ -44,7 +44,7 @@ VALUES
    ('/contract-template/list', 'contract-template.list', 'contract-template/list', NULL, '模板列表', 'folder', 42, FALSE, TRUE, '{"group":"contract"}'::jsonb, 0, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP, NULL),
    ('/cross-checking', 'cross-checking', 'cross-checking', NULL, '交叉评查', 'flow', 60, FALSE, TRUE, '{"group":"cross-review"}'::jsonb, 0, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP, NULL),
    ('/cross-checking/upload', 'cross-checking.upload', 'cross-checking/upload', NULL, '创建任务', 'upload', 61, FALSE, TRUE, '{"group":"cross-review"}'::jsonb, 0, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP, NULL),
-    ('/cross-checking/result', 'cross-checking.result', 'cross-checking/result', NULL, '评查结果', 'table', 62, FALSE, TRUE, '{"group":"cross-review"}'::jsonb, 0, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP, NULL)
+    ('/cross-checking/result', 'cross-checking.result', 'cross-checking/result', NULL, '评查任务列表', 'table', 62, FALSE, TRUE, '{"group":"cross-review"}'::jsonb, 0, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP, NULL)
 ON CONFLICT DO NOTHING;

 UPDATE role_route