leaudit-platform-backend/scripts/创建sql/README.md

# SQL 上线操作手册

本目录统一存放数据库相关 SQL。

目标不是只告诉你“文件在哪”，而是让开发、DBA、运维拿到后可以直接按顺序执行、验收、排查。

## 目录约定

- `schema_*`：建表、补字段、补索引、结构补丁
- `seed_*`：初始化数据、菜单、权限、路由种子
- `precheck_*`：正式迁移/删表前的只读巡检脚本
- `migrate_*`：数据迁移、历史结构升级
- `*_patch.sql`：补丁脚本
- `*_audit.sql`：审计/巡检类脚本

## 通用执行规范

### 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_contract_templates.sql`
2. `seed_contract_templates_rbac.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`
  - 用途：补齐用户、角色、权限、路由核心表结构
  - 场景：新库初始化或旧库尚未具备 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`

### 七、合同模板

- `schema_contract_templates.sql`
  - 用途：在主库创建合同模板分类表和模板表
  - 主要内容：新增 `contract_categories`、`contract_templates`、补索引和注释
  - 执行时机：上线合同模板新后端接口前必跑

- `seed_contract_templates_rbac.sql`
  - 用途：补齐合同模板只读权限点
  - 主要内容：新增 `contract_template:list:read`、`contract_template:search:read`、`contract_template:detail:read`
  - 依赖：`sys_routes` 中已经存在 `/contract-template/list` 和 `/contract-template/search`

- `migrate_legacy_contract_templates.py`
  - 用途：把老库 `docauditai` 的合同模板分类、模板记录和旧 bucket 文件迁入主库 `leaudit_platform`
  - 主要内容：
    - 读取老库 `public.contract_categories`、`public.contract_templates`
    - 从旧 bucket `docauditai` 读取 `contract-template/...` 对象
    - 复制到新 bucket `leaudit` 的 `contract-templates/...` 相对路径
    - 回写主库 `contract_categories`、`contract_templates.file_path`、`contract_templates.pdf_file_path`
  - 适用场景：主库已完成建表与权限初始化，但仍是 demo 数据或空数据时
  - 注意：
    - 脚本会重置主库 `contract_categories` / `contract_templates` 当前数据并按老库正式数据重建
    - 当前已知会自动修正 1 条老脏数据：
      - `contract_templates.id=3`
      - 标题：`房屋租赁合同（我方承租）`
      - 老 `file_path` 误指向“我方出租”docx，迁移时会自动改成“我方承租”docx

#### 推荐顺序

1. `schema_contract_templates.sql`
2. `seed_contract_templates_rbac.sql`
3. `python scripts/migrate_legacy_contract_templates.py`
4. `python scripts/migrate_legacy_contract_templates.py --apply`

#### 标准执行命令

```bash
psql -h <host> -U <user> -d <db_name> -v ON_ERROR_STOP=1 -f scripts/创建sql/schema_contract_templates.sql
psql -h <host> -U <user> -d <db_name> -v ON_ERROR_STOP=1 -f scripts/创建sql/seed_contract_templates_rbac.sql

# 先 dry-run，看旧路径 -> 新路径映射
python scripts/migrate_legacy_contract_templates.py

# 确认无误后正式执行：复制 OSS 文件 + 回写主库
python scripts/migrate_legacy_contract_templates.py --apply
```

#### 执行后验收

```sql
SELECT to_regclass('public.contract_categories');
SELECT to_regclass('public.contract_templates');

SELECT permission_key
FROM permissions
WHERE permission_key LIKE 'contract_template:%'
ORDER BY permission_key;

SELECT r.role_key, p.permission_key, rp.grant_type, rp.data_scope
FROM role_permissions rp
JOIN roles r ON r.id = rp.role_id
JOIN permissions p ON p.id = rp.permission_id
WHERE p.permission_key LIKE 'contract_template:%'
ORDER BY r.role_key, p.permission_key;

SELECT COUNT(*) AS category_count FROM public.contract_categories;
SELECT COUNT(*) AS template_count FROM public.contract_templates;

SELECT id, template_code, title, file_path, pdf_file_path
FROM public.contract_templates
ORDER BY id
LIMIT 10;
```

#### 当前基线验收结果

- 主库 `leaudit_platform`
  - `contract_categories = 9`
  - `contract_templates = 27`
- 新 bucket `leaudit`
  - `contract-templates/...` 对象总数 = `54`
- 新路径样例
  - `contract-templates/买卖合同/mmht/source__买卖合同范本.docx`
  - `contract-templates/买卖合同/mmht/preview__买卖合同范本.pdf`

### 七、RAG

- `schema_add_rag_chat.sql`
  - 用途：RAG 数据集、会话等相关结构初始化/补充
  - 说明：若环境还没补齐 RBAC 菜单/权限，联动检查 `user_rbac_seed.sql`

### 八、文档版本管理

- `migrate_20260429_document_versioning.sql`
  - 用途：给 `leaudit_documents` 补齐版本归档能力
  - 主要内容：增加版本链字段、归一化名称、历史数据回填

## 生产环境最小执行清单

### 通用模板

1. 确认目标库
2. 备份
3. 跑 `precheck_*` 或确认依赖
4. 执行 1 个脚本
5. 做 1 轮验收
6. 再执行下一个脚本
7. 重启相关服务
8. 做接口与业务验证

### 系统使用统计模板

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. 用超级管理员和地区管理员分别验证接口返回范围

## 维护规则

- 新增 SQL 一律放 `scripts/创建sql/`
- 新增脚本时同步补本 README
- 若脚本执行顺序变化，优先更新这里，再更新业务文档
- 若脚本已废弃，保留文件时必须在头部写明“已废弃”和替代脚本