文件模板

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

模块结构

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

文件模板模型

# 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 转换：

# 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 方法用于程序化获取模板，返回与详情一致的序列化结构：

# 按编码获取导入模板
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 导入导出功能配合使用：

# 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 方法支持按编码查询，便于程序化获取模板。