Initialize backendized SurClaw report system

- Add React/Vite frontend for login, dashboard, reports, templates, users, settings, AI, speech, and media workflows.

- Add NestJS/Prisma/PostgreSQL backend with auth, dashboard stats, reports, templates, users, departments, settings, files, AI, speech, audit logs, and HTML sanitization.

- Add Prisma schema, migrations, seed data, persistent app sessions, Docker/Nginx deployment files, and upload volume configuration.

- Add Vitest, Playwright, backend integration tests, and project documentation for requirements, design, permissions, API contracts, testing, deployment, security, and progress.

- Configure production local fallback switch and remove unused Gemini direct dependency/env wiring.
This commit is contained in:
2026-05-02 01:37:20 +08:00
commit 014aca8619
162 changed files with 27116 additions and 0 deletions

View File

@@ -0,0 +1,88 @@
# 模块文档:模板管理
## 涉及文件
- `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。
- 从 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` 归属本人。
## 导入导出格式
单模板导出大致结构:
```json
{
"version": "1.0",
"type": "surclaw_template_package",
"title": "模板名称",
"description": "模板描述",
"content": "模板 HTML",
"fields": []
}
```
批量导出使用 `type: "surclaw_template_package_batch"`,包含 `templates` 数组。当前导入逻辑只接受单模板包。