docs: record AI matching internal key policy

2026-08-21 16:54:35 +08:00
parent 052f51785b
commit 69ae1e1103
4 changed files with 31 additions and 4 deletions
@@ -166,6 +166,18 @@ Android 的 `pddProductDetailV1` 采集器执行以下固定流程：

 无障碍节点只投影为 Agent 进程内的瞬时不可变模型，不序列化、不上传、不写入文件。完整状态机接入后 Agent 才上报 `collector.pdd.product-detail.v1`。

+## 管理端：AI 规格匹配设置
+
+```http
+GET  /api/admin/v1/ai-matching-settings
+PUT  /api/admin/v1/ai-matching-settings
+POST /api/admin/v1/ai-matching-settings/test
+```
+
+这是采购规格匹配的单例配置，Provider 固定为 `openai_compatible`。管理员可读取、保存和测试连接；保存请求包含 `enabled`、`baseUrl`、`model`、`timeoutSeconds` 与 `apiKey`。根据 #62 已确认的内部部署例外，管理员 `GET` 响应会返回已保存的明文 `apiKey`，供下次查看和替换；采购员 `GET` 只返回 `enabled`，不能读取 Provider、地址、模型或 API Key，也不能保存或测试。
+
+Base URL 支持内网或公网的 `http://`、`https://`，不限制为局域网地址。服务端只在管理员点击测试或采购规格没有唯一确定性结果时，才向 Provider 发送目标颜色/尺码和 PDD 可选颜色/尺码；请求中不包含控件树、截图、地址、账号或订单。HTTP 不加密 API Key 的传输，生产环境建议使用 HTTPS。服务端禁止跟随 Provider 重定向，Provider 返回的颜色/尺码必须逐字等于当前候选原始标签，否则按无匹配处理。
+
 ## 管理端：采集任务

 ```http
@@ -483,7 +495,7 @@ Admin 列表与详情由 #35 实现；#44 在 SYB 商品列表提供单条/当
 | `POST` | `/api/agent/v1/purchase-tasks/{taskId}/order-submit-started` | 创建订单前先落不可逆标记；演练任务永远拒绝 |
 | `POST` | `/api/agent/v1/purchase-tasks/{taskId}/result` | 请求体携带 `taskAttemptId` 和 `requestId`；幂等提交演练、规格探测、订单或失败结果 |

-结果提交至少关联 `taskId`、`taskAttemptId`、`deviceId`、规则快照哈希和结构化结果。相同 attempt 的相同结果重复提交返回同一事实；不同内容拒绝覆盖。慢路径第一趟提交规格后释放设备与已知账号租约，任务进入 `spec_probe_pending`；服务端固化同一 attempt 的 AI/人工决策后，第二趟使用新的 attempt 重新派发。无匹配结果则明确失败。`order_result_unknown` 只允许管理员或采购员人工解除，永不自动重派。
+结果提交至少关联 `taskId`、`taskAttemptId`、`deviceId`、规则快照哈希和结构化结果。相同 attempt 的相同结果重复提交返回同一事实；不同内容拒绝覆盖。慢路径第一趟提交规格后释放设备与已知账号租约，任务进入 `spec_probe_pending`；服务端先使用已确认人工映射，否则对实时/档案可选规格做繁简、空白/全半角/大小写及公斤/斤的唯一确定性匹配，仍无唯一结果才调用 AI。第二趟只会收到服务端已固化的精确 PDD 原始标签；无匹配、候选不完整、歧义或 Provider 异常均使任务失败，不再派发。`order_result_unknown` 只允许管理员或采购员人工解除，永不自动重派。

 `openSpecPanel.textAliases` 是可选的候选过滤条件，不是原始页面文本选择器。省略该字段时，Agent 使用语义安全的规格入口或底部购买入口；提供时也只能与这些安全候选取交集，匹配不到即返回 `RULE_NOT_MATCHED`。

@@ -57,6 +57,7 @@ Android Portal/Agent
 | `pdd_account` | 可选的账号调度引用，只保存名称和状态，不保存凭据 |
 | `purchase_task` | 商品外键和不可变快照、执行模式、状态/租约 guard、价格边界、订单、人工支付复核、物流与回填事实 |
 | `purchase_task_attempt` | `task_id + attempt_id` 幂等执行记录、阶段、规则哈希、固化规格决策和结构化错误 |
+| `ai_matching_setting` | 唯一单例的启用状态、OpenAI-compatible Base URL、模型、超时、内部部署明文 API Key 和更新人；仅管理员设置接口可以读取该字段 |

 `collection_task` 的状态仅为 `pending`、`running`、`completed`、`completed_partial`、`failed`。设备身份和心跳表属于 Agent 领取任务的必要基础，不承载 PDD 业务数据。

@@ -112,10 +113,12 @@ Android Portal/Agent
 | SYB 后台导入任务、进度、单任务互斥与启动恢复 | `server/app/goauto/sybimport/sync_run.go`、`sync_run_handler.go`；表 `syb_sync_run`，迁移 `server/cmd/migrate/migration/version-local/1786701000000_syb_sync_run.go` |
 | 采购任务数据与类型化规则契约 | `server/app/goauto/models/purchase.go`、`server/app/goauto/purchasecontract/`；迁移 `server/cmd/migrate/migration/version-local/1786701100000_purchase_contract.go` |
 | 采购任务单条/批量预检与创建、租约、attempt 幂等、Admin 只读查询和人工处置状态机 | `server/app/goauto/purchase/`；批量编排复用单任务事务且不新增迁移；既有追加迁移为 `server/cmd/migrate/migration/version-local/1786701200000_purchase_state_machine.go` |
+| 采购规格标准化匹配与 AI Provider 设置 | `server/app/goauto/aimatching/`；服务端先做繁简、空白/全半角/大小写和公斤/斤的唯一确定性匹配，再按需调用单一 OpenAI-compatible Provider；`1786701300000_ai_matching_setting.go` 创建设置表，`1786701400000_ai_matching_setting_plain_api_key.go` 将原加密列迁移为内部明文 `api_key`，仅管理员读取 |
 | 任务领取、结果、重置与删除 | `server/app/goauto/task/` |
 | 管理端基线 | `web/`（go-admin-ui v3.0.0） |
 | 管理端闭环页面 | `web/src/views/goauto/` |
 | Admin 采购任务列表、详情与人工处理 | `web/src/views/goauto/purchase-tasks/`、`web/src/api/goauto/purchase-tasks.js`；创建入口不在本模块 |
+| Admin AI 规格匹配设置 | `web/src/views/goauto/ai-matching-settings/`、`web/src/api/goauto/ai-matching-settings.js`；管理员可查看、维护和测试 Provider（包括内部明文 API Key），采购员只可查看启用状态 |
 | Admin 失败采购任务批量重试 | `POST /api/admin/v1/purchase-tasks/batch-retry`；服务端 `server/app/goauto/purchase/retry.go` 负责资格判定、逐项幂等创建与部分成功结果，Admin 页面只允许选择服务端标记可重试的行；不修改 Android Agent |
 | SYB 店铺管理页面与接口封装 | `web/src/views/goauto/syb-shops/`、`web/src/api/goauto/syb-shops.js`；确认原型快照 `prototypes/49/v1/index.html` |
 | SYB 异步导入、当前页采购选择/确认/逐条结果与同步记录页面 | `web/src/views/goauto/syb-products/`、`web/src/views/goauto/syb-sync-runs/`、`web/src/api/goauto/syb-products.js`、`web/src/api/goauto/purchase-tasks.js`；确认原型见 #44 设计证据，导入原型快照为 `prototypes/50/v2/index.html` |
@@ -116,7 +116,8 @@
 - Agent 本地 SQLite/Outbox 负责断网和重启恢复，服务端以 `task_id + task_attempt_id` 幂等接收并保存最终事实。
 - 人工支付复核只记录 `paid` / `unpaid`；系统不执行或识别支付。快递单号与回填状态属于采购任务，后续物流工单实现。
 - 采购任务领取时同时占用设备租约和可选 PDD 账号租约；租约过期后才可释放并重新领取。设备还存在采集任务时不能领取采购任务。
- 规格映射不完整、PDD 档案为待采集或没有规格时，规则必须具有 `purchase.spec-probe.v1`；第一趟只探测规格并释放租约，服务端固化同一 attempt 的决策后才派发第二趟。无匹配结果明确失败。
+- 采购规格由服务端按顺序决策：先使用已确认的人工映射；否则仅在同一规格角色的可选 PDD 原始标签中做唯一确定性匹配（繁体转简体、空格/全半角/大小写统一，以及公斤/斤换算）；仍无唯一结果才调用已启用的服务端 AI。AI 必须返回候选集中的原始标签，候选不完整、歧义、AI 无结果或服务不可用均明确失败，不派发第二趟、更不创建订单。
+- 规格映射不完整、PDD 档案为待采集或没有规格时，规则必须具有 `purchase.spec-probe.v1`；第一趟只探测规格并释放租约，服务端固化同一 attempt 的决策后才派发第二趟。Android 不自行匹配或猜测；其只接收服务端已经固化的精确原始规格标签。
 - Agent 提交的相同 attempt 最终结果只能写入一次；相同请求重放返回原事实，不同内容拒绝覆盖。`order_result_unknown` 不参与自动派发，只能人工解除。
 - 已创建订单默认禁止再次采购；管理员或采购员可以做一次性重新采购授权，新任务创建成功时在同一事务消耗授权，旧任务和旧订单保留。已标记为已支付的订单不能授权或创建重新采购任务。
 - 人工回填候选只允许从已支付订单选择；同一 SYB 明细后来选择的订单覆盖旧候选，但不删除旧订单事实。
@@ -131,7 +132,7 @@
 - 登录失效、验证码、风控、人机验证和找不到唯一控件时失败并给出具体错误。
 - Android Agent 端不使用 OCR/VLM 兜底，不保存原始控件树或截图。采集阶段不猜测缺失数据。
 - 服务端顺云宝（SYB）登录例外：允许调用配置的线上 OCR 服务识别登录验证码（见 [#48](https://git.ilapage.cn/OPC/goauto/issues/48)）。验证码图片会离开本项目发送到该服务，更换服务地址前必须重新评估。此例外只适用于 SYB 登录，不扩大到 Agent 端或任何 PDD 相关流程。
- 采购阶段的规格匹配由服务端决策（见 [#46](https://git.ilapage.cn/OPC/goauto/issues/46)）：Agent 本地不得自行猜测规格或点击相近候选，只执行服务端下发的精确规格；AI 无匹配结果时明确失败。
+- 采购阶段的规格匹配由服务端决策（见 [#46](https://git.ilapage.cn/OPC/goauto/issues/46)、[#62](https://git.ilapage.cn/OPC/goauto/issues/62)）：Agent 本地不得自行猜测规格或点击相近候选，只执行服务端下发的精确规格；AI Provider 只有一个 OpenAI-compatible 配置，由管理员维护。根据 #62 已确认的内部部署例外，API Key 明文保存在专用设置表，并只向管理员设置接口返回以便查看和替换；它仍不得写入代码、日志、工单、Wiki、任务快照、采购员接口或 Android 接口。Provider Base URL 不限制内网或公网，支持 HTTP/HTTPS；HTTP 不加密传输中的 API Key，生产环境建议 HTTPS。
 - 采购规则的 `openSpecPanel` 默认不写死页面文字。Agent 只在已由页面语义确认的规格入口或底部购买入口中选择；规则若提供 `textAliases`，只能进一步缩小这些安全候选，不能把任意同名页面文字变成可点击入口。
 - 正式采购规则可以调用独立审核的改地址、创建待付款订单和只读核单动作；采集规则和演练规则不能调用。真机首次安装或验证仍需独立人工授权。
 - 系统不提供自动支付、实时屏幕或管理端远程控制。付款、免密支付及任何等价动作始终禁止。
@@ -160,7 +161,7 @@
 | 虾皮 | Shopee 的中文展示名。管理端界面一律用「虾皮」，数据库表名、字段名、API 路径等程序标识符保持 `shopee_product`（单数）/ `shopee_item_id` 不变 |
 | SYB | 顺云宝 ERP（ShunYunBao，域名 shunyunbaoerp.com），虾皮订单与货运单的外部来源系统。管理端界面一律用「SYB」，不再使用「货运宝」「顺云宝」等别名；数据库表名与字段保持 `syb_products` |
 | 货运单 | SYB 中的一张单据（`code`，如 260728TB95MJTQ），下挂一条或多条商品明细。与系统名「SYB」区分，不可混用 |
-| AI 规格匹配 | 人工映射缺失、PDD 商品无规格数据或目标规格定位不到时，由服务端 AI 接口把虾皮目标颜色尺码匹配到 PDD 实际规格；候选集限定为实时可选规格，无结果即失败 |
+| AI 规格匹配 | 人工映射后仍无法以确定性标准化唯一匹配时，服务端才调用单一 OpenAI-compatible Provider，把虾皮目标颜色尺码匹配到 PDD 实际可选规格；结果必须是候选原始标签，无结果、歧义或 Provider 不可用即失败 |
 | 快路径 / 慢路径 | 采购执行的两种路径：Agent 能直接定位到下发的目标规格为快路径；定位不到则触发全量遍历采集并重新匹配，为慢路径 |
 | 两趟执行 | 慢路径的实现方式：第一趟采集规格后结束并释放设备，服务端离线匹配，第二趟重新派发下单，复用 `task_attempt` 机制 |
 | 采购探测 | 采购时对 PDD 商品页的实时规格采集，同时作为一次商品信息更新写回档案，按 `completed` / `completed_partial` 语义处理 |
@@ -27,6 +27,8 @@ go build ./...

 默认运行目标是 MySQL。开发者在仓库根目录的 `config.yaml` 中维护本机连接参数和启动端口；该文件已被 Git 忽略，不得提交。可从不含凭据的 `config.example.yaml` 复制。启动脚本读取配置后，仅通过当前进程环境注入数据库连接、服务端端口和前端 API 地址，不把账号密码写回 `server/config/settings.yml`、日志、工单或文档。

+如需启用 AI 规格匹配，管理员在“AI 规格匹配”页面配置单一 OpenAI-compatible Provider 的 Base URL、模型、超时和 API Key；根据 #62 已确认的内部部署例外，API Key 明文保存在专用设置表，并只在管理员设置页面回显，不能出现在代码、日志、工单、Wiki、任务快照、采购员接口或 Android 接口。Base URL 支持公网或内网的 HTTP/HTTPS 地址，不作局域网限制；HTTP 不加密传输中的 API Key，生产环境建议 HTTPS。
+
 已经执行过旧版 GoAuto 表结构的数据库，会由 `1786700300000_collection_execution.go` 增量补齐任务幂等、结果、软删除和颜色价格字段；不要通过修改已执行迁移的版本号强制重跑。

 Windows 本地 MySQL 8.4 可以从仓库根目录双击或执行：
@@ -48,6 +50,15 @@ go test ./app/goauto/...

 该命令同时覆盖设备注册的首次签发、requestId 重放、错误 Token、防接管、停用/吊销、HTTPS、限流、心跳任务一致性和超时离线失败测试。

+AI 规格匹配的隔离验证：
+
+```powershell
+Set-Location server
+go test ./app/goauto/aimatching ./app/goauto/purchase
+```
+
+该测试覆盖确定性标准化、歧义拒绝、Provider 回退的候选原文校验、内部 API Key 的管理员读取/采购员隔离以及 HTTP/HTTPS Base URL 校验；不会调用真实 Provider 或创建订单。
+
 如需用临时 SQLite 做隔离联调，服务端命令必须显式带上 SQLite 构建标签：

 ```powershell