From 290a17ea1525a5b6fa10a545a0f246a5566d91a3 Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Tue, 8 Sep 2026 14:41:56 +0800 Subject: [PATCH 1/4] feat(purchase): add agent order backfill endpoint (#241) --- docs/08-agent-api-contract.md | 73 +++ server/app/goauto/models/purchase.go | 10 +- .../app/goauto/models/purchase_order_guard.go | 30 ++ server/app/goauto/purchase/order_backfill.go | 202 ++++++++ .../goauto/purchase/order_backfill_handler.go | 25 + .../goauto/purchase/order_backfill_test.go | 474 ++++++++++++++++++ server/app/goauto/purchase/router.go | 1 + .../purchasecontract/address_suffix_test.go | 17 + .../app/goauto/purchasecontract/contract.go | 13 + 9 files changed, 844 insertions(+), 1 deletion(-) create mode 100644 server/app/goauto/models/purchase_order_guard.go create mode 100644 server/app/goauto/purchase/order_backfill.go create mode 100644 server/app/goauto/purchase/order_backfill_handler.go create mode 100644 server/app/goauto/purchase/order_backfill_test.go create mode 100644 server/app/goauto/purchasecontract/address_suffix_test.go diff --git a/docs/08-agent-api-contract.md b/docs/08-agent-api-contract.md index 6db704d..59c1323 100644 --- a/docs/08-agent-api-contract.md +++ b/docs/08-agent-api-contract.md @@ -985,3 +985,76 @@ Agent 携带既有 Token（可已失效）及恢复码重新调用注册接口 `orderCount` 是已验证页的原始列表读取数量；`detailCount`、`created`、`updated` 为已提交明细及其新增/覆盖数量；`daysProcessed` 是完整通过的日期数，不是已尝试日期数。失败日期/页码/阶段写入现有脱敏限长 errorMessage。部分成功不刷新店铺的完整同步统计。 Web 唯一展示位置为“采集采购 → SYB 同步记录”：列表状态、状态筛选及详情支持部分成功，详情保留已保存数量、错误原因与重新同步补齐提示。定时任务日志只表示异步任务受理，不等于最终业务同步成功。 + +## Agent 采购订单批量回填（#241） + +本节为 #241 服务端实现契约，2026-09-08 按用户授权直接更新本地镜像；线上 Wiki 与其他长期文档由审核阶段同步。本节不表示已经部署或完成真机验收。 + +`POST /api/agent/v1/purchase-tasks/order-backfill` + +使用 `Authorization: Bearer `，沿用 `RequireAgentHTTPS`、`GOAUTO_ALLOW_INSECURE_AGENT_HTTP` 与既有可信转发协议策略。无需 Admin JWT、claim、start 或 attempt。设备号只从认证读取，请求不得指定 deviceId、地址全文、收件人、手机号或原始控件树；未知 JSON 字段拒绝。此接口只记录已观察到的订单事实，不执行设备动作、创建订单或付款。 + +请求示例（页面时间先按 Asia/Shanghai 理解，再以带时区 RFC3339/RFC3339Nano 发送）： + +```json +{ + "requestId": "5826cdda-dcd6-442e-90c3-9b75ba6fb8d8", + "items": [ + {"addressSuffix": "_cg7", "pddOrderNo": "EXAMPLE-ORDER-7", "orderSubmittedAt": "2026-09-08T20:30:00+08:00"}, + {"addressSuffix": "_cg72", "pddOrderNo": "EXAMPLE-ORDER-72"} + ] +} +``` + +- requestId 必须为 UUID；items 为 1～50 条，保持输入顺序；请求体上限沿用 1 MiB。 +- addressSuffix 只接受 `AddressSuffix(id)` 生成的完整字符串。任务号为非零 uint64，拒绝前导零、正负号、空格、尾随文本、多个后缀与溢出；`_cg7` 与 `_cg72` 分别定位任务 7 和 72。 +- pddOrderNo 必填，最多 100 个 Unicode 字符，不接受首尾空白、换行或制表符，不自动裁剪后覆盖旧值。 +- orderSubmittedAt 缺失或 null 时回落任务 irreversible_at；空字符串、无时区文本及非法时间是条目错误，不触发回落。存储统一 UTC。页面值与 irreversible_at 都缺失时该条失败。 + +有效批次返回 HTTP 200，包括全部条目失败的批次；每条独立事务，失败不撤销其他条目已提交的数据。响应包裹为 `data`，并设 `Cache-Control: no-store`： + +```json +{ + "data": { + "requestId": "5826cdda-dcd6-442e-90c3-9b75ba6fb8d8", + "items": [ + {"index": 0, "taskId": 7, "result": "backfilled", "code": "BACKFILLED", "status": "order_created", "statusVersion": 5, "pddOrderNo": "EXAMPLE-ORDER-7", "orderSubmittedAt": "2026-09-08T12:30:00Z", "timeSource": "page", "retryable": false}, + {"index": 1, "taskId": 72, "result": "backfilled", "code": "BACKFILLED", "status": "order_created", "statusVersion": 4, "pddOrderNo": "EXAMPLE-ORDER-72", "orderSubmittedAt": "2026-09-08T12:31:00Z", "timeSource": "irreversible_at", "retryable": false} + ] + } +} +``` + +index 从 0 开始；后缀无法解析时不返回 taskId。result 为 `backfilled`、`already_backfilled`、`conflict` 或 `failed`。已认证设备所属任务可返回提交后的状态、版本、已保存订单号及时间；拒绝条目尽可能返回当前已提交事实。跨设备任务和不存在任务不返回这些业务字段，事务回滚后的内存值绝不作为最终事实返回。 + +timeSource 说明已保存时间的来源：`page` 为页面值，`irreversible_at` 为估算回落，`existing_unknown` 为原先已创建的历史订单且没有可证明的来源。没有已保存时间时省略 timeSource。客户端必须保留估算标记，不得把回落值或 unknown 宣称为页面真实时间。重复回填不会用新页面时间自动校正旧时间。 + +| 条目 code | result | 含义 | +|---|---|---| +| `BACKFILLED` | backfilled | 本条完成回填 | +| `ALREADY_BACKFILLED` | already_backfilled | 正式任务已为 order_created 且订单号相同，无写入 | +| `PURCHASE_BACKFILL_SUFFIX_INVALID` | failed | 非法、非规范、零、溢出或歧义后缀 | +| `PURCHASE_TASK_NOT_FOUND` | failed | 任务不存在 | +| `PURCHASE_BACKFILL_DEVICE_MISMATCH` | failed | 未绑定设备或不属于认证设备 | +| `PURCHASE_STATE_CONFLICT` | failed | 非正式采购，或状态不允许回填 | +| `PURCHASE_INVALID_REQUEST` | failed | 订单号非法 | +| `PURCHASE_ORDER_TIME_INVALID` | failed | 提供的页面时间无效 | +| `PURCHASE_ORDER_TIME_MISSING` | failed | 页面时间与 irreversible_at 均无有效值 | +| `PURCHASE_BACKFILL_ORDER_CONFLICT` | conflict | 任务已有不同订单号 | +| `PURCHASE_BACKFILL_BATCH_CONFLICT` | conflict | 同批同任务出现多个不同订单号，该任务所有条目均拒绝 | +| `PURCHASE_BACKFILL_ORDER_ALREADY_USED` | conflict | 同一订单号已对应其他任务 | +| `INTERNAL_ERROR` | failed | 数据库失败、死锁等，retryable=true，可安全重放 | + +批级 JSON/UUID/数量错误为 HTTP 422 `PURCHASE_INVALID_REQUEST`；鉴权、停用设备和 HTTPS 限制复用既有错误（401 `DEVICE_TOKEN_INVALID`、403 `DEVICE_DISABLED`、426 `HTTPS_REQUIRED`）。批级失败使用既有 `{code,message,retryable}` 包裹，未开始条目写入。 + +### 状态、幂等与并发 + +新服务在事务中锁定任务并检查来源状态，仅允许当前设备的 `live + order_result_unknown` 首次写入；`live + order_created` 只在订单号相同时返回已回填。其他状态（包括 running、failed、cancelled 与演练）均拒绝。复用 SetStatus 同步占用字段，同一事务递增 statusVersion、设置 statusChangedAt、清空主任务当前错误及租约；原始 attempt、规则快照、支付与物流、SYB 回写字段不变。 + +requestId 沿用 UUID 约定，不增加批次表或全局幂等缓存。既有 unknown_resolve_request_id 槽存储 `backfill::<由 requestId 和后缀派生的 UUID>`（最多 61 字符），用于任务级关联和保留本功能时间来源。相同任务和订单号即使更换 requestId 也无写入；同 requestId 改内容仍重新执行设备、状态和订单冲突检查，不凭 requestId 直接放行。批内不同任务提交同一订单号时，先成功提交者占用，其余条目返回订单已被使用；已存在的历史重复订单号不自动修复。 + +订单号尚无唯一索引，本实现不迁移数据库。共享模型保存钩子复用 `purchase_rule_setting.id=1` 行作短事务互斥锁，再以锁定读检查订单号归属，覆盖回填、原人工解除和旧结果提交路径；单例缺失时拒绝写入，数据库死锁时回滚失败事务。原 ResolveUnknown 与 Admin 鉴权代码保持不变。禁止通过跳过模型钩子的直接 SQL 写入宣称具备此保证。 + +新回填路径禁用包含绑定参数的 SQL 日志，不记录请求正文、订单号、地址或原始树；任务号和认证设备号沿既有任务关联不可变 ruleSnapshot。此接口未新增日志载荷或任务/attempt。 + +本地测试覆盖事务回滚、并发服务调用和旧写入路径，使用 SQLite；MySQL 8.4 多连接/多进程的实际行锁、生产数据和真机端到端回填尚待环境验收，不以单元测试替代。 diff --git a/server/app/goauto/models/purchase.go b/server/app/goauto/models/purchase.go index 2d0c5dd..bee8fb5 100644 --- a/server/app/goauto/models/purchase.go +++ b/server/app/goauto/models/purchase.go @@ -202,7 +202,15 @@ func (task *PurchaseTask) BeforeCreate(_ *gorm.DB) error { return task.syncPurchaseGuardSlots() } -func (task *PurchaseTask) BeforeSave(_ *gorm.DB) error { return task.syncPurchaseGuardSlots() } +func (task *PurchaseTask) BeforeSave(tx *gorm.DB) error { + if err := task.syncPurchaseGuardSlots(); err != nil { + return err + } + if task.PDDOrderNo != nil && *task.PDDOrderNo != "" { + return CheckPurchaseOrderNumber(tx, task.ID, *task.PDDOrderNo) + } + return nil +} func (task *PurchaseTask) SetStatus(status string) error { task.Status = status diff --git a/server/app/goauto/models/purchase_order_guard.go b/server/app/goauto/models/purchase_order_guard.go new file mode 100644 index 0000000..5e9f7ee --- /dev/null +++ b/server/app/goauto/models/purchase_order_guard.go @@ -0,0 +1,30 @@ +package models + +import ( + "errors" + + "gorm.io/gorm" + "gorm.io/gorm/clause" +) + +var ErrPurchaseOrderNumberUsed = errors.New("purchase order number belongs to another task") + +// CheckPurchaseOrderNumber must run inside the caller's write transaction. +// The existing singleton setting row serializes order assignments across +// processes, including an absent order number, without relying on gap locks or +// a new schema constraint. Locking reads see the latest committed assignment. +// A missing singleton fails closed. Deadlocks roll back the losing transaction. +func CheckPurchaseOrderNumber(tx *gorm.DB, taskID uint64, orderNo string) error { + var setting PurchaseRuleSetting + if err := tx.Session(&gorm.Session{NewDB: true}).Clauses(clause.Locking{Strength: "UPDATE"}).First(&setting, 1).Error; err != nil { + return err + } + var others []PurchaseTask + if err := tx.Session(&gorm.Session{NewDB: true}).Select("id").Clauses(clause.Locking{Strength: "UPDATE"}).Where("pdd_order_no = ? AND id <> ?", orderNo, taskID).Find(&others).Error; err != nil { + return err + } + if len(others) != 0 { + return ErrPurchaseOrderNumberUsed + } + return nil +} diff --git a/server/app/goauto/purchase/order_backfill.go b/server/app/goauto/purchase/order_backfill.go new file mode 100644 index 0000000..fa4072d --- /dev/null +++ b/server/app/goauto/purchase/order_backfill.go @@ -0,0 +1,202 @@ +package purchase + +import ( + "context" + "errors" + "strings" + "time" + "unicode/utf8" + + "go-admin/app/goauto/device" + "go-admin/app/goauto/models" + "go-admin/app/goauto/purchasecontract" + + "github.com/google/uuid" + "gorm.io/gorm" + "gorm.io/gorm/clause" + "gorm.io/gorm/logger" +) + +const ( + MaxOrderBackfillItems = 50 + CodeBackfillSuffix = "PURCHASE_BACKFILL_SUFFIX_INVALID" + CodeBackfillDevice = "PURCHASE_BACKFILL_DEVICE_MISMATCH" + CodeBackfillOrderConflict = "PURCHASE_BACKFILL_ORDER_CONFLICT" + CodeBackfillBatchConflict = "PURCHASE_BACKFILL_BATCH_CONFLICT" + CodeBackfillOrderUsed = "PURCHASE_BACKFILL_ORDER_ALREADY_USED" +) + +type OrderBackfillRequest struct { + RequestID string `json:"requestId"` + Items []OrderBackfillItem `json:"items"` +} + +type OrderBackfillItem struct { + AddressSuffix string `json:"addressSuffix"` + PDDOrderNo string `json:"pddOrderNo"` + // A string keeps an invalid page timestamp local to this item. + OrderSubmittedAt *string `json:"orderSubmittedAt,omitempty"` +} + +type OrderBackfillResult struct { + Index int `json:"index"` + TaskID uint64 `json:"taskId,omitempty"` + Result string `json:"result"` + Code string `json:"code"` + Status string `json:"status,omitempty"` + StatusVersion uint64 `json:"statusVersion,omitempty"` + PDDOrderNo *string `json:"pddOrderNo,omitempty"` + OrderSubmittedAt *time.Time `json:"orderSubmittedAt,omitempty"` + TimeSource string `json:"timeSource,omitempty"` + Retryable bool `json:"retryable"` +} + +type OrderBackfillResponse struct { + RequestID string `json:"requestId"` + Items []OrderBackfillResult `json:"items"` +} + +func (s *Service) BackfillOrders(ctx context.Context, req OrderBackfillRequest, token string) (OrderBackfillResponse, error) { + out := OrderBackfillResponse{RequestID: req.RequestID} + d, err := device.NewService(s.DB).Authenticate(ctx, token) + if err != nil { + return out, err + } + if _, err := uuid.Parse(req.RequestID); err != nil || len(req.Items) == 0 || len(req.Items) > MaxOrderBackfillItems { + return out, fail(CodeInvalidRequest, "requestId 必须为 UUID，items 必须包含 1 到 50 条") + } + ids := make([]uint64, len(req.Items)) + orders := make(map[uint64]string) + conflicts := make(map[uint64]bool) + for i, item := range req.Items { + id, err := purchasecontract.ParseAddressSuffix(item.AddressSuffix) + if err != nil { + continue + } + ids[i] = id + if previous, ok := orders[id]; ok && previous != item.PDDOrderNo { + conflicts[id] = true + } + orders[id] = item.PDDOrderNo + } + out.Items = make([]OrderBackfillResult, len(req.Items)) + for i, item := range req.Items { + r := OrderBackfillResult{Index: i, TaskID: ids[i], Result: "failed"} + if ids[i] == 0 { + r.Code = CodeBackfillSuffix + } else { + r = s.backfillOrder(ctx, d.ID, ids[i], req.RequestID, item, conflicts[ids[i]]) + r.Index = i + } + out.Items[i] = r + } + return out, nil +} + +func (s *Service) backfillOrder(ctx context.Context, deviceID, taskID uint64, requestID string, item OrderBackfillItem, batchConflict bool) OrderBackfillResult { + r := OrderBackfillResult{TaskID: taskID, Result: "failed"} + var task models.PurchaseTask + // SQL errors must not print bound order numbers or the task's address snapshot. + db := s.DB.Session(&gorm.Session{Logger: logger.Default.LogMode(logger.Silent)}).WithContext(ctx) + err := db.Transaction(func(tx *gorm.DB) error { + if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&task, taskID).Error; err != nil { + return purchaseNotFound(err) + } + if task.DeviceID == nil || *task.DeviceID != deviceID { + return fail(CodeBackfillDevice, "任务不属于当前设备") + } + if batchConflict { + return fail(CodeBackfillBatchConflict, "同批任务有不同订单号") + } + if task.ExecutionMode != models.PurchaseExecutionModeLive || (task.Status != models.PurchaseTaskStatusOrderResultUnknown && task.Status != models.PurchaseTaskStatusOrderCreated) { + return fail(CodeStateConflict, "当前任务不允许回填") + } + if item.PDDOrderNo == "" || strings.TrimSpace(item.PDDOrderNo) != item.PDDOrderNo || utf8.RuneCountInString(item.PDDOrderNo) > 100 || strings.ContainsAny(item.PDDOrderNo, "\r\n\t") { + return fail(CodeInvalidRequest, "订单号无效") + } + if task.PDDOrderNo != nil && *task.PDDOrderNo != "" && *task.PDDOrderNo != item.PDDOrderNo { + return fail(CodeBackfillOrderConflict, "已有不同订单号") + } + // The shared model guard also protects manual resolution and late results. + if err := models.CheckPurchaseOrderNumber(tx, taskID, item.PDDOrderNo); err != nil { + return err + } + if task.Status == models.PurchaseTaskStatusOrderCreated { + if task.PDDOrderNo == nil || *task.PDDOrderNo != item.PDDOrderNo { + return fail(CodeStateConflict, "已创建订单缺少匹配订单号") + } + r.Result, r.Code = "already_backfilled", "ALREADY_BACKFILLED" + return nil + } + var submitted time.Time + source := "page" + if item.OrderSubmittedAt != nil { + var err error + submitted, err = time.Parse(time.RFC3339Nano, *item.OrderSubmittedAt) + if err != nil || submitted.IsZero() || submitted.Year() < 1000 || submitted.Year() > 9999 { + return fail(CodeOrderTimeInvalid, "下单时间必须为 RFC3339") + } + } else { + if task.IrreversibleAt == nil || task.IrreversibleAt.IsZero() { + return fail(CodeOrderTimeMissing, "下单时间和不可逆时间均缺失") + } + submitted, source = *task.IrreversibleAt, "irreversible_at" + } + submitted = submitted.UTC() + task.PDDOrderNo, task.OrderSubmittedAt = &item.PDDOrderNo, &submitted + if err := task.SetStatus(models.PurchaseTaskStatusOrderCreated); err != nil { + return internal(err) + } + task.StatusVersion++ + task.StatusChangedAt = s.Now() + task.ErrorCode, task.ErrorMessage = nil, nil + task.LeaseExpiresAt = nil + // Reuse the existing resolution request slot. Scope a batch UUID to a + // task, and retain provenance without a schema change or replay cache. + marker := "backfill:" + source + ":" + uuid.NewSHA1(uuid.NameSpaceOID, []byte(requestID+":"+item.AddressSuffix)).String() + task.UnknownResolveRequestID = &marker + if err := tx.Save(&task).Error; err != nil { + return err + } + r.Result, r.Code = "backfilled", "BACKFILLED" + return nil + }) + if err != nil { + r.Result, r.Code = "failed", CodeInternal + r.Retryable = true + var se *ServiceError + if errors.As(err, &se) { + r.Code, r.Retryable = se.Code, se.Retryable + } + if errors.Is(err, models.ErrPurchaseOrderNumberUsed) { + r.Code, r.Retryable = CodeBackfillOrderUsed, false + } + if r.Code == CodeBackfillBatchConflict || r.Code == CodeBackfillOrderConflict || r.Code == CodeBackfillOrderUsed { + r.Result = "conflict" + } + } + // Return only this device's committed facts, including on a rejected item. + // Never return in-memory changes from a rolled back transaction. + saved := task + readable := err == nil + if !readable { + saved = models.PurchaseTask{} + readable = db.Where("id = ? AND device_id = ?", taskID, deviceID).First(&saved).Error == nil + } + if readable { + r.Status, r.StatusVersion = saved.Status, saved.StatusVersion + r.PDDOrderNo, r.OrderSubmittedAt = saved.PDDOrderNo, saved.OrderSubmittedAt + if saved.OrderSubmittedAt != nil { + r.TimeSource = "existing_unknown" + if saved.UnknownResolveRequestID != nil { + if strings.HasPrefix(*saved.UnknownResolveRequestID, "backfill:page:") { + r.TimeSource = "page" + } + if strings.HasPrefix(*saved.UnknownResolveRequestID, "backfill:irreversible_at:") { + r.TimeSource = "irreversible_at" + } + } + } + } + return r +} diff --git a/server/app/goauto/purchase/order_backfill_handler.go b/server/app/goauto/purchase/order_backfill_handler.go new file mode 100644 index 0000000..66529ea --- /dev/null +++ b/server/app/goauto/purchase/order_backfill_handler.go @@ -0,0 +1,25 @@ +package purchase + +import ( + "net/http" + + "github.com/gin-gonic/gin" +) + +func (h Handler) BackfillOrders(c *gin.Context) { + var req OrderBackfillRequest + if !decode(c, &req) { + return + } + s, ok := h.service(c) + if !ok { + return + } + out, err := s.BackfillOrders(c.Request.Context(), req, bearer(c.GetHeader("Authorization"))) + if err != nil { + writeError(c, err) + return + } + c.Header("Cache-Control", "no-store") + c.JSON(http.StatusOK, gin.H{"data": out}) +} diff --git a/server/app/goauto/purchase/order_backfill_test.go b/server/app/goauto/purchase/order_backfill_test.go new file mode 100644 index 0000000..4717a6d --- /dev/null +++ b/server/app/goauto/purchase/order_backfill_test.go @@ -0,0 +1,474 @@ +package purchase + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "reflect" + "strings" + "sync" + "testing" + "time" + + "go-admin/app/goauto/device" + "go-admin/app/goauto/models" + "go-admin/app/goauto/purchasecontract" + + "github.com/gin-gonic/gin" + "github.com/google/uuid" + "gorm.io/gorm" +) + +func backfillTask(t *testing.T, db *gorm.DB, f fixture, status string) models.PurchaseTask { + t.Helper() + now := testService(db).Now() + task := models.PurchaseTask{TaskType: models.PurchaseTaskTypeStock, ExecutionMode: models.PurchaseExecutionModeLive, + Status: status, DeviceID: &f.device.ID, PDDProductID: f.pdd.ID, Quantity: 1, Currency: "CNY", + CreateRequestID: uuid.NewString(), RuleSnapshot: string(purchasecontract.DefaultLiveRule()), + SpecDecisionSnapshot: `{}`, RequiredCapabilitiesJSON: `[]`, IrreversibleAt: &now, + ErrorCode: strptr("ORIGINAL_ERROR"), ErrorMessage: strptr("original failure")} + if err := db.Create(&task).Error; err != nil { + t.Fatal(err) + } + return task +} + +func strptr(s string) *string { return &s } + +func backfillItem(id uint64, order string) OrderBackfillItem { + return OrderBackfillItem{AddressSuffix: purchasecontract.AddressSuffix(id), PDDOrderNo: order} +} + +func runBackfill(t *testing.T, s *Service, token, requestID string, items ...OrderBackfillItem) []OrderBackfillResult { + t.Helper() + out, err := s.BackfillOrders(context.Background(), OrderBackfillRequest{RequestID: requestID, Items: items}, token) + if err != nil { + t.Fatal(err) + } + if len(out.Items) != len(items) || out.RequestID != requestID { + t.Fatalf("bad envelope: %+v", out) + } + return out.Items +} + +func loadBackfillTask(t *testing.T, db *gorm.DB, id uint64) models.PurchaseTask { + t.Helper() + var task models.PurchaseTask + if err := db.First(&task, id).Error; err != nil { + t.Fatal(err) + } + return task +} + +func TestOrderBackfillMixedBatchAndReplay(t *testing.T) { + db := testDB(t) + f := seed(t, db, liveCaps(), true) + s := testService(db) + a := backfillTask(t, db, f, models.PurchaseTaskStatusOrderResultUnknown) + a.TaskType, a.SYBProductID = models.PurchaseTaskTypeSYBOrder, &f.syb.ID + if err := db.Save(&a).Error; err != nil { + t.Fatal(err) + } + b := backfillTask(t, db, f, models.PurchaseTaskStatusOrderResultUnknown) + c := backfillTask(t, db, f, models.PurchaseTaskStatusOrderResultUnknown) + if err := db.Model(&c).Update("irreversible_at", nil).Error; err != nil { + t.Fatal(err) + } + page := backfillItem(b.ID, "ORDER-B") + page.OrderSubmittedAt = strptr("2026-09-08T20:30:00+08:00") + rid := uuid.NewString() + items := []OrderBackfillItem{backfillItem(a.ID, "ORDER-A"), {AddressSuffix: "_cg0", PDDOrderNo: "bad"}, page, backfillItem(c.ID, "ORDER-C"), backfillItem(99999, "missing")} + results := runBackfill(t, s, f.token, rid, items...) + want := []string{"BACKFILLED", CodeBackfillSuffix, "BACKFILLED", CodeOrderTimeMissing, CodeTaskNotFound} + for i, r := range results { + if r.Code != want[i] || r.Index != i { + t.Fatalf("item %d: %+v", i, r) + } + } + if results[0].TimeSource != "irreversible_at" || !results[0].OrderSubmittedAt.Equal(*a.IrreversibleAt) { + t.Fatalf("fallback: %+v", results[0]) + } + if results[2].TimeSource != "page" || results[2].OrderSubmittedAt.Format(time.RFC3339) != "2026-09-08T12:30:00Z" { + t.Fatalf("page: %+v", results[2]) + } + saved := loadBackfillTask(t, db, a.ID) + if saved.StatusVersion != a.StatusVersion+1 || saved.ErrorCode != nil || saved.ErrorMessage != nil || saved.DeviceRunSlot != nil || saved.AccountRunSlot != nil || saved.ActiveSlot == nil || saved.Status != models.PurchaseTaskStatusOrderCreated { + t.Fatalf("state metadata: %+v", saved) + } + if saved.PaymentReviewStatus != a.PaymentReviewStatus || saved.LogisticsStatus != a.LogisticsStatus || saved.WritebackStatus != a.WritebackStatus || saved.RuleSnapshot != a.RuleSnapshot { + t.Fatal("unrelated business facts changed") + } + for _, replayID := range []string{rid, uuid.NewString()} { + item := items[0] + item.OrderSubmittedAt = strptr("2026-09-09T00:00:00Z") + r := runBackfill(t, s, f.token, replayID, item)[0] + if r.Result != "already_backfilled" || r.TimeSource != "irreversible_at" { + t.Fatalf("replay: %+v", r) + } + if got := loadBackfillTask(t, db, a.ID); !reflect.DeepEqual(saved, got) { + t.Fatal("replay changed persisted task") + } + } + if got := loadBackfillTask(t, db, c.ID); got.PDDOrderNo != nil || got.StatusVersion != c.StatusVersion { + t.Fatal("missing time wrote data") + } +} + +func TestOrderBackfillRejectsOwnershipStatesAndInvalidTime(t *testing.T) { + db := testDB(t) + f := seed(t, db, liveCaps(), true) + s := testService(db) + for _, status := range []string{models.PurchaseTaskStatusPending, models.PurchaseTaskStatusRunning, models.PurchaseTaskStatusOrderSubmitStarted, models.PurchaseTaskStatusSpecProbePending, models.PurchaseTaskStatusFailed, models.PurchaseTaskStatusCancelled, models.PurchaseTaskStatusRehearsalCompleted} { + task := backfillTask(t, db, f, status) + before := loadBackfillTask(t, db, task.ID) + r := runBackfill(t, s, f.token, uuid.NewString(), backfillItem(task.ID, "ORDER"))[0] + if r.Code != CodeStateConflict { + t.Fatalf("%s: %+v", status, r) + } + if got := loadBackfillTask(t, db, task.ID); !reflect.DeepEqual(got, before) { + t.Fatal("rejection wrote data") + } + // Release the fixture's device slot before testing the next running state. + if err := task.SetStatus(models.PurchaseTaskStatusCancelled); err != nil { + t.Fatal(err) + } + if err := db.Save(&task).Error; err != nil { + t.Fatal(err) + } + } + task := backfillTask(t, db, f, models.PurchaseTaskStatusOrderResultUnknown) + if err := db.Model(&task).Update("device_id", nil).Error; err != nil { + t.Fatal(err) + } + r := runBackfill(t, s, f.token, uuid.NewString(), backfillItem(task.ID, "ORDER"))[0] + if r.Code != CodeBackfillDevice || r.Status != "" || r.PDDOrderNo != nil { + t.Fatalf("ownership leaked: %+v", r) + } + other, err := device.NewService(db).Register(context.Background(), device.RegisterRequest{RequestID: uuid.NewString(), InstallID: uuid.NewString(), Name: "Other", Manufacturer: "Test", Model: "Test", AndroidVersion: "15", AgentVersion: "1", PDDVersion: "7", Capabilities: liveCaps()}, "") + if err != nil { + t.Fatal(err) + } + if err := db.Model(&task).Update("device_id", other.DeviceID).Error; err != nil { + t.Fatal(err) + } + if r := runBackfill(t, s, f.token, uuid.NewString(), backfillItem(task.ID, "ORDER"))[0]; r.Code != CodeBackfillDevice { + t.Fatalf("cross device: %+v", r) + } + if err := db.Model(&task).Updates(map[string]any{"device_id": f.device.ID, "execution_mode": models.PurchaseExecutionModeRehearsal}).Error; err != nil { + t.Fatal(err) + } + if r := runBackfill(t, s, f.token, uuid.NewString(), backfillItem(task.ID, "ORDER"))[0]; r.Code != CodeStateConflict { + t.Fatalf("rehearsal: %+v", r) + } + if err := db.Model(&task).Update("execution_mode", models.PurchaseExecutionModeLive).Error; err != nil { + t.Fatal(err) + } + for _, raw := range []string{"", "2026-09-08 12:00:00", "0001-01-01T00:00:00Z", "garbage"} { + item := backfillItem(task.ID, "ORDER") + item.OrderSubmittedAt = &raw + if r := runBackfill(t, s, f.token, uuid.NewString(), item)[0]; r.Code != CodeOrderTimeInvalid { + t.Fatalf("invalid time: %+v", r) + } + } +} + +func TestOrderBackfillConflictsNeverOverwrite(t *testing.T) { + db := testDB(t) + f := seed(t, db, liveCaps(), true) + s := testService(db) + a := backfillTask(t, db, f, models.PurchaseTaskStatusOrderResultUnknown) + b := backfillTask(t, db, f, models.PurchaseTaskStatusOrderResultUnknown) + rid := uuid.NewString() + r := runBackfill(t, s, f.token, rid, backfillItem(a.ID, "A"), backfillItem(a.ID, "B"), backfillItem(b.ID, "B")) + if r[0].Code != CodeBackfillBatchConflict || r[1].Code != CodeBackfillBatchConflict || r[2].Code != "BACKFILLED" { + t.Fatalf("batch: %+v", r) + } + r = runBackfill(t, s, f.token, rid, backfillItem(a.ID, "B"), backfillItem(b.ID, "C")) + if r[0].Code != CodeBackfillOrderUsed || r[1].Code != CodeBackfillOrderConflict { + t.Fatalf("changed requestId payload bypassed checks: %+v", r) + } + if got := loadBackfillTask(t, db, b.ID); *got.PDDOrderNo != "B" || got.StatusVersion != b.StatusVersion+1 { + t.Fatal("conflict overwrote") + } + if got := loadBackfillTask(t, db, a.ID); got.PDDOrderNo != nil { + t.Fatal("conflict wrote data") + } + // Even an unknown task with an existing conflicting value must preserve it. + a.PDDOrderNo = strptr("OLD") + if err := db.Save(&a).Error; err != nil { + t.Fatal(err) + } + if r := runBackfill(t, s, f.token, uuid.NewString(), backfillItem(a.ID, "NEW"))[0]; r.Code != CodeBackfillOrderConflict { + t.Fatalf("unknown existing: %+v", r) + } +} + +func TestOrderBackfillConcurrentResolveUnknown(t *testing.T) { + db := testDB(t) + f := seed(t, db, liveCaps(), true) + s := testService(db) + // SQLite serializes transactions through one connection. These concurrent + // service calls verify both winner orders; they do not certify MySQL locks. + sqlDB, _ := db.DB() + sqlDB.SetMaxOpenConns(1) + for i := 0; i < 12; i++ { + task := backfillTask(t, db, f, models.PurchaseTaskStatusOrderResultUnknown) + start := make(chan struct{}) + var wg sync.WaitGroup + wg.Add(2) + var out OrderBackfillResponse + var backErr, manualErr error + go func() { + defer wg.Done() + <-start + out, backErr = s.BackfillOrders(context.Background(), OrderBackfillRequest{RequestID: uuid.NewString(), Items: []OrderBackfillItem{backfillItem(task.ID, "BACK-"+purchasecontract.AddressSuffix(task.ID))}}, f.token) + }() + go func() { + defer wg.Done() + <-start + _, _, manualErr = s.ResolveUnknown(context.Background(), task.ID, ManualRequest{RequestID: uuid.NewString(), OperatorID: 1, Status: models.PurchaseTaskStatusOrderCreated, PDDOrderNo: "MANUAL-" + purchasecontract.AddressSuffix(task.ID), OrderSubmittedAt: task.IrreversibleAt}) + }() + close(start) + wg.Wait() + if backErr != nil { + t.Fatal(backErr) + } + got := loadBackfillTask(t, db, task.ID) + if got.StatusVersion != task.StatusVersion+1 || got.Status != models.PurchaseTaskStatusOrderCreated { + t.Fatal("competing writes changed version twice") + } + if manualErr == nil { + if out.Items[0].Code != CodeBackfillOrderConflict || !strings.HasPrefix(*got.PDDOrderNo, "MANUAL-") { + t.Fatalf("manual winner: %+v", out) + } + } else if code(manualErr) != CodeStateConflict || out.Items[0].Code != "BACKFILLED" || !strings.HasPrefix(*got.PDDOrderNo, "BACK-") { + t.Fatalf("backfill winner: %+v %v", out, manualErr) + } + } +} + +func TestOrderBackfillConcurrentLateResultAndOtherTask(t *testing.T) { + db := testDB(t) + f := seed(t, db, liveCaps(), true) + s := testService(db) + sqlDB, _ := db.DB() + sqlDB.SetMaxOpenConns(1) + a := backfillTask(t, db, f, models.PurchaseTaskStatusOrderResultUnknown) + attempt := models.PurchaseTaskAttempt{TaskID: a.ID, AttemptID: uuid.NewString(), AttemptNumber: 1, Phase: models.PurchaseAttemptPhasePurchase, Status: models.PurchaseAttemptStatusFailed, DeviceID: &f.device.ID, RuleSnapshotHash: purchaseRuleSnapshotHash(a.RuleSnapshot), SpecDecisionSnapshot: `{}`} + if err := db.Omit("Task").Create(&attempt).Error; err != nil { + t.Fatal(err) + } + if err := db.First(&attempt, attempt.ID).Error; err != nil { + t.Fatal(err) + } + start := make(chan struct{}) + var wg sync.WaitGroup + wg.Add(2) + var out OrderBackfillResponse + var backErr, lateErr error + go func() { + defer wg.Done() + <-start + out, backErr = s.BackfillOrders(context.Background(), OrderBackfillRequest{RequestID: uuid.NewString(), Items: []OrderBackfillItem{backfillItem(a.ID, "BACK")}}, f.token) + }() + go func() { + defer wg.Done() + <-start + _, lateErr = s.SubmitResult(context.Background(), a.ID, ResultRequest{RequestID: uuid.NewString(), TaskAttemptID: attempt.AttemptID, ResultType: "order_created", PDDOrderNo: "LATE", OrderSubmittedAt: a.IrreversibleAt}, f.token) + }() + close(start) + wg.Wait() + if backErr != nil || out.Items[0].Code != "BACKFILLED" || code(lateErr) != CodeStateConflict { + t.Fatalf("late race: %+v %v %v", out, backErr, lateErr) + } + var savedAttempt models.PurchaseTaskAttempt + if err := db.First(&savedAttempt, attempt.ID).Error; err != nil { + t.Fatal(err) + } + if !reflect.DeepEqual(savedAttempt, attempt) { + t.Fatal("backfill rewrote attempt") + } + b := backfillTask(t, db, f, models.PurchaseTaskStatusOrderResultUnknown) + _, _, err := s.ResolveUnknown(context.Background(), b.ID, ManualRequest{RequestID: uuid.NewString(), OperatorID: 1, Status: models.PurchaseTaskStatusOrderCreated, PDDOrderNo: "BACK", OrderSubmittedAt: b.IrreversibleAt}) + if err == nil { + t.Fatal("manual path assigned another task's order") + } + if got := loadBackfillTask(t, db, b.ID); got.PDDOrderNo != nil || got.StatusVersion != b.StatusVersion { + t.Fatal("other task changed on conflict") + } +} + +func TestOrderBackfillHTTPBoundary(t *testing.T) { + db := testDB(t) + f := seed(t, db, liveCaps(), true) + task := backfillTask(t, db, f, models.PurchaseTaskStatusOrderResultUnknown) + gin.SetMode(gin.TestMode) + r := gin.New() + r.POST("/order-backfill", device.RequireAgentHTTPS(false, false), (Handler{DB: db}).BackfillOrders) + body, _ := json.Marshal(OrderBackfillRequest{RequestID: uuid.NewString(), Items: []OrderBackfillItem{backfillItem(task.ID, "HTTP")}}) + for _, test := range []struct { + body, token string + status int + }{ + {string(body), "", http.StatusUnauthorized}, + {`{"requestId":"bad","items":[]}`, f.token, http.StatusUnprocessableEntity}, + {`{"requestId":"x","address":"forbidden"}`, f.token, http.StatusUnprocessableEntity}, + {string(body), f.token, http.StatusOK}, + } { + req := httptest.NewRequest(http.MethodPost, "/order-backfill", strings.NewReader(test.body)) + req.Header.Set("Authorization", "Bearer "+test.token) + w := httptest.NewRecorder() + r.ServeHTTP(w, req) + if w.Code != test.status { + t.Fatalf("HTTP %d: %s", w.Code, w.Body.String()) + } + } + _, err := testService(db).BackfillOrders(context.Background(), OrderBackfillRequest{RequestID: uuid.NewString(), Items: make([]OrderBackfillItem, 51)}, f.token) + if code(err) != CodeInvalidRequest { + t.Fatalf("batch limit: %v", err) + } +} + +func TestOrderBackfillConcurrentSameOrderDifferentTasks(t *testing.T) { + db := testDB(t) + f := seed(t, db, liveCaps(), true) + s := testService(db) + sqlDB, _ := db.DB() + sqlDB.SetMaxOpenConns(1) + a := backfillTask(t, db, f, models.PurchaseTaskStatusOrderResultUnknown) + b := backfillTask(t, db, f, models.PurchaseTaskStatusOrderResultUnknown) + start := make(chan struct{}) + results := make(chan OrderBackfillResponse, 2) + errors := make(chan error, 2) + for _, id := range []uint64{a.ID, b.ID} { + go func(id uint64) { + <-start + out, err := s.BackfillOrders(context.Background(), OrderBackfillRequest{RequestID: uuid.NewString(), Items: []OrderBackfillItem{backfillItem(id, "SAME")}}, f.token) + results <- out + errors <- err + }(id) + } + close(start) + codes := make(map[string]int) + for i := 0; i < 2; i++ { + out := <-results + if err := <-errors; err != nil { + t.Fatal(err) + } + codes[out.Items[0].Code]++ + } + if codes["BACKFILLED"] != 1 || codes[CodeBackfillOrderUsed] != 1 { + t.Fatalf("concurrent assignments: %+v", codes) + } + var count int64 + if err := db.Model(&models.PurchaseTask{}).Where("pdd_order_no = ?", "SAME").Count(&count).Error; err != nil || count != 1 { + t.Fatalf("duplicate order: %d %v", count, err) + } +} + +func TestOrderBackfillRejectsLateAssignmentOfSameOrder(t *testing.T) { + db := testDB(t) + f := seed(t, db, liveCaps(), true) + s := testService(db) + a := backfillTask(t, db, f, models.PurchaseTaskStatusOrderResultUnknown) + if r := runBackfill(t, s, f.token, uuid.NewString(), backfillItem(a.ID, "SHARED"))[0]; r.Code != "BACKFILLED" { + t.Fatal(r) + } + b := backfillTask(t, db, f, models.PurchaseTaskStatusOrderSubmitStarted) + lease := s.Now().Add(time.Minute) + b.LeaseExpiresAt = &lease + if err := db.Save(&b).Error; err != nil { + t.Fatal(err) + } + attempt := models.PurchaseTaskAttempt{TaskID: b.ID, AttemptID: uuid.NewString(), AttemptNumber: 1, Phase: models.PurchaseAttemptPhasePurchase, Status: models.PurchaseAttemptStatusRunning, DeviceID: &f.device.ID, RuleSnapshotHash: purchaseRuleSnapshotHash(b.RuleSnapshot), SpecDecisionSnapshot: `{}`} + if err := db.Omit("Task").Create(&attempt).Error; err != nil { + t.Fatal(err) + } + _, err := s.SubmitResult(context.Background(), b.ID, ResultRequest{RequestID: uuid.NewString(), TaskAttemptID: attempt.AttemptID, ResultType: "order_created", PDDOrderNo: "SHARED", OrderSubmittedAt: b.IrreversibleAt}, f.token) + if err == nil { + t.Fatal("old result path assigned duplicate order") + } + got := loadBackfillTask(t, db, b.ID) + if got.StatusVersion != b.StatusVersion || got.PDDOrderNo != nil { + t.Fatal("old result transaction was not rolled back") + } + var saved models.PurchaseTaskAttempt + if err := db.First(&saved, attempt.ID).Error; err != nil { + t.Fatal(err) + } + if saved.Status != models.PurchaseAttemptStatusRunning || saved.ResultRequestID != nil { + t.Fatal("attempt result survived rolled back assignment") + } +} + +func TestOrderBackfillHTTPTransportPolicy(t *testing.T) { + gin.SetMode(gin.TestMode) + for _, allow := range []string{"false", "true"} { + t.Setenv("GOAUTO_ALLOW_INSECURE_AGENT_HTTP", allow) + r := gin.New() + r.POST("/order-backfill", device.RequireAgentHTTPS(true, false), (Handler{}).BackfillOrders) + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/order-backfill", strings.NewReader(`{}`))) + if allow == "false" && w.Code != http.StatusUpgradeRequired { + t.Fatalf("HTTPS bypass: %d", w.Code) + } + if allow == "true" && w.Code == http.StatusUpgradeRequired { + t.Fatal("HTTP compatibility broken") + } + } +} + +func TestOrderBackfillMultiConnectionResolveRace(t *testing.T) { + db := testDB(t) + f := seed(t, db, liveCaps(), true) + s := testService(db) + sqlDB, err := db.DB() + if err != nil { + t.Fatal(err) + } + sqlDB.SetMaxOpenConns(4) + task := backfillTask(t, db, f, models.PurchaseTaskStatusOrderResultUnknown) + start := make(chan struct{}) + var wg sync.WaitGroup + wg.Add(2) + var back OrderBackfillResponse + var backErr, manualErr error + req := OrderBackfillRequest{RequestID: uuid.NewString(), Items: []OrderBackfillItem{backfillItem(task.ID, "BACK")}} + go func() { defer wg.Done(); <-start; back, backErr = s.BackfillOrders(context.Background(), req, f.token) }() + go func() { + defer wg.Done() + <-start + _, _, manualErr = s.ResolveUnknown(context.Background(), task.ID, ManualRequest{RequestID: uuid.NewString(), OperatorID: 1, Status: models.PurchaseTaskStatusOrderCreated, PDDOrderNo: "MANUAL", OrderSubmittedAt: task.IrreversibleAt}) + }() + close(start) + wg.Wait() + // SQLite returns table-lock errors rather than waiting on FOR UPDATE. + // Only that documented DB contention or a domain conflict is acceptable; + // after the competing calls finish, replay must converge without overwrite. + if backErr != nil && !strings.Contains(backErr.Error(), "locked") { + t.Fatal(backErr) + } + if manualErr != nil && code(manualErr) != CodeStateConflict && !strings.Contains(manualErr.Error(), "locked") { + t.Fatal(manualErr) + } + if backErr == nil && back.Items[0].Code != "BACKFILLED" && back.Items[0].Code != CodeBackfillOrderConflict && !(back.Items[0].Code == CodeInternal && back.Items[0].Retryable) { + t.Fatalf("unexpected race result: %+v", back) + } + before := loadBackfillTask(t, db, task.ID) + replay := runBackfill(t, s, f.token, req.RequestID, req.Items...)[0] + after := loadBackfillTask(t, db, task.ID) + if before.PDDOrderNo != nil && !reflect.DeepEqual(before, after) { + t.Fatal("replay overwrote the concurrent winner") + } + if after.StatusVersion != task.StatusVersion+1 || after.Status != models.PurchaseTaskStatusOrderCreated { + t.Fatal("race did not converge to a single transition") + } + if manualErr == nil { + if *after.PDDOrderNo != "MANUAL" || replay.Code != CodeBackfillOrderConflict { + t.Fatal("manual winner overwritten") + } + } else if *after.PDDOrderNo != "BACK" || (replay.Code != "BACKFILLED" && replay.Code != "ALREADY_BACKFILLED") { + t.Fatalf("backfill did not converge: %+v", replay) + } +} diff --git a/server/app/goauto/purchase/router.go b/server/app/goauto/purchase/router.go index 98a3307..849dc2e 100644 --- a/server/app/goauto/purchase/router.go +++ b/server/app/goauto/purchase/router.go @@ -18,6 +18,7 @@ func InitRouter(engine *gin.Engine, auth *jwt.GinJWTMiddleware) { agent := engine.Group("/api/agent/v1/purchase-tasks").Use(device.RequireAgentHTTPS(config.ApplicationConfig.Mode == "prod", trust)) agent.GET("", h.AgentHistory) agent.GET("/next", h.Next) + agent.POST("/order-backfill", h.BackfillOrders) agent.GET("/:taskId", h.AgentHistoryDetail) agent.POST("/:taskId/retry", h.AgentRetry) agent.POST("/:taskId/reset", h.AgentReset) diff --git a/server/app/goauto/purchasecontract/address_suffix_test.go b/server/app/goauto/purchasecontract/address_suffix_test.go new file mode 100644 index 0000000..1468f20 --- /dev/null +++ b/server/app/goauto/purchasecontract/address_suffix_test.go @@ -0,0 +1,17 @@ +package purchasecontract + +import "testing" + +func TestParseAddressSuffix(t *testing.T) { + for _, id := range []uint64{7, 72, ^uint64(0)} { + got, err := ParseAddressSuffix(AddressSuffix(id)) + if err != nil || got != id { + t.Fatalf("id=%d got=%d err=%v", id, got, err) + } + } + for _, raw := range []string{"", "_cg", "_cg0", "_cg00", "_cg07", "_cg+7", "_cg-7", "_cg18446744073709551616", "_CG7", "_cg7x", "_cg7_cg72", "address_cg7", " _cg7", "_cg7 ", "_cg７", "_cg7\n"} { + if id, err := ParseAddressSuffix(raw); err == nil || id != 0 { + t.Errorf("accepted %q: %d", raw, id) + } + } +} diff --git a/server/app/goauto/purchasecontract/contract.go b/server/app/goauto/purchasecontract/contract.go index 910db76..7bb8a13 100644 --- a/server/app/goauto/purchasecontract/contract.go +++ b/server/app/goauto/purchasecontract/contract.go @@ -9,6 +9,7 @@ import ( "math" "regexp" "sort" + "strconv" "strings" "unicode/utf8" ) @@ -360,6 +361,18 @@ func RequiredCapabilities(rule RuleSnapshot) []string { func AddressSuffix(taskID uint64) string { return fmt.Sprintf("_cg%d", taskID) } +// ParseAddressSuffix accepts only the exact canonical suffix, never an address. +func ParseAddressSuffix(suffix string) (uint64, error) { + if !strings.HasPrefix(suffix, "_cg") { + return 0, errors.New("invalid address suffix") + } + id, err := strconv.ParseUint(strings.TrimPrefix(suffix, "_cg"), 10, 64) + if err != nil || id == 0 || AddressSuffix(id) != suffix { + return 0, errors.New("invalid address suffix") + } + return id, nil +} + func ensureEOF(decoder *json.Decoder) error { var extra any if err := decoder.Decode(&extra); err != io.EOF { From 72b8b5d4d01ada433117f19596cae634a2e344b2 Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Tue, 8 Sep 2026 15:02:51 +0800 Subject: [PATCH 2/4] fix(purchase): preserve conflicting order results for manual resolution (#241) --- docs/08-agent-api-contract.md | 4 +- .../app/goauto/models/purchase_order_guard.go | 13 +++- server/app/goauto/purchase/handler.go | 2 +- server/app/goauto/purchase/lifecycle.go | 26 ++++++- server/app/goauto/purchase/manual.go | 10 ++- .../goauto/purchase/order_backfill_test.go | 38 ++++++++-- .../goauto/purchase/order_conflict_test.go | 74 +++++++++++++++++++ server/app/goauto/purchase/types.go | 1 + 8 files changed, 155 insertions(+), 13 deletions(-) create mode 100644 server/app/goauto/purchase/order_conflict_test.go diff --git a/docs/08-agent-api-contract.md b/docs/08-agent-api-contract.md index 59c1323..ca049b8 100644 --- a/docs/08-agent-api-contract.md +++ b/docs/08-agent-api-contract.md @@ -556,7 +556,9 @@ Android #42/#36 使用本地 SQLite 保存恢复与重传所需的任务、attem 创建订单前先在本地事务保存 `order_submit_started`、不可逆时间、稳定的 `orderSubmitRequestId` 和脱敏最终确认快照，再调用服务端同名接口；只有两侧标记完成并重新校验商品、规格、数量、单价、地址后缀、PDD 包/Activity 与唯一创建订单按钮后，才点击一次。重启时重放同一标记请求并只读核单；无法取得唯一未付款订单号和 PDD 下单时间时提交 `order_result_unknown`。支付文字仅用于识别未付款/离开支付页，永不点击。服务端数据库仍是最终事实来源；双方均不保存原始控件树、截图、PDD 凭据或完整收货地址。 创建订单后若出现 Android 多微信应用选择器，只读核单器必须同时确认前台包为 `android` / `com.android.intentresolver`、Activity 为白名单 `ChooserActivity` / `ResolverActivity`、页面出现已知系统选择器标题且至少一个候选以“微信”开头，才允许执行一次系统返回；不得点击任何微信候选。若前台已经是精确微信包 `com.tencent.mm`，只读核单器不得点击、输入、登录、支付或强制停止微信，只允许执行一次无参数 PDD 启动 Intent 并等待既有 PDD 任务栈回到前台；`startActivity()` 成功只表示恢复请求已发起。请求后在固定最多 15 次、每次 200ms 的宽限期内允许微信或空窗口短暂残留，不执行点击、返回、输入或滑动；观察到 PDD 后结束宽限，宽限超时、已经观察到 PDD 后再次进入微信或出现稳定未知应用时返回未知结果。随后若前台为 PDD `com.xunmeng.pinduoduo.app_pay.core.PayActivity` 或当前页面出现支付动作文字，最多再返回一次。返回后只读解析唯一订单号和下单时间；选择器或支付页重复出现、白名单不成立、恢复动作重复、无法到达订单详情、结果不唯一或超时均返回未知结果，禁止再次点击创建订单、取消订单或支付。 -`order_result_unknown` 保持订单号和下单时间为空，但允许携带创建订单前已经严格验证的 `actualUnitPriceCent`。Agent 同时提交脱敏稳定失败阶段，服务端只接受白名单并按错误码写入固定提示，不信任或保存页面原文；阶段覆盖空窗口超时、选择器返回失败、微信恢复失败/超时、未知应用、支付页返回失败/重复、订单上下文缺失、订单号缺失/歧义、下单时间缺失/无效和待付款证据缺失。任务与 attempt 保存同一错误阶段，Admin 和 Agent 历史读取数据库最终事实；旧 Agent 未提交阶段时归一为 `PURCHASE_ORDER_RESULT_UNKNOWN`。 +Agent 主动提交 `order_result_unknown` 时保持订单号和下单时间为空，但允许携带创建订单前已经严格验证的 `actualUnitPriceCent`。Agent 同时提交脱敏稳定失败阶段，服务端只接受白名单并按错误码写入固定提示，不信任或保存页面原文；阶段覆盖空窗口超时、选择器返回失败、微信恢复失败/超时、未知应用、支付页返回失败/重复、订单上下文缺失、订单号缺失/歧义、下单时间缺失/无效和待付款证据缺失。任务与 attempt 保存同一错误阶段，Admin 和 Agent 历史读取数据库最终事实；旧 Agent 未提交阶段时归一为 `PURCHASE_ORDER_RESULT_UNKNOWN`。 + +#241 追加：全局订单号唯一性校验在人工处理结果未知、取消及 lifecycle 保存路径返回 `PURCHASE_ORDER_NUMBER_ALREADY_USED`（HTTP 409、`retryable=false`），提示“订单号已属于任务 CG-任务ID”；批量回填继续使用原有 `PURCHASE_BACKFILL_ORDER_ALREADY_USED`。不可逆边界后的 `order_created` 结果回传为例外：发现该号已属于其他任务时成功受理结果，将 `order_submit_started` 降级为 `order_result_unknown`，不回滚或自动重派。冲突订单号不写入 `pdd_order_no`，而以“读到订单号 X，但该号已属于任务 CG-yy”保存到任务和 attempt 的 `error_message`，两者 `error_code` 均为 `PURCHASE_ORDER_NUMBER_ALREADY_USED`；保留下单时间、不可逆时间及实际单价。attempt 以 failed 结束并保留原始 `order_created` 结果类型、请求 ID 和摘要，重复提交按原幂等协议返回；任务释放租约和运行槽，进入既有人工处理结果未知通道，权限不变。 | 错误码 | 普通提示 | |---|---| diff --git a/server/app/goauto/models/purchase_order_guard.go b/server/app/goauto/models/purchase_order_guard.go index 5e9f7ee..a880dd8 100644 --- a/server/app/goauto/models/purchase_order_guard.go +++ b/server/app/goauto/models/purchase_order_guard.go @@ -2,6 +2,7 @@ package models import ( "errors" + "fmt" "gorm.io/gorm" "gorm.io/gorm/clause" @@ -9,6 +10,16 @@ import ( var ErrPurchaseOrderNumberUsed = errors.New("purchase order number belongs to another task") +type PurchaseOrderNumberUsedError struct { + TaskID uint64 +} + +func (e *PurchaseOrderNumberUsedError) Error() string { + return fmt.Sprintf("订单号已属于任务 CG-%d", e.TaskID) +} + +func (e *PurchaseOrderNumberUsedError) Unwrap() error { return ErrPurchaseOrderNumberUsed } + // CheckPurchaseOrderNumber must run inside the caller's write transaction. // The existing singleton setting row serializes order assignments across // processes, including an absent order number, without relying on gap locks or @@ -24,7 +35,7 @@ func CheckPurchaseOrderNumber(tx *gorm.DB, taskID uint64, orderNo string) error return err } if len(others) != 0 { - return ErrPurchaseOrderNumberUsed + return &PurchaseOrderNumberUsedError{TaskID: others[0].ID} } return nil } diff --git a/server/app/goauto/purchase/handler.go b/server/app/goauto/purchase/handler.go index 5bfb059..52d2935 100644 --- a/server/app/goauto/purchase/handler.go +++ b/server/app/goauto/purchase/handler.go @@ -542,7 +542,7 @@ func writeError(c *gin.Context, err error) { status = http.StatusForbidden case CodeTaskNotFound: status = http.StatusNotFound - case CodeStateConflict, CodeCapabilityMismatch, CodeDeviceBusy, CodeTaskClaimed, CodeLeaseExpired, CodeMappingRequired, CodeResultConflict, CodeRePurchaseRequired: + case CodeStateConflict, CodeCapabilityMismatch, CodeDeviceBusy, CodeTaskClaimed, CodeLeaseExpired, CodeMappingRequired, CodeResultConflict, CodeRePurchaseRequired, CodeOrderNumberUsed: status = http.StatusConflict } c.JSON(status, gin.H{"code": code, "message": msg, "retryable": retryable}) diff --git a/server/app/goauto/purchase/lifecycle.go b/server/app/goauto/purchase/lifecycle.go index 543eb42..91e5ce2 100644 --- a/server/app/goauto/purchase/lifecycle.go +++ b/server/app/goauto/purchase/lifecycle.go @@ -6,6 +6,7 @@ import ( "encoding/hex" "encoding/json" "errors" + "fmt" "strings" "time" @@ -378,6 +379,22 @@ func (s *Service) SubmitResult(ctx context.Context, taskID uint64, req ResultReq t.PDDOrderNo = &req.PDDOrderNo t.OrderSubmittedAt = req.OrderSubmittedAt t.ActualUnitPriceCent = req.ActualUnitPriceCent + // Keep the assignment lock until commit. A conflicting observation + // after the irreversible boundary must reach manual resolution, + // not roll back the result or claim another task's order number. + if e := models.CheckPurchaseOrderNumber(tx, t.ID, req.PDDOrderNo); e != nil { + var conflict *models.PurchaseOrderNumberUsedError + if !errors.As(e, &conflict) { + return TaskPayload{}, conflictOrInternal(e) + } + next = models.PurchaseTaskStatusOrderResultUnknown + t.PDDOrderNo = nil + failureCode := CodeOrderNumberUsed + message := fmt.Sprintf("读到订单号 %s，但该号已属于任务 %s", req.PDDOrderNo, taskNumber(conflict.TaskID)) + t.ErrorCode, t.ErrorMessage = &failureCode, &message + a.Status = models.PurchaseAttemptStatusFailed + a.ErrorCode, a.ErrorMessage = &failureCode, &message + } case "order_result_unknown": if t.ExecutionMode != models.PurchaseExecutionModeLive || t.Status != models.PurchaseTaskStatusOrderSubmitStarted { return TaskPayload{}, fail(CodeStateConflict, "当前任务不能标记订单结果未知") @@ -525,7 +542,10 @@ func (s *Service) applySpecDecision(ctx context.Context, taskID uint64, req Spec } t.StatusVersion++ t.StatusChangedAt = s.Now() - return tx.Save(&t).Error + if e := tx.Save(&t).Error; e != nil { + return conflictOrInternal(e) + } + return nil }) return t, replayed, err } @@ -728,6 +748,10 @@ func purchaseNotFound(err error) error { return internal(err) } func conflictOrInternal(err error) error { + var conflict *models.PurchaseOrderNumberUsedError + if errors.As(err, &conflict) { + return fail(CodeOrderNumberUsed, conflict.Error()) + } if isDuplicate(err) { return fail(CodeDeviceBusy, "设备或拼多多账号已有运行任务") } diff --git a/server/app/goauto/purchase/manual.go b/server/app/goauto/purchase/manual.go index acbd205..6767a97 100644 --- a/server/app/goauto/purchase/manual.go +++ b/server/app/goauto/purchase/manual.go @@ -80,7 +80,10 @@ func (s *Service) SelectWriteback(ctx context.Context, id uint64, req ManualRequ } out.WritebackStatus = models.PurchaseWritebackStatusPending out.WritebackSelectRequestID = &req.RequestID - return tx.Save(&out).Error + if e := tx.Save(&out).Error; e != nil { + return conflictOrInternal(e) + } + return nil }) return out, replayed, err } @@ -166,7 +169,10 @@ func (s *Service) manual(ctx context.Context, id uint64, req ManualRequest, appl return internal(e) } } - return tx.Save(&out).Error + if e := tx.Save(&out).Error; e != nil { + return conflictOrInternal(e) + } + return nil }) return out, replayed, err } diff --git a/server/app/goauto/purchase/order_backfill_test.go b/server/app/goauto/purchase/order_backfill_test.go index 4717a6d..0f4f8ec 100644 --- a/server/app/goauto/purchase/order_backfill_test.go +++ b/server/app/goauto/purchase/order_backfill_test.go @@ -385,20 +385,44 @@ func TestOrderBackfillRejectsLateAssignmentOfSameOrder(t *testing.T) { if err := db.Omit("Task").Create(&attempt).Error; err != nil { t.Fatal(err) } - _, err := s.SubmitResult(context.Background(), b.ID, ResultRequest{RequestID: uuid.NewString(), TaskAttemptID: attempt.AttemptID, ResultType: "order_created", PDDOrderNo: "SHARED", OrderSubmittedAt: b.IrreversibleAt}, f.token) - if err == nil { - t.Fatal("old result path assigned duplicate order") + req := ResultRequest{RequestID: uuid.NewString(), TaskAttemptID: attempt.AttemptID, ResultType: "order_created", PDDOrderNo: "SHARED", OrderSubmittedAt: b.IrreversibleAt} + out, err := s.SubmitResult(context.Background(), b.ID, req, f.token) + if err != nil || out.Status != models.PurchaseTaskStatusOrderResultUnknown { + t.Fatalf("conflicting result must commit as unknown: %+v %v", out, err) } got := loadBackfillTask(t, db, b.ID) - if got.StatusVersion != b.StatusVersion || got.PDDOrderNo != nil { - t.Fatal("old result transaction was not rolled back") + if got.Status != models.PurchaseTaskStatusOrderResultUnknown || got.StatusVersion != b.StatusVersion+1 || got.PDDOrderNo != nil { + t.Fatalf("duplicate assignment was not safely downgraded: %+v", got) + } + wantMessage := "读到订单号 SHARED，但该号已属于任务 " + taskNumber(a.ID) + if got.ErrorCode == nil || *got.ErrorCode != CodeOrderNumberUsed || got.ErrorMessage == nil || *got.ErrorMessage != wantMessage { + t.Fatalf("conflict evidence missing: %+v", got) + } + if got.OrderSubmittedAt == nil || !got.OrderSubmittedAt.Equal(*req.OrderSubmittedAt) || got.IrreversibleAt == nil || got.LeaseExpiresAt != nil || got.DeviceRunSlot != nil || got.AccountRunSlot != nil { + t.Fatalf("boundary evidence or released lease missing: %+v", got) } var saved models.PurchaseTaskAttempt if err := db.First(&saved, attempt.ID).Error; err != nil { t.Fatal(err) } - if saved.Status != models.PurchaseAttemptStatusRunning || saved.ResultRequestID != nil { - t.Fatal("attempt result survived rolled back assignment") + if saved.Status != models.PurchaseAttemptStatusFailed || saved.ResultRequestID == nil || *saved.ResultRequestID != req.RequestID || saved.ResultHash == nil || saved.ResultType == nil || *saved.ResultType != "order_created" || saved.FinishedAt == nil || saved.ErrorCode == nil || *saved.ErrorCode != CodeOrderNumberUsed || saved.ErrorMessage == nil || *saved.ErrorMessage != wantMessage { + t.Fatalf("attempt result and conflict evidence missing: %+v", saved) + } + out, err = s.SubmitResult(context.Background(), b.ID, req, f.token) + if err != nil || !out.Replayed || out.Status != models.PurchaseTaskStatusOrderResultUnknown || loadBackfillTask(t, db, b.ID).StatusVersion != got.StatusVersion { + t.Fatalf("unknown result replay failed: %+v %v", out, err) + } + owner := loadBackfillTask(t, db, a.ID) + if owner.PDDOrderNo == nil || *owner.PDDOrderNo != "SHARED" || owner.Status != models.PurchaseTaskStatusOrderCreated { + t.Fatalf("existing owner changed: %+v", owner) + } + var count int64 + if err := db.Model(&models.PurchaseTask{}).Where("pdd_order_no = ?", "SHARED").Count(&count).Error; err != nil || count != 1 { + t.Fatalf("duplicate order: %d %v", count, err) + } + resolved, _, err := s.ResolveUnknown(context.Background(), b.ID, ManualRequest{RequestID: uuid.NewString(), OperatorID: 1, Status: models.PurchaseTaskStatusOrderCreated, PDDOrderNo: "CORRECTED", OrderSubmittedAt: req.OrderSubmittedAt}) + if err != nil || resolved.Status != models.PurchaseTaskStatusOrderCreated { + t.Fatalf("manual resolution unavailable: %+v %v", resolved, err) } } diff --git a/server/app/goauto/purchase/order_conflict_test.go b/server/app/goauto/purchase/order_conflict_test.go new file mode 100644 index 0000000..b62e91f --- /dev/null +++ b/server/app/goauto/purchase/order_conflict_test.go @@ -0,0 +1,74 @@ +package purchase + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "testing" + "time" + + "go-admin/app/goauto/models" + + "github.com/gin-gonic/gin" + "github.com/google/uuid" + "gorm.io/gorm" +) + +func TestOrderNumberConflictBusinessErrors(t *testing.T) { + for _, path := range []string{"resolve_unknown", "cancel", "lifecycle"} { + t.Run(path, func(t *testing.T) { + db := testDB(t) + f := seed(t, db, liveCaps(), true) + s := testService(db) + owner := backfillTask(t, db, f, models.PurchaseTaskStatusOrderResultUnknown) + if r := runBackfill(t, s, f.token, uuid.NewString(), backfillItem(owner.ID, "SHARED"))[0]; r.Code != "BACKFILLED" { + t.Fatal(r) + } + status := models.PurchaseTaskStatusOrderResultUnknown + if path == "lifecycle" { + status = models.PurchaseTaskStatusRunning + } + task := backfillTask(t, db, f, status) + if path != "resolve_unknown" { + // Model legacy duplicate data predating the global save guard. + if err := db.Session(&gorm.Session{SkipHooks: true}).Model(&models.PurchaseTask{}).Where("id = ?", task.ID).Updates(map[string]any{"pdd_order_no": "SHARED", "lease_expires_at": s.Now().Add(time.Minute)}).Error; err != nil { + t.Fatal(err) + } + } + req := ManualRequest{RequestID: uuid.NewString(), OperatorID: 1, Status: models.PurchaseTaskStatusOrderCreated, PDDOrderNo: "SHARED", OrderSubmittedAt: task.IrreversibleAt, Reason: "人工取消"} + var err error + switch path { + case "resolve_unknown": + _, _, err = s.ResolveUnknown(context.Background(), task.ID, req) + case "cancel": + _, _, err = s.Cancel(context.Background(), task.ID, req) + case "lifecycle": + attempt := models.PurchaseTaskAttempt{TaskID: task.ID, AttemptID: uuid.NewString(), AttemptNumber: 1, Phase: models.PurchaseAttemptPhasePurchase, Status: models.PurchaseAttemptStatusRunning, DeviceID: &f.device.ID, RuleSnapshotHash: purchaseRuleSnapshotHash(task.RuleSnapshot), SpecDecisionSnapshot: `{}`} + if e := db.Omit("Task").Create(&attempt).Error; e != nil { + t.Fatal(e) + } + _, err = s.MarkOrderSubmitStarted(context.Background(), task.ID, ActionRequest{RequestID: req.RequestID}, f.token) + } + want := "订单号已属于任务 " + taskNumber(owner.ID) + if code(err) != CodeOrderNumberUsed || err.Error() != want { + t.Fatalf("unmapped conflict: %v", err) + } + w := httptest.NewRecorder() + c, _ := gin.CreateTestContext(w) + writeError(c, err) + var body struct { + Code string `json:"code"` + Message string `json:"message"` + Retryable bool `json:"retryable"` + } + if e := json.Unmarshal(w.Body.Bytes(), &body); e != nil || w.Code != http.StatusConflict || body.Code != CodeOrderNumberUsed || body.Message != want || body.Retryable { + t.Fatalf("unexpected HTTP error: %d %s (%v)", w.Code, w.Body.String(), e) + } + got := loadBackfillTask(t, db, task.ID) + if got.Status != status || got.StatusVersion != task.StatusVersion || got.UnknownResolveRequestID != nil || got.CancelRequestID != nil || got.OrderSubmitRequestID != nil { + t.Fatalf("rejected mutation persisted: %+v", got) + } + }) + } +} diff --git a/server/app/goauto/purchase/types.go b/server/app/goauto/purchase/types.go index b3431b6..0a1d7c2 100644 --- a/server/app/goauto/purchase/types.go +++ b/server/app/goauto/purchase/types.go @@ -22,6 +22,7 @@ const ( CodeRetryStale = "PURCHASE_RETRY_STALE" CodeSpecReprobeRejected = "PURCHASE_SPEC_REPROBE_REJECTED" CodeOrderResultUnknown = "PURCHASE_ORDER_RESULT_UNKNOWN" + CodeOrderNumberUsed = "PURCHASE_ORDER_NUMBER_ALREADY_USED" CodeOrderEmptyTimeout = "PURCHASE_ORDER_EMPTY_TIMEOUT" CodeOrderChooserBack = "PURCHASE_ORDER_CHOOSER_BACK_FAILED" CodeOrderWechatRestore = "PURCHASE_ORDER_WECHAT_RESTORE_FAILED" From ca7f768a79343896667032c96481981869e31175 Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Tue, 8 Sep 2026 15:14:10 +0800 Subject: [PATCH 3/4] docs: sync agent API contract mirror for #241 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 线上 Wiki 页 Android-Agent-API-Contract 已更新并回读，revision 1f5ee1b29c66773fa571d862241b63f02dae283b。本提交只同步镜像头， 正文由 harness.py sync 从线上重建，未反向覆盖 Wiki。 Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01NTDbDcwbDw1TSAcE6wfh2F --- docs/08-agent-api-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/08-agent-api-contract.md b/docs/08-agent-api-contract.md index ca049b8..fffee0a 100644 --- a/docs/08-agent-api-contract.md +++ b/docs/08-agent-api-contract.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Android-Agent-API-Contract wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Android-Agent-API-Contract.- -wiki_revision: 217239a85b50c880e004ecc19a559fb5e03555e1 -synchronized_at: 2026-09-08T01:38:42Z +wiki_revision: 1f5ee1b29c66773fa571d862241b63f02dae283b +synchronized_at: 2026-09-08T07:09:23Z # MVP 共享 API 契约 From 482ba3408a250ed54e3789d8baa486c8e4a4ff07 Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Tue, 8 Sep 2026 15:24:11 +0800 Subject: [PATCH 4/4] docs: sync business rules and code map mirrors for #241 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 线上 Wiki 已更新并回读： Business-Rules-and-Glossary afb3eb896e41d9aea0f15ad2682ec70b7a3924ea Architecture-and-Code-Map d547c17924ac53422232ad9d6c55a34c8cd8d63c 镜像由 harness.py sync 从线上重建，sync --check 通过，未反向覆盖 Wiki。 Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01NTDbDcwbDw1TSAcE6wfh2F --- docs/02-architecture-and-code-map.md | 6 ++++-- docs/03-business-rules-and-glossary.md | 7 +++++-- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/02-architecture-and-code-map.md b/docs/02-architecture-and-code-map.md index 7e17775..f92c8a4 100644 --- a/docs/02-architecture-and-code-map.md +++ b/docs/02-architecture-and-code-map.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Architecture-and-Code-Map wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Architecture-and-Code-Map.- -wiki_revision: f465790ee95fef0f1a501626da50cc66d740f0fc -synchronized_at: 2026-09-08T01:38:06Z +wiki_revision: d547c17924ac53422232ad9d6c55a34c8cd8d63c +synchronized_at: 2026-09-08T07:16:20Z # 架构与代码地图 @@ -68,6 +68,8 @@ Android Portal/Agent | `pdd_account` | 可选的账号调度引用，只保存名称和状态，不保存凭据 | | `purchase_task` | 商品外键和不可变快照、执行模式、状态/租约 guard、价格边界、订单、人工支付复核、物流与回填事实 | | `purchase_task_attempt` | `task_id + attempt_id` 幂等执行记录、阶段、规则哈希、固化规格决策和结构化错误 | + +> #241 新增：`server/app/goauto/purchase/order_backfill.go` 与 `order_backfill_handler.go` 提供 `POST /api/agent/v1/purchase-tasks/order-backfill`（Device Token 鉴权，逐条事务、逐条结果）；`server/app/goauto/models/purchase_order_guard.go` 在 `PurchaseTask.BeforeSave` 上全局强制订单号唯一，以 `purchase_rule_setting` 单例行串行化订单号分配，避免新增唯一索引迁移；`purchasecontract.ParseAddressSuffix` 为 `AddressSuffix` 的反解，通过回比而非负向前瞻实现（Go RE2 不支持前瞻）。 | `ai_matching_setting` | 唯一单例的启用状态、OpenAI-compatible Base URL、模型、超时、内部部署明文 API Key 和更新人；仅管理员设置接口可以读取该字段 | `collection_task` 的状态仅为 `pending`、`running`、`completed`、`completed_partial`、`failed`。设备身份和心跳表属于 Agent 领取任务的必要基础，不承载 PDD 业务数据。 diff --git a/docs/03-business-rules-and-glossary.md b/docs/03-business-rules-and-glossary.md index c9a519d..2748bbb 100644 --- a/docs/03-business-rules-and-glossary.md +++ b/docs/03-business-rules-and-glossary.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Business-Rules-and-Glossary wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Business-Rules-and-Glossary.- -wiki_revision: 7d7f515652a2b24880e55cfd95e94d3c25cbbc4d -synchronized_at: 2026-09-08T02:22:59Z +wiki_revision: afb3eb896e41d9aea0f15ad2682ec70b7a3924ea +synchronized_at: 2026-09-08T07:16:32Z # 业务规则与术语 @@ -58,6 +58,9 @@ synchronized_at: 2026-09-08T02:22:59Z - 对采购人员展示的阶段固定为：待人工处理、未关联 PDD、PDD 待采集、PDD 采集中、PDD 采集失败、规格待匹配、可创建采购、已创建任务、采购成功、待人工核对。 - 主阶段优先级为：待人工核对 → 采购成功 → 已创建任务 → 待人工处理 → 未关联 PDD → PDD 待采集/采集中/采集失败 → 规格待匹配 → 可创建采购。每行只显示一个阶段和对应下一步。 - “待人工核对”表示订单结果不明确，必须先人工核查并禁止自动重试；“采购成功”表示已取得 PDD 订单号和下单时间，不代表已经支付。 +- 一个 PDD 订单号只能属于一个采购任务，该唯一性在采购任务保存路径上全局强制（#241）。人工处理结果未知、取消及 lifecycle 保存路径撞号时返回 `PURCHASE_ORDER_NUMBER_ALREADY_USED`，提示订单号已属于哪个任务，由采购员人工核对，不静默覆盖原值。 +- 不可逆边界之后的 `order_created` 结果回传是上述规则的例外：此时 PDD 真单已创建，发现订单号已属于其他任务时不回滚、不判失败，而是把任务降级为 `order_result_unknown`，冲突订单号以「读到订单号 X，但该号已属于任务 CG-yy」保存在任务与 attempt 的 `error_message`，`pdd_order_no` 留空以维持唯一性，保留下单时间与不可逆时间，进入既有人工处理结果未知通道。首要目标是保住「真单已存在」这一事实，不制造无记录的真实订单。 +- Agent 可按收货地址后缀 `_cg<任务号>` 批量回填订单号与下单时间（#241）。后缀只承载任务号，请求不含地址全文或收件人信息；只允许回填该设备自己的正式采购任务；页面下单时间优先，缺失时回落该任务的 `irreversible_at` 并标记时间来源，两者皆空则该条失败。 - 已失败、已取消或演练完成的旧采购任务不单独占用主阶段；当前数据仍满足条件时恢复显示“可创建采购”，旧任务继续在采购管理留痕和按既有规则处理。 - 未选择处理阶段时，商品列表仍先返回，当前页阶段和采购准备继续异步批量读取且不调用 AI Provider；选择阶段筛选时，服务端必须先对完整查询结果派生并筛选阶段，再计算总数和分页，不能只过滤当前页。