leaudit-platform-backend/scripts/创建sql

SQL 上线操作手册

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

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

目录约定

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

通用执行规范

1. 推荐命令

生产执行时统一带 ON_ERROR_STOP=1：

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

标准执行命令

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

执行后验收

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

标准执行命令

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

执行后验收

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
• 若脚本执行顺序变化，优先更新这里，再更新业务文档
• 若脚本已废弃，保留文件时必须在头部写明“已废弃”和替代脚本