docs(tasks): define app and backend VLM integration

This commit is contained in:
QiuSW
2026-07-27 09:22:03 +08:00
parent 45d4d11fe5
commit 45d1436033
12 changed files with 357 additions and 11 deletions
+33
View File
@@ -16,6 +16,7 @@
| IX-007 | US-005 | App 候选确认 | 接受/拒绝/转人工 | 停止自动化并回传人员结论 | P0 | 已定 |
| IX-008 | US-006 | App/管理端错误状态 | 自动失败、取消、重试上传 | 显示结构化原因和恢复动作 | P0 | 已定 |
| IX-009 | US-008 | App 候选理由/管理端决策详情 | 接受、拒绝、改选或修正 | 保存逐候选结构化人工标签 | P1 | 已定,T-208 后置 |
| IX-010 | US-009 | 管理 Web VLM 设置 | 保存、测试或启用配置版本 | 后端代理模型且密钥不下发 App | P0 | 已定,T-207 |
## IX-001 管理 Web 登录
@@ -278,6 +279,38 @@
- 理由使用 checkbox/radio 和明确 label,不依赖颜色;主要理由可用单选控件指定。
- 批量应用前显示候选数量和标题摘要,默认不选中。
## IX-010 管理 VLM 服务
- 页面:管理 Web `/settings/vlm`;Android 设置页只读显示后端 AI 状态。
- 角色:采购管理员。
- 前置条件:后端加密 master key 已配置。
- 服务依赖:T-207 provider 配置、加密存储、安全 HTTP transport 和连接测试。
**正常路径**
1. ADMIN 填写服务名称、HTTPS Base URL、模型、超时和重试上限,选择
`/v1/chat/completions`,输入 write-only API Key。
2. 保存前显示非秘密配置摘要;提交成功创建不可变新版本,并可设为新 execution 的
默认版本。
3. “测试连接”使用内置脱敏文字和测试图片,不读取或发送任何采购任务。
4. 页面显示当前默认版本、启用状态、最近测试时间和稳定结果,不显示 Key。
**状态与异常**
- Key 字段始终为空;已有 Key 只显示“已配置”。留空表示沿用,替换必须明确确认。
- master key 缺失时禁止保存含 Key 的配置和测试真实服务,但不阻塞任务管理页面。
- URL 非 HTTPS、指向受限网络、发生重定向/DNS rebinding 或模型字段非法时在字段
附近提示,不发出供应商请求。
- 超时、鉴权失败、限流和 schema 不兼容显示稳定分类和 request ID;供应商响应正文
只进入受控诊断且默认不持久化。
- 非 ADMIN 返回拒绝且不泄露配置是否存在;所有 POST 使用 CSRF 和防重复提交。
**App 边界**
- App 只显示“后端 AI 可用/不可用”和可操作建议,不显示 provider 名称、模型、
Base URL、Key 或选择控件。
- Release App 不保留可用于后端任务的端上 provider 配置;Debug mock 与生产隔离。
## 通用交互约束
- Web 和 App 的所有提交都防重复,网络超时后以服务端状态为准。