feat: 实现 AI 规格候选匹配与审计 (#201)

docs/admin/01-requirements.md

@@ -531,7 +531,7 @@ MVP 之后：
 
 - 不做面向外部的公网服务，只在内网/本机运行。
 - 不直接对接蝦皮和拼多多的接口。
-- 不自动决定买哪个商品——PDD 链接和规格匹配都由人确认。
+- 不由模型选择或更换 PDD 商品链接；规格自动匹配只能从后端当前可购买候选中选择，硬校验不通过时仍由人确认。
 - 不自动付款。
 - 不开放用户自助注册；第一个管理员只能通过首次初始化创建。
 - 不做复杂 RBAC、细粒度页面权限、单点登录和第三方登录。

docs/admin/02-architecture.md

@@ -263,6 +263,11 @@ AI 服务商的普通配置和非敏感审计由 `repository` 写入 MySQL。API
 本地、云元数据和未显式允许的私网地址；重定向和实际拨号也执行相同检查。部署级
 `allowed_hosts` 是私有模型端点的唯一例外入口，网页不能修改。
 
+规格匹配按“确定性规则 → 有限候选 → 模型选择 → 服务端硬校验 → 事务写入”的顺序执行。
+模型只看到商品标题、SYB 规格文本和后端生成的候选短编号，不能生成真实 PDD 选项键。
+唯一确定的规则结果不调用模型；有效人工映射始终优先。保存前重新计算上下文版本并检查
+当前可购买候选，防止 PDD 重采集或人工并发修改后写入过期结果。
+
 ## 10. 相关文档
 
 - [上手指南](00-getting-started.md)

docs/admin/03-data-model.md

@@ -583,12 +583,24 @@ CREATE TABLE spec_mappings (
     spec_raw        TEXT NOT NULL,
     mapped_at       VARCHAR(35) NOT NULL,
     mapped_by       VARCHAR(191),
+    source          VARCHAR(16) NOT NULL DEFAULT 'manual', -- manual / rule / ai
+    source_provider_id VARCHAR(191),
+    source_model    VARCHAR(191),
+    confidence_bps  INT,
+    source_reason   VARCHAR(500),
+    source_version  VARCHAR(64),
+    context_version CHAR(64),
     PRIMARY KEY (shopee_goods_id, spec_key, pdd_goods_id),
     KEY idx_spec_mappings_goods (shopee_goods_id),
     KEY idx_spec_mappings_pdd (pdd_goods_id)
 );
 ```
 
+v21 增加的来源字段描述当前生效映射。人工在详情页保存时，`source` 固定改为 `manual`
+并清空 AI 元数据；规则唯一确定的结果使用 `rule`；通过模型和服务端硬门禁的结果使用
+`ai`。这些字段不改变映射唯一键。PDD 重新采集后如果 `pdd_option_key` 已不存在，三种
+来源都按同一规则判为失效，不能进入采购任务。
+
 `[必须]` 不加外键。顺运宝明细可能比蝦皮报表更早到达，同步要先创建 skeleton 商品；
 PDD 商品还可软删除，映射作为审计和可恢复数据必须保留。
 
@@ -679,6 +691,15 @@ SELECT rules_version, COUNT(*) AS 无建议决策数
 FROM spec_mapping_decisions WHERE suggested_option_key IS NULL GROUP BY rules_version;
 ```
 
+### 6.4 `ai_spec_match_decisions` AI 决策审计（MySQL v21）
+
+本表只追加，记录一次 AI 匹配动作使用的上下文版本、规则/提示词版本、服务商和模型快照、
+候选短编号到真实选项键的映射、置信度、结论和简短原因。它不保存 API Key、完整提示词、
+完整请求/响应、顺运宝订单号、店铺账号、用户资料、地址或 Client 信息。
+
+合格映射和成功决策在同一事务提交。低置信度、伪造候选、模型拒绝、超时和格式错误也
+追加脱敏结论，但不写 `spec_mappings`。人工后来覆盖当前映射时不会删除本表历史。
+
 ## 7. `tasks` 任务
 
 采集任务和采购任务共用一张表，用 `task_type` 区分。

docs/admin/06-quality-security.md

@@ -268,3 +268,5 @@ CMAutoBuyAdmin/
 - 连接测试只发送模型名和最小无业务文本，不发送订单号、店铺账号、用户、地址或 Client 信息。
 - Base URL、DNS 解析、实际拨号和重定向都要执行 SSRF 校验；私有地址只能由部署级允许列表开放。
 - 测试失败、超时和非 2xx 响应不得记录 Authorization、完整请求或完整响应。
+- 规格匹配请求只包含商品标题、规格文本和候选短编号，不包含订单号、店铺账号、用户、地址或 Client 信息。
+- 模型返回值必须经过严格 JSON 结构、候选白名单、颜色冲突、额外维度、置信度和上下文版本校验；模型自报置信度不能替代硬门禁。