Files

admin 8e0332b3cf Migrate legacy AI and speech settings to backend

- Add a super-admin-only settings merge that copies legacy local AI provider keys into an empty backend settings record.

- Add matching migration for legacy Xunfei APPID, APIKey, and APISecret without overwriting existing backend secrets.

- Cover the migration and secret-preservation behavior with SystemSettings unit tests.

- Update feature, module, progress, and testing docs for the settings migration behavior.

2026-05-02 02:22:26 +08:00

3.3 KiB

Raw Blame History

模块文档：系统设置

涉及文件

src/pages/SystemSettings.tsx
src/api/settings.ts
src/types.ts
src/utils/storage.ts
server/src/settings

模块职责

系统设置负责维护视频抽帧、AI 接口、讯飞语音和默认模板配置。超级管理员可以看到全部设置；其他用户主要配置默认报告模板。

页面优先调用 GET /api/settings/system 读取设置，保存时调用 PATCH /api/settings/system。只有开发模式或显式开启 VITE_ENABLE_LOCAL_FALLBACK=true 时，API 不可用才保留 localStorage.systemSettings 回退。后端使用 SystemSetting 表保存全局设置，并用 scope = user:<id> 保存个人默认模板。

视频抽帧配置

配置字段包括：

frameCount：抽取帧数。
framePositions：每帧对应的视频进度百分比。
frameMode：调整帧数时使用整体均匀抽取或保持当前抽帧。
autoInsertFrames：是否自动插入关键帧。
autoInsertDelay：自动插入延迟。
autoInsertFrameIndices：哪些抽帧序号参与自动插入。

保存时会对 framePositions 排序，并把 frameCount 同步为位置数组长度。

AI 接口配置

activeAiProvider 指向当前服务商，aiProviders 保存各服务商配置。默认服务商包括：

Kimi
DeepSeek
OpenAI
Custom

系统通过后端 /api/ai/models 测试连接和获取模型列表，通过 /api/ai/chat 在报告编辑器中生成内容。后端读取全局共用 Provider Key 并代理 OpenAI 兼容 /models 与 /chat/completions，普通用户读取设置时不会拿到 AI Key。

从旧前端 mock 版本迁移时，如果超级管理员浏览器的 localStorage.systemSettings 中仍保留旧 AI Key，而后端全局配置为空，设置页会在读取后端配置后把本地旧密钥合并到当前设置并自动写入后端。该逻辑只用于迁移已有浏览器缓存；源码、文档和 Docker 配置仍不内置真实密钥。

讯飞语音配置

xfSpeechConfig 保存讯飞 WebSocket IAT 所需的 APPID、APIKey 和 APISecret。报告编辑器只连接本系统 /api/speech/iat，由后端读取这些配置、生成讯飞鉴权 URL 并转发音频和识别结果。普通用户读取设置时不会拿到 APIKey/APISecret。

讯飞配置同样支持从旧本地 xfSpeechConfig 向后端 Settings API 做一次性迁移。迁移成功后，医生端语音听写只依赖后端代理和登录 Session。

默认模板

defaultTemplate 指向模板 ID。新建报告时，如果当前用户可见该模板，编辑器会自动加载对应模板内容；否则回退到默认内置报告内容。

重置能力

超级管理员可执行：

恢复系统设置出厂设置：优先调用 POST /api/settings/system/reset，只有本地回退开启时失败才重置本地 systemSettings。
重置全部数据：仅本地回退开启时执行 localStorage.clear() 并刷新；生产构建默认阻止把本地清空误认为后端数据重置。

注意事项

systemSettings 的本地混淆不等于安全加密；当前仅作为开发/显式本地回退模式下 API 不可用时的兼容缓存。
初始化、类型和系统设置页面已统一使用 xfSpeechConfig；当前由后端语音代理使用。
默认 API Key 或语音密钥不应留在生产前端代码中。

3.3 KiB Raw Blame History Unescape Escape