Files

admin 5a4056d899 Add reusable HTML template export

- Add template export utilities for standard JSON packages and standalone HTML template packages.

- Make the top-level JSON export use the standard surclaw template package format so it can be imported again.

- Add an HTML template package export that embeds A4/print styling and template metadata for visual preview and round-trip import.

- Extend template import to accept both JSON and HTML template package files while keeping old raw template JSON compatible.

- Add tests for package creation, HTML round-trip import, legacy JSON import, and file name cleanup.

- Update template management, feature, progress, testing, and AGENTS documentation for the new export formats.

2026-05-02 03:49:21 +08:00

3.8 KiB

Raw Blame History

模块文档：模板管理

涉及文件

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 返回空列表会按真实空数据展示，不再自动把本地模板当作生产数据。

支持：

新增模板。
编辑模板名称和描述。
删除或批量删除模板。
保存当前模板内容。
打印模板预览。
单个导出 JSON 模板包、HTML 模板包和 PDF 打印预览，批量导出 JSON。
从 JSON 模板包或 HTML 模板包导入。

新增、编辑、保存内容和删除模板会优先调用后端 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 归属本人。

导入导出格式

单模板 JSON 模板包大致结构：

{
  "version": "1.0",
  "type": "surclaw_template_package",
  "title": "模板名称",
  "description": "模板描述",
  "content": "模板 HTML",
  "fields": []
}

HTML 模板包是一个可直接用浏览器打开的完整 HTML 文件，包含 A4 页面样式、打印样式和内嵌的 surclaw_template_package 元数据。它比 JSON 更适合保留“报告整体观感”，也可以重新导入系统恢复模板 HTML 和字段定义。

PDF 导出走浏览器打印，适合归档和人工查看，不适合再次导入编辑。

批量导出使用 type: "surclaw_template_package_batch"，包含 templates 数组。当前导入逻辑只接受单模板 JSON/HTML 包。

3.8 KiB Raw Blame History Unescape Escape