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:
98
docs/modules/report-editor.md
Normal file
98
docs/modules/report-editor.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# 模块文档：报告编辑器
|
||||
|
||||
## 涉及文件
|
||||
|
||||
- `src/pages/ReportEditor.tsx`
|
||||
- `src/api/reports.ts`
|
||||
- `src/api/ai.ts`
|
||||
- `src/api/speech.ts`
|
||||
- `src/api/library.ts`
|
||||
- `src/api/files.ts`
|
||||
- `src/utils/defaultContent.ts`
|
||||
- `src/utils/print.ts`
|
||||
- `src/types.ts`
|
||||
|
||||
## 模块职责
|
||||
|
||||
报告编辑器是系统核心模块，负责新建/编辑报告、字段同步、富文本排版、视频关键帧处理、AI 辅助撰写、语音输入、草稿恢复和报告保存。
|
||||
|
||||
## 页面模式
|
||||
|
||||
- `/report-editor`：新建报告。
|
||||
- `/report-editor?id=RPT_xxx`：编辑已有报告。
|
||||
- `/report-editor?id=RPT_xxx&restore=1`：从历史版本恢复内容后进入编辑器。
|
||||
|
||||
## 草稿机制
|
||||
|
||||
编辑器会在卸载、页面隐藏和部分操作后写入 `reportEditorDraft_${username}`。草稿包含正文 HTML、表单数据、视频列表、关键帧、当前标签页、模板 ID 和 AI 聊天上下文。
|
||||
|
||||
保存报告后会清理草稿。
|
||||
|
||||
## 智能字段
|
||||
|
||||
模板中的智能字段形如：
|
||||
|
||||
```html
|
||||
<span class="field-value" data-bind="patientName" contenteditable="true"></span>
|
||||
```
|
||||
|
||||
编辑器会把侧边表单状态同步到正文，也会在用户直接编辑正文中的绑定字段时反向更新表单。日期和时间字段会按字段配置做格式化和解析。
|
||||
|
||||
字段库优先从 `/api/library/fields` 读取，成功后同步 `formFieldsConfig`、`multiSelectOptions` 和 `anesthesiaOptions` 兼容缓存；只有开发模式或显式开启 `VITE_ENABLE_LOCAL_FALLBACK=true` 时，API 不可用才继续读取本地缓存。
|
||||
|
||||
## 图片占位符
|
||||
|
||||
`.image-placeholder` 用于在模板或报告中保留图片位置。
|
||||
|
||||
- 普通占位符可点击选择图片，也可接收视频关键帧。
|
||||
- `data-mode="manual"` 用于 Logo、签名等静态位置，不允许拖入关键帧。
|
||||
- 已填充图片后会增加 `.has-image`。
|
||||
|
||||
模板图片资源优先从 `/api/files?kind=TEMPLATE_ASSET` 读取；只有本地回退开启时，API 不可用才继续读取本地 `imageAssets`。
|
||||
|
||||
## 视频与抽帧
|
||||
|
||||
用户上传视频后，系统使用浏览器对象 URL 进行即时预览，同时优先通过 `POST /api/files` 以 `kind = VIDEO` 上传后端文件资源。抽帧逻辑按系统设置中的 `framePositions` 百分比定位视频时间，绘制到 canvas 后转为 JPEG，并优先以 `kind = FRAME` 上传后端文件资源。
|
||||
|
||||
支持：
|
||||
|
||||
- 自动抽帧。
|
||||
- 手动截帧。
|
||||
- 点击关键帧跳转视频时间。
|
||||
- 拖拽关键帧到报告占位符。
|
||||
- 自动把选中的抽帧序号插入空置图片占位符。
|
||||
|
||||
报告保存前会等待当前视频和关键帧上传完成，并把 `fileId/url`、排序和抽帧信息通过 Reports API 同步到后端 `ReportMedia` 关系表。只有本地回退开启时，API 不可用才保留本地对象 URL/Data URL 回退。
|
||||
|
||||
## AI 撰写
|
||||
|
||||
AI 面板支持两种模式：
|
||||
|
||||
- 对话模式：根据当前报告内容和图片上下文回答问题。
|
||||
- 修改模式：选中 `.ai-region` 后要求模型返回 JSON，其中包含 `reply` 和 `updatedHtml`。
|
||||
|
||||
模型返回 HTML 后，系统会清理换行和 `<br>`，生成差异预览。用户确认后才写入目标 `.ai-content`。
|
||||
|
||||
当前 AI 调用使用后端代理：
|
||||
|
||||
- `/api/ai/chat`
|
||||
- 后端读取全局共用 Provider Key 并代理到 OpenAI 兼容 `/chat/completions`
|
||||
- 支持图片以 `image_url` 内容传入
|
||||
|
||||
## 语音输入
|
||||
|
||||
讯飞听写通过后端 WebSocket 代理：
|
||||
|
||||
- 前端连接 `/api/speech/iat`，不再生成讯飞鉴权 URL，也不读取 APPID/APIKey/APISecret。
|
||||
- 浏览器采集麦克风音频，转换为 16k PCM 后发送音频帧。
|
||||
- 后端读取 Settings API 中的 `xfSpeechConfig`，连接讯飞 IAT，上游首帧由后端补齐 `common.app_id` 和默认 `business` 参数。
|
||||
- 识别结果由后端转发回前端，并追加到 AI 输入框。
|
||||
|
||||
## 保存规则
|
||||
|
||||
- 保存草稿不强制患者姓名和住院号。
|
||||
- 完成报告要求患者姓名和住院号。
|
||||
- 保存时优先调用 `POST /api/reports` 或 `PATCH /api/reports/:id`；后端会先做 HTML 白名单清洗，再写入 PostgreSQL 并维护历史版本。
|
||||
- 编辑已有已完成报告时，后端会把旧内容追加到历史记录并递增 `revision`。
|
||||
- 只有本地回退开启时，API 不可用才保留原有本地 `localStorage.reports` 保存逻辑；生产构建默认关闭这条路径。
|
||||
- 完成报告后跳转到报告管理页。
|
||||
Reference in New Issue
Block a user