Files

admin 014aca8619 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.

2026-05-02 01:41:57 +08:00

5.3 KiB

Raw Blame History

数据与存储

存储封装

src/utils/storage.ts 提供统一读写：

storage.get<T>(key, fallback)：从 localStorage 读取 JSON。
storage.set<T>(key, value)：写入 JSON。
storage.remove(key)：删除本地键。
storage.getSession/setSession/removeSession：读写 sessionStorage。

systemSettings 会经过简单 XOR + Base64 混淆，并兼容读取历史明文 JSON。当前系统设置已优先写入后端 SystemSetting 表。本地兼容回退由 VITE_ENABLE_LOCAL_FALLBACK 控制，开发模式默认启用，生产构建默认关闭。

localStorage 键

键	数据	来源/用途
`currentUser`	`User`	当前登录用户兼容缓存。登录认证来自后端 Session，缓存用于尚未后端化的页面。
`users`	`User[]`	用户兼容缓存。登录成功和用户管理页会用后端用户信息同步用户、角色、部门、模板授权和签名 URL；旧签名 Data URL 和旧演示密码字段可能仍暂存在本地。
`templates`	`Template[]`	模板兼容缓存。模板读写已优先走后端 Templates API，缓存用于离线回退、旧数据和未迁移页面。
`reports`	`Report[]`	报告兼容缓存。报告读写已优先走后端 Reports API，缓存用于离线回退、旧数据和未迁移页面。
`systemSettings`	`SystemSettings`	抽帧、AI、语音和默认模板配置的兼容缓存；主路径优先走 `/api/settings/system`。
`formFieldsConfig`	`FormField[]`	字段库兼容缓存；主路径优先走 `/api/library/fields`。
`imageAssets`	`{ id; name; dataUrl }[]`	模板/报告可插入图片资源兼容缓存；模板图片主路径优先走 `/api/files?kind=TEMPLATE_ASSET`。
`customTimeFormats`	`string[]`	模板字段可选时间格式兼容缓存；主路径优先走 `/api/library/fields`。
`multiSelectOptions`	`Record<string, string[]>`	医生、助手、麻醉师等多选字段选项兼容缓存；主路径优先走 `/api/library/fields`。
`anesthesiaOptions`	`string[]`	麻醉方式选项兼容缓存；主路径优先走 `/api/library/fields`。
`reportEditorDraft_${username}`	草稿对象	某用户当前未提交编辑器草稿。

sessionStorage 键

键	数据	用途
`restore_${reportId}`	HTML 字符串	从历史版本恢复时临时传递内容给编辑器。

初始化流程

开发模式下，登录页 Login 首次加载时会补齐以下迁移期数据：

默认模板 surgery。
默认用户：admin、manager、0001。
默认表单字段 DEFAULT_FORM_FIELDS。
默认图片资源 logo_square.png。
默认系统设置，包括抽帧位置、AI Provider、自动插入策略和语音配置。

真实账号认证不再读取 users.password，而是调用后端 /api/auth/login。用户管理页已优先调用 /api/users，但 users.password 字段仍可能存在于旧本地缓存和开发回退数据中，后续应随迁移脚本移除。

数据生命周期

报告保存为草稿或完成态时优先写入后端；开发回退开启时会同步 reports 缓存，API 不可用时才写入本地 reports。
新建报告成功保存后会清理当前用户草稿。
编辑已有报告时会把旧内容推入 history。
开发回退模式下，系统设置页“重置全部数据”会执行 localStorage.clear() 并刷新页面；生产构建默认阻止把该操作误认为后端数据重置。

迁移注意

旧版 AI 设置可能是扁平字段，SystemSettings 页面会迁移到 aiProviders 结构。
个人模板通过 Template.scope = "personal" 和 Template.ownerUser 归属医生本人；部门模板通过 Template.scope = "department" 和 Template.department 标记部门。
后端模板使用 templates.scope、owner_department_id、owner_user_id 和 template_department_permissions 表达同样权限；前端字段作为兼容 DTO 返回。
后端用户使用 users.department_id、users.role 和 template_department_permissions 计算前端兼容的 visibleTemplates/manageableTemplates。
后端设置使用 SystemSetting.scope = global 保存全局设置，使用 scope = user:<id> 保存个人默认模板。
后端字段库使用 SystemSetting.scope = global 和 key = fieldLibrary 保存字段、时间格式和选项库。
后端签名文件使用 FileResource.kind = SIGNATURE 和 User.signatureFileId 关联，文件内容由 /api/files/:id/content 受控读取。
后端模板图片资源通过 POST /api/files 以 kind = TEMPLATE_ASSET 写入 FileResource，模板和报告编辑器优先读取 /api/files?kind=TEMPLATE_ASSET。
报告修订版本通过 Report.revision 保存；已完成报告每次再次保存会递增版本，并把旧版本写入 Report.history。
后端视频和关键帧文件通过 POST /api/files 以 kind = VIDEO/FRAME 写入 FileResource；报告保存时通过 ReportMedia 关系表保存视频/关键帧的 fileId/url、排序和抽帧信息。Report.metadata 只保留患者等前端扩展字段，旧数据里的媒体数组仍可作为兼容回退读取。
报告日期目前部分逻辑使用 createdAt 的日期字符串，部分逻辑会按 Date 解析 ISO 字符串，后续建议统一为 ISO 时间戳加展示格式化。

5.3 KiB Raw Blame History Unescape Escape