358 lines
11 KiB
Markdown
358 lines
11 KiB
Markdown
# 模板本地化部署说明
|
||
|
||
## 一、概述
|
||
|
||
本系统已从 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. **手动添加**（推荐用于批量模板）
|
||
```bash
|
||
# 将模板文件复制到对应目录
|
||
cp 新模板.docx template_finish/2-初核模版/1.初核请示/
|
||
```
|
||
|
||
2. **通过接口上传**（用于单个模板）
|
||
- 使用 `/api/template/parse` 接口解析模板占位符
|
||
- 使用 `/api/template/save` 接口保存模板
|
||
- 模板会自动保存到 `template_finish/uploaded/` 目录
|
||
|
||
### 4.3 更新数据库
|
||
|
||
有两种方式将新模板更新到数据库：
|
||
|
||
#### 方式一：使用更新脚本（推荐用于批量更新）
|
||
|
||
1. **运行路径更新脚本**
|
||
```bash
|
||
python update_template_paths_to_local.py
|
||
```
|
||
|
||
脚本功能：
|
||
- 自动扫描 `template_finish/` 文件夹下的所有模板文件
|
||
- 匹配数据库中的模板记录（根据文件名）
|
||
- 更新 `file_path` 字段为本地相对路径
|
||
- 支持精确匹配和模糊匹配
|
||
|
||
2. **脚本输出说明**
|
||
- `[更新]`：成功更新路径的记录
|
||
- `[跳过]`：已经是本地路径的记录
|
||
- `[未找到]`：本地找不到匹配文件的记录
|
||
|
||
#### 方式二：手动更新数据库（用于单个模板）
|
||
|
||
1. **获取模板的相对路径**
|
||
- 从项目根目录到模板文件的相对路径
|
||
- 使用正斜杠 `/` 作为路径分隔符
|
||
- 例如：`template_finish/2-初核模版/1.初核请示/新模板.docx`
|
||
|
||
2. **执行 SQL 更新**
|
||
```sql
|
||
UPDATE f_polic_file_config
|
||
SET file_path = 'template_finish/2-初核模版/1.初核请示/新模板.docx'
|
||
WHERE id = <模板ID>;
|
||
```
|
||
|
||
3. **或者插入新记录**
|
||
```sql
|
||
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：放置模板文件**
|
||
```bash
|
||
# 将文件复制到对应目录
|
||
cp 新初核请示模板.docx template_finish/2-初核模版/1.初核请示/
|
||
```
|
||
|
||
**步骤 3：更新数据库**
|
||
|
||
**选项 A：使用脚本自动更新**
|
||
```bash
|
||
python update_template_paths_to_local.py
|
||
```
|
||
脚本会自动匹配文件名并更新路径。
|
||
|
||
**选项 B：手动更新**
|
||
```sql
|
||
-- 假设模板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：解析模板**
|
||
```bash
|
||
POST /api/template/parse
|
||
Content-Type: multipart/form-data
|
||
|
||
{
|
||
"file": <模板文件>
|
||
}
|
||
```
|
||
|
||
**步骤 2：保存模板**
|
||
```bash
|
||
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 常用命令
|
||
|
||
```bash
|
||
# 更新数据库中的模板路径（批量）
|
||
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 数据库查询示例
|
||
|
||
```sql
|
||
-- 查看所有模板及其路径
|
||
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
|