85 lines
3.1 KiB
Markdown
85 lines
3.1 KiB
Markdown
# 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` | 统一维护文案，改库即生效 |
|