// Package syncfailure 跨系统调用失败台账(2026-11-08)。 // 口径:① 只记「本地事务已提交、对端通知失败」的跨系统回调,供人工重试; // ② 不自动重试(遵守 2026-11-05「断网即失败、禁止离线队列/自动补传」拍板); // ③ 写入一律 best-effort:表未建或插入失败只打日志,绝不阻断业务; // ④ 表由部署时手工执行迁移 SQL 建立,启动期禁止任何 DDL。 package syncfailure import ( "database/sql" "encoding/json" "log" "strings" "time" ) // Row 一条失败台账 type Row struct { ID int64 `json:"id"` Direction string `json:"direction"` BizType string `json:"bizType"` BizKey string `json:"bizKey"` Endpoint string `json:"endpoint"` PayloadJSON string `json:"payloadJson"` ErrorMsg string `json:"errorMsg"` IdempotencyKey string `json:"idempotencyKey"` Status string `json:"status"` RetryCount int `json:"retryCount"` CreatedAt int64 `json:"createdAt"` LastErrorAt int64 `json:"lastErrorAt"` HandledBy string `json:"handledBy"` } // Key 幂等键:direction|biz_type|biz_key;重复失败只更新同一行,不会产生重复通知。 func Key(direction, bizType, bizKey string) string { return direction + "|" + bizType + "|" + bizKey } // Record 落一条失败台账。payload 序列化后存 payload_json,重试时按 endpoint 原样重放。 // best-effort:任何错误只打日志返回,调用方无需处理。 func Record(db *sql.DB, direction, bizType, bizKey, endpoint string, payload any, errMsg string) { if db == nil { return } body, err := json.Marshal(payload) if err != nil { body = []byte("{}") } now := time.Now().Unix() _, err = db.Exec( `INSERT INTO sync_failure (direction, biz_type, biz_key, endpoint, payload_json, error_msg, idempotency_key, status, retry_count, created_at, last_error_at, handled_by) VALUES ($1,$2,$3,$4,$5,$6,$7,'PENDING',0,$8,$8,'') ON CONFLICT (idempotency_key) DO UPDATE SET error_msg = EXCLUDED.error_msg, last_error_at = EXCLUDED.last_error_at, status = 'PENDING', handled_by = '' WHERE sync_failure.status <> 'SUCCESS'`, direction, bizType, bizKey, endpoint, string(body), errMsg, Key(direction, bizType, bizKey), now) if err != nil { log.Printf("[sync-failure] 落台账失败(已退回日志,不阻断业务) %s/%s/%s: %v", direction, bizType, bizKey, err) } } // List 台账列表;status/bizType 为空表示不过滤。 func List(db *sql.DB, status, bizType string) ([]Row, error) { if db == nil { return []Row{}, nil } q := `SELECT id, direction, biz_type, biz_key, endpoint, payload_json, error_msg, idempotency_key, status, retry_count, created_at, last_error_at, handled_by FROM sync_failure WHERE 1=1` args := []any{} if strings.TrimSpace(status) != "" { args = append(args, strings.TrimSpace(status)) q += " AND status = $" + itoa(len(args)) } if strings.TrimSpace(bizType) != "" { args = append(args, strings.TrimSpace(bizType)) q += " AND biz_type = $" + itoa(len(args)) } q += " ORDER BY id DESC LIMIT 500" rows, err := db.Query(q, args...) if err != nil { return nil, err } defer rows.Close() out := []Row{} for rows.Next() { var r Row if err := rows.Scan(&r.ID, &r.Direction, &r.BizType, &r.BizKey, &r.Endpoint, &r.PayloadJSON, &r.ErrorMsg, &r.IdempotencyKey, &r.Status, &r.RetryCount, &r.CreatedAt, &r.LastErrorAt, &r.HandledBy); err != nil { return nil, err } out = append(out, r) } return out, rows.Err() } // Get 按 ID 取一条(重试前读取 endpoint/payload_json)。 func Get(db *sql.DB, id int64) (Row, error) { var r Row err := db.QueryRow( `SELECT id, direction, biz_type, biz_key, endpoint, payload_json, error_msg, idempotency_key, status, retry_count, created_at, last_error_at, handled_by FROM sync_failure WHERE id = $1`, id). Scan(&r.ID, &r.Direction, &r.BizType, &r.BizKey, &r.Endpoint, &r.PayloadJSON, &r.ErrorMsg, &r.IdempotencyKey, &r.Status, &r.RetryCount, &r.CreatedAt, &r.LastErrorAt, &r.HandledBy) return r, err } // Payload 解析 payload_json 为重放用的请求体。 func Payload(r Row) map[string]any { m := map[string]any{} _ = json.Unmarshal([]byte(r.PayloadJSON), &m) return m } // MarkSuccess 重试成功 / 对端已终态 → SUCCESS。 func MarkSuccess(db *sql.DB, id int64) error { _, err := db.Exec(`UPDATE sync_failure SET status='SUCCESS', error_msg='', last_error_at=$2 WHERE id=$1`, id, time.Now().Unix()) return err } // MarkRetryFailed 重试失败 → retry_count+1,记录最后错误;超过 10 次置 DEAD 待人工处置。 func MarkRetryFailed(db *sql.DB, id int64, errMsg string) error { _, err := db.Exec( `UPDATE sync_failure SET retry_count = retry_count + 1, error_msg = $2, last_error_at = $3, status = CASE WHEN retry_count + 1 >= 10 THEN 'DEAD' ELSE 'PENDING' END WHERE id = $1`, id, errMsg, time.Now().Unix()) return err } // Ignore 线下已处理 → DEAD,留痕处理人。 func Ignore(db *sql.DB, id int64, handledBy string) error { _, err := db.Exec(`UPDATE sync_failure SET status='DEAD', handled_by=$2, last_error_at=$3 WHERE id=$1`, id, handledBy, time.Now().Unix()) return err } func itoa(n int) string { if n < 10 { return string(rune('0' + n)) } return string(rune('0'+n/10)) + string(rune('0'+n%10)) }