ai-business-write/技术文档/模板本地化部署说明.md

模板本地化部署说明

一、概述

本系统已从 MinIO 服务器读取模板改为从本地 template_finish/ 文件夹读取模板。本文档说明当前的部署逻辑、新模板开发流程以及如何将新模板更新到数据库中。

二、当前部署逻辑

2.1 模板读取机制

系统现在从本地文件系统读取模板，不再依赖 MinIO 服务器：

1. 模板存储位置：所有模板文件存储在项目根目录下的 template_finish/ 文件夹中
2. 路径格式：数据库中的 file_path 字段存储的是相对路径（相对于项目根目录），格式如：

   template_finish/2-初核模版/1.初核请示/1.请示报告卡（XXX）.docx
   

3. 读取流程：
   • 系统从数据库获取模板的 file_path 字段
   • 将相对路径转换为绝对路径（基于项目根目录）
   • 从本地文件系统读取模板文件
   • 复制到临时目录供后续处理使用

2.2 代码实现位置

• 模板读取：services/document_service.py 中的 download_template_from_minio() 方法

  • 虽然方法名仍包含 "minio"，但实际功能已改为从本地读取
  • 使用 Path 对象处理路径，确保跨平台兼容性

• 模板保存：app.py 中的 /api/template/save 接口

  • 新上传的模板保存到 template_finish/uploaded/ 目录
  • 自动生成带时间戳的文件名，避免文件名冲突

2.3 数据库表结构

模板配置存储在 f_polic_file_config 表中，关键字段：

• id: 模板ID（主键）
• name: 模板名称（显示名称）
• file_path: 本地相对路径（格式：template_finish/...）
• tenant_id: 租户ID
• state: 状态（1=启用，0=禁用）

三、模板文件夹结构

3.1 目录组织

template_finish/ 文件夹按照业务类型组织，当前结构如下：

template_finish/
├── 1-谈话函询模板/
│   ├── 函询模板/
│   └── 谈话模版/
├── 2-初核模版/
│   ├── 1.初核请示/
│   ├── 2.谈话审批/
│   │   ├── 谈话通知书/
│   │   ├── 走读式谈话审批/
│   │   └── 走读式谈话流程/
│   └── 3.初核结论/
├── 3-立案模版/
│   ├── 党员/
│   │   ├── 移送审理/
│   │   ├── 立案审查/
│   │   └── 装卷/
│   └── 非党员监察对象/
│       ├── 移送审理/
│       ├── 立案调查/
│       └── 装卷（目录）/
├── 4-审理模版/
├── 5-处分决定模版/
└── uploaded/          # 新上传的模板存放目录（通过接口上传的模板）

3.2 文件命名规范

• 支持的文件格式：.doc, .docx, .wps
• 文件名应清晰描述模板用途
• 建议使用中文文件名，便于识别

四、新模板开发流程

4.1 准备模板文件

1. 创建模板文档

   • 使用 Word 创建模板文件（.docx 格式）
   • 在需要填充数据的位置使用占位符，格式：{{field_code}}
   • 例如：{{target_name}}、{{clue_info}} 等

2. 确定存储位置

   • 根据业务类型，将模板文件放到对应的子目录
   • 例如：初核相关的模板放到 template_finish/2-初核模版/ 下

4.2 添加模板到本地文件夹

1. 手动添加（推荐用于批量模板）

   # 将模板文件复制到对应目录
   cp 新模板.docx template_finish/2-初核模版/1.初核请示/
   

2. 通过接口上传（用于单个模板）

   • 使用 /api/template/parse 接口解析模板占位符
   • 使用 /api/template/save 接口保存模板
   • 模板会自动保存到 template_finish/uploaded/ 目录

4.3 更新数据库

有两种方式将新模板更新到数据库：

方式一：使用更新脚本（推荐用于批量更新）

1. 运行路径更新脚本

   python update_template_paths_to_local.py
   

   脚本功能：

   • 自动扫描 template_finish/ 文件夹下的所有模板文件
   • 匹配数据库中的模板记录（根据文件名）
   • 更新 file_path 字段为本地相对路径
   • 支持精确匹配和模糊匹配

2. 脚本输出说明

   • [更新]：成功更新路径的记录
   • [跳过]：已经是本地路径的记录
   • [未找到]：本地找不到匹配文件的记录

方式二：手动更新数据库（用于单个模板）

1. 获取模板的相对路径

   • 从项目根目录到模板文件的相对路径
   • 使用正斜杠 / 作为路径分隔符
   • 例如：template_finish/2-初核模版/1.初核请示/新模板.docx

2. 执行 SQL 更新

   UPDATE f_polic_file_config
   SET file_path = 'template_finish/2-初核模版/1.初核请示/新模板.docx'
   WHERE id = <模板ID>;
   

3. 或者插入新记录

   INSERT INTO f_polic_file_config
   (id, tenant_id, parent_id, name, input_data, file_path, created_time, created_by, updated_time, updated_by, state)
   VALUES
   (<模板ID>, 615873064429507639, <父级ID>, '模板名称', '{}', 
    'template_finish/2-初核模版/1.初核请示/新模板.docx', 
    NOW(), 655162080928945152, NOW(), 655162080928945152, 1);
   

五、完整开发示例

5.1 场景：添加一个新的初核请示模板

步骤 1：准备模板文件

• 创建 新初核请示模板.docx
• 在文档中添加占位符，如：{{target_name}}、{{clue_info}} 等

步骤 2：放置模板文件

# 将文件复制到对应目录
cp 新初核请示模板.docx template_finish/2-初核模版/1.初核请示/

步骤 3：更新数据库

选项 A：使用脚本自动更新

python update_template_paths_to_local.py

脚本会自动匹配文件名并更新路径。

选项 B：手动更新

-- 假设模板ID为 1234567890
UPDATE f_polic_file_config
SET file_path = 'template_finish/2-初核模版/1.初核请示/新初核请示模板.docx'
WHERE id = 1234567890;

步骤 4：验证

• 通过 /api/file-configs 接口查看模板列表
• 确认 file_path 字段为本地相对路径
• 测试文档生成功能，确保能正确读取模板

5.2 场景：通过接口上传新模板

步骤 1：解析模板

POST /api/template/parse
Content-Type: multipart/form-data

{
  "file": <模板文件>
}

步骤 2：保存模板

POST /api/template/save
Content-Type: application/json

{
  "tenant_id": 615873064429507639,
  "filename": "新模板.docx",
  "temp_file_path": "<从parse接口返回的临时路径>",
  "field_relations": [...],
  "template_name": "新模板名称"
}

模板会自动保存到 template_finish/uploaded/ 目录，数据库中的 file_path 会自动设置为本地路径。

六、注意事项

6.1 路径规范

1. 使用相对路径：数据库中的 file_path 必须是相对于项目根目录的相对路径
2. 路径分隔符：使用正斜杠 /，系统会自动处理跨平台兼容性
3. 路径前缀：所有路径必须以 template_finish/ 开头

6.2 文件管理

1. 不要删除模板文件：删除本地模板文件会导致系统无法读取模板
2. 保持目录结构：不要随意移动或重命名模板文件，需要同步更新数据库
3. 文件名唯一性：在同一目录下，确保文件名唯一，避免匹配错误

6.3 数据库维护

1. 定期同步：如果手动修改了模板文件位置，运行更新脚本同步数据库
2. 路径验证：定期检查数据库中的 file_path 是否指向存在的文件
3. 备份数据：在批量更新前，建议备份 f_polic_file_config 表

6.4 开发建议

1. 版本控制：将 template_finish/ 文件夹纳入版本控制（Git）
2. 测试验证：添加新模板后，务必测试文档生成功能
3. 文档记录：记录每个模板的用途、占位符说明等信息

七、故障排查

7.1 模板读取失败

错误信息：模板文件不存在: ...

可能原因：

1. 数据库中的 file_path 路径不正确
2. 模板文件已被移动或删除
3. 路径格式错误（使用了绝对路径或错误的相对路径）

解决方法：

1. 检查数据库中的 file_path 字段
2. 确认文件是否存在于指定路径
3. 运行更新脚本重新匹配路径

7.2 路径匹配失败

错误信息：[未找到] 匹配文件

可能原因：

1. 文件名不一致（数据库中的文件名与本地文件名不匹配）
2. 文件扩展名不同（如 .doc vs .docx）
3. 文件在错误的目录中

解决方法：

1. 检查文件名是否完全一致（包括扩展名）
2. 手动更新数据库中的 file_path
3. 确保文件在正确的目录结构中

7.3 新模板无法使用

可能原因：

1. 数据库中没有对应的记录
2. 模板记录的 state 字段为 0（未启用）
3. 缺少字段关联关系

解决方法：

1. 检查 f_polic_file_config 表中是否有对应记录
2. 确认 state = 1（已启用）
3. 检查 f_polic_file_field 表中的字段关联关系

八、相关文件

• 模板读取服务：services/document_service.py
• 路径更新脚本：update_template_paths_to_local.py
• 模板保存接口：app.py 中的 /api/template/save
• 模板解析接口：app.py 中的 /api/template/parse

九、快速参考

9.1 常用命令

# 更新数据库中的模板路径（批量）
python update_template_paths_to_local.py

# 查看模板列表（API）
GET /api/file-configs?tenant_id=615873064429507639

# 测试文档生成（API）
POST /api/document/generate

9.2 关键路径

• 模板目录：template_finish/
• 新上传模板目录：template_finish/uploaded/
• 模板读取代码：services/document_service.py (第118行)
• 路径更新脚本：update_template_paths_to_local.py

9.3 数据库查询示例

-- 查看所有模板及其路径
SELECT id, name, file_path, state 
FROM f_polic_file_config 
WHERE tenant_id = 615873064429507639 
AND state = 1;

-- 查找路径为MinIO格式的模板（需要更新）
SELECT id, name, file_path 
FROM f_polic_file_config 
WHERE tenant_id = 615873064429507639 
AND file_path LIKE '/%TEMPLATE/%';

-- 查找本地路径的模板
SELECT id, name, file_path 
FROM f_polic_file_config 
WHERE tenant_id = 615873064429507639 
AND file_path LIKE 'template_finish/%';

9.4 占位符格式

模板中使用占位符的格式：{{field_code}}

示例：

• {{target_name}} - 被核查人姓名
• {{clue_info}} - 线索信息
• {{verify_date}} - 核实日期

十、更新历史

• 2025-12-16：完成从 MinIO 到本地文件系统的迁移
  • 修改模板读取逻辑为本地读取
  • 更新数据库中的 20 条模板路径记录
  • 修改模板保存接口为本地保存
  • 创建路径更新脚本 update_template_paths_to_local.py

---

维护人员：开发团队
最后更新：2025-12-16
文档版本：v1.0