ai-business-write/技术文档/README_初始化模板树状结构.md

初始化模板树状结构 - 使用说明

概述

init_template_tree_from_directory.py 脚本用于完全重置 f_polic_file_config 表中的模板数据，根据 template_finish 目录结构重新创建所有记录，建立正确的树状层级关系。

⚠️ 重要警告

此操作会删除当前租户的所有模板数据！

包括：

• f_polic_file_config 表中的所有记录
• f_polic_file_field 表中的相关关联记录

然后根据 template_finish 目录结构完全重建。

执行前请务必备份数据库！

功能特点

1. 完全重建: 删除旧数据，根据目录结构重新创建
2. 树状结构: 自动建立正确的 parent_id 层级关系
3. 文件上传: 可选择是否上传文件到 MinIO
4. 安全确认: 多重确认机制，防止误操作
5. 模拟模式: 先预览再执行，确保安全

目录结构要求

脚本会扫描 template_finish 目录，期望的结构如下：

template_finish/
└── 2-初核模版/                    (一级目录)
    ├── 1.初核请示/                (二级目录)
    │   ├── 1.请示报告卡（XXX）.docx
    │   ├── 2.初步核实审批表（XXX）.docx
    │   └── 3.附件初核方案(XXX).docx
    ├── 2.谈话审批/                (二级目录)
    │   ├── 谈话通知书/            (三级目录)
    │   │   ├── 谈话通知书第一联.docx
    │   │   ├── 谈话通知书第二联.docx
    │   │   └── 谈话通知书第三联.docx
    │   ├── 走读式谈话审批/        (三级目录)
    │   │   ├── 1.请示报告卡（初核谈话）.docx
    │   │   ├── 2谈话审批表.docx
    │   │   └── ...
    │   └── 走读式谈话流程/        (三级目录)
    │       ├── 1.谈话笔录.docx
    │       └── ...
    └── 3.初核结论/                (二级目录)
        ├── 8-1请示报告卡（初核报告结论） .docx
        └── 8.XXX初核情况报告.docx

使用方法

基本使用

python init_template_tree_from_directory.py

执行流程

1. 警告提示: 显示操作警告
2. 第一次确认: 输入 yes 继续
3. 扫描目录: 自动扫描 template_finish 目录
4. 显示预览: 显示目录结构预览
5. 选择上传: 选择是否上传文件到 MinIO
6. 模拟删除: 显示将删除的数据
7. 模拟创建: 显示将创建的节点
8. 最终确认: 再次输入 yes 执行实际更新
9. 执行删除: 删除旧数据
10. 执行创建: 创建新数据

交互式提示

确认继续？(yes/no，默认no): yes
是否上传文件到MinIO？(yes/no，默认yes): yes
确认执行实际更新？(yes/no，默认no): yes

处理逻辑

1. 删除旧数据

• 先删除 f_polic_file_field 表中的关联记录
• 再删除 f_polic_file_config 表中的配置记录
• 只删除当前租户（tenant_id = 615873064429507639）的数据

2. 创建新数据

按层级顺序创建：

1. 目录节点:

   • 不包含 template_code 字段
   • input_data 为 NULL
   • file_path 为 NULL

2. 文件节点:

   • 包含 template_code（从 DOCUMENT_TYPE_MAPPING 获取）
   • input_data 包含 JSON 格式的配置
   • file_path 为 MinIO 路径（如果上传了文件）

3. 树状关系

• 一级目录: parent_id = NULL
• 二级目录: parent_id = 一级目录的ID
• 三级目录: parent_id = 二级目录的ID
• 文件: parent_id = 所在目录的ID

模板识别

脚本通过 DOCUMENT_TYPE_MAPPING 字典识别文件类型：

• 匹配文件名（不含扩展名）
• 提取 template_code 和 business_type
• 如果无法识别，template_code 为空字符串

文件上传

如果选择上传文件到 MinIO：

• 文件路径格式: /{tenant_id}/TEMPLATE/{year}/{month}/{filename}
• 例如: /615873064429507639/TEMPLATE/2025/12/1.请示报告卡（XXX）.docx
• 上传失败不会中断流程，但 file_path 将为 NULL

输出示例

================================================================================
初始化模板树状结构（从目录结构完全重建）
================================================================================

⚠️  警告：此操作将删除当前租户的所有模板数据！

确认继续？(yes/no，默认no): yes
✓ 数据库连接成功

扫描目录结构...
  找到 28 个节点
  其中目录: 7 个
  其中文件: 21 个

执行模拟删除...
  [模拟] 将删除 113 条关联记录
  [模拟] 将删除 34 条配置记录

执行模拟创建...
  ✓ [模拟]创建目录: 2-初核模版 (ID: ...)
  ✓ [模拟]创建文件: 1.请示报告卡（XXX） (ID: ...) [父: ...] [code: REPORT_CARD]
  ...

确认执行实际更新？(yes/no，默认no): yes

执行实际删除...
  ✓ 删除了 113 条关联记录
  ✓ 删除了 34 条配置记录

执行实际创建...
  ✓ 创建目录: 2-初核模版 (ID: ...)
  ✓ 创建文件: 1.请示报告卡（XXX） (ID: ...) [父: ...] [code: REPORT_CARD]
  ...

✓ 创建完成！共创建 28 个节点

验证结果

执行完成后，可以使用验证脚本检查结果：

python verify_tree_structure.py

注意事项

1. 备份数据库: 执行前务必备份数据库
2. 确认目录结构: 确保 template_finish 目录结构正确
3. 文件存在: 确保所有 .docx 文件都存在
4. MinIO 连接: 如果选择上传文件，确保 MinIO 连接正常
5. 不可逆操作: 删除操作不可逆，请谨慎执行

故障排查

问题1: template_code 不能为 NULL

原因: 数据库表结构要求 template_code 不能为 NULL

解决: 脚本已处理，目录节点不插入 template_code，文件节点使用空字符串

问题2: 文件上传失败

原因: MinIO 连接问题或文件不存在

解决:

• 检查 MinIO 配置
• 检查文件是否存在
• 上传失败不会中断流程，可以后续手动上传

问题3: 父子关系错误

原因: 目录结构扫描顺序问题

解决: 脚本已按层级顺序处理，确保父节点先于子节点创建

相关脚本

• update_template_tree.py - 更新现有数据的 parent_id（不删除数据）
• verify_tree_structure.py - 验证树状结构
• check_existing_data.py - 检查现有数据

联系信息

如有问题，请检查：

1. 数据库连接配置
2. 目录结构是否正确
3. 文件是否都存在
4. MinIO 配置是否正确