docs: refine sql operations handbook

docs/HANDOFF.md

@@ -318,13 +318,14 @@
 | 位置 | 作用 |
 |------|------|
 | `rules/contract_loan/rules.yaml` | 借款合同规则集修复点 |
+| `scripts/创建sql/README.md` | 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/接口/` | 当前有效接口主文档 |
+| `docs/README.md` | 当前模块化文档总导航 |
 
 ---
 

scripts/创建sql/README.md

@@ -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`
+1. 确认目标库
-2. `user_rbac_seed.sql`
+2. 备份
-3. `schema_v2_add_evaluation_tables.sql`
+3. 跑 `precheck_*` 或确认依赖
-4. `seed_home_entry_modules.sql`
+4. 执行 1 个脚本
+5. 做 1 轮验收
+6. 再执行下一个脚本
+7. 重启相关服务
+8. 做接口与业务验证
 
-### 系统使用统计上线
+### 系统使用统计模板
 
-1. `schema_add_usage_stats.sql`
+1. 备份 `sso_users`、`sys_routes`、`permissions`、`role_permissions`、`role_route`、`leaudit_audit_runs`
-2. `seed_usage_stats_rbac.sql`
+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`
+- 新增 SQL 一律放 `scripts/创建sql/`
-2. `migrate_rule_groups_to_business_roots.sql`
+- 新增脚本时同步补本 README
-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 也请继续放这里