From c0ed12d776382a3a710aea1737b94e8946658725 Mon Sep 17 00:00:00 2001 From: chengma Date: Fri, 14 Aug 2026 10:09:21 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=E4=BB=BB=E5=8A=A1=20?= =?UTF-8?q?#201?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...min实现AI规格候选匹配直接落库与来源审计.md | 71 +++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 docs/task/201-Admin实现AI规格候选匹配直接落库与来源审计.md diff --git a/docs/task/201-Admin实现AI规格候选匹配直接落库与来源审计.md b/docs/task/201-Admin实现AI规格候选匹配直接落库与来源审计.md new file mode 100644 index 0000000..900cd48 --- /dev/null +++ b/docs/task/201-Admin实现AI规格候选匹配直接落库与来源审计.md @@ -0,0 +1,71 @@ +# 201 Admin：实现 AI 规格候选匹配、直接落库与来源审计 + +- 类型：需求 +- 父级大工单：#14 +- 所属 MVP / 版本：#199 / AI规格批量匹配 +- 状态：已完成 +- 日期：2026-08-14 +- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/201 + +## 背景与目标 + +现有确定性规则只能排序 PDD 规格，歧义结果仍需逐条人工保存。本任务在现有候选和采购 +门禁上增加 OpenAI 兼容模型选择，并且只允许合格结果写入当前有效映射。人工映射始终 +优先，AI 决策历史只追加、不删除。 + +## 最终方案 + +- MySQL v21 为 `spec_mappings` 增加 `manual`、`rule`、`ai` 来源以及服务商、模型、 + 置信度、原因、版本和上下文版本字段；新增不含凭据和订单信息的 AI 决策审计表。 +- 先运行原有规则。唯一确定结果直接以 `rule` 保存，不调用模型；额外维度能从 SYB + 文本得到唯一信号时先缩小候选，否则转人工。 +- 模型只收到商品标题、SYB 规格文本和最多 24 个候选短编号。返回值使用严格 JSON， + 服务端维护短编号到真实 `pdd_option_key` 的映射，伪造编号无法落库。 +- 自动保存前重新读取 PDD 采集结果和上下文版本，并再次执行可购买、颜色冲突、额外 + 维度和候选白名单检查。模型置信度必须达到批次快照中的管理员阈值。 +- 自动 upsert 在数据库表达人工优先和幂等规则：任何人工映射都不被覆盖；同一上下文 + 的并发自动结果由先写入者获胜；PDD/规则上下文变化后可以替换旧自动结果。 +- 人工详情保存固定把当前来源改回 `manual` 并清空当前 AI 元数据，但保留只追加审计。 + +## 改了哪些 + +- `admin/service/ai_specmatch_client.go`：OpenAI 兼容请求、响应大小限制和严格 JSON 解析。 +- `admin/service/ai_specmatch.go`：规则短路、候选约束、模型调用、硬门禁、事务落库和审计。 +- `admin/repository/mapping.go`、`admin/repository/ai_config.go`：映射来源、自动幂等写入、 + AI 决策审计和当前启用服务商读取。 +- `admin/repository/mysql_db.go`：MySQL v21 追加迁移和 schema 自检。 +- `admin/repository/syb.go`、`admin/service/purchase_workflow.go`：读取映射来源，人工保存 + 恢复 `manual` 来源并记录上下文版本。 +- `admin/model/model.go`：增加当前映射和 AI 决策模型。 +- `admin/service/ai_specmatch*_test.go`、`admin/repository/mysql_db_integration_test.go`： + 增加模型结构、候选白名单、额外维度、低置信度、规则短路、人工并发优先和迁移测试。 +- `docs/admin/`：同步需求、架构、数据模型和安全基线。 + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| 模型只能选择当前真实候选，伪造候选被拒绝 | 通过 | +| 唯一规则结果和已有人工映射不调用模型 | 通过 | +| 冲突、额外维度不明、低置信度、无效 JSON、超时和上下文变化不落库 | 通过（代码与假模型测试；上下文事务实库待验证） | +| 合格结果写入有效映射并可被采购校验复用 | 通过（代码路径） | +| 人工修改恢复 manual 且保留 AI 审计 | 通过（集成用例已编写） | +| PDD 重新采集后失效判断与人工映射一致 | 通过（复用现有可购买选项校验） | +| 审计不含密钥、完整提示词/响应和订单/个人数据 | 通过 | +| 并发不覆盖人工映射，同一上下文保持幂等 | 通过（原子 SQL 与集成用例已编写） | +| MySQL 8.4 `_test` 迁移、事务和并发 | 未验证：本机未启用隔离测试库 | +| 固定 Go 1.23.0 build、test、vet | 通过 | + +## 测试 + +- 执行的命令： + - `go test ./service ./repository -count=1` + - `$env:GOTOOLCHAIN="go1.23.0"; go build ./...; go test ./... -count=1; go vet ./...` +- 结果：固定 Go 1.23.0 的构建、全量测试和静态检查全部通过；不需要 MySQL 的模型协议、 + 严格结构、候选编号和额外维度单元测试已实际执行。 +- **没验证到的部分**：未执行 MySQL 8.4 `_test` 实库迁移、事务回滚和并发用例；未调用 + 真实 AI 服务商；未在生产数据上评价匹配准确率。 + +## 相关提交 + +- `aac289a` feat: 实现 AI 规格候选匹配与审计 (#201)