:::tip 文件模板
文件模板模块用于管理系统中的文件模板，如导入导出模板、报表模板等。支持模板文件上传、按编码查询、文件 URL 自动转换等功能。
:::

## 模块结构

```
src/modules/file_template/
├── models.py     # 文件模板模型
├── schema.py     # 表单验证（WTForms）
├── repository.py # 数据访问层
├── service.py    # 业务逻辑层（继承 BaseService）
└── router.py     # 路由控制器
```

## 文件模板模型

```python
# src/modules/file_template/models.py
class FileTemplate(BaseModel, BaseDB):
    """
    文件模板模型

    用于存储文件模板信息，如：导入导出模板、报表模板等。
    """
    __tablename__ = DB_PREFIX + "file_template"
    __table_comment__ = "文件模板表"

    # 模板名称
    name = db.Column(db.String(100), nullable=True, index=True, comment="模板名称")
    # 模板编码（唯一标识，用于程序化查询）
    code = db.Column(db.String(50), nullable=False, index=True, comment="模板编码")
    # 文件名称（原始文件名）
    file_name = db.Column(db.String(255), nullable=True, comment="文件名称")
    # 文件路径（存储相对路径，如 /file_template/xxx.xlsx）
    file_path = db.Column(db.String(255), nullable=True, comment="文件路径")
    # 备注
    note = db.Column(db.String(255), nullable=True, comment="文件模板备注")
    # 排序
    sort = db.Column(db.Integer, nullable=False, default=0, server_default=text('0'),
                     comment="文件模板顺序")
```

## 服务层特色

文件模板服务继承 `BaseService`，通过钩子实现文件处理和 URL 转换：

```python
# src/modules/file_template/service.py
class FileTemplateService(BaseService):
    repository = FileTemplateRepository
    form = FileTemplateForm
    model_name = "模板"

    @classmethod
    def before_add(cls, form):
        """新增前钩子：保存模板文件"""
        _handle_template_file(form)

    @classmethod
    def before_update(cls, form, obj):
        """更新前钩子：保存模板文件"""
        _handle_template_file(form)

    @classmethod
    def _detail_dict(cls, obj):
        """详情序列化：文件路径转换为可访问URL"""
        data = model_to_dict(obj)
        data["filePath"] = get_file_url(data.get("filePath"))
        return data

    @classmethod
    def _enrich_page_records(cls, records):
        """分页富化：文件路径转换为可访问URL"""
        for record in records:
            record["filePath"] = get_file_url(record.get("filePath"))
        return records

    @classmethod
    def get_by_code(cls, code):
        """按模板编码查询（用于程序化获取模板）"""
        obj = cls.repository.first_by({"code": code})
        return cls._detail_dict(obj) if obj else None
```

### 文件处理流程

```
前端上传临时文件 → 获得临时 URL（如 /temp/xxx.xlsx）
    ↓
提交表单（filePath 携带临时 URL）
    ↓
Service before_add/before_update 钩子
    ↓
save_file(filePath, "file_template")
    ↓
临时文件迁移到正式目录（upload/file_template/）
    ↓
数据库存相对路径
    ↓
查询时 get_file_url 拼接完整访问地址
```

### 按编码查询

`get_by_code` 方法用于程序化获取模板，返回与详情一致的序列化结构：

```python
# 按编码获取导入模板
template = FileTemplateService.get_by_code("user_import_template")
if template:
    download_url = template["filePath"]  # 已转为完整 URL
```

## API 接口

| 方法 | 路径 | 权限节点 | 说明 |
|:---|:---|:---|:---|
| GET | `/api/v1/fileTemplate/page` | `sys:fileTemplate:page` | 分页查询 |
| GET | `/api/v1/fileTemplate/detail/<id>` | `sys:fileTemplate:detail` | 详情查询 |
| GET | `/api/v1/fileTemplate/code/<code>` | - | 按编码查询 |
| POST | `/api/v1/fileTemplate/add` | `sys:fileTemplate:add` | 新增模板 |
| PUT | `/api/v1/fileTemplate/update` | `sys:fileTemplate:update` | 编辑模板 |
| DELETE | `/api/v1/fileTemplate/delete/<id>` | `sys:fileTemplate:delete` | 删除模板 |
| DELETE | `/api/v1/fileTemplate/batchDelete` | `sys:fileTemplate:batchDelete` | 批量删除 |

## 与 Excel 导入导出的配合

文件模板模块常与 Excel 导入导出功能配合使用：

```python
# 1. 获取导入模板下载地址
template = FileTemplateService.get_by_code("user_import_template")
download_url = template["filePath"]

# 2. 前端下载模板 → 填写数据 → 上传文件

# 3. 后端解析上传文件
abs_path = excel_utils.resolve_uploaded_excel()
rows, errors = excel_utils.parse_excel_rows(abs_path, USER_IMPORT_COLUMNS)
```

## 总结

文件模板模块用于管理系统中的各类模板文件。`before_add`/`before_update` 钩子自动将临时文件迁移到正式目录，`_detail_dict`/`_enrich_page_records` 钩子自动将文件路径转换为可访问 URL。`get_by_code` 方法支持按编码查询，便于程序化获取模板。