From 12414658d001c052929637fe0e4b90f71212f2e2 Mon Sep 17 00:00:00 2001 From: chengma Date: Mon, 17 Aug 2026 16:53:11 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=AE=9A=E4=B9=89=E8=BF=90=E8=A1=8C?= =?UTF-8?q?=E6=97=B6=E8=A7=84=E6=A0=BC=E8=A7=A3=E6=9E=90=E5=A5=91=E7=BA=A6?= =?UTF-8?q?=E4=B8=8E=E5=AE=A1=E8=AE=A1=E6=A8=A1=E5=9E=8B=20(#254)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- admin/model/model.go | 50 ++++++ admin/repository/mysql_db.go | 110 +++++++++++- admin/repository/mysql_db_integration_test.go | 94 ++++++++++ admin/repository/purchase_spec_resolution.go | 143 ++++++++++++++++ docs/admin/03-data-model.md | 97 ++++++++++- docs/admin/04-client-api.md | 70 +++++++- docs/client/03-data-model.md | 27 ++- docs/client/04-admin-api-contract.md | 161 +++++++++++++++++- 8 files changed, 736 insertions(+), 16 deletions(-) create mode 100644 admin/repository/purchase_spec_resolution.go diff --git a/admin/model/model.go b/admin/model/model.go index 3ea8423..ce65719 100644 --- a/admin/model/model.go +++ b/admin/model/model.go @@ -407,6 +407,56 @@ type AISpecMatchDecision struct { DecidedBy, DecidedAt string } +// PurchaseSpecResolutionOutcome 是一次采购运行时规格解析的持久化结论。 +// pending 只表示候选观察已经落库，尚未完成规则或 AI 决策。 +type PurchaseSpecResolutionOutcome string + +const ( + PurchaseSpecResolutionPending PurchaseSpecResolutionOutcome = "pending" + PurchaseSpecResolutionMatched PurchaseSpecResolutionOutcome = "matched" + PurchaseSpecResolutionUncertain PurchaseSpecResolutionOutcome = "uncertain" + PurchaseSpecResolutionRejected PurchaseSpecResolutionOutcome = "rejected" + PurchaseSpecResolutionFailed PurchaseSpecResolutionOutcome = "failed" +) + +// PurchaseSpecResolutionSource 记录最终结论由哪条受控路径产生。 +type PurchaseSpecResolutionSource string + +const ( + PurchaseSpecResolutionRule PurchaseSpecResolutionSource = "rule" + PurchaseSpecResolutionAI PurchaseSpecResolutionSource = "ai" + PurchaseSpecResolutionReused PurchaseSpecResolutionSource = "reused" +) + +// PurchaseSpecResolution 同时保存 Client 的候选观察和 Admin 的最终决策。 +// JSON 字段只允许保存接口契约定义的规格数据，不得写入控件树、订单或凭据。 +type PurchaseSpecResolution struct { + ResolutionID, TaskID, AttemptID, ClientID string + TaskVersion int64 + PddGoodsID, OriginalOptionsJSON, SelectedColor string + TargetSize, CandidatesJSON, CandidateSnapshotHash string + ObservedAt, RequestHash string + Outcome PurchaseSpecResolutionOutcome + DecisionSource PurchaseSpecResolutionSource + ChosenCandidateID, ResolvedOptionsJSON string + ConfidenceBPS int + ConfidenceSet bool + Reason, ProviderID, SourceModel, ConfigFingerprint string + RulesVersion, PromptVersion, CreatedAt, DecidedAt string +} + +// PurchaseSpecResolutionDecision 是 Repository 完成一次解析记录时需要的最小字段。 +type PurchaseSpecResolutionDecision struct { + ResolutionID string + Outcome PurchaseSpecResolutionOutcome + DecisionSource PurchaseSpecResolutionSource + ChosenCandidateID, ResolvedOptionsJSON string + ConfidenceBPS int + ConfidenceSet bool + Reason, ProviderID, SourceModel, ConfigFingerprint string + RulesVersion, PromptVersion, DecidedAt string +} + type AIMatchBatch struct { BatchID, Status, CreatedByUserID string TotalCount, ProcessedCount, SuccessCount, ReusedCount int diff --git a/admin/repository/mysql_db.go b/admin/repository/mysql_db.go index 968b4a3..3f3f6ae 100644 --- a/admin/repository/mysql_db.go +++ b/admin/repository/mysql_db.go @@ -20,7 +20,7 @@ import ( "cmautobuy/admin/spec" ) -const mysqlSchemaVersion = 25 +const mysqlSchemaVersion = 26 // OpenMySQL 打开生产 MySQL 8 数据库。错误信息绝不包含完整 DSN 或密码。 func OpenMySQL(cfg config.DatabaseConfig) (*sql.DB, error) { @@ -724,10 +724,71 @@ func MigrateMySQL(db *sql.DB) error { if _, err := db.Exec(`INSERT INTO schema_migrations (version, applied_at) VALUES (?, ?)`, 25, time.Now().UTC().Format(time.RFC3339Nano)); err != nil { return fmt.Errorf("记录 MySQL schema v25 失败: %w", err) } + current = 25 + } + if current < 26 { + if err := migrateMySQLV26(db); err != nil { + return fmt.Errorf("执行 MySQL schema v26 失败: %w", err) + } + if err := checkMySQLV26Shape(db); err != nil { + return fmt.Errorf("MySQL schema v26 自检失败，未记录版本: %w", err) + } + if _, err := db.Exec(`INSERT INTO schema_migrations (version, applied_at) VALUES (?, ?)`, 26, time.Now().UTC().Format(time.RFC3339Nano)); err != nil { + return fmt.Errorf("记录 MySQL schema v26 失败: %w", err) + } } return CheckMySQLSchema(db) } +// migrateMySQLV26 建立采购运行时规格解析审计。一个记录同时保存候选观察和最终决策， +// 不覆盖 PDD 商品主数据，也不通过外键阻止任务的既有硬删除流程。 +func migrateMySQLV26(db *sql.DB) error { + _, err := db.Exec(`CREATE TABLE IF NOT EXISTS purchase_spec_resolutions ( + resolution_id VARCHAR(191) COLLATE utf8mb4_bin PRIMARY KEY, + task_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL, + attempt_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL, + client_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL, + task_version BIGINT NOT NULL, + pdd_goods_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL, + original_options_json JSON NOT NULL, + selected_color VARCHAR(191) NOT NULL, + target_size VARCHAR(191) NOT NULL, + candidates_json JSON NOT NULL, + candidate_snapshot_hash CHAR(64) COLLATE utf8mb4_bin NOT NULL, + request_hash CHAR(64) COLLATE utf8mb4_bin NOT NULL, + observed_at VARCHAR(35) NOT NULL, + outcome VARCHAR(16) NOT NULL DEFAULT 'pending', + decision_source VARCHAR(16) NULL, + chosen_candidate_id VARCHAR(16) COLLATE utf8mb4_bin NULL, + resolved_options_json JSON NULL, + confidence_bps INT NULL, + reason VARCHAR(500) NULL, + provider_id VARCHAR(191) COLLATE utf8mb4_bin NULL, + source_model VARCHAR(191) NULL, + config_fingerprint CHAR(64) COLLATE utf8mb4_bin NULL, + rules_version VARCHAR(32) NULL, + prompt_version VARCHAR(32) NULL, + created_at VARCHAR(35) NOT NULL, + decided_at VARCHAR(35) NULL, + UNIQUE KEY uq_purchase_spec_resolution_identity (task_id,attempt_id,candidate_snapshot_hash), + KEY idx_purchase_spec_resolution_task (task_id,created_at DESC,resolution_id), + KEY idx_purchase_spec_resolution_outcome (outcome,created_at,resolution_id), + CONSTRAINT chk_purchase_spec_resolution_task_version CHECK (task_version > 0), + CONSTRAINT chk_purchase_spec_resolution_options CHECK ( + JSON_TYPE(original_options_json)='OBJECT' AND JSON_LENGTH(original_options_json) BETWEEN 1 AND 16 AND + JSON_TYPE(candidates_json)='ARRAY' AND JSON_LENGTH(candidates_json) BETWEEN 1 AND 100 AND + (resolved_options_json IS NULL OR JSON_TYPE(resolved_options_json)='OBJECT')), + CONSTRAINT chk_purchase_spec_resolution_outcome CHECK (outcome IN ('pending','matched','uncertain','rejected','failed')), + CONSTRAINT chk_purchase_spec_resolution_source CHECK (decision_source IS NULL OR decision_source IN ('rule','ai','reused')), + CONSTRAINT chk_purchase_spec_resolution_confidence CHECK (confidence_bps IS NULL OR confidence_bps BETWEEN 0 AND 10000), + CONSTRAINT chk_purchase_spec_resolution_decision CHECK ( + (outcome='pending' AND decided_at IS NULL AND decision_source IS NULL AND chosen_candidate_id IS NULL AND resolved_options_json IS NULL) OR + (outcome='matched' AND decided_at IS NOT NULL AND decision_source IS NOT NULL AND chosen_candidate_id IS NOT NULL AND resolved_options_json IS NOT NULL AND reason IS NOT NULL) OR + (outcome IN ('uncertain','rejected','failed') AND decided_at IS NOT NULL AND chosen_candidate_id IS NULL AND resolved_options_json IS NULL AND reason IS NOT NULL)) + ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci`) + return err +} + // migrateMySQLV25 在现有档口入库码业务表上增加后台批次状态，不另建批次表。 func migrateMySQLV25(db *sql.DB) error { for _, column := range []struct{ name, ddl string }{ @@ -2185,6 +2246,7 @@ func CheckMySQLSchema(db *sql.DB) error { "ai_provider_configs", "ai_provider_audits", "ai_spec_match_decisions", "ai_match_batches", "ai_match_batch_items", + "purchase_spec_resolutions", } if err := checkMySQLSchema(db, mysqlRequiredTables); err != nil { return err @@ -2255,7 +2317,51 @@ func CheckMySQLSchema(db *sql.DB) error { if err := checkMySQLV24Shape(db); err != nil { return err } - return checkMySQLV25Shape(db) + if err := checkMySQLV25Shape(db); err != nil { + return err + } + return checkMySQLV26Shape(db) +} + +func checkMySQLV26Shape(db *sql.DB) error { + if err := checkMySQLSchema(db, []string{"purchase_spec_resolutions"}); err != nil { + return err + } + for _, name := range []string{ + "resolution_id", "task_id", "attempt_id", "client_id", "task_version", "pdd_goods_id", + "original_options_json", "selected_color", "target_size", "candidates_json", + "candidate_snapshot_hash", "request_hash", "observed_at", "outcome", "decision_source", + "chosen_candidate_id", "resolved_options_json", "confidence_bps", "reason", "provider_id", + "source_model", "config_fingerprint", "rules_version", "prompt_version", "created_at", "decided_at", + } { + exists, err := mysqlColumnExists(db, "purchase_spec_resolutions", name) + if err != nil || !exists { + return fmt.Errorf("采购运行时规格解析字段 %s 缺失: %v", name, err) + } + } + for _, item := range []struct{ kind, name string }{ + {"index", "uq_purchase_spec_resolution_identity"}, + {"index", "idx_purchase_spec_resolution_task"}, + {"index", "idx_purchase_spec_resolution_outcome"}, + {"constraint", "chk_purchase_spec_resolution_task_version"}, + {"constraint", "chk_purchase_spec_resolution_options"}, + {"constraint", "chk_purchase_spec_resolution_outcome"}, + {"constraint", "chk_purchase_spec_resolution_source"}, + {"constraint", "chk_purchase_spec_resolution_confidence"}, + {"constraint", "chk_purchase_spec_resolution_decision"}, + } { + var exists bool + var err error + if item.kind == "index" { + exists, err = mysqlIndexExists(db, "purchase_spec_resolutions", item.name) + } else { + exists, err = mysqlConstraintExists(db, "purchase_spec_resolutions", item.name) + } + if err != nil || !exists { + return fmt.Errorf("采购运行时规格解析%s %s 缺失: %v", item.kind, item.name, err) + } + } + return nil } func checkMySQLV25Shape(db *sql.DB) error { diff --git a/admin/repository/mysql_db_integration_test.go b/admin/repository/mysql_db_integration_test.go index 2dbc3f9..9fe0d09 100644 --- a/admin/repository/mysql_db_integration_test.go +++ b/admin/repository/mysql_db_integration_test.go @@ -1166,6 +1166,100 @@ func TestMySQLMigrate_V24升级V25且后台队列状态有效(t *testing.T) { } } +func TestMySQLMigrate_V25升级V26且规格解析审计幂等(t *testing.T) { + db := openMySQLMigrationTestDB(t) + defer db.Close() + cleanMySQLTestSchema(t, db) + defer cleanMySQLTestSchema(t, db) + if err := MigrateMySQL(db); err != nil { + t.Fatal(err) + } + mustExec(t, db, `DROP TABLE purchase_spec_resolutions`) + mustExec(t, db, `DELETE FROM schema_migrations WHERE version>=26`) + if err := MigrateMySQL(db); err != nil { + t.Fatalf("v25 升级 v26 失败: %v", err) + } + if err := MigrateMySQL(db); err != nil { + t.Fatalf("v26 重复迁移失败: %v", err) + } + if err := checkMySQLV26Shape(db); err != nil { + t.Fatal(err) + } + + createdAt := "2026-08-17T08:00:00Z" + resolution := model.PurchaseSpecResolution{ + ResolutionID: "PSR-1", + TaskID: "cg254", + AttemptID: "attempt-254", + ClientID: "client-254", + TaskVersion: 3, + PddGoodsID: "937122477375", + OriginalOptionsJSON: `{"color":"黑色","size":"60公斤"}`, + SelectedColor: "黑色", + TargetSize: "60公斤", + CandidatesJSON: `[{"candidate_id":"c1","raw_text":"120斤","options":{"color":"黑色","size":"120斤"}}]`, + CandidateSnapshotHash: strings.Repeat("a", 64), + RequestHash: strings.Repeat("b", 64), + ObservedAt: createdAt, + CreatedAt: createdAt, + } + if err := InsertPurchaseSpecResolution(db, resolution); err != nil { + t.Fatal(err) + } + replayed, err := GetPurchaseSpecResolutionForReplay(db, resolution.TaskID, resolution.AttemptID, + resolution.CandidateSnapshotHash, resolution.RequestHash) + if err != nil || replayed == nil || replayed.ResolutionID != resolution.ResolutionID { + t.Fatalf("相同请求未命中解析记录: resolution=%+v err=%v", replayed, err) + } + if _, err := GetPurchaseSpecResolutionForReplay(db, resolution.TaskID, resolution.AttemptID, + resolution.CandidateSnapshotHash, strings.Repeat("c", 64)); !errors.Is(err, ErrPurchaseSpecResolutionConflict) { + t.Fatalf("相同业务身份的不同请求应冲突，实际 %v", err) + } + duplicate := resolution + duplicate.ResolutionID = "PSR-2" + if err := InsertPurchaseSpecResolution(db, duplicate); !errors.Is(err, ErrPurchaseSpecResolutionExists) { + t.Fatalf("业务身份唯一键未生效，实际 %v", err) + } + + decision := model.PurchaseSpecResolutionDecision{ + ResolutionID: resolution.ResolutionID, + Outcome: model.PurchaseSpecResolutionMatched, + DecisionSource: model.PurchaseSpecResolutionAI, + ChosenCandidateID: "c1", + ResolvedOptionsJSON: `{"color":"黑色","size":"120斤"}`, + ConfidenceBPS: 9300, + ConfidenceSet: true, + Reason: "候选唯一且通过门禁", + ProviderID: "AI-1", + SourceModel: "model-1", + ConfigFingerprint: strings.Repeat("d", 64), + RulesVersion: "runtime-v1", + PromptVersion: "runtime-v1", + DecidedAt: "2026-08-17T08:00:01Z", + } + if err := CompletePurchaseSpecResolution(db, decision); err != nil { + t.Fatal(err) + } + completed, err := GetPurchaseSpecResolutionByID(db, resolution.ResolutionID) + if err != nil || completed == nil || completed.Outcome != model.PurchaseSpecResolutionMatched || + completed.DecisionSource != model.PurchaseSpecResolutionAI || !completed.ConfidenceSet || completed.ConfidenceBPS != 9300 { + t.Fatalf("解析决策读取不完整: resolution=%+v err=%v", completed, err) + } + if err := CompletePurchaseSpecResolution(db, decision); !errors.Is(err, ErrPurchaseSpecResolutionCompleted) { + t.Fatalf("已经完成的决策不应被覆盖，实际 %v", err) + } + + tooManyCandidates := resolution + tooManyCandidates.ResolutionID = "PSR-TOO-MANY" + tooManyCandidates.AttemptID = "attempt-too-many" + tooManyCandidates.CandidateSnapshotHash = strings.Repeat("e", 64) + tooManyCandidates.RequestHash = strings.Repeat("f", 64) + tooManyCandidates.CandidatesJSON = `[` + strings.TrimSuffix(strings.Repeat(`{"candidate_id":"c1"},`, 101), ",") + `]` + if err := InsertPurchaseSpecResolution(db, tooManyCandidates); err == nil { + t.Fatal("数据库必须拒绝超过 100 个候选的解析观察") + } +} + func TestUpsertInnerCodeImportRow_软删除记录按状态安全恢复(t *testing.T) { db := openMySQLMigrationTestDB(t) defer db.Close() diff --git a/admin/repository/purchase_spec_resolution.go b/admin/repository/purchase_spec_resolution.go new file mode 100644 index 0000000..1322923 --- /dev/null +++ b/admin/repository/purchase_spec_resolution.go @@ -0,0 +1,143 @@ +package repository + +import ( + "database/sql" + "errors" + "fmt" + + "github.com/go-sql-driver/mysql" + + "cmautobuy/admin/model" +) + +var ( + // ErrPurchaseSpecResolutionExists 表示解析编号或业务身份已经存在，调用方应读取旧记录复查。 + ErrPurchaseSpecResolutionExists = errors.New("采购运行时规格解析记录已存在") + // ErrPurchaseSpecResolutionConflict 表示相同业务身份对应了不同请求内容。 + ErrPurchaseSpecResolutionConflict = errors.New("采购运行时规格解析请求冲突") + // ErrPurchaseSpecResolutionNotFound 表示要完成的解析记录不存在。 + ErrPurchaseSpecResolutionNotFound = errors.New("采购运行时规格解析记录不存在") + // ErrPurchaseSpecResolutionCompleted 表示解析记录已经完成，不能覆盖第一次决策。 + ErrPurchaseSpecResolutionCompleted = errors.New("采购运行时规格解析记录已经完成") +) + +// InsertPurchaseSpecResolution 保存一次候选观察。匹配逻辑不在 Repository 中执行。 +func InsertPurchaseSpecResolution(q Execer, resolution model.PurchaseSpecResolution) error { + if resolution.Outcome == "" { + resolution.Outcome = model.PurchaseSpecResolutionPending + } + _, err := q.Exec(`INSERT INTO purchase_spec_resolutions + (resolution_id,task_id,attempt_id,client_id,task_version,pdd_goods_id, + original_options_json,selected_color,target_size,candidates_json,candidate_snapshot_hash, + request_hash,observed_at,outcome,created_at) + VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`, + resolution.ResolutionID, resolution.TaskID, resolution.AttemptID, resolution.ClientID, + resolution.TaskVersion, resolution.PddGoodsID, resolution.OriginalOptionsJSON, + resolution.SelectedColor, resolution.TargetSize, resolution.CandidatesJSON, + resolution.CandidateSnapshotHash, resolution.RequestHash, resolution.ObservedAt, + resolution.Outcome, resolution.CreatedAt) + if err == nil { + return nil + } + var mysqlErr *mysql.MySQLError + if errors.As(err, &mysqlErr) && mysqlErr.Number == 1062 { + return ErrPurchaseSpecResolutionExists + } + return fmt.Errorf("写入采购运行时规格解析观察失败: %w", err) +} + +// GetPurchaseSpecResolutionByID 按公开解析编号读取候选观察和最终决策。 +func GetPurchaseSpecResolutionByID(q Execer, resolutionID string) (*model.PurchaseSpecResolution, error) { + return scanPurchaseSpecResolution(q.QueryRow(purchaseSpecResolutionSelect+` WHERE resolution_id=?`, resolutionID)) +} + +// GetPurchaseSpecResolutionByIdentity 按任务、执行尝试和候选快照读取唯一解析记录。 +func GetPurchaseSpecResolutionByIdentity(q Execer, taskID, attemptID, candidateSnapshotHash string) (*model.PurchaseSpecResolution, error) { + return scanPurchaseSpecResolution(q.QueryRow(purchaseSpecResolutionSelect+ + ` WHERE task_id=? AND attempt_id=? AND candidate_snapshot_hash=?`, + taskID, attemptID, candidateSnapshotHash)) +} + +// GetPurchaseSpecResolutionForReplay 复查幂等重放。相同业务身份但请求哈希不同必须冲突。 +func GetPurchaseSpecResolutionForReplay(q Execer, taskID, attemptID, candidateSnapshotHash, requestHash string) (*model.PurchaseSpecResolution, error) { + resolution, err := GetPurchaseSpecResolutionByIdentity(q, taskID, attemptID, candidateSnapshotHash) + if err != nil || resolution == nil { + return resolution, err + } + if resolution.RequestHash != requestHash { + return nil, ErrPurchaseSpecResolutionConflict + } + return resolution, nil +} + +// CompletePurchaseSpecResolution 只允许把 pending 记录完成一次，保留第一次决策审计。 +func CompletePurchaseSpecResolution(q Execer, decision model.PurchaseSpecResolutionDecision) error { + result, err := q.Exec(`UPDATE purchase_spec_resolutions SET + outcome=?,decision_source=?,chosen_candidate_id=?,resolved_options_json=?,confidence_bps=?, + reason=?,provider_id=?,source_model=?,config_fingerprint=?,rules_version=?,prompt_version=?,decided_at=? + WHERE resolution_id=? AND outcome='pending'`, + decision.Outcome, nullableText(string(decision.DecisionSource)), nullableText(decision.ChosenCandidateID), + nullableText(decision.ResolvedOptionsJSON), nullableInt(decision.ConfidenceBPS, decision.ConfidenceSet), + nullableText(decision.Reason), nullableText(decision.ProviderID), nullableText(decision.SourceModel), + nullableText(decision.ConfigFingerprint), nullableText(decision.RulesVersion), nullableText(decision.PromptVersion), + decision.DecidedAt, decision.ResolutionID) + if err != nil { + return fmt.Errorf("完成采购运行时规格解析失败: %w", err) + } + affected, err := result.RowsAffected() + if err != nil { + return fmt.Errorf("读取采购运行时规格解析更新结果失败: %w", err) + } + if affected == 1 { + return nil + } + existing, err := GetPurchaseSpecResolutionByID(q, decision.ResolutionID) + if err != nil { + return err + } + if existing == nil { + return ErrPurchaseSpecResolutionNotFound + } + return ErrPurchaseSpecResolutionCompleted +} + +const purchaseSpecResolutionSelect = `SELECT + resolution_id,task_id,attempt_id,client_id,task_version,pdd_goods_id, + original_options_json,selected_color,target_size,candidates_json,candidate_snapshot_hash, + request_hash,observed_at,outcome,decision_source,chosen_candidate_id,resolved_options_json, + confidence_bps,reason,provider_id,source_model,config_fingerprint,rules_version,prompt_version, + created_at,decided_at FROM purchase_spec_resolutions` + +func scanPurchaseSpecResolution(row *sql.Row) (*model.PurchaseSpecResolution, error) { + var resolution model.PurchaseSpecResolution + var source, candidateID, resolvedOptions, reason, providerID sql.NullString + var sourceModel, configFingerprint, rulesVersion, promptVersion, decidedAt sql.NullString + var confidence sql.NullInt64 + err := row.Scan( + &resolution.ResolutionID, &resolution.TaskID, &resolution.AttemptID, &resolution.ClientID, + &resolution.TaskVersion, &resolution.PddGoodsID, &resolution.OriginalOptionsJSON, + &resolution.SelectedColor, &resolution.TargetSize, &resolution.CandidatesJSON, + &resolution.CandidateSnapshotHash, &resolution.RequestHash, &resolution.ObservedAt, + &resolution.Outcome, &source, &candidateID, &resolvedOptions, &confidence, &reason, + &providerID, &sourceModel, &configFingerprint, &rulesVersion, &promptVersion, + &resolution.CreatedAt, &decidedAt) + if errors.Is(err, sql.ErrNoRows) { + return nil, nil + } + if err != nil { + return nil, fmt.Errorf("读取采购运行时规格解析失败: %w", err) + } + resolution.DecisionSource = model.PurchaseSpecResolutionSource(source.String) + resolution.ChosenCandidateID = candidateID.String + resolution.ResolvedOptionsJSON = resolvedOptions.String + resolution.ConfidenceBPS = int(confidence.Int64) + resolution.ConfidenceSet = confidence.Valid + resolution.Reason = reason.String + resolution.ProviderID = providerID.String + resolution.SourceModel = sourceModel.String + resolution.ConfigFingerprint = configFingerprint.String + resolution.RulesVersion = rulesVersion.String + resolution.PromptVersion = promptVersion.String + resolution.DecidedAt = decidedAt.String + return &resolution, nil +} diff --git a/docs/admin/03-data-model.md b/docs/admin/03-data-model.md index 94de907..1803e46 100644 --- a/docs/admin/03-data-model.md +++ b/docs/admin/03-data-model.md @@ -127,6 +127,8 @@ v18（#208）新增 `shops` 业务店铺和 `shop_channel_aliases` 渠道名称 名称精确回填，无法确认的记录保持未关联。 v19（#212）将产品概念收敛为唯一店铺名称和唯一启停状态。迁移按“任一旧开关停用 则保持停用”的安全规则合并 v18 状态，重建由 `shops` 派生的兼容数据和两侧关联。 +v26（#254）新增 `purchase_spec_resolutions`，用一张表保存采购执行中的候选观察、 +幂等身份和最终规格决策；不修改历史 SQLite migration，也不覆盖 PDD 商品主数据。 **v3 为什么丢弃旧 `sku_mappings` 数据（见 #20）：** 新主键需要 `pdd_option_key`， 这是 Go 的 `service.OptionKey()` 用 `json.Marshal` 算出来的规范化键，SQL 语句 @@ -884,8 +886,8 @@ syb_orders ─(shopee_goods_id, spec_key)─┘ （skus_json 里是所有规格和价格） syb_orders ──创建──→ tasks ──分配──→ clients - ↑ -users（采购员）──1:N 当前归属──────────┘ + └──1:N──→ purchase_spec_resolutions +users（采购员）──1:N 当前归属──────────→ clients ``` 两条关联都可以变，这是有意的： @@ -906,6 +908,7 @@ Admin 使用集中 MySQL 8.4，Client 仍使用各自的本地 SQLite；两者 | 任务编号 | `tasks.task_id` | `pdd_tasks.remote_task_id` | | 任务状态 | 7 个（§6） | 8 个，是本机执行状态 | | 采集结果 | `pdd_products.skus_json` | `pdd_tasks.pdd_data` | +| 运行时规格解析 | `purchase_spec_resolutions` 候选观察与最终决策 | #257 在本地保存请求、幂等键和响应；原任务 payload 不覆盖 | `[必须]` **两边的状态是两套，不要试图同步。** Admin 只知道"发出去了 / 收到结果了"，中间过程看不到，这是有意的设计。 @@ -1052,3 +1055,93 @@ CREATE UNIQUE INDEX idx_client_assignment_current 不新增批次表：提交时所选 `ready` 记录必须在同一事务内全部转为 `queued`；后台每次最多 读取 20 条并逐条领取为 `applying`。页面按 `apply_batch_id` 聚合当前批次进度。Admin 重启时，`queued` 恢复为 `ready` 且不会自动写远端，`applying` 转为 `needs_check`。 + +## 18. `purchase_spec_resolutions` 采购运行时规格解析（MySQL v26） + +Client 在同一次采购中选中颜色后，如果任务尺码和 PDD 页面尺码无法精确对应，就通过 +[Client 接口契约](../client/04-admin-api-contract.md) §7.1 提交当前可购买候选。本表用 +**一条记录**同时保存候选观察、幂等身份和最终决策，不拆观察表、决策表或模型响应表。 + +```sql +CREATE TABLE purchase_spec_resolutions ( + resolution_id VARCHAR(191) COLLATE utf8mb4_bin PRIMARY KEY, + task_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL, + attempt_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL, + client_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL, + task_version BIGINT NOT NULL CHECK (task_version > 0), + pdd_goods_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL, + original_options_json JSON NOT NULL, + selected_color VARCHAR(191) NOT NULL, + target_size VARCHAR(191) NOT NULL, + candidates_json JSON NOT NULL, + candidate_snapshot_hash CHAR(64) COLLATE utf8mb4_bin NOT NULL, + request_hash CHAR(64) COLLATE utf8mb4_bin NOT NULL, + observed_at VARCHAR(35) NOT NULL, + + outcome VARCHAR(16) NOT NULL DEFAULT 'pending', + decision_source VARCHAR(16), + chosen_candidate_id VARCHAR(16) COLLATE utf8mb4_bin, + resolved_options_json JSON, + confidence_bps INT, + reason VARCHAR(500), + provider_id VARCHAR(191) COLLATE utf8mb4_bin, + source_model VARCHAR(191), + config_fingerprint CHAR(64) COLLATE utf8mb4_bin, + rules_version VARCHAR(32), + prompt_version VARCHAR(32), + created_at VARCHAR(35) NOT NULL, + decided_at VARCHAR(35), + + UNIQUE KEY uq_purchase_spec_resolution_identity + (task_id, attempt_id, candidate_snapshot_hash), + KEY idx_purchase_spec_resolution_task + (task_id, created_at DESC, resolution_id), + KEY idx_purchase_spec_resolution_outcome + (outcome, created_at, resolution_id), + CONSTRAINT chk_purchase_spec_resolution_options CHECK ( + JSON_TYPE(original_options_json) = 'OBJECT' + AND JSON_LENGTH(original_options_json) BETWEEN 1 AND 16 + AND JSON_TYPE(candidates_json) = 'ARRAY' + AND JSON_LENGTH(candidates_json) BETWEEN 1 AND 100 + AND (resolved_options_json IS NULL + OR JSON_TYPE(resolved_options_json) = 'OBJECT')), + CONSTRAINT chk_purchase_spec_resolution_outcome CHECK ( + outcome IN ('pending', 'matched', 'uncertain', 'rejected', 'failed')), + CONSTRAINT chk_purchase_spec_resolution_source CHECK ( + decision_source IS NULL OR decision_source IN ('rule', 'ai', 'reused')), + CONSTRAINT chk_purchase_spec_resolution_confidence CHECK ( + confidence_bps IS NULL OR confidence_bps BETWEEN 0 AND 10000), + CONSTRAINT chk_purchase_spec_resolution_decision CHECK ( + (outcome = 'pending' AND decided_at IS NULL + AND decision_source IS NULL AND chosen_candidate_id IS NULL + AND resolved_options_json IS NULL) + OR (outcome = 'matched' AND decided_at IS NOT NULL + AND decision_source IS NOT NULL AND chosen_candidate_id IS NOT NULL + AND resolved_options_json IS NOT NULL AND reason IS NOT NULL) + OR (outcome IN ('uncertain', 'rejected', 'failed') + AND decided_at IS NOT NULL AND chosen_candidate_id IS NULL + AND resolved_options_json IS NULL AND reason IS NOT NULL)) +); +``` + +- `(task_id, attempt_id, candidate_snapshot_hash)` 是业务唯一身份；`request_hash` 用于发现 + 同一身份改了目标尺码、候选原文或其他内容。HTTP 的 `idempotency_keys` 仍保存可安全 + 重放的完整响应，两层幂等不能互相替代。 +- `pending` 是内部恢复状态，不返回给 Client。先用短事务写候选观察，规则或 AI 调用在 + 事务外执行；最终 outcome 与 `idempotency_keys.response_body` 在另一个短事务一起提交。 + 崩溃留下 pending 时，相同请求读取原记录继续恢复，不能新建第二条。 +- `matched` 必须有来源、候选短编号、原始 options、原因和决定时间；候选必须逐字来自 + `candidates_json`。`uncertain/rejected/failed` 不得填写候选和 resolved options，避免 + Client 把不确定结果当作可点击规格。 +- `confidence_bps` 可空。NULL 表示规则或复用路径没有可比较分数，不得转换成 0；AI + 分数使用 0～10000 基点。服务商、模型、配置指纹和规则/提示版本都是非敏感快照， + 表中没有 API Key、完整提示词或完整模型响应。 +- 本表故意不设指向 `tasks` 或 `clients` 的外键。现有页面允许硬删除任务和临时 Client + 清单记录，规格决策审计不能因此阻塞原流程或被级联删除；Repository 查询始终使用稳定 + ID，不把缺少主表记录解释成新的业务状态。 +- 本表不参与任务状态机，不更新 `tasks.status/result_data`，也不写 + `pdd_products.skus_json` 或长期 `spec_mappings`。它只回答这一执行尝试在这一候选快照下 + 可以安全选择哪个原始候选。 +- `original_options_json`、`candidates_json` 和 `resolved_options_json` 只保存接口定义的 + 颜色/尺码字符串。不得保存原始无障碍 XML、截图、订单号、收货信息、Cookie、Token、 + 密码或 API Key；时间统一保存为 UTC ISO 8601。 diff --git a/docs/admin/04-client-api.md b/docs/admin/04-client-api.md index 1992bc0..88b0e38 100644 --- a/docs/admin/04-client-api.md +++ b/docs/admin/04-client-api.md @@ -8,20 +8,25 @@ 本文档中 `[必须]` / `[建议]` / `[待定]` 的含义见 [文档索引](../README.md#文档标注说明)。 -## 1. 一共四个接口 +## 1. 一共五个接口 ```http PUT /api/v1/client/registration 登记或更新 Client POST /api/v1/client/tasks/claim 领一个任务 POST /api/v1/client/tasks/{task_id}/result 提交成功结果 POST /api/v1/client/tasks/{task_id}/failure 提交失败/需人工 +POST /api/v1/client/tasks/{task_id}/spec-resolution 一次性解析当前规格候选 ``` +#254 冻结第五个接口的契约和审计模型；Handler、路由和匹配服务由 #255 实现。在 #255 +完成前，旧 Client 仍只使用原四个接口，新 Client 不得把路由尚未提供误判为可重试的 AI 失败。 + `task_id` 是不透明的稳定字符串，当前采集任务为 `cjN`、采购任务为 `cgN`。Client 必须原样保存和回传，不校验旧前缀，不从编号推导类型； 业务类型始终以响应中的 `type` 为准。 -`[必须]` **不得新增"让 Client 查询状态"类接口**，也不得加回租约和心跳。 +第五个接口只接收 Client 当下观察到的规格候选并同步返回一份持久化决策，不读取或返回 +任务调度状态。`[必须]` **不得新增“让 Client 查询状态”类接口**，也不得加回租约和心跳。 理由见 Client 契约 §1.1：本项目人工付款，重复下单只产生重复的**未付款**订单， 不值得为它引入一整套中断逻辑。 @@ -167,7 +172,7 @@ upsert clients： 实现上就是 `ON CONFLICT ... DO UPDATE SET` 里**不包含 `name`**， 不需要额外加"是否人工改过"的标记列。 -`[必须]` `result` 和 `failure` 接口**也要刷新 `last_seen_at`**。 +`[必须]` `result`、`failure` 和 `spec-resolution` 接口**也要刷新 `last_seen_at`**。 否则客户端执行长任务期间不调 claim，会被误判成离线。 新客户端直接调用 claim 时，`204` 是正常的无任务结果，Client 必须正常处理；如果已经预先分配任务，也可能首次调用就返回 `200`。 @@ -247,6 +252,52 @@ Client `SubmissionReceipt` 的统一确认字段，不能只返回 `task_status` `[必须]` §4.1 的无条件接受**同样适用于本接口**。 +### 5.1 采购运行时规格解析 + +权威 HTTP schema、长度限制、哈希算法和错误代码见 Client 契约 §7.1。Admin 侧路由为： + +```http +POST /api/v1/client/tasks/{task_id}/spec-resolution +Idempotency-Key: spec-resolution-v1: +``` + +本命令只在 Client 已进入采购规格面板、选中颜色后仍无法精确匹配任务尺码时使用。请求 +schema v1 只包含：`task_version`、`attempt_id`、`pdd_goods_id`、领取任务时的 +`original_options`、`selected_color`、`target_size`、当前颜色下 1～100 条可购买候选、 +候选快照哈希和观测时间。整个请求体最多 64 KiB。候选编号必须按页面顺序严格使用 +`c1`～`c100`，每条只保存页面原文及原始 `color/size`；禁止原始控件树和截图。 + +处理顺序： + +1. 限制请求体大小并校验 schema、字段长度、候选数量、连续短编号、原文和 options； +2. 按 Client 契约 §7.1 的长度前缀算法重新计算候选快照哈希和确定性幂等键； +3. 核对任务存在、类型为采购、版本和 PDD 商品一致，并确认 `X-Client-Id` 在 + `task_claims` 中领取过该任务；任务当前是否取消、重派或结束不作为状态查询条件； +4. 计算完整规范请求的 `request_hash`。先按 + `(task_id, attempt_id, candidate_snapshot_hash)` 复查 `purchase_spec_resolutions`： + 相同 `request_hash` 复用旧记录，不同 `request_hash` 返回 `409 IDEMPOTENCY_CONFLICT`； +5. 用短事务保存 pending 候选观察，事务外执行后续工单提供的规则/AI 服务，只允许选择 + 请求中已有候选；再用一个短事务完成解析记录并把可安全重放的响应写入 + `idempotency_keys`。Admin 崩溃留下的 pending 记录由相同请求恢复，不另建记录； +6. 返回 `200`，不更新 `tasks.status`、`tasks.result_data` 或 + `pdd_products.skus_json`，刷新 Client `last_seen_at`。 + +业务响应固定为 `matched/uncertain/rejected/failed`。只有 `matched` 返回非空 `match`， +且 `candidate_id`、`raw_text`、`options` 必须是请求候选的逐字副本；`source` 只允许 +`rule/ai/reused/null`，`confidence_bps` 为 `0～10000` 或 NULL。NULL 表示来源没有可比较 +置信度，不能当作 0。`failed` 是已落库、可幂等重放的业务结论，仍返回 HTTP 200；只有 +记录尚未落库时的基础设施故障才返回可有限重试的 `503 SPEC_RESOLUTION_UNAVAILABLE`。 + +稳定校验错误与 Client 契约保持一致：`INVALID_BODY`、 +`INVALID_SPEC_RESOLUTION_SCHEMA`、`INVALID_SPEC_RESOLUTION_REQUEST`、 +`SPEC_RESOLUTION_HASH_MISMATCH`、`TASK_NOT_FOUND`、`TASK_NOT_PURCHASE`、 +`TASK_VERSION_CONFLICT`、`PDD_GOODS_MISMATCH`、`TASK_NOT_CLAIMED_BY_CLIENT`、 +`IDEMPOTENCY_CONFLICT`。所有错误使用本文 §7 的统一 JSON 结构。 + +解析表只保存候选观察、最终决策、非敏感服务商/模型指纹和审计时间。不保存模型 API +Key、完整提示词/响应、原始 XML、订单号、收货信息、Cookie 或 Token。旧 Client 不调用 +本命令，原四个接口的路径和语义不变。本命令不提供 GET、进度查询、心跳或轮询能力。 + ## 6. 幂等怎么做 `[必须]` 建一张表记录处理过的键： @@ -264,7 +315,9 @@ CREATE TABLE idempotency_keys ( - 键相同、哈希不同 → 返回 `409 IDEMPOTENCY_CONFLICT`； - 键不存在 → 正常处理，然后连同响应一起写入，**和业务写入在同一事务**。 -不这么做的话，Client 网络超时重发就会产生两条结果。 +不这么做的话，Client 网络超时重发就会产生两条结果。规格解析还要同时依靠 +`purchase_spec_resolutions` 的业务唯一键防止换一个 HTTP 键重复决策；观察、决策和 +`idempotency_keys` 必须在同一事务收敛。 ## 7. 错误格式 @@ -318,10 +371,17 @@ Client 契约里散落的 Admin 侧硬要求，汇总在这里，**可以直接 - [ ] 采购任务的 `quantity`、`max_price_cent` 必有值，后者是人民币订单总价上限的分整数 - [ ] 可以预先指派 live 任务给可见 Client，但领取时不向只声明 `dry_run` 的客户端返回 live 任务 - [ ] `result` / `failure` 幂等：同键同内容返回同结果 +- [ ] `spec-resolution` 校验 64 KiB、schema、字段长度、1～100 候选和连续短编号 +- [ ] 重新计算候选快照哈希和确定性幂等键，不信任 Client 自报哈希 +- [ ] 相同任务、尝试、候选快照只保存一条解析记录；同内容返回首次响应，不同内容返回 `409` +- [ ] 只有 matched 返回请求内候选的逐字副本；不接受模型生成规格 +- [ ] uncertain / rejected / failed 安全停止且可幂等重放，置信度保留 NULL 语义 +- [ ] 规格解析不修改任务状态和 PDD 主数据，不提供 GET、轮询、租约或心跳 +- [ ] 规格解析审计不含原始 XML、订单、收货信息和任何凭据 - [ ] 同键不同内容返回 `409` - [ ] **任务已取消，仍接受结果** - [ ] **任务已重派，仍接受结果** - [ ] **同一任务接受多个客户端的多份结果** - [ ] 只有从未分配过的任务才返回 `403` -- [ ] `claim` / `result` / `failure` 都刷新 `last_seen_at` +- [ ] `claim` / `result` / `failure` / `spec-resolution` 都刷新 `last_seen_at` - [ ] token 不进日志 diff --git a/docs/client/03-data-model.md b/docs/client/03-data-model.md index 1b25bc9..5fde4b7 100644 --- a/docs/client/03-data-model.md +++ b/docs/client/03-data-model.md @@ -200,7 +200,7 @@ CREATE INDEX idx_pdd_tasks_visible_list |---|---| | `[必须]` 状态机没有 `pending` | 起点是 `claimed`，见 §7 | | `[必须]` 已完成任务永久保留 | `succeeded` / `failed` / `cancelled` 的记录**不删**。崩溃恢复防重复下单依赖历史记录，见 §7.3 | -| `[必须]` 本地不保存 Admin 侧状态 | Client 拿到任务就做完，中途不查 Admin 怎么想。Admin 取消了、重派了，Client 一律不感知，照做完照提交，见 [04 接口契约](04-admin-api-contract.md) §1 | +| `[必须]` 本地不保存 Admin 侧状态 | Client 拿到任务就做完，中途不查 Admin 调度状态。采购规格无法精确选择时可以提交一次候选解析命令，但它不返回取消、重派等状态，见 [04 接口契约](04-admin-api-contract.md) §1、§7.1 | | `[必须]` 提交一定会被接受 | Admin 必须无条件接受已派发过的结果，见 [04](04-admin-api-contract.md) §6.1。所以本地不需要"提交被拒"的处理分支 | **关于"永久保留"：** 任务记录不设保留期，一直留着。界面上的“删除”只写入 @@ -274,6 +274,27 @@ CREATE INDEX idx_task_runs_task `result_data` 保存这次成功采集的完整结果；`pdd_tasks.pdd_data` 只保存最新结果。 这样重新采集可以更新当前数据，同时仍能按 `attempt_no` 追查旧结果。 +### 4.1 采购运行时规格解析的持久化边界 + +[接口契约 §7.1](04-admin-api-contract.md) 定义了一个与 `task_runs.attempt_id` 绑定的一次性 +规格解析命令。Admin 的 `purchase_spec_resolutions` 是服务端候选观察和最终决策的权威 +审计；Client 本地仍必须在发送前保存以下最小信息，后续由工单 #257 增加 SQLite migration +和 Repository： + +- `task_id`（本地外键）与 `attempt_id`； +- 完整且大小受限的请求 JSON、确定性 `Idempotency-Key` 和请求哈希； +- `candidate_snapshot_hash`、Admin `resolution_id`、outcome、source、可空置信度； +- matched 时 Admin 返回的候选短编号、原始文字和 options，以及收到时间。 + +这类请求需要同步取得响应才能决定本次采购是否继续，**不能伪装成普通结果 Outbox**； +但发送前仍必须持久化，网络重试只能重放相同键和相同内容。原始 +`pdd_tasks.admin_payload`、`target_color/target_size` 永远不覆盖；解析结果只是当前 +`task_runs` 的执行期有效规格。进入过 `irreversible_action_at` 的运行不得新建或重放解析 +以继续采购，只能核对订单。 + +#254 只冻结接口和 Admin 审计模型，当前 Client SQLite schema 不在本工单改动。未实现 +#257 的旧 Client 继续按“规格不匹配即失败”运行，不调用新接口，也不会出现半持久化状态。 + ## 5. `outbox_events` 保存等待提交 Admin 的可靠事件。 @@ -369,6 +390,10 @@ def save_result_and_enqueue( ::failure-v1 # 提交失败/人工处理 ``` +运行时规格解析不进入本表的普通结果 Outbox。它的确定性键是 +`spec-resolution-v1:`，完整算法见 [接口契约 §7.1](04-admin-api-contract.md)； +#257 必须把该键和原请求保存到独立的执行期解析记录后才发送。 + ```python _KEY_SUFFIX = { "collect_result": "result-v1", diff --git a/docs/client/04-admin-api-contract.md b/docs/client/04-admin-api-contract.md index 2ae4b2c..a87ec91 100644 --- a/docs/client/04-admin-api-contract.md +++ b/docs/client/04-admin-api-contract.md @@ -12,8 +12,9 @@ **核心：Admin 是调度器，Client 是执行器，执行器不参与调度决策。** -- Client 的任务流程只有三个动作：领一个任务、提交结果、提交失败。 - 设置页另有一个幂等 Client 登记动作。**没有任何"去问 Admin 现在怎么想"的调用。** +- Client 的常规任务流程只有三个动作：领一个任务、提交结果、提交失败。 + 采购规格无法精确选择时，允许在同一次执行中额外提交一次 §7.1 规格解析命令； + 设置页另有一个幂等 Client 登记动作。**没有任何“去问 Admin 现在怎么想”的状态查询。** - Client 拿到任务就做完，中途不管任务是否被取消、是否被重派。 - Admin 负责任务的创建、更新、取消和派发（含重派），这些 Client 一律不感知。 - 结果提交必须幂等；网络重试不能创建重复结果。 @@ -43,7 +44,7 @@ X-Request-Id: Content-Type: application/json ``` -结果和失败提交额外携带： +结果、失败和运行时规格解析提交额外携带： ```http Idempotency-Key: @@ -410,9 +411,153 @@ Idempotency-Key: task-id:attempt-id:failure-v1 - `[必须]` §6.1 的无条件接受规则同样适用于本接口。 - `[必须]` Admin 决定是否创建新的执行机会，但对已经可能下单的任务不得通过普通重试触发再次购买。 +### 7.1 采购运行时规格解析命令 + +“运行时规格解析”是指：Client 已经打开当前 PDD 商品并选中颜色，但任务目标尺码 +无法与页面上的可购买尺码精确对应时，把这一刻的候选快照交给 Admin 做一次受审计的 +规格决策。它是**一次性 POST 业务命令**，不是任务状态查询、心跳或轮询；Client 不得 +用它询问任务是否取消、是否重派或 AI 是否完成。 + +```http +POST /api/v1/client/tasks/{task_id}/spec-resolution +Idempotency-Key: spec-resolution-v1: +``` + +请求体 schema v1： + +```json +{ + "schema_version": 1, + "task_version": 3, + "attempt_id": "attempt-uuid", + "pdd_goods_id": "937122477375", + "original_options": {"color": "黑色", "size": "60公斤"}, + "selected_color": "黑色", + "target_size": "60公斤", + "candidates": [ + { + "candidate_id": "c1", + "raw_text": "120斤", + "options": {"color": "黑色", "size": "120斤"} + }, + { + "candidate_id": "c2", + "raw_text": "130斤", + "options": {"color": "黑色", "size": "130斤"} + } + ], + "candidate_snapshot_hash": "64位小写十六进制 SHA-256", + "observed_at": "2026-08-17T08:00:00Z" +} +``` + +字段和大小限制： + +| 字段 | 规则 | +|---|---| +| 整个 JSON 请求体 | UTF-8 编码后最多 64 KiB；未知字段允许忽略但不得改变已知字段含义 | +| `schema_version` | v1 固定为 `1`；未知主版本拒绝，不猜测兼容 | +| `task_version` | 正整数，必须等于领取到的任务版本 | +| `attempt_id` | 1～191 个字符，同一次 `task_runs` 执行稳定复用 | +| `pdd_goods_id` | 1～191 个字符，必须等于任务商品 | +| `original_options` | 1～16 个字符串键值；键和值各 1～191 个字符，保持领取任务时的动态规格原文 | +| `selected_color` / `target_size` | 各 1～191 个字符，不允许控制字符 | +| `candidates` | 1～100 条，只提交当前颜色下页面显示为可购买的尺码，保持页面顺序 | +| `candidate_id` | 严格按数组顺序使用 `c1`、`c2` … `c100`，不得跳号或重复 | +| `raw_text` | PDD 页面原始尺码文字，1～191 个字符，不允许控制字符 | +| `options` | v1 只含非空 `color`、`size`；`color` 必须等于 `selected_color`，`size` 必须逐字等于 `raw_text` | +| `candidate_snapshot_hash` | 按下述算法计算的 64 位小写十六进制 SHA-256 | +| `observed_at` | 带时区 ISO 8601；推荐 UTC | + +候选短编号由 Client 按页面顺序生成，Admin 必须逐项验证编号、原文和 options，不能 +接受模型自行增加、改写或重新编号后的规格。快照哈希使用长度前缀，避免分隔符碰撞： + +```text +frame(value) = UTF-8 字节长度的十进制文本 + ":" + value +material = frame("spec-resolution-v1") + + frame(pdd_goods_id) + + frame(selected_color) + + frame(候选数量的十进制文本) + + 依页面顺序为每条候选追加： + frame(candidate_id) + frame(raw_text) + + frame(options.color) + frame(options.size) +candidate_snapshot_hash = lowercase_hex(sha256(UTF-8(material))) +``` + +幂等键同样是确定值，不直接拼接可能很长的任务编号： + +```text +identity_material = frame(task_id) + frame(attempt_id) + + frame(candidate_snapshot_hash) + frame("spec-resolution-v1") +Idempotency-Key = "spec-resolution-v1:" + lowercase_hex(sha256(UTF-8(identity_material))) +``` + +Admin 必须重新计算两个哈希。相同业务身份 +`task_id + attempt_id + candidate_snapshot_hash` 只对应一条解析记录；相同键和相同内容 +返回第一次保存的完整响应，相同键或相同业务身份携带不同内容返回 +`409 IDEMPOTENCY_CONFLICT`。网络超时可以用原键和原请求重放，但 Client 不得修改内容后 +沿用旧键，也不得循环请求等待结果。 + +成功处理统一返回 `200 OK`。`failed` 是已经持久化的业务结论，不是 HTTP 500： + +```json +{ + "schema_version": 1, + "resolution_id": "psr-uuid", + "outcome": "matched", + "source": "ai", + "candidate_snapshot_hash": "请求中的同一哈希", + "match": { + "candidate_id": "c1", + "raw_text": "120斤", + "options": {"color": "黑色", "size": "120斤"} + }, + "confidence_bps": 9300, + "reason": "目标重量与候选范围唯一对应", + "resolved_at": "2026-08-17T08:00:01Z" +} +``` + +| `outcome` | 含义 | `match` | +|---|---|---| +| `matched` | 规则、AI 或历史解析得到唯一且通过服务端门禁的请求内候选 | 必须是请求候选的逐字副本 | +| `uncertain` | 有分析结果，但不能唯一、安全地选中一个候选 | `null` | +| `rejected` | 请求结构有效，但业务规则明确拒绝自动选择 | `null` | +| `failed` | 解析服务超时、格式错误或其他已审计失败 | `null` | + +`source` 只允许 `rule`、`ai`、`reused` 或 `null`；`confidence_bps` 为 `0～10000` +整数或 `null`，`null` 表示该来源没有可比较的置信度，不能当作 0。`reason` 最多 500 +个字符。只有 `matched` 可以返回非空 `match`，其编号、原文和 options 必须逐字来自 +本次请求；响应不得包含模型生成的新规格。Client 仍须在继续前重新读取页面、复算快照并 +精确核对，不能因为 Admin 返回 matched 就跳过既有数量、总价、地址、不可逆标记和单次 +提交门禁。 + +稳定错误至少包括： + +| HTTP | `error.code` | 场景 | +|---|---|---| +| `400` | `INVALID_BODY` | 非法 JSON 或请求体超过 64 KiB | +| `400` | `INVALID_SPEC_RESOLUTION_SCHEMA` | `schema_version` 不支持 | +| `422` | `INVALID_SPEC_RESOLUTION_REQUEST` | 字段长度、候选数量、候选编号或 options 无效 | +| `422` | `SPEC_RESOLUTION_HASH_MISMATCH` | 快照哈希或确定性幂等键与字段不一致 | +| `404` | `TASK_NOT_FOUND` | 任务不存在 | +| `422` | `TASK_NOT_PURCHASE` | 不是采购任务 | +| `409` | `TASK_VERSION_CONFLICT` | 请求任务版本与已领取版本不一致 | +| `422` | `PDD_GOODS_MISMATCH` | PDD 商品 ID 与任务不一致 | +| `403` | `TASK_NOT_CLAIMED_BY_CLIENT` | 该 Client 从未领取过此任务 | +| `409` | `IDEMPOTENCY_CONFLICT` | 相同幂等身份提交了不同内容 | +| `503` | `SPEC_RESOLUTION_UNAVAILABLE` | 在解析记录落库前 Admin 暂不可用，可有限重试原请求 | + +任务已取消、重派或结束本身不是本命令的查询条件；只要该 Client 曾领取任务且任务身份 +仍能核对，Admin 可以保存解析审计，但**不得修改任务状态**。候选观察先用短事务持久化； +规则/AI 调用不得占用数据库事务，最终决策和安全重放响应必须与 `idempotency_keys` 在同一 +短事务提交。该记录不得覆盖 `pdd_products.skus_json`，也不得 +保存原始无障碍 XML、截图、订单号、收货信息、Cookie、Token 或 API Key。旧 Client 不 +调用本接口，继续按“规格不匹配即提交失败”的既有流程运行。 + ## 8. 幂等与重试 -- `[必须]` 结果和失败提交必须使用持久化的 `Idempotency-Key`，格式见 [03 数据模型](03-data-model.md) §5.2。 +- `[必须]` 结果、失败和运行时规格解析提交必须使用持久化的 `Idempotency-Key`；前两者格式见 [03 数据模型](03-data-model.md) §5.2，规格解析格式见 §7.1。 - `[必须]` Client 在发送前将完整请求写入 Outbox；重试使用相同键和相同内容。 - `[必须]` `claim` 需要 Admin 保证重复请求不会一次分配出多个任务。 - `[建议]` 对 `429`、`500` 和 `503` 使用有上限的指数退避，并遵守 `Retry-After`。 @@ -420,13 +565,14 @@ Idempotency-Key: task-id:attempt-id:failure-v1 ## 9. Mock Admin 要求 -`MockAdminGateway` 与 HTTP 实现暴露同一应用层接口。登记和三个任务方法都必须使用同一契约： +`MockAdminGateway` 与 HTTP 实现暴露同一应用层接口。登记、三个常规任务方法和一次性规格解析命令都必须使用同一契约： ```text register_client(client, capabilities) # §4.1 claim_next(client, capabilities) # §5 submit_result(task_id, idempotency_key, result) # §6 submit_failure(task_id, idempotency_key, failure) # §7 +resolve_purchase_spec(task_id, idempotency_key, observation) # §7.1 ``` Mock 必须支持： @@ -436,6 +582,7 @@ Mock 必须支持： - 网络超时和暂时故障； - 幂等重复提交（相同键相同内容）； - 幂等冲突（相同键不同内容）； +- 规格解析的 matched / uncertain / rejected / failed，以及候选哈希不一致； - **提交一个 Admin 侧已取消的任务，仍返回 `accepted: true`**（用来验证 §6.1）； - 结果校验失败。 @@ -457,7 +604,9 @@ Mock 测试通过不能替代与真实 Admin 的契约测试。 - 任务分「指定分配」和「无主」两种，`claim` 两种都返回，指定的优先。 采集任务不指定，采购任务可指定可留空。Client 不读全局任务池。见 §5.1。 -- **没有租约、没有心跳、没有状态回查。** 任务流程只有 §5 / §6 / §7 三个调用；设置页另有 §4.1 的幂等登记调用。 +- **没有租约、没有心跳、没有状态回查。** 常规任务流程仍是 §5 / §6 / §7； + §7.1 只是在同一次采购规格无法精确选择时提交候选并同步取得持久化决策，设置页另有 + §4.1 的幂等登记调用。 - Admin 必须无条件接受已派发过的 Client 提交的结果。见 §6.1。 改动这张表里任何一条，都属于会影响业务结果的变更，必须先更新工单并经用户确认。