# 模板本地化部署说明

## 一、概述

本系统已从 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