admin
2cabe7e4fd
- Allow system frame position percentages to keep two decimal places without reordering saved values. - Stop frontend and backend settings normalization from sorting framePositions on load or save. - Capture automatic video frames in timeline order while retaining each configured position index. - Insert automatically selected frames into report placeholders according to the configured percentage order. - Add frame position utilities and unit coverage for two-decimal rounding, clamping, order preservation, and timeline capture planning. - Update README, AGENTS, feature, requirement, report editor, system settings, progress, and testing docs for the new frame ordering behavior.
62 lines
3.3 KiB
Markdown
62 lines
3.3 KiB
Markdown
# 模块文档：系统设置
|
||
|
||
## 涉及文件
|
||
|
||
- `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` 排序，只会把每个百分比规范到 0-100 区间和两位小数，并把 `frameCount` 同步为位置数组长度。报告编辑器自动截帧时会按时间顺序执行实际截图；自动插入图片时按 `framePositions` 的配置顺序和 `autoInsertFrameIndices` 插入。
|
||
|
||
## AI 接口配置
|
||
|
||
`activeAiProvider` 指向当前服务商，`aiProviders` 保存各服务商配置。默认服务商包括：
|
||
|
||
- Kimi
|
||
- DeepSeek
|
||
- OpenAI
|
||
- Custom
|
||
|
||
系统通过后端 `/api/ai/models` 测试连接和获取模型列表，通过 `/api/ai/chat` 在报告编辑器中生成内容。后端读取全局共用 Provider Key 并代理 OpenAI 兼容 `/models` 与 `/chat/completions`，普通用户读取设置时不会拿到 AI Key。
|
||
|
||
## 讯飞语音配置
|
||
|
||
`xfSpeechConfig` 保存讯飞 WebSocket IAT 所需的 APPID、APIKey 和 APISecret。报告编辑器只连接本系统 `/api/speech/iat`，由后端读取这些配置、生成讯飞鉴权 URL 并转发音频和识别结果。普通用户读取设置时不会拿到 APIKey/APISecret。
|
||
|
||
## 默认模板
|
||
|
||
`defaultTemplate` 指向模板 ID。新建报告时，如果当前用户可见该模板，编辑器会自动加载对应模板内容；否则回退到默认内置报告内容。
|
||
|
||
## 重置能力
|
||
|
||
超级管理员可执行：
|
||
|
||
- 恢复演示出厂设置：调用 `POST /api/settings/system/reset`，前端做二次确认后由后端恢复 demo mode。
|
||
|
||
当前 demo mode reset 会清空报告、报告历史、报告媒体、文件资源和审计日志；用户只保留 `admin`、`manager`、`0001` 三个默认账号；模板只保留“腹腔镜胆囊切除术报告”；系统设置恢复默认抽帧策略、默认模板、Kimi Provider 和讯飞语音代理配置。该能力用于演示环境快速回到可演示状态，不是生产备份/恢复方案。
|
||
|
||
## 注意事项
|
||
|
||
- `systemSettings` 的本地混淆不等于安全加密；当前仅作为开发/显式本地回退模式下 API 不可用时的兼容缓存。
|
||
- 初始化、类型和系统设置页面已统一使用 `xfSpeechConfig`；当前由后端语音代理使用。
|
||
- demo mode 内置第三方服务演示凭据，生产部署前必须替换或移除，并通过正式密钥管理流程维护。
|