签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,145 @@
+:::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` 方法支持按编码查询，便于程序化获取模板。