admin
44decaa396
- Add fieldLibrary metadata to HTML template packages, including form fields, custom time formats, multi-select options, and anesthesia options. - Restore imported template field metadata into local compatibility caches and the backend field library API when available. - Preserve legacy JSON template import compatibility while keeping user-facing exports on HTML packages. - Prevent template field saves from overwriting stored multi-select and anesthesia options with empty values. - Update README, AGENTS, feature, requirement, design, module, progress, component, and testing docs for complete template export behavior. - Extend template export tests to cover field library metadata round-tripping.
97 lines
4.0 KiB
Markdown
97 lines
4.0 KiB
Markdown
# 模块文档：模板管理
|
||
|
||
## 涉及文件
|
||
|
||
- `src/pages/TemplateManage.tsx`
|
||
- `src/api/templates.ts`
|
||
- `src/api/library.ts`
|
||
- `src/api/files.ts`
|
||
- `server/src/templates/*`
|
||
- `server/src/library/*`
|
||
- `server/src/files/*`
|
||
- `src/utils/defaultContent.ts`
|
||
- `src/utils/print.ts`
|
||
- `src/types.ts`
|
||
|
||
## 模块职责
|
||
|
||
模板管理用于维护报告模板 HTML、字段库、图片资源、AI 可编辑区域和模板导入导出。医生不可进入该模块。
|
||
|
||
## 模板列表
|
||
|
||
模板列表优先通过 `GET /api/templates?access=manage` 读取，后端根据当前 Session 用户过滤可管理模板：
|
||
|
||
- 超级管理员可管理全部模板。
|
||
- 管理员可管理本部门模板或被授权可管理模板。
|
||
- 医生不能进入模板管理页，但可以通过报告编辑器新建自己的个人模板。
|
||
|
||
只有开发模式或显式开启 `VITE_ENABLE_LOCAL_FALLBACK=true` 时，API 不可用才回退读取 `localStorage.templates`，用于迁移期旧数据和离线测试。API 返回空列表会按真实空数据展示，不再自动把本地模板当作生产数据。
|
||
|
||
支持：
|
||
|
||
- 新增模板。
|
||
- 编辑模板名称和描述。
|
||
- 删除或批量删除模板。
|
||
- 保存当前模板内容。
|
||
- 打印模板预览。
|
||
- 单个导出 HTML 模板包和 PDF 打印预览。
|
||
- 从 HTML 模板包或历史 JSON 模板包导入。
|
||
|
||
新增、编辑、保存内容和删除模板会优先调用后端 `POST/PATCH/DELETE /api/templates`，后端会对模板 HTML 做白名单清洗；成功后同步 `localStorage.templates` 作为兼容缓存。只有本地回退开启时，API 失败才允许写本地模板。
|
||
|
||
## 模板内容编辑
|
||
|
||
模板正文是 `contentEditable` HTML。工具栏支持常见富文本命令、表格、图片占位符和 AI 区域插入。编辑器内部维护 undo/redo 栈，并根据内容高度扩展 A4 页面高度。
|
||
|
||
## 字段库
|
||
|
||
字段定义优先通过 `GET/PATCH /api/library/fields` 读写，后端保存到 `SystemSetting.key = fieldLibrary`；`formFieldsConfig` 继续作为迁移期兼容缓存，并仅在本地回退开启且 API 不可用时作为回退。字段支持：
|
||
|
||
- 显示/隐藏。
|
||
- 系统锁定字段保护。
|
||
- 文本、单选、多选、日期、时间、签名、图片等类型。
|
||
- 选项维护。
|
||
- 时间格式和默认值。
|
||
- 下划线样式。
|
||
|
||
插入字段时，模板会写入带 `data-bind` 的 `.field-value`，报告编辑器按该 key 进行表单同步。
|
||
|
||
## 图片资源
|
||
|
||
模板图片资源优先通过通用文件 API 上传和读取：
|
||
|
||
- `GET /api/files?kind=TEMPLATE_ASSET`
|
||
- `POST /api/files`
|
||
- `DELETE /api/files/:id`
|
||
|
||
页面仍把资源同步到 `imageAssets` 作为迁移期兼容缓存。只有本地回退开启时，API 不可用的上传图片才会回退为本地 Data URL。
|
||
|
||
## 后端模板模型
|
||
|
||
后端 `Template` 表保存模板名称、描述、HTML 正文、字段 JSON、模板范围、归属部门或归属用户。部门授权由 `TemplateDepartmentPermission` 表维护，支持 `canUse` 和 `canManage`。医生个人模板使用 `scope = PERSONAL` 和 `ownerUserId` 归属本人。
|
||
|
||
## 导入导出格式
|
||
|
||
前端用户可见导出只保留 HTML 模板包和 PDF 打印预览。历史 JSON 模板包仍可导入，兼容结构大致如下：
|
||
|
||
```json
|
||
{
|
||
"version": "1.1",
|
||
"type": "surclaw_template_package",
|
||
"title": "模板名称",
|
||
"description": "模板描述",
|
||
"content": "模板 HTML",
|
||
"fields": [],
|
||
"fieldLibrary": {
|
||
"formFields": [],
|
||
"customTimeFormats": [],
|
||
"multiSelectOptions": {},
|
||
"anesthesiaOptions": []
|
||
}
|
||
}
|
||
```
|
||
|
||
HTML 模板包是一个可直接用浏览器打开的完整 HTML 文件，包含 A4 页面样式、打印样式和内嵌的 `surclaw_template_package` 元数据。元数据会随包保存模板正文、模板对应字段，以及字段管理相关设置：字段库、时间格式、多选字段选项和麻醉方式选项。它比单独 JSON 文件更适合保留“报告整体观感”，也是当前推荐的可回导模板交换格式。
|
||
|
||
PDF 导出走浏览器打印，适合归档和人工查看，不适合再次导入编辑。
|