TanWenyan/leaudit-platform-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bd8b7a494ca9484c994ac4d6e8d5e4e1bc78c5a7
leaudit-platform-backend/scripts/创建sql/README.md
T

11 KiB
Raw Blame History

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