feat: 增加管理员 AI 模型配置 (#200)

2026-08-14 09:49:11 +08:00
parent ad44f83ea6
commit 018da3f732
24 changed files with 1546 additions and 8 deletions
@@ -400,6 +400,14 @@ Admin 本地时区，付款状态只是 Client 核单上报时的快照，Admin

 **底部状态条：** 在线 / 离线数量统计。

+### 4.6 AI 规格批量匹配（#199）
+
+- AI 集成保留在 Admin 内部，不增加独立微服务；MVP 使用 OpenAI 兼容协议。
+- 只有管理员能够维护服务商、模型和部署级密钥；采购员只能发起规格匹配。
+- API Key 不进入数据库、`data/`、日志或 HTTP 响应，保存后只显示固定掩码和尾四位。
+- 模型只能选择服务端提供的当前可购买候选；不确定、超时或硬校验失败时保持人工处理。
+- AI 匹配不会创建采购任务，不改变 Client 接口，也不放宽真实采购门禁。
+
 ## 5. 创建采购任务的校验

 `[必须]` 下面任何一条不满足就不允许创建，并明确告诉操作员缺什么：
@@ -252,7 +252,18 @@ handler 返回批次 JSON；管理员在统一导入记录页查看摘要
  Web 登录中间件也不覆盖 `/api/v1/client/*`。
 - 详见 [04 Client 接口实现](04-client-api.md)。

-## 9. 相关文档
+## 9. AI 配置与密钥边界
+
+AI 服务商的普通配置和非敏感审计由 `repository` 写入 MySQL。API Key 通过
+`service.AISecretStore` 写入部署指定的独立文件；该文件必须使用绝对路径，不能位于
+仓库、`data/` 或 release 目录，生产建议为 `/etc/cmautobuy/ai-secrets.yaml` 且权限为
+`600`。页面只得到“是否配置”和固定掩码尾号。
+
+外部模型调用位于独立 HTTP 客户端边界：只允许 HTTPS，拒绝 URL 内凭据、环回、链路
+本地、云元数据和未显式允许的私网地址；重定向和实际拨号也执行相同检查。部署级
+`allowed_hosts` 是私有模型端点的唯一例外入口，网页不能修改。
+
+## 10. 相关文档

 - [上手指南](00-getting-started.md)
 - [术语表](00-glossary.md)
@@ -974,3 +974,14 @@ CREATE UNIQUE INDEX idx_client_assignment_current
 - 相同来源和批次号携带不同请求哈希时记录冲突并返回 HTTP 409。
 - `response_body` 只保存可安全重放的结果摘要，不得包含凭据或原始商品数据。
 - `source_observed_at` 用于拒绝较旧数据覆盖较新数据；缺席记录绝不代表删除。
+
+## 15. AI 服务商配置（MySQL v20）
+
+`ai_provider_configs` 只保存非敏感配置：服务商名称、HTTPS Base URL、模型、超时、最大
+并发、自动写入置信度基点、启用状态和最近连接测试摘要。`active_slot` 是生成列并带唯一
+索引，数据库层保证任一时刻最多一个启用项。普通配置或密钥发生变化时，当前服务商会
+停用并把测试状态重置为 `pending`，必须重新测试后才能启用。
+
+`ai_provider_audits` 追加记录创建、修改、测试、启停以及密钥替换/清除动作，只保存字段
+名和非敏感状态。两张表都没有 API Key、Token 或 Secret 列；API Key 只存在部署指定的
+独立密钥文件。
@@ -907,6 +907,16 @@ placeholder 写「任务编号 / 订单号 / 商品 ID」，**不要写全「PDD
 - 采购员仍由管理员在用户管理页重置密码；本阶段不提供采购员自助改密和忘记密码入口。
 - 弹窗继续遵守公共关闭规则：取消、关闭按钮、Esc 和直接点击遮罩可关闭，从密码框拖选到遮罩不会误关闭。

+### 8.4 AI 模型配置页
+
+“AI 配置”只在管理员导航中显示，采购员直接访问页面或写接口也必须返回 403。页面采用
+高密度表格：一行一个服务商，显示接口、模型、运行参数、密钥状态、连接测试和启用状态。
+所有输入使用可见 `label`；保存、测试、启停和清除均为带 CSRF 的普通 POST 表单。
+
+API Key 使用密码输入框，只允许替换或清除。已保存值显示固定掩码和尾四位，不提供查看、
+复制或下载明文的入口。修改普通配置或密钥后明确提示“需要重新测试”；测试失败保留上一
+个已启用服务商，错误消息只说明原因和恢复动作，不展示响应正文。
+
 ## 9. 反馈方式

 | 场景 | 怎么反馈 |
@@ -260,3 +260,11 @@ CMAutoBuyAdmin/
 4. 变更不泄露敏感信息；
 5. Gitea 工单更新最终结果和提交哈希；
 6. 完成记录归档到 `docs/task`。
+
+## 11. AI 外部调用安全
+
+- API Key 不得进入数据库、`data/`、日志、页面响应、测试快照、工单或归档；测试只使用假密钥。
+- 密钥文件使用同目录临时文件、`fsync`、原子替换和 `600` 权限，失败时旧文件保持可用。
+- 连接测试只发送模型名和最小无业务文本，不发送订单号、店铺账号、用户、地址或 Client 信息。
+- Base URL、DNS 解析、实际拨号和重定向都要执行 SSRF 校验；私有地址只能由部署级允许列表开放。
+- 测试失败、超时和非 2xx 响应不得记录 Authorization、完整请求或完整响应。