# 6.14 文件模板管理

:::tip 概述
文件模板管理用于维护系统中使用的文件模板（如导出模板、协议文本等），支持按编码查询模板。`FileTemplateService` 继承 `BaseService`（系统共享，不隔离）。
:::

## 模块特点

| 特性 | 说明 |
|------|------|
| 基类 | `BaseService`（系统共享，不隔离） |
| Trait 组合 | `HasCrudOperations, HasFileProcessing, HasQueryScopes, HasUniqueCheck` |
| 文件字段 | `file_path`（模板文件路径），读取时补全域名 |
| 唯一校验 | `code` 全局唯一 |
| 模糊搜索 | `name`、`code` |
| 特殊接口 | `getTemplateByCode` 按编码查询模板 |

## API 接口

| 方法 | 路径 | 权限码 | 说明 |
|------|------|--------|------|
| GET | `/api/file/template/page` | sys:fileTemplate:page | 分页列表 |
| GET | `/api/file/template/detail/{id}` | sys:fileTemplate:detail | 详情 |
| POST | `/api/file/template/add` | sys:fileTemplate:add | 新增 |
| PUT | `/api/file/template/update` | sys:fileTemplate:update | 修改 |
| DELETE | `/api/file/template/delete/{id}` | sys:fileTemplate:delete | 删除 |
| DELETE | `/api/file/template/batchDelete` | sys:fileTemplate:batchDelete | 批量删除 |
| GET | `/api/file/template/getTemplateByCode/{code}` | — | 按编码查询模板 |

:::tip 路径风格
本模块路由为二级路径 `file/template/*`（2026-10 起由驼峰 `fileTemplate/*` 调整），前端 API 模块 URL 需与之一致。
:::

## Service 配置（来自项目实际代码）

```php
class FileTemplateService extends BaseService
{
    use HasCrudOperations, HasFileProcessing, HasQueryScopes, HasUniqueCheck;

    protected string $modelClass = FileTemplate::class;

    // 单文件字段：模板文件路径保存时迁移、读取时补全域名
    protected array $fileFields = ['file_path'];
    protected string $fileSaveDir = 'file_template';

    protected array $pageLikeFields = ['name', 'code'];
    protected array $pageEqFields = [];

    // code 全局唯一
    protected array $uniqueFields = ['code'];

    // 按编码查询模板（getTemplateByCode 接口使用）
    public function getTemplateByCode(string $code): ?array { /* ... */ }
}
```

## Controller（getTemplateByCode）

```php
// app/Http/Controllers/Api/FileTemplateController.php（来自项目实际代码）

public function getTemplateByCode(string $code): JsonResponse
{
    $result = $this->fileTemplateService->getTemplateByCode($code);
    if (! $result) {
        return $this->fail('模板不存在');
    }

    return $this->success($result);
}
```

:::tip 按编码查询
`getTemplateByCode` 接口未配置 `#[Permission]` 注解，所有已登录用户均可访问——常用于前端按编码读取模板配置的场景（如打印模板、协议文本动态加载）。
:::

## 使用场景

| 场景 | 编码示例 | 说明 |
|------|---------|------|
| 导出模板 | `export_user` | 前端按编码取模板定义渲染导出字段 |
| 协议/合同文本 | `agreement_v1` | 动态加载富文本模板 |
| 通知文案 | `notice_welcome` | 统一维护文案，改库即生效 |