# pay v2 · P7 codes 共享库(激活码兑换内核)Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development(推荐)或 superpowers:executing-plans 逐任务实现本计划。步骤用 `- [ ]` checkbox 追踪。 > **设计文档(全景蓝图):** `docs/pay-v2-unified-gateway-design.html` §9(codes 兑换内核)/ §9.1(部署选型 A,已定)/ §9.2(履约动作多态)/ §12(通用权益描述符,可扩展性验证)。本计划是 pay v2 八阶段中的 **P7**,承接 `2026-07-10-pay-v2-p1-core-model.md` 末尾"后续阶段"列出的 P7 条目。 **Goal:** 把 pangolin 现有 `server/internal/codes/`(码模型/状态机/生成器/兑换事务/webhook 灌码)抽成一个与 pay **不同部署、不同仓库**的独立 Go 共享库,供 pangolin(订阅)、jiu(门店 license)、未来 dudu(额度)等产品各自 `import` 嵌入。库本身**entitlement-agnostic**——码携带通用「权益描述符」而非硬编码 plan+天数,兑换的"最终开通落库"通过宿主注入的回调函数完成,兑换是**宿主本地事务**(码表与宿主业务表同库)。 **Architecture:** 移植 pangolin `internal/codes` 的 canonical 部分(哈希存储 / 状态机 unused-redeemed-void / Crockford Base32 生成器 / 锁+CAS+幂等兑换骨架 / 批次 / 审计),去掉 pangolin 专属的 `plan_id`+`duration_days`+`subscriptions` 硬编码,替换成通用 `Entitlement{Kind, Payload}` 信封;webhook 签名从 pangolin 的「仅对 body 做 HMAC」升级为 pay-contract 既有的「system+timestamp+nonce+body 一并入 MAC」多产品既定惯例。库只依赖 `database/sql`(host 传入已打开的 `*sql.DB`/`*sql.Tx`,mysql 或 sqlite 均可,库不 import 具体驱动),Redis 相关能力(限流/去重)隔离进可选子包,避免强加给不跑 Redis 的宿主。 ## 部署与模块选型(已决策,依据设计文档 §9.1 方案 A) | 选项 | 说明 | 结论 | |---|---|---| | pay 仓内 `pkg/codes` 子包 | 复用 pay 的 go.mod | ❌ 不采用——pay 依赖很重(gin/GORM/alipay SDK/wechatpay-go),codes 的宿主(pangolin/jiu)只想要码逻辑,不想被迫拉进整个支付网关的依赖树;codes 与 pay 收款管线正交(§9 已定"不并入 pay"),放进 pay 仓在逻辑和依赖两个维度都是错误信号。 | | pangolin 仓内保留、jiu 抄一份 | 零迁移成本 | ❌ 不采用——违反"共享库"目标,retire 到两份漂移代码,与设计文档 §9.1"方案 A = 共享库嵌入各产品"的决策矛盾。 | | **独立仓库 + 独立 Go module(方案 A 落地形态)** | 新仓 `~/code/codes`,module `github.com/wangjia/codes`,各产品 `go get`/`replace` 引入 | ✅ **已定**——依赖最小(核心包零第三方依赖,仅 stdlib;可选 Redis 能力隔离进 `codes/redisx` 子包,不 import 就不产生依赖);可被 pangolin/jiu/dudu 平等 import;版本可独立打 tag,不与任何单一产品的发布节奏绑定。 | **落地约定**(照用户全局仓库管理惯例):新仓源码放 `~/code/codes`,`git init` 后 remote 指向 `ssh://git@git.51yanmei.com:2222/wangjia/codes.git`(需先在 Gitea web 建仓才能 push;若尚未建仓,先本地 commit,push 留到 Gitea 仓建好后)。**本计划只搭这个新仓库,不改 pangolin/jiu 现有代码**——pangolin 现有 `server/internal/codes/` 迁移到 import 本库是后续独立工作(brain todo,pay 定稿 + codes 库稳定后再动),本计划不做。 ## Global Constraints - **Module**:`github.com/wangjia/codes`,`go 1.23`(取 pangolin `1.25.10` / pay `1.26.1` 的下界,保证两者都能正常 `require` 本库)。核心包(根目录 `codes`)编译期**零第三方依赖**——只有 `internal/idgen` 用到的 stdlib(`crypto/rand`/`crypto/sha256`)和测试期用到 `modernc.org/sqlite`(纯 Go 免 CGO,仅测试文件 import,不进宿主生产依赖图)。`codes/redisx` 子包才 import `github.com/redis/go-redis/v9`,宿主不 import 这个子包就不会被拉进 Redis 依赖。 - **同库本地事务是唯一原子性保证**:`Redeem[T]` 接收宿主已开启的 `*sql.Tx`,码状态翻转与宿主的 `grant` 回调写同一个事务——这要求宿主的权益表与 codes 表**在同一个数据库连接/同一个 `*sql.DB` 之下**(设计文档 §9.1 方案 A 的前提)。若宿主权益数据在另一个物理库,本库不提供分布式事务,那是方案 B(独立服务 + saga)的范畴,不在本计划内。 - **明文码永不落库/永不进日志**:数据库与审计日志只存 `SHA-256(canonical_plaintext)`;明文只在 `Mint` 的返回值里出现一次(调用方——通常是 webhook 处理器或运营 CLI——自行负责安全投递)。 - **状态机三态**:`unused → redeemed`(经 `Redeem`)、`unused → void`(经 `VoidCode`),**没有其他合法转移**;`redeemed`/`void` 都是终态。 - **通用权益描述符**:`Entitlement{Kind, Payload}` 替代硬编码 `plan_id`+`duration_days`;`Kind=duration` 承载时长型(`{plan,days}`),`Kind=quota` 承载额度型(`{resource,amount}`,对应 dudu 秒数/未来流量包)。库只做信封校验(`Validate()`),**从不解释 `Payload` 内的业务字段**——那是宿主 `GrantFunc` 的职责。 - **幂等**:同一 `redeemerRef` 重复兑换同一码 → `Idempotent:true`、不重复执行 `grant`;不同 `redeemerRef` 兑换已兑换码 → `ErrCodeRedeemed`。`redeemerRef` 是不透明字符串(`"user:123"` / `"shop:9"`),库不关心其归属维度——这正是设计文档 §9.1 强调"归属维度(user/shop)…留给各产品"的落地方式。 - 每步 `go build ./...` 通过;测试 `go test ./...`(sqlite `:memory:` 免 docker;`redisx` 用 `github.com/alicebob/miniredis/v2` 免 docker——与 pangolin `server/go.mod` 现有测试依赖一致)。 - **本计划范围之外**(明确排除,避免范围蔓延):admin 批次列表/CSV 导出(pangolin `admin_support.go`/`export.go` 已有实现,宿主若需要可直接在自己的 admin 层调用 `Store` 的基础方法拼,不进本库);pangolin/jiu 迁移到 import 本库(单独任务);独立服务化方案 B、reseller 门户、优惠券变体(设计文档 §7/§9.1 标注的 later)。 --- ### Task 1: 模块脚手架 + Entitlement 描述符 + 状态机 + 哨兵错误 **Files:** - Create: `go.mod`(新仓根目录) - Create: `entitlement.go` - Create: `status.go` - Create: `errors.go` - Test: `entitlement_test.go` - Test: `status_test.go` **Interfaces:** - Produces: - `type EntitlementKind string` + 常量 `EntitlementDuration` / `EntitlementQuota` - `type Entitlement struct{ Kind EntitlementKind; Payload json.RawMessage }` - `type DurationPayload struct{ Plan string; Days int }` / `type QuotaPayload struct{ Resource string; Amount int64 }` - `func NewDurationEntitlement(plan string, days int) (Entitlement, error)` / `func NewQuotaEntitlement(resource string, amount int64) (Entitlement, error)` - `func (e Entitlement) DecodeDuration() (DurationPayload, error)` / `func (e Entitlement) DecodeQuota() (QuotaPayload, error)` - `func (e Entitlement) Validate() error` - `type Status string` + 常量 `StatusUnused` / `StatusRedeemed` / `StatusVoid`;`func (s Status) Redeemable() bool` / `func (s Status) Voidable() bool` - 哨兵错误:`ErrDuplicate` / `ErrCodeNotFound` / `ErrCodeRedeemed` / `ErrCodeVoid` / `ErrInvalidCode` / `ErrLocked` / `ErrNotVoidable` - [ ] **Step 0: 建仓** ```bash mkdir -p ~/code/codes && cd ~/code/codes git init go mod init github.com/wangjia/codes git remote add origin ssh://git@git.51yanmei.com:2222/wangjia/codes.git ``` （Gitea 仓需先在 web 建好才能 push;未建好先只本地 commit。） - [ ] **Step 1: 写失败测试** `entitlement_test.go`: ```go package codes_test import ( "encoding/json" "testing" "github.com/wangjia/codes" ) func TestDurationEntitlementRoundTrip(t *testing.T) { e, err := codes.NewDurationEntitlement("pro", 30) if err != nil { t.Fatalf("NewDurationEntitlement: %v", err) } if e.Kind != codes.EntitlementDuration { t.Fatalf("kind = %q, want duration", e.Kind) } if err := e.Validate(); err != nil { t.Fatalf("Validate: %v", err) } p, err := e.DecodeDuration() if err != nil { t.Fatalf("DecodeDuration: %v", err) } if p.Plan != "pro" || p.Days != 30 { t.Fatalf("got %+v", p) } if _, err := e.DecodeQuota(); err == nil { t.Fatal("DecodeQuota on a duration entitlement should error") } // 整个 Entitlement 可安全过 JSON(webhook payload 的编码方式)。 raw, err := json.Marshal(e) if err != nil { t.Fatalf("marshal: %v", err) } var back codes.Entitlement if err := json.Unmarshal(raw, &back); err != nil { t.Fatalf("unmarshal: %v", err) } p2, err := back.DecodeDuration() if err != nil || p2 != p { t.Fatalf("round-trip mismatch: %+v vs %+v (err=%v)", p2, p, err) } } func TestQuotaEntitlementRoundTrip(t *testing.T) { e, err := codes.NewQuotaEntitlement("data_gb", 100) if err != nil { t.Fatalf("NewQuotaEntitlement: %v", err) } q, err := e.DecodeQuota() if err != nil { t.Fatalf("DecodeQuota: %v", err) } if q.Resource != "data_gb" || q.Amount != 100 { t.Fatalf("got %+v", q) } } func TestEntitlementValidateRejectsEmpty(t *testing.T) { if err := (codes.Entitlement{}).Validate(); err == nil { t.Fatal("empty entitlement should fail Validate") } if err := (codes.Entitlement{Kind: codes.EntitlementDuration}).Validate(); err == nil { t.Fatal("duration entitlement with empty payload should fail Validate") } } ``` `status_test.go`: ```go package codes_test import ( "testing" "github.com/wangjia/codes" ) func TestStatusTransitions(t *testing.T) { cases := []struct { s codes.Status redeemable, voidable bool }{ {codes.StatusUnused, true, true}, {codes.StatusRedeemed, false, false}, {codes.StatusVoid, false, false}, } for _, c := range cases { if got := c.s.Redeemable(); got != c.redeemable { t.Errorf("%s.Redeemable() = %v, want %v", c.s, got, c.redeemable) } if got := c.s.Voidable(); got != c.voidable { t.Errorf("%s.Voidable() = %v, want %v", c.s, got, c.voidable) } } } ``` - [ ] **Step 2: 跑测试确认失败** Run: `cd ~/code/codes && go test ./... -v` Expected: 编译失败——`codes` 包内容不存在。 - [ ] **Step 3: 写实现** `entitlement.go`: ```go // Package codes implements a product-agnostic activation-code lifecycle: // generation, hashed storage, a local-transaction redeem skeleton with a // host-supplied grant callback, batches, and audit. It is deliberately not // entitlement-aware — see Entitlement — and not payment-aware (see // pay-v2-unified-gateway-design.html §9 for the boundary with pay). // // Security invariant: plaintext codes are NEVER written to storage or logs. // Only SHA-256(canonical_plaintext) is persisted; plaintext appears exactly // once, in Mint's return value. package codes import ( "encoding/json" "fmt" ) // EntitlementKind selects how Entitlement.Payload should be interpreted by // the host's GrantFunc. codes treats Payload as opaque bytes beyond envelope // validation — it never inspects business fields. type EntitlementKind string const ( EntitlementDuration EntitlementKind = "duration" EntitlementQuota EntitlementKind = "quota" ) // Entitlement is the generic "what does this code grant" descriptor. It // replaces a hardcoded plan_id+duration_days pair so one library carries a // subscription extension (pangolin/jiu) or a quota top-up (dudu seconds, // future traffic packs) without a schema change (design doc §12). type Entitlement struct { Kind EntitlementKind `json:"kind"` Payload json.RawMessage `json:"payload"` } // DurationPayload is the Kind=duration payload shape. type DurationPayload struct { Plan string `json:"plan"` Days int `json:"days"` } // QuotaPayload is the Kind=quota payload shape. type QuotaPayload struct { Resource string `json:"resource"` Amount int64 `json:"amount"` } func NewDurationEntitlement(plan string, days int) (Entitlement, error) { b, err := json.Marshal(DurationPayload{Plan: plan, Days: days}) if err != nil { return Entitlement{}, fmt.Errorf("codes: marshal duration payload: %w", err) } return Entitlement{Kind: EntitlementDuration, Payload: b}, nil } func NewQuotaEntitlement(resource string, amount int64) (Entitlement, error) { b, err := json.Marshal(QuotaPayload{Resource: resource, Amount: amount}) if err != nil { return Entitlement{}, fmt.Errorf("codes: marshal quota payload: %w", err) } return Entitlement{Kind: EntitlementQuota, Payload: b}, nil } func (e Entitlement) DecodeDuration() (DurationPayload, error) { if e.Kind != EntitlementDuration { return DurationPayload{}, fmt.Errorf("codes: entitlement kind %q is not duration", e.Kind) } var p DurationPayload if err := json.Unmarshal(e.Payload, &p); err != nil { return DurationPayload{}, fmt.Errorf("codes: decode duration payload: %w", err) } return p, nil } func (e Entitlement) DecodeQuota() (QuotaPayload, error) { if e.Kind != EntitlementQuota { return QuotaPayload{}, fmt.Errorf("codes: entitlement kind %q is not quota", e.Kind) } var p QuotaPayload if err := json.Unmarshal(e.Payload, &p); err != nil { return QuotaPayload{}, fmt.Errorf("codes: decode quota payload: %w", err) } return p, nil } // Validate checks the envelope only: Kind/Payload are non-empty, and for the // two known kinds the payload decodes. Unknown kinds pass through opaquely // so new entitlement shapes don't require a codes library release first. func (e Entitlement) Validate() error { if e.Kind == "" { return fmt.Errorf("codes: entitlement kind is empty") } if len(e.Payload) == 0 { return fmt.Errorf("codes: entitlement payload is empty") } switch e.Kind { case EntitlementDuration: _, err := e.DecodeDuration() return err case EntitlementQuota: _, err := e.DecodeQuota() return err default: return nil } } ``` `status.go`: ```go package codes // Status is the code lifecycle state. The only legal transitions are // unused→redeemed (via Redeem) and unused→void (via VoidCode); both other // states are terminal. type Status string const ( StatusUnused Status = "unused" StatusRedeemed Status = "redeemed" StatusVoid Status = "void" ) func (s Status) Redeemable() bool { return s == StatusUnused } func (s Status) Voidable() bool { return s == StatusUnused } ``` `errors.go`: ```go package codes import "errors" var ( ErrDuplicate = errors.New("codes: duplicate code hash") ErrCodeNotFound = errors.New("codes: code not found") ErrCodeRedeemed = errors.New("codes: code already redeemed") ErrCodeVoid = errors.New("codes: code has been voided") ErrInvalidCode = errors.New("codes: invalid code format") ErrLocked = errors.New("codes: too many failed attempts, temporarily locked") ErrNotVoidable = errors.New("codes: code is not in a voidable state") ) ``` - [ ] **Step 4: 跑测试确认通过** Run: `cd ~/code/codes && go test ./... -v` Expected: `TestDurationEntitlementRoundTrip` / `TestQuotaEntitlementRoundTrip` / `TestEntitlementValidateRejectsEmpty` / `TestStatusTransitions` 全 PASS。 - [ ] **Step 5: Commit** ```bash cd ~/code/codes git add go.mod entitlement.go status.go errors.go entitlement_test.go status_test.go git commit -m "feat: module scaffold + 通用权益描述符 Entitlement + 状态机 + 哨兵错误" ``` --- ### Task 2: Crockford Base32 生成器(移植 pangolin idgen)+ 根包薄封装 **Files:** - Create: `internal/idgen/idgen.go` - Test: `internal/idgen/idgen_test.go` - Create: `codegen.go`(根包薄封装,对外 API) - Test: `codegen_test.go` **Interfaces:** - Produces(`internal/idgen`,包内私有,不对宿主暴露): - `func GenerateCode() (string, error)` — 15 随机 Crockford Base32 数据字符 + 1 位 mod-37 校验字符(16 字符),`crypto/rand`。 - `func CanonicalizeCode(code string) (string, error)` — 归一化(大写、I/L→1、O→0、去连字符/空格)+ 校验位验证。 - `func HashCode(canonical string) string` — SHA-256 hex。 - Produces(根包 `codes`,对外 API): - `func GenerateCode() (string, error)` / `func Canonicalize(code string) (string, error)` / `func Hash(canonical string) string` — 薄封装,委托给 `internal/idgen`。 此任务**原样移植** `pangolin/server/internal/codes` 依赖的 `internal/idgen` 的 Crockford Base32 部分(去掉与本库无关的 UUID v7 生成),含其完整的校验位/防偏抽样算法与既有测试集,是激活码格式与安全性的 canonical 来源,不重新发明。 - [ ] **Step 1: 写失败测试** `internal/idgen/idgen_test.go`: ```go package idgen_test import ( "strings" "testing" "github.com/wangjia/codes/internal/idgen" ) func TestGenerateCodeFormat(t *testing.T) { for i := 0; i < 1000; i++ { code, err := idgen.GenerateCode() if err != nil { t.Fatalf("GenerateCode: %v", err) } if len(code) != 16 { t.Errorf("code %q: length = %d, want 16", code, len(code)) } canonical, err := idgen.CanonicalizeCode(code) if err != nil { t.Errorf("CanonicalizeCode(%q): %v", code, err) } if canonical != code { t.Errorf("canonical form mismatch: got %q, want %q", canonical, code) } } } func TestGenerateCodeUniqueness(t *testing.T) { const n = 5_000 seen := make(map[string]struct{}, n) for i := 0; i < n; i++ { code, err := idgen.GenerateCode() if err != nil { t.Fatalf("GenerateCode: %v", err) } h := idgen.HashCode(code) if _, dup := seen[h]; dup { t.Fatalf("hash collision at iteration %d: code=%s hash=%s", i, code, h) } seen[h] = struct{}{} } } func TestCanonicalizeCodeNormalization(t *testing.T) { base, err := idgen.GenerateCode() if err != nil { t.Fatalf("GenerateCode: %v", err) } lower := strings.ToLower(base) canonical, err := idgen.CanonicalizeCode(lower) if err != nil { t.Errorf("CanonicalizeCode(lower) error: %v", err) } if canonical != base { t.Errorf("CanonicalizeCode(lower) = %q, want %q", canonical, base) } if idx := strings.IndexByte(base, '1'); idx >= 0 && idx < 15 { for _, sub := range []string{"I", "L", "i", "l"} { variant := base[:idx] + sub + base[idx+1:] c, err := idgen.CanonicalizeCode(variant) if err != nil { t.Errorf("CanonicalizeCode(%q) error: %v", variant, err) continue } if c != base { t.Errorf("CanonicalizeCode(%q) = %q, want %q", variant, c, base) } } } if idx := strings.IndexByte(base, '0'); idx >= 0 && idx < 15 { variant := base[:idx] + "O" + base[idx+1:] c, err := idgen.CanonicalizeCode(variant) if err != nil { t.Errorf("CanonicalizeCode(%q) error: %v", variant, err) } else if c != base { t.Errorf("CanonicalizeCode(%q) = %q, want %q", variant, c, base) } } } func TestCheckCharDetectsSingleErrors(t *testing.T) { const alpha = "0123456789ABCDEFGHJKMNPQRSTVWXYZ" code, err := idgen.GenerateCode() if err != nil { t.Fatalf("GenerateCode: %v", err) } for pos := 0; pos < 15; pos++ { original := rune(code[pos]) for _, replacement := range alpha { if replacement == original { continue } mutated := code[:pos] + string(replacement) + code[pos+1:] if _, err := idgen.CanonicalizeCode(mutated); err == nil { t.Errorf("mutating pos %d (%c→%c) not detected: code=%q mutated=%q", pos, original, replacement, code, mutated) } } } } func TestHashCodeConsistency(t *testing.T) { code1, _ := idgen.GenerateCode() code2, _ := idgen.GenerateCode() for code1 == code2 { code2, _ = idgen.GenerateCode() } h1a := idgen.HashCode(code1) h1b := idgen.HashCode(code1) h2 := idgen.HashCode(code2) if h1a != h1b { t.Error("HashCode is not deterministic") } if h1a == h2 { t.Error("different codes produced the same digest") } if len(h1a) != 64 { t.Errorf("HashCode length = %d, want 64 (hex SHA-256)", len(h1a)) } } func TestCanonicalizeCodeRejectsInvalidLength(t *testing.T) { for _, c := range []string{"", "ABCDE", "ABCDEFGH12345678X"} { if _, err := idgen.CanonicalizeCode(c); err == nil { t.Errorf("CanonicalizeCode(%q) should fail for length %d", c, len(c)) } } } func TestCanonicalizeCodeRejectsInvalidChars(t *testing.T) { base, _ := idgen.GenerateCode() invalid := "!" + base[1:] if _, err := idgen.CanonicalizeCode(invalid); err == nil { t.Errorf("CanonicalizeCode(%q) should fail for invalid character", invalid) } } func TestHyphenStripping(t *testing.T) { code, err := idgen.GenerateCode() if err != nil { t.Fatalf("GenerateCode: %v", err) } hyphenated := code[:4] + "-" + code[4:8] + "-" + code[8:12] + "-" + code[12:] canonical, err := idgen.CanonicalizeCode(hyphenated) if err != nil { t.Errorf("CanonicalizeCode(hyphenated) error: %v", err) } if canonical != code { t.Errorf("CanonicalizeCode(hyphenated) = %q, want %q", canonical, code) } } ``` - [ ] **Step 2: 跑测试确认失败** Run: `cd ~/code/codes && go test ./internal/idgen/ -v` Expected: 编译失败——`internal/idgen` 包不存在。 - [ ] **Step 3: 写实现** `internal/idgen/idgen.go`(移植自 `pangolin/server/internal/idgen/idgen.go`,去掉 UUID v7 部分——本库不需要): ```go // Package idgen generates 16-character Crockford Base32 activation codes // with a mod-37 check character. Ported from pangolin's // server/internal/idgen (Crockford portion only — UUID v7 generation is not // needed by this library). package idgen import ( "crypto/rand" "crypto/sha256" "encoding/hex" "errors" "fmt" "strings" ) // crockfordAlphabet is the 32-symbol encoding alphabet (excludes I, L, O, U // to prevent visual confusion with 1, 1, 0, and V respectively). const crockfordAlphabet = "0123456789ABCDEFGHJKMNPQRSTVWXYZ" // crockfordCheck is the extended 37-symbol check-character alphabet used for // the Crockford mod-37 check symbol. Symbols 0–31 match crockfordAlphabet; // symbols 32–36 are *, ~, $, =, U. const crockfordCheck = "0123456789ABCDEFGHJKMNPQRSTVWXYZ*~$=U" // crockfordDecode maps every printable ASCII character to its Crockford // numeric value (0–31), or -1 if invalid. Normalisation (I/i/l/L→1, O/o→0) // is baked in at init time. var crockfordDecode [128]int8 func init() { for i := range crockfordDecode { crockfordDecode[i] = -1 } for i, ch := range crockfordAlphabet { crockfordDecode[ch] = int8(i) if ch >= 'A' && ch <= 'Z' { crockfordDecode[ch-'A'+'a'] = int8(i) } } crockfordDecode['I'] = crockfordDecode['1'] crockfordDecode['i'] = crockfordDecode['1'] crockfordDecode['l'] = crockfordDecode['1'] crockfordDecode['L'] = crockfordDecode['1'] crockfordDecode['O'] = crockfordDecode['0'] crockfordDecode['o'] = crockfordDecode['0'] } // computeCheckValue computes the Crockford mod-37 check value (Horner's // method) of the first 15 characters of s (already canonical). Returns -1 // on any invalid character. func computeCheckValue(s string) int { result := 0 for i := 0; i < 15; i++ { ch := s[i] if ch >= 128 { return -1 } v := int(crockfordDecode[ch]) if v < 0 { return -1 } result = (result*32 + v) % 37 } return result } func validateCheckChar(canonical string) error { if len(canonical) != 16 { return errors.New("idgen: invalid length for check validation") } expected := computeCheckValue(canonical) if expected < 0 { return errors.New("idgen: invalid data characters in code") } want := rune(crockfordCheck[expected]) got := rune(canonical[15]) if got != want { return fmt.Errorf("idgen: check character mismatch: want %c, got %c", want, got) } return nil } // CanonicalizeCode converts an activation-code string into canonical form: // uppercase, I/L→1 and O→0 substituted, hyphens/spaces stripped, check // character validated. Returns an error on invalid characters, wrong length // (after stripping), or a bad check character. func CanonicalizeCode(code string) (string, error) { code = strings.TrimSpace(code) code = strings.ReplaceAll(code, "-", "") code = strings.ReplaceAll(code, " ", "") if len(code) != 16 { return "", fmt.Errorf("idgen: code must be exactly 16 characters, got %d", len(code)) } var buf [16]byte for i := 0; i < 16; i++ { ch := code[i] if ch >= 128 { return "", fmt.Errorf("idgen: non-ASCII character at position %d", i) } v := crockfordDecode[ch] if v < 0 { if i < 15 { return "", fmt.Errorf("idgen: invalid character %q at position %d", ch, i) } buf[i] = []byte(strings.ToUpper(string(ch)))[0] continue } buf[i] = crockfordAlphabet[v] } canonical := string(buf[:]) if err := validateCheckChar(canonical); err != nil { return "", err } return canonical, nil } // HashCode returns the hex-encoded SHA-256 digest of the canonical plaintext // code — the value that gets persisted; the plaintext itself never is. func HashCode(canonical string) string { sum := sha256.Sum256([]byte(canonical)) return hex.EncodeToString(sum[:]) } // GenerateCode generates one random activation code in canonical Crockford // Base32 form: 15 random data characters + 1 mod-37 check character. // crypto/rand with rejection sampling (accept range [0,224), 224=7×32) to // avoid modular bias. func GenerateCode() (string, error) { const dataLen = 15 var buf [dataLen]byte i := 0 for i < dataLen { var tmp [dataLen * 2]byte if _, err := rand.Read(tmp[:]); err != nil { return "", fmt.Errorf("idgen: crypto/rand: %w", err) } for _, b := range tmp { if b < 224 { buf[i] = crockfordAlphabet[b%32] i++ if i == dataLen { break } } } } data := string(buf[:]) checkVal := computeCheckValue(data + "0") if checkVal < 0 { return "", errors.New("idgen: internal check computation error") } return data + string(crockfordCheck[checkVal]), nil } ``` - [ ] **Step 4: 跑测试确认通过** Run: `cd ~/code/codes && go test ./internal/idgen/ -v` Expected: 全 PASS。 - [ ] **Step 5: 根包薄封装 + 测试** `codegen_test.go`: ```go package codes_test import ( "testing" "github.com/wangjia/codes" ) func TestGenerateCanonicalizeHashRoundTrip(t *testing.T) { code, err := codes.GenerateCode() if err != nil { t.Fatalf("GenerateCode: %v", err) } canonical, err := codes.Canonicalize(code) if err != nil { t.Fatalf("Canonicalize: %v", err) } if canonical != code { t.Fatalf("canonical mismatch: %q vs %q", canonical, code) } h := codes.Hash(canonical) if len(h) != 64 { t.Fatalf("Hash length = %d, want 64", len(h)) } } ``` `codegen.go`: ```go package codes import "github.com/wangjia/codes/internal/idgen" // GenerateCode generates one random 16-char Crockford Base32 activation code. func GenerateCode() (string, error) { return idgen.GenerateCode() } // Canonicalize normalises and validates a user-entered code string. func Canonicalize(code string) (string, error) { return idgen.CanonicalizeCode(code) } // Hash returns the hex SHA-256 digest of a canonical code — the only form // ever persisted. func Hash(canonical string) string { return idgen.HashCode(canonical) } ``` - [ ] **Step 6: 跑测试确认通过 + 全量编译** Run: `cd ~/code/codes && go build ./... && go test ./...` Expected: 编译通过,`internal/idgen` 与根包均 `ok`。 - [ ] **Step 7: Commit** ```bash cd ~/code/codes git add internal/idgen/ codegen.go codegen_test.go git commit -m "feat: Crockford Base32 生成器(移植 pangolin idgen)+ 根包薄封装" ``` --- ### Task 3: Dialect + 内嵌 migrations(mysql+sqlite)+ Store CRUD **Files:** - Create: `dialect.go` - Test: `dialect_test.go` - Create: `migrations/mysql/000001_codes.up.sql` / `000001_codes.down.sql` - Create: `migrations/sqlite/000001_codes.up.sql` / `000001_codes.down.sql` - Create: `migrations.go` - Test: `migrations_test.go` - Create: `store.go` - Create: `testdb_test.go`(包内测试共用 helper) - Test: `store_test.go` **Interfaces:** - Produces: - `type Dialect string` + 常量 `DialectMySQL`/`DialectSQLite`;`func (d Dialect) LockForUpdate() string` - `var migrationsFS embed.FS`(私有)+ `func ApplyMigrations(ctx context.Context, db *sql.DB, dialect Dialect) error` - `type Code struct{ ID int64; CodeHash string; BatchID int64; Entitlement Entitlement; Status Status; RedeemedBy string; RedeemedAt *time.Time; VoidReason string; CreatedAt time.Time }` - `type Batch struct{ ID int64; Channel string; Entitlement Entitlement; CreatedBy, Note string; CreatedAt time.Time }` - `type Store struct{...}` · `func NewStore(db *sql.DB, dialect Dialect) *Store` - `(*Store) CreateBatch(ctx, channel string, ent Entitlement, createdBy, note string) (int64, error)` - `(*Store) CreateCode(ctx, codeHash string, batchID int64, ent Entitlement) error`(重复 hash → `ErrDuplicate`) - `(*Store) FindByHash(ctx, codeHash string) (*Code, error)` - `(*Store) FindByHashForUpdate(ctx, tx *sql.Tx, codeHash string) (*Code, error)` - `(*Store) MarkRedeemed(ctx, tx *sql.Tx, id int64, redeemerRef string, at time.Time) error` - `(*Store) Void(ctx, id int64, reason string) (bool, error)` - `(*Store) WriteAudit(ctx, tx *sql.Tx, actor, action, target string, meta map[string]any) error`(`tx==nil` 时直接用 `s.db`) - [ ] **Step 1: 写失败测试(Dialect,不需要 DB)** `dialect_test.go`: ```go package codes_test import ( "testing" "github.com/wangjia/codes" ) func TestDialectLockForUpdate(t *testing.T) { if got := codes.DialectMySQL.LockForUpdate(); got != "FOR UPDATE" { t.Errorf("mysql LockForUpdate = %q", got) } if got := codes.DialectSQLite.LockForUpdate(); got != "" { t.Errorf("sqlite LockForUpdate = %q, want empty (single-writer engine)", got) } } ``` - [ ] **Step 2: 跑测试确认失败** Run: `cd ~/code/codes && go test ./... -run TestDialectLockForUpdate -v` Expected: 编译失败——`Dialect`/`DialectMySQL`/`DialectSQLite` 未定义。 - [ ] **Step 3: 写 dialect.go** ```go package codes // Dialect captures the one SQL construct this library needs that differs // between engines: pessimistic row locking inside a transaction. SQLite is a // single-writer engine — a BEGIN'd write transaction already serializes // concurrent writers, so no explicit lock clause is needed there. type Dialect string const ( DialectMySQL Dialect = "mysql" DialectSQLite Dialect = "sqlite" ) func (d Dialect) LockForUpdate() string { if d == DialectMySQL { return "FOR UPDATE" } return "" } ``` - [ ] **Step 4: 跑测试确认通过** Run: `cd ~/code/codes && go test ./... -run TestDialectLockForUpdate -v` → PASS。 - [ ] **Step 5: 写 migration SQL(mysql + sqlite)** `migrations/mysql/000001_codes.up.sql`: ```sql CREATE TABLE codes_batches ( id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, channel VARCHAR(32) NOT NULL, entitlement_kind VARCHAR(32) NOT NULL, entitlement_payload JSON NOT NULL, created_by VARCHAR(64) NOT NULL, note VARCHAR(255) NULL, created_at DATETIME NOT NULL ); CREATE TABLE codes ( id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, code_hash CHAR(64) NOT NULL, batch_id BIGINT UNSIGNED NOT NULL, entitlement_kind VARCHAR(32) NOT NULL, entitlement_payload JSON NOT NULL, status VARCHAR(16) NOT NULL DEFAULT 'unused', redeemed_by VARCHAR(128) NULL, redeemed_at DATETIME NULL, void_reason VARCHAR(255) NULL, created_at DATETIME NOT NULL, UNIQUE KEY uq_codes_code_hash (code_hash), KEY idx_codes_status (status), KEY idx_codes_batch (batch_id) ); CREATE TABLE codes_audit_log ( id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, actor VARCHAR(128) NOT NULL, action VARCHAR(32) NOT NULL, target VARCHAR(128) NOT NULL, meta JSON NULL, at DATETIME NOT NULL ); ``` `migrations/mysql/000001_codes.down.sql`: ```sql DROP TABLE codes_audit_log; DROP TABLE codes; DROP TABLE codes_batches; ``` `migrations/sqlite/000001_codes.up.sql`: ```sql CREATE TABLE codes_batches ( id INTEGER PRIMARY KEY AUTOINCREMENT, channel TEXT NOT NULL, entitlement_kind TEXT NOT NULL, entitlement_payload TEXT NOT NULL, created_by TEXT NOT NULL, note TEXT NULL, created_at DATETIME NOT NULL ); CREATE TABLE codes ( id INTEGER PRIMARY KEY AUTOINCREMENT, code_hash TEXT NOT NULL UNIQUE, batch_id INTEGER NOT NULL, entitlement_kind TEXT NOT NULL, entitlement_payload TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'unused' CHECK (status IN ('unused','redeemed','void')), redeemed_by TEXT NULL, redeemed_at DATETIME NULL, void_reason TEXT NULL, created_at DATETIME NOT NULL ); CREATE INDEX idx_codes_status ON codes (status); CREATE INDEX idx_codes_batch ON codes (batch_id); CREATE TABLE codes_audit_log ( id INTEGER PRIMARY KEY AUTOINCREMENT, actor TEXT NOT NULL, action TEXT NOT NULL, target TEXT NOT NULL, meta TEXT NULL, at DATETIME NOT NULL ); ``` `migrations/sqlite/000001_codes.down.sql`: ```sql DROP TABLE codes_audit_log; DROP TABLE codes; DROP TABLE codes_batches; ``` - [ ] **Step 6: 写失败测试(ApplyMigrations)** `migrations_test.go`: ```go package codes_test import ( "context" "database/sql" "testing" "github.com/wangjia/codes" _ "modernc.org/sqlite" ) func TestApplyMigrationsSQLite(t *testing.T) { db, err := sql.Open("sqlite", "file::memory:?cache=shared") if err != nil { t.Fatalf("open: %v", err) } db.SetMaxOpenConns(1) // :memory:+shared cache: one connection = one schema defer db.Close() if err := codes.ApplyMigrations(context.Background(), db, codes.DialectSQLite); err != nil { t.Fatalf("ApplyMigrations: %v", err) } for _, table := range []string{"codes_batches", "codes", "codes_audit_log"} { var name string err := db.QueryRow(`SELECT name FROM sqlite_master WHERE type='table' AND name=?`, table).Scan(&name) if err != nil { t.Errorf("table %s missing: %v", table, err) } } } ``` - [ ] **Step 7: 跑测试确认失败** Run: `cd ~/code/codes && go get modernc.org/sqlite@latest && go test ./... -run TestApplyMigrationsSQLite -v` Expected: 编译失败——`ApplyMigrations` 未定义。 - [ ] **Step 8: 写 migrations.go** ```go package codes import ( "context" "database/sql" "embed" "fmt" "sort" "strings" ) //go:embed migrations/mysql/*.sql migrations/sqlite/*.sql var migrationsFS embed.FS // ApplyMigrations executes every *.up.sql file for dialect, in lexical // order, inside one transaction. It's a zero-dependency convenience for // hosts that don't already run golang-migrate; hosts that do (e.g. // pangolin) can instead point their own migrate runner at the embedded // files under "migrations//" via golang-migrate's iofs source. func ApplyMigrations(ctx context.Context, db *sql.DB, dialect Dialect) error { dir := "migrations/" + string(dialect) entries, err := migrationsFS.ReadDir(dir) if err != nil { return fmt.Errorf("codes.ApplyMigrations: read %s: %w", dir, err) } var files []string for _, e := range entries { if strings.HasSuffix(e.Name(), ".up.sql") { files = append(files, e.Name()) } } sort.Strings(files) tx, err := db.BeginTx(ctx, nil) if err != nil { return fmt.Errorf("codes.ApplyMigrations: begin: %w", err) } defer tx.Rollback() for _, f := range files { raw, err := migrationsFS.ReadFile(dir + "/" + f) if err != nil { return fmt.Errorf("codes.ApplyMigrations: read %s: %w", f, err) } for _, stmt := range splitStatements(string(raw)) { if _, err := tx.ExecContext(ctx, stmt); err != nil { return fmt.Errorf("codes.ApplyMigrations: exec %s: %w", f, err) } } } if err := tx.Commit(); err != nil { return fmt.Errorf("codes.ApplyMigrations: commit: %w", err) } return nil } // splitStatements splits a .sql file's content into individual statements on // ";" terminators — sufficient for this package's DDL (no semicolons inside // string literals). func splitStatements(sqlText string) []string { parts := strings.Split(sqlText, ";") out := make([]string, 0, len(parts)) for _, p := range parts { if p = strings.TrimSpace(p); p != "" { out = append(out, p) } } return out } ``` - [ ] **Step 9: 跑测试确认通过** Run: `cd ~/code/codes && go test ./... -run TestApplyMigrationsSQLite -v` → PASS。 - [ ] **Step 10: 写失败测试(Store CRUD)** `testdb_test.go`(供本任务及后续任务的包内测试共用): ```go package codes import ( "context" "database/sql" "testing" _ "modernc.org/sqlite" ) // openTestDB opens an in-memory SQLite DB with the codes schema migrated. // Shared by every *_test.go in this package (all live in `package codes`, // not `codes_test`, so this helper is visible package-wide). func openTestDB(t *testing.T) *sql.DB { t.Helper() db, err := sql.Open("sqlite", "file::memory:?cache=shared") if err != nil { t.Fatalf("open sqlite: %v", err) } db.SetMaxOpenConns(1) // :memory:+shared cache: one connection = one schema t.Cleanup(func() { _ = db.Close() }) if err := ApplyMigrations(context.Background(), db, DialectSQLite); err != nil { t.Fatalf("apply migrations: %v", err) } return db } ``` `store_test.go`: ```go package codes import ( "context" "testing" ) func mustDuration(t *testing.T, plan string, days int) Entitlement { t.Helper() e, err := NewDurationEntitlement(plan, days) if err != nil { t.Fatalf("NewDurationEntitlement: %v", err) } return e } func TestStoreCreateBatchAndCode(t *testing.T) { db := openTestDB(t) s := NewStore(db, DialectSQLite) ctx := context.Background() ent := mustDuration(t, "pro", 30) batchID, err := s.CreateBatch(ctx, "manual", ent, "cli", "test batch") if err != nil { t.Fatalf("CreateBatch: %v", err) } if batchID == 0 { t.Fatal("batchID should be non-zero") } hash := Hash("ABCDEFGHJKMNPQR0") // any 16-char string is fine here; Store doesn't validate format if err := s.CreateCode(ctx, hash, batchID, ent); err != nil { t.Fatalf("CreateCode: %v", err) } got, err := s.FindByHash(ctx, hash) if err != nil { t.Fatalf("FindByHash: %v", err) } if got == nil { t.Fatal("FindByHash: not found") } if got.Status != StatusUnused || got.BatchID != batchID { t.Fatalf("got %+v", got) } p, err := got.Entitlement.DecodeDuration() if err != nil || p.Plan != "pro" || p.Days != 30 { t.Fatalf("entitlement round-trip failed: %+v (err=%v)", p, err) } // duplicate hash -> ErrDuplicate if err := s.CreateCode(ctx, hash, batchID, ent); err != ErrDuplicate { t.Fatalf("duplicate CreateCode err = %v, want ErrDuplicate", err) } // FindByHash on unknown hash -> nil, no error miss, err := s.FindByHash(ctx, "no-such-hash") if err != nil || miss != nil { t.Fatalf("FindByHash(unknown) = %+v, %v", miss, err) } } func TestStoreVoid(t *testing.T) { db := openTestDB(t) s := NewStore(db, DialectSQLite) ctx := context.Background() ent := mustDuration(t, "pro", 30) batchID, _ := s.CreateBatch(ctx, "manual", ent, "cli", "") hash := Hash("VOIDTESTHASH0001") if err := s.CreateCode(ctx, hash, batchID, ent); err != nil { t.Fatalf("CreateCode: %v", err) } code, _ := s.FindByHash(ctx, hash) ok, err := s.Void(ctx, code.ID, "printing error") if err != nil || !ok { t.Fatalf("Void ok=%v err=%v", ok, err) } after, _ := s.FindByHash(ctx, hash) if after.Status != StatusVoid || after.VoidReason != "printing error" { t.Fatalf("got %+v", after) } // voiding an already-void code is a no-op false, not an error ok2, err := s.Void(ctx, code.ID, "again") if err != nil || ok2 { t.Fatalf("second Void ok=%v err=%v, want false,nil", ok2, err) } } func TestStoreWriteAudit(t *testing.T) { db := openTestDB(t) s := NewStore(db, DialectSQLite) ctx := context.Background() if err := s.WriteAudit(ctx, nil, "cli", "mint", "batch:1", map[string]any{"count": 5}); err != nil { t.Fatalf("WriteAudit: %v", err) } var n int if err := db.QueryRowContext(ctx, `SELECT COUNT(*) FROM codes_audit_log`).Scan(&n); err != nil { t.Fatalf("count: %v", err) } if n != 1 { t.Fatalf("audit rows = %d, want 1", n) } } ``` - [ ] **Step 11: 跑测试确认失败** Run: `cd ~/code/codes && go test . -run 'TestStoreCreateBatchAndCode|TestStoreVoid|TestStoreWriteAudit' -v` Expected: 编译失败——`Store`/`NewStore`/`Code`/`Batch` 未定义。 - [ ] **Step 12: 写 store.go** ```go package codes import ( "context" "database/sql" "encoding/json" "fmt" "strings" "time" ) // Code mirrors one `codes` row. Entitlement is decoded from the stored JSON // envelope; the caller interprets Payload via DecodeDuration/DecodeQuota. type Code struct { ID int64 CodeHash string BatchID int64 Entitlement Entitlement Status Status RedeemedBy string RedeemedAt *time.Time VoidReason string CreatedAt time.Time } // Batch mirrors one `codes_batches` row. type Batch struct { ID int64 Channel string Entitlement Entitlement CreatedBy string Note string CreatedAt time.Time } // Store wraps a *sql.DB (host-owned connection pool — mysql or sqlite) and // exposes every database operation this library needs. Methods taking a // *sql.Tx run inside that host-managed transaction; others use the pool // directly. type Store struct { db *sql.DB dialect Dialect } func NewStore(db *sql.DB, dialect Dialect) *Store { return &Store{db: db, dialect: dialect} } func (s *Store) CreateBatch(ctx context.Context, channel string, ent Entitlement, createdBy, note string) (int64, error) { if err := ent.Validate(); err != nil { return 0, err } res, err := s.db.ExecContext(ctx, `INSERT INTO codes_batches (channel, entitlement_kind, entitlement_payload, created_by, note, created_at) VALUES (?, ?, ?, ?, ?, ?)`, channel, string(ent.Kind), string(ent.Payload), createdBy, nullableString(note), time.Now().UTC()) if err != nil { return 0, fmt.Errorf("codes.Store.CreateBatch: %w", err) } id, err := res.LastInsertId() if err != nil { return 0, fmt.Errorf("codes.Store.CreateBatch last id: %w", err) } return id, nil } // CreateCode inserts one codes row. Returns ErrDuplicate on a code_hash // unique-constraint violation (mysql or sqlite) — the caller should retry // with a freshly generated code (see Mint). func (s *Store) CreateCode(ctx context.Context, codeHash string, batchID int64, ent Entitlement) error { if err := ent.Validate(); err != nil { return err } _, err := s.db.ExecContext(ctx, `INSERT INTO codes (code_hash, batch_id, entitlement_kind, entitlement_payload, status, created_at) VALUES (?, ?, ?, ?, 'unused', ?)`, codeHash, batchID, string(ent.Kind), string(ent.Payload), time.Now().UTC()) if err != nil { if isDuplicateKey(err) { return ErrDuplicate } return fmt.Errorf("codes.Store.CreateCode: %w", err) } return nil } const selectCodeSQL = `SELECT id, code_hash, batch_id, entitlement_kind, entitlement_payload, status, redeemed_by, redeemed_at, void_reason, created_at FROM codes` func (s *Store) FindByHash(ctx context.Context, codeHash string) (*Code, error) { row := s.db.QueryRowContext(ctx, selectCodeSQL+" WHERE code_hash = ?", codeHash) return scanCode(row) } // FindByHashForUpdate locks the row for tx's duration (mysql: SELECT…FOR // UPDATE; sqlite: no clause needed — the write transaction already // serializes). Call inside the tx passed to Redeem. func (s *Store) FindByHashForUpdate(ctx context.Context, tx *sql.Tx, codeHash string) (*Code, error) { q := selectCodeSQL + " WHERE code_hash = ? " + s.dialect.LockForUpdate() row := tx.QueryRowContext(ctx, q, codeHash) return scanCode(row) } func scanCode(row *sql.Row) (*Code, error) { var c Code var kind, payload string var redeemedBy, voidReason sql.NullString var redeemedAt sql.NullTime err := row.Scan(&c.ID, &c.CodeHash, &c.BatchID, &kind, &payload, &c.Status, &redeemedBy, &redeemedAt, &voidReason, &c.CreatedAt) if err == sql.ErrNoRows { return nil, nil } if err != nil { return nil, fmt.Errorf("codes.Store: scan code: %w", err) } c.Entitlement = Entitlement{Kind: EntitlementKind(kind), Payload: json.RawMessage(payload)} c.RedeemedBy = redeemedBy.String if redeemedAt.Valid { t := redeemedAt.Time c.RedeemedAt = &t } c.VoidReason = voidReason.String return &c, nil } // MarkRedeemed flips a code to redeemed inside tx. Guarded by // "AND status='unused'" so a concurrent winner's write can't be clobbered — // belt-and-suspenders alongside the row lock taken by FindByHashForUpdate. func (s *Store) MarkRedeemed(ctx context.Context, tx *sql.Tx, id int64, redeemerRef string, at time.Time) error { _, err := tx.ExecContext(ctx, `UPDATE codes SET status='redeemed', redeemed_by=?, redeemed_at=? WHERE id=? AND status='unused'`, redeemerRef, at, id) if err != nil { return fmt.Errorf("codes.Store.MarkRedeemed: %w", err) } return nil } // Void marks an unused code void outside any host transaction (an // independent admin action, not part of a redeem flow). Returns false (no // error) if the code was not unused. func (s *Store) Void(ctx context.Context, id int64, reason string) (bool, error) { res, err := s.db.ExecContext(ctx, `UPDATE codes SET status='void', void_reason=? WHERE id=? AND status='unused'`, reason, id) if err != nil { return false, fmt.Errorf("codes.Store.Void: %w", err) } n, _ := res.RowsAffected() return n > 0, nil } // WriteAudit inserts an audit row. Pass tx to keep it inside a caller's // transaction (e.g. Redeem); pass nil to write standalone (e.g. Mint, Void). func (s *Store) WriteAudit(ctx context.Context, tx *sql.Tx, actor, action, target string, meta map[string]any) error { metaJSON := "null" if len(meta) > 0 { b, err := json.Marshal(meta) if err != nil { return fmt.Errorf("codes.Store.WriteAudit: marshal meta: %w", err) } metaJSON = string(b) } type execer interface { ExecContext(context.Context, string, ...any) (sql.Result, error) } var ex execer = s.db if tx != nil { ex = tx } if _, err := ex.ExecContext(ctx, `INSERT INTO codes_audit_log (actor, action, target, meta, at) VALUES (?, ?, ?, ?, ?)`, actor, action, target, metaJSON, time.Now().UTC()); err != nil { return fmt.Errorf("codes.Store.WriteAudit: %w", err) } return nil } func nullableString(s string) any { if s == "" { return nil } return s } // isDuplicateKey recognises unique-constraint violations across the two // supported engines without importing either driver package. func isDuplicateKey(err error) bool { if err == nil { return false } msg := err.Error() return strings.Contains(msg, "Duplicate entry") || strings.Contains(msg, "1062") || strings.Contains(msg, "UNIQUE constraint failed") } ``` - [ ] **Step 13: 跑测试确认通过** Run: `cd ~/code/codes && go test . -run 'TestStoreCreateBatchAndCode|TestStoreVoid|TestStoreWriteAudit' -v` → PASS。 - [ ] **Step 14: 全量编译 + 测试 + go mod tidy** Run: `cd ~/code/codes && go mod tidy && go build ./... && go test ./...` Expected: 编译通过,全部测试 `ok`;`go.mod`/`go.sum` 新增 `modernc.org/sqlite`(仅测试用到)。 - [ ] **Step 15: Commit** ```bash cd ~/code/codes git add dialect.go dialect_test.go migrations/ migrations.go migrations_test.go store.go testdb_test.go store_test.go go.mod go.sum git commit -m "feat: Dialect + 内嵌 mysql/sqlite migrations + Store CRUD(哈希存储/状态机/审计)" ``` --- ### Task 4: Mint — 批次生成(碰撞重试) **Files:** - Create: `mint.go` - Test: `mint_test.go` **Interfaces:** - Consumes: `Store`(Task3)、`GenerateCode`/`Hash`(Task2)、`Entitlement`(Task1)。 - Produces: - `type MintRequest struct{ Channel string; Entitlement Entitlement; Count int; CreatedBy, Note string }` - `type MintResult struct{ BatchID int64; Codes []string; Channel string; Entitlement Entitlement }` - `func Mint(ctx context.Context, store *Store, req MintRequest) (*MintResult, error)` - [ ] **Step 1: 写失败测试** `mint_test.go`: ```go package codes import ( "context" "testing" ) func TestMintGeneratesRequestedCount(t *testing.T) { db := openTestDB(t) s := NewStore(db, DialectSQLite) ent := mustDuration(t, "team", 90) res, err := Mint(context.Background(), s, MintRequest{ Channel: "store", Entitlement: ent, Count: 5, CreatedBy: "webhook:card-store", Note: "batch A", }) if err != nil { t.Fatalf("Mint: %v", err) } if res.BatchID == 0 { t.Fatal("BatchID should be non-zero") } if len(res.Codes) != 5 { t.Fatalf("len(Codes) = %d, want 5", len(res.Codes)) } seen := make(map[string]struct{}) for _, plain := range res.Codes { canonical, err := Canonicalize(plain) if err != nil || canonical != plain { t.Fatalf("code %q not canonical: %v", plain, err) } if _, dup := seen[plain]; dup { t.Fatalf("duplicate plaintext %q", plain) } seen[plain] = struct{}{} row, err := s.FindByHash(context.Background(), Hash(plain)) if err != nil || row == nil { t.Fatalf("FindByHash(%q): row=%v err=%v", plain, row, err) } if row.Status != StatusUnused || row.BatchID != res.BatchID { t.Fatalf("row = %+v", row) } p, err := row.Entitlement.DecodeDuration() if err != nil || p.Plan != "team" || p.Days != 90 { t.Fatalf("entitlement = %+v (err=%v)", p, err) } } } func TestMintRejectsInvalidRequest(t *testing.T) { db := openTestDB(t) s := NewStore(db, DialectSQLite) ent := mustDuration(t, "pro", 30) if _, err := Mint(context.Background(), s, MintRequest{Channel: "store", Entitlement: ent, Count: 0}); err == nil { t.Fatal("Count=0 should error") } if _, err := Mint(context.Background(), s, MintRequest{Channel: "store", Count: 1}); err == nil { t.Fatal("empty Entitlement should error") } } ``` - [ ] **Step 2: 跑测试确认失败** Run: `cd ~/code/codes && go test . -run TestMint -v` Expected: 编译失败——`Mint`/`MintRequest`/`MintResult` 未定义。 - [ ] **Step 3: 写实现** `mint.go`: ```go package codes import ( "context" "fmt" ) // MintRequest describes a batch of Count codes to generate, all sharing one // Entitlement (design doc §9.2: "购买激活码" = pay 收款 + codes mint 发码). type MintRequest struct { Channel string // open string (e.g. "store"/"tg"/"line"/"manual") — host may extend Entitlement Entitlement Count int CreatedBy string Note string } // MintResult carries the plaintext codes — the ONLY time they ever appear. // The caller (webhook handler, admin CLI, purchase-fulfillment handler) is // responsible for delivering them securely; codes never logs or persists // plaintext. type MintResult struct { BatchID int64 Codes []string Channel string Entitlement Entitlement } // Mint generates Count codes for one Entitlement, writes the batch + code // hashes via store, and returns the plaintext codes. Duplicate-hash retries // (birthday collision, astronomically unlikely for 75-bit codes) are handled // automatically up to maxRetries per slot. func Mint(ctx context.Context, store *Store, req MintRequest) (*MintResult, error) { const maxRetries = 10 if req.Count <= 0 { return nil, fmt.Errorf("codes.Mint: count must be > 0, got %d", req.Count) } if err := req.Entitlement.Validate(); err != nil { return nil, fmt.Errorf("codes.Mint: %w", err) } batchID, err := store.CreateBatch(ctx, req.Channel, req.Entitlement, req.CreatedBy, req.Note) if err != nil { return nil, fmt.Errorf("codes.Mint: %w", err) } plaintexts := make([]string, 0, req.Count) for i := 0; i < req.Count; i++ { var code string ok := false for attempt := 0; attempt < maxRetries; attempt++ { c, err := GenerateCode() if err != nil { return nil, fmt.Errorf("codes.Mint: generate: %w", err) } err = store.CreateCode(ctx, Hash(c), batchID, req.Entitlement) if err == ErrDuplicate { continue } if err != nil { return nil, fmt.Errorf("codes.Mint: %w", err) } code, ok = c, true break } if !ok { return nil, fmt.Errorf("codes.Mint: exceeded %d retries for slot %d", maxRetries, i) } plaintexts = append(plaintexts, code) } return &MintResult{BatchID: batchID, Codes: plaintexts, Channel: req.Channel, Entitlement: req.Entitlement}, nil } ``` - [ ] **Step 4: 跑测试确认通过 + 全量** Run: `cd ~/code/codes && go build ./... && go test ./...` Expected: 全 `ok`。 - [ ] **Step 5: Commit** ```bash cd ~/code/codes git add mint.go mint_test.go git commit -m "feat: Mint 批次生成(碰撞重试,明文只出现一次)" ``` --- ### Task 5: Redeem[T] 兑换事务骨架 + VoidCode(本计划核心) **Files:** - Create: `redeem.go` - Test: `redeem_test.go` **Interfaces:** - Consumes: `Store`(Task3)、`Entitlement`/`Status`(Task1)。 - Produces: - `type GrantFunc[T any] func(ctx context.Context, tx *sql.Tx, code Code) (T, error)` - `type RedeemResult[T any] struct{ Idempotent bool; Code Code; Grant T }` - `func Redeem[T any](ctx context.Context, store *Store, tx *sql.Tx, codeHash, redeemerRef string, grant GrantFunc[T]) (*RedeemResult[T], error)` - `func VoidCode(ctx context.Context, store *Store, codeHash, actor, reason string) error` **设计要点**(对应用户给的目标签名 `Redeem(ctx, tx, codeHash, grantFn)`):`tx` 由**宿主**开启并最终 `Commit`/`Rollback`——`Redeem` 本身不管理事务生命周期。这样宿主可以把自己的权益写入(`grant` 回调)和 `Redeem` 内部的码状态翻转放进**同一个事务**,只要两者在同一个 `*sql.DB` 下,提交/回滚就是原子的(设计文档 §9.1 方案 A 的落地)。`grant` 返回任意类型 `T`(Go 泛型),让宿主直接拿到强类型的开通结果(如 `pangolin.SubscriptionID` 或 `jiu.LicenseExpiry`),不用 `any` 断言。 - [ ] **Step 1: 写失败测试** `redeem_test.go`: ```go package codes import ( "context" "database/sql" "testing" "time" ) // setupHostSubs creates a minimal stand-in for a host's own entitlement // table (e.g. pangolin's `subscriptions`), living in the SAME db as codes — // exactly the deployment-A premise this test exercises. func setupHostSubs(t *testing.T, db *sql.DB) { t.Helper() _, err := db.Exec(`CREATE TABLE test_subs (id INTEGER PRIMARY KEY AUTOINCREMENT, user_ref TEXT NOT NULL, expires_at DATETIME NOT NULL)`) if err != nil { t.Fatalf("create test_subs: %v", err) } } // grantDuration is a stand-in GrantFunc: apply "extend by days" against // test_subs, returning the new expiry. func grantDuration(days int) GrantFunc[time.Time] { return func(ctx context.Context, tx *sql.Tx, code Code) (time.Time, error) { p, err := code.Entitlement.DecodeDuration() if err != nil { return time.Time{}, err } newExpiry := time.Now().UTC().AddDate(0, 0, p.Days) if _, err := tx.ExecContext(ctx, `INSERT INTO test_subs (user_ref, expires_at) VALUES (?, ?)`, "placeholder", newExpiry); err != nil { return time.Time{}, err } _ = days return newExpiry, nil } } func mintOne(t *testing.T, s *Store, ent Entitlement) string { t.Helper() res, err := Mint(context.Background(), s, MintRequest{Channel: "manual", Entitlement: ent, Count: 1, CreatedBy: "test"}) if err != nil { t.Fatalf("Mint: %v", err) } return res.Codes[0] } func TestRedeemSuccessAndIdempotent(t *testing.T) { db := openTestDB(t) setupHostSubs(t, db) s := NewStore(db, DialectSQLite) ent := mustDuration(t, "pro", 30) plain := mintOne(t, s, ent) hash := Hash(plain) ctx := context.Background() // First redeem: succeeds, grant runs once. tx, err := db.BeginTx(ctx, nil) if err != nil { t.Fatalf("begin: %v", err) } res, err := Redeem(ctx, s, tx, hash, "user:1", grantDuration(30)) if err != nil { t.Fatalf("Redeem: %v", err) } if res.Idempotent { t.Fatal("first redeem should not be idempotent") } if err := tx.Commit(); err != nil { t.Fatalf("commit: %v", err) } var subCount int db.QueryRow(`SELECT COUNT(*) FROM test_subs`).Scan(&subCount) if subCount != 1 { t.Fatalf("test_subs rows = %d, want 1", subCount) } // Second redeem, same redeemerRef: idempotent, grant NOT re-invoked. tx2, _ := db.BeginTx(ctx, nil) res2, err := Redeem(ctx, s, tx2, hash, "user:1", grantDuration(30)) if err != nil { t.Fatalf("Redeem (idempotent): %v", err) } if !res2.Idempotent { t.Fatal("second redeem by same user should be idempotent") } tx2.Commit() db.QueryRow(`SELECT COUNT(*) FROM test_subs`).Scan(&subCount) if subCount != 1 { t.Fatalf("test_subs rows after idempotent redeem = %d, want still 1 (grant must not re-run)", subCount) } } func TestRedeemDifferentUserFails(t *testing.T) { db := openTestDB(t) setupHostSubs(t, db) s := NewStore(db, DialectSQLite) ent := mustDuration(t, "pro", 30) plain := mintOne(t, s, ent) hash := Hash(plain) ctx := context.Background() tx, _ := db.BeginTx(ctx, nil) if _, err := Redeem(ctx, s, tx, hash, "user:1", grantDuration(30)); err != nil { t.Fatalf("first redeem: %v", err) } tx.Commit() tx2, _ := db.BeginTx(ctx, nil) defer tx2.Rollback() if _, err := Redeem(ctx, s, tx2, hash, "user:2", grantDuration(30)); err != ErrCodeRedeemed { t.Fatalf("err = %v, want ErrCodeRedeemed", err) } } func TestRedeemGrantFailureRollsBackWholeTx(t *testing.T) { db := openTestDB(t) setupHostSubs(t, db) s := NewStore(db, DialectSQLite) ent := mustDuration(t, "pro", 30) plain := mintOne(t, s, ent) hash := Hash(plain) ctx := context.Background() failingGrant := func(ctx context.Context, tx *sql.Tx, code Code) (time.Time, error) { return time.Time{}, sql.ErrTxDone // any error stands in for "host's grant failed" } tx, _ := db.BeginTx(ctx, nil) _, err := Redeem(ctx, s, tx, hash, "user:1", failingGrant) if err == nil { t.Fatal("expected grant error to propagate") } if rbErr := tx.Rollback(); rbErr != nil { t.Fatalf("rollback: %v", rbErr) } // Code must still be unused — the whole tx (code state + grant) rolled back atomically. row, _ := s.FindByHash(ctx, hash) if row.Status != StatusUnused { t.Fatalf("code status after rollback = %s, want unused", row.Status) } var subCount int db.QueryRow(`SELECT COUNT(*) FROM test_subs`).Scan(&subCount) if subCount != 0 { t.Fatalf("test_subs rows after rollback = %d, want 0", subCount) } } func TestRedeemNotFoundAndVoid(t *testing.T) { db := openTestDB(t) setupHostSubs(t, db) s := NewStore(db, DialectSQLite) ent := mustDuration(t, "pro", 30) ctx := context.Background() tx, _ := db.BeginTx(ctx, nil) defer tx.Rollback() if _, err := Redeem(ctx, s, tx, "no-such-hash", "user:1", grantDuration(30)); err != ErrCodeNotFound { t.Fatalf("err = %v, want ErrCodeNotFound", err) } plain := mintOne(t, s, ent) hash := Hash(plain) if err := VoidCode(ctx, s, hash, "admin:1", "compromised batch"); err != nil { t.Fatalf("VoidCode: %v", err) } tx2, _ := db.BeginTx(ctx, nil) defer tx2.Rollback() if _, err := Redeem(ctx, s, tx2, hash, "user:1", grantDuration(30)); err != ErrCodeVoid { t.Fatalf("err = %v, want ErrCodeVoid", err) } // voiding an already-redeemed code is rejected plain2 := mintOne(t, s, ent) hash2 := Hash(plain2) tx3, _ := db.BeginTx(ctx, nil) if _, err := Redeem(ctx, s, tx3, hash2, "user:9", grantDuration(30)); err != nil { t.Fatalf("redeem plain2: %v", err) } tx3.Commit() if err := VoidCode(ctx, s, hash2, "admin:1", "too late"); err != ErrNotVoidable { t.Fatalf("err = %v, want ErrNotVoidable", err) } } ``` - [ ] **Step 2: 跑测试确认失败** Run: `cd ~/code/codes && go test . -run TestRedeem -v` Expected: 编译失败——`Redeem`/`GrantFunc`/`VoidCode` 未定义。 - [ ] **Step 3: 写实现** `redeem.go`: ```go package codes import ( "context" "database/sql" "fmt" "time" ) // GrantFunc performs the host's local entitlement write (extend a pangolin // subscription row, bump a jiu license, …) inside the SAME *sql.Tx as the // code-state flip, so grant + redeem commit atomically as long as the // host's entitlement table lives in the same database as the codes tables // (design doc §9.1 — the entire premise of deployment option A). type GrantFunc[T any] func(ctx context.Context, tx *sql.Tx, code Code) (T, error) // RedeemResult is Redeem's outcome. type RedeemResult[T any] struct { // Idempotent is true when redeemerRef already redeemed this code; Grant // is the zero value in that case — grant is intentionally NOT re-run, so // the host must not assume Grant reflects current state on a replay. Idempotent bool Code Code Grant T } // Redeem executes one redemption attempt inside the caller-owned transaction // tx. The caller owns tx's lifecycle (BeginTx/Commit/Rollback) — this lets // the host fold its own entitlement writes (via grant) and any other // business writes into the exact same local transaction. // // Flow: SELECT…FOR UPDATE (locks the row for tx's duration) → state-machine // check → idempotency short-circuit → grant(ctx, tx, code) → MarkRedeemed → // audit log. Any returned error means the caller must roll back tx; Redeem // itself never commits or rolls back. func Redeem[T any](ctx context.Context, store *Store, tx *sql.Tx, codeHash, redeemerRef string, grant GrantFunc[T]) (*RedeemResult[T], error) { var zero T code, err := store.FindByHashForUpdate(ctx, tx, codeHash) if err != nil { return nil, err } if code == nil { return nil, ErrCodeNotFound } switch code.Status { case StatusRedeemed: if code.RedeemedBy == redeemerRef { return &RedeemResult[T]{Idempotent: true, Code: *code, Grant: zero}, nil } return nil, ErrCodeRedeemed case StatusVoid: return nil, ErrCodeVoid } grantResult, err := grant(ctx, tx, *code) if err != nil { return nil, fmt.Errorf("codes.Redeem: grant: %w", err) } now := time.Now().UTC() if err := store.MarkRedeemed(ctx, tx, code.ID, redeemerRef, now); err != nil { return nil, err } if err := store.WriteAudit(ctx, tx, redeemerRef, "redeem", fmt.Sprintf("code:%d", code.ID), map[string]any{ "batch_id": code.BatchID, "kind": string(code.Entitlement.Kind), }); err != nil { return nil, err } code.Status = StatusRedeemed code.RedeemedBy = redeemerRef code.RedeemedAt = &now return &RedeemResult[T]{Idempotent: false, Code: *code, Grant: grantResult}, nil } // VoidCode marks an unused code void (printing error, compromised batch) so // it can never be redeemed. Standalone admin action — not part of a Redeem // flow, so it manages its own (non-transactional) writes. Returns // ErrCodeNotFound / ErrNotVoidable as appropriate. func VoidCode(ctx context.Context, store *Store, codeHash, actor, reason string) error { code, err := store.FindByHash(ctx, codeHash) if err != nil { return err } if code == nil { return ErrCodeNotFound } if !code.Status.Voidable() { return ErrNotVoidable } ok, err := store.Void(ctx, code.ID, reason) if err != nil { return err } if !ok { return ErrNotVoidable } return store.WriteAudit(ctx, nil, actor, "void", fmt.Sprintf("code:%d", code.ID), map[string]any{"reason": reason}) } ``` - [ ] **Step 4: 跑测试确认通过 + 全量** Run: `cd ~/code/codes && go build ./... && go test ./... -v` Expected:`TestRedeemSuccessAndIdempotent` / `TestRedeemDifferentUserFails` / `TestRedeemGrantFailureRollsBackWholeTx` / `TestRedeemNotFoundAndVoid` 全 PASS,其余任务测试保持绿。 - [ ] **Step 5: Commit** ```bash cd ~/code/codes git add redeem.go redeem_test.go git commit -m "feat: Redeem[T] 兑换事务骨架(锁+CAS+幂等+宿主grant回调)+ VoidCode" ``` --- ### Task 6: RateLimiter + NonceChecker 接口(零依赖默认实现)+ GuardedRedeem **Files:** - Create: `ratelimit.go` - Create: `noncecheck.go` - Create: `guard.go` - Test: `guard_test.go` **Interfaces:** - Produces: - `type RateLimiter interface{ Allowed(ctx, key string) (bool, error); RecordFailure(ctx, key string) error; Reset(ctx, key string) error }` - `type NoopRateLimiter struct{}`(始终放行,零依赖默认值) - `type NonceChecker interface{ SeenOrStore(ctx, nonce string, ttl time.Duration) (bool, error) }` - `type InMemoryNonceChecker struct{...}` · `func NewInMemoryNonceChecker() *InMemoryNonceChecker`(单进程默认值,供 webhook/测试用) - `func GuardedRedeem[T any](ctx, store *Store, limiter RateLimiter, tx *sql.Tx, codeHash, redeemerRef string, grant GrantFunc[T]) (*RedeemResult[T], error)` 这两个接口**只在这一步定义**,是为了让 Task 7 的 `redisx` 子包(Redis 限流 + 去重)和 Task 8 的 webhook 处理器都能实现/依赖同一份契约,而不必反向依赖子包。 - [ ] **Step 1: 写失败测试** `guard_test.go`: ```go package codes import ( "context" "database/sql" "errors" "sync" "testing" "time" ) // fakeLimiter is an in-memory RateLimiter test double counting failures. type fakeLimiter struct { mu sync.Mutex fails map[string]int failMax int resets int } func newFakeLimiter(failMax int) *fakeLimiter { return &fakeLimiter{fails: make(map[string]int), failMax: failMax} } func (f *fakeLimiter) Allowed(_ context.Context, key string) (bool, error) { f.mu.Lock() defer f.mu.Unlock() return f.fails[key] < f.failMax, nil } func (f *fakeLimiter) RecordFailure(_ context.Context, key string) error { f.mu.Lock() defer f.mu.Unlock() f.fails[key]++ return nil } func (f *fakeLimiter) Reset(_ context.Context, key string) error { f.mu.Lock() defer f.mu.Unlock() f.fails[key] = 0 f.resets++ return nil } func TestGuardedRedeemLocksOutAfterFailures(t *testing.T) { db := openTestDB(t) setupHostSubs(t, db) s := NewStore(db, DialectSQLite) limiter := newFakeLimiter(2) ctx := context.Background() grantCalls := 0 grant := GrantFunc[int](func(ctx context.Context, tx *sql.Tx, code Code) (int, error) { grantCalls++ return 0, nil }) // two failed attempts against a nonexistent code hash for i := 0; i < 2; i++ { tx, _ := db.BeginTx(ctx, nil) _, err := GuardedRedeem(ctx, s, limiter, tx, "missing", "user:1", grant) tx.Rollback() if err != ErrCodeNotFound { t.Fatalf("attempt %d: err = %v, want ErrCodeNotFound", i, err) } } // third attempt: locked out before ever touching the DB/grant tx, _ := db.BeginTx(ctx, nil) defer tx.Rollback() _, err := GuardedRedeem(ctx, s, limiter, tx, "missing", "user:1", grant) if err != ErrLocked { t.Fatalf("err = %v, want ErrLocked", err) } if grantCalls != 0 { t.Fatalf("grant should never have been called, got %d calls", grantCalls) } } func TestGuardedRedeemResetsOnSuccess(t *testing.T) { db := openTestDB(t) setupHostSubs(t, db) s := NewStore(db, DialectSQLite) limiter := newFakeLimiter(5) ctx := context.Background() ent := mustDuration(t, "pro", 30) plain := mintOne(t, s, ent) hash := Hash(plain) tx, _ := db.BeginTx(ctx, nil) _, err := GuardedRedeem(ctx, s, limiter, tx, hash, "user:1", grantDuration(30)) if err != nil { t.Fatalf("GuardedRedeem: %v", err) } tx.Commit() if limiter.resets != 1 { t.Fatalf("resets = %d, want 1", limiter.resets) } } func TestNoopRateLimiterNeverBlocks(t *testing.T) { var l RateLimiter = NoopRateLimiter{} ok, err := l.Allowed(context.Background(), "anyone") if err != nil || !ok { t.Fatalf("NoopRateLimiter.Allowed = %v, %v", ok, err) } if err := l.RecordFailure(context.Background(), "anyone"); err != nil { t.Fatalf("RecordFailure: %v", err) } } func TestInMemoryNonceCheckerDedup(t *testing.T) { c := NewInMemoryNonceChecker() ctx := context.Background() dup1, err := c.SeenOrStore(ctx, "n1", time.Minute) if err != nil || dup1 { t.Fatalf("first SeenOrStore: dup=%v err=%v", dup1, err) } dup2, err := c.SeenOrStore(ctx, "n1", time.Minute) if err != nil || !dup2 { t.Fatalf("second SeenOrStore: dup=%v err=%v, want dup=true", dup2, err) } dup3, err := c.SeenOrStore(ctx, "n2", time.Minute) if err != nil || dup3 { t.Fatalf("different nonce: dup=%v err=%v", dup3, err) } _ = errors.New // silence unused import if trimmed later } ``` - [ ] **Step 2: 跑测试确认失败** Run: `cd ~/code/codes && go test . -run 'TestGuardedRedeem|TestNoopRateLimiter|TestInMemoryNonceChecker' -v` Expected: 编译失败——`RateLimiter`/`GuardedRedeem`/`NonceChecker` 未定义。 - [ ] **Step 3: 写实现** `ratelimit.go`: ```go package codes import "context" // RateLimiter guards redemption attempts against brute-force guessing. // NoopRateLimiter (the zero-dependency default) never blocks; production // hosts running Redis should use codes/redisx.RateLimiter instead — kept in // a separate subpackage so importing the core codes package never pulls in // a Redis client. type RateLimiter interface { // Allowed reports whether key (typically redeemerRef) may attempt a // redemption right now. Allowed(ctx context.Context, key string) (bool, error) // RecordFailure registers one failed attempt for key. RecordFailure(ctx context.Context, key string) error // Reset clears key's failure count (called after a successful redeem). Reset(ctx context.Context, key string) error } // NoopRateLimiter never blocks and never errors — the default when a host // doesn't want (or doesn't yet have) rate limiting. type NoopRateLimiter struct{} func (NoopRateLimiter) Allowed(context.Context, string) (bool, error) { return true, nil } func (NoopRateLimiter) RecordFailure(context.Context, string) error { return nil } func (NoopRateLimiter) Reset(context.Context, string) error { return nil } ``` `noncecheck.go`: ```go package codes import ( "context" "sync" "time" ) // NonceChecker deduplicates webhook deliveries. InMemoryNonceChecker is a // single-process default (fine for one webhook instance, or tests); // multi-instance deployments should use codes/redisx.NonceChecker instead. type NonceChecker interface { // SeenOrStore returns true if nonce was already seen (and does NOT // store it again); otherwise stores it with ttl and returns false. SeenOrStore(ctx context.Context, nonce string, ttl time.Duration) (bool, error) } // InMemoryNonceChecker is a sync.Map-backed NonceChecker with lazy TTL // sweep. Not safe across multiple process instances behind a load balancer // — use codes/redisx.NonceChecker there. type InMemoryNonceChecker struct { mu sync.Mutex seen map[string]time.Time } func NewInMemoryNonceChecker() *InMemoryNonceChecker { return &InMemoryNonceChecker{seen: make(map[string]time.Time)} } func (c *InMemoryNonceChecker) SeenOrStore(_ context.Context, nonce string, ttl time.Duration) (bool, error) { c.mu.Lock() defer c.mu.Unlock() now := time.Now() for n, exp := range c.seen { if now.After(exp) { delete(c.seen, n) } } if exp, ok := c.seen[nonce]; ok && now.Before(exp) { return true, nil } c.seen[nonce] = now.Add(ttl) return false, nil } ``` `guard.go`: ```go package codes import ( "context" "database/sql" ) // GuardedRedeem wraps Redeem with a RateLimiter fail-lock, mirroring // pangolin's per-user redeem lockout: ErrLocked is returned without // touching the DB (grant is never invoked) if key has exceeded its failure // budget; any Redeem error records one failure; success or an idempotent // replay resets the counter. func GuardedRedeem[T any](ctx context.Context, store *Store, limiter RateLimiter, tx *sql.Tx, codeHash, redeemerRef string, grant GrantFunc[T]) (*RedeemResult[T], error) { if limiter == nil { limiter = NoopRateLimiter{} } allowed, err := limiter.Allowed(ctx, redeemerRef) if err != nil { return nil, err } if !allowed { return nil, ErrLocked } result, err := Redeem(ctx, store, tx, codeHash, redeemerRef, grant) if err != nil { if recErr := limiter.RecordFailure(ctx, redeemerRef); recErr != nil { return nil, recErr } return nil, err } if resetErr := limiter.Reset(ctx, redeemerRef); resetErr != nil { return nil, resetErr } return result, nil } ``` - [ ] **Step 4: 跑测试确认通过 + 全量** Run: `cd ~/code/codes && go build ./... && go test ./... -v` Expected: 全 PASS(注意 `guard_test.go` 里未用到的 `errors` import 若报错,直接删掉那行 `_ = errors.New` 占位与对应 import——写实现时不要引入不必要的 import)。 - [ ] **Step 5: Commit** ```bash cd ~/code/codes git add ratelimit.go noncecheck.go guard.go guard_test.go git commit -m "feat: RateLimiter/NonceChecker 接口(零依赖默认实现)+ GuardedRedeem 失败锁定" ``` --- ### Task 7: redisx 子包(可选)— Redis 限流 + 去重(miniredis 测试,免 docker) **Files:** - Create: `redisx/ratelimit.go` - Create: `redisx/nonce.go` - Test: `redisx/ratelimit_test.go` - Test: `redisx/nonce_test.go` **Interfaces:** - Consumes: `codes.RateLimiter` / `codes.NonceChecker` 接口(Task6)。 - Produces: - `type redisx.RateLimiter struct{...}` · `func redisx.NewRateLimiter(rdb *redis.Client, prefix string, failMax int, lockDur time.Duration) *RateLimiter`(实现 `codes.RateLimiter`) - `type redisx.NonceChecker struct{...}` · `func redisx.NewNonceChecker(rdb *redis.Client, prefix string) *NonceChecker`(实现 `codes.NonceChecker`) **这是唯一 import Redis 客户端的地方**——不 import `codes/redisx` 的宿主完全不产生 Redis 依赖。逻辑移植自 pangolin `internal/codes/service.go` 的 `redisKeyFail`/`isLocked`/`recordFail`/`clearFail`(失败计数器 + TTL)与 `webhook.go` 的 `checkAndStoreNonce`(`SET NX` 原子去重)。 - [ ] **Step 1: 写失败测试(RateLimiter)** `redisx/ratelimit_test.go`: ```go package redisx_test import ( "context" "testing" "time" "github.com/alicebob/miniredis/v2" "github.com/redis/go-redis/v9" "github.com/wangjia/codes/redisx" ) func newTestRedis(t *testing.T) *redis.Client { t.Helper() mr, err := miniredis.Run() if err != nil { t.Fatalf("miniredis.Run: %v", err) } t.Cleanup(mr.Close) return redis.NewClient(&redis.Options{Addr: mr.Addr()}) } func TestRateLimiterLocksAfterFailMax(t *testing.T) { rdb := newTestRedis(t) rl := redisx.NewRateLimiter(rdb, "test:fail:", 3, time.Hour) ctx := context.Background() for i := 0; i < 3; i++ { allowed, err := rl.Allowed(ctx, "user:1") if err != nil || !allowed { t.Fatalf("attempt %d: allowed=%v err=%v", i, allowed, err) } if err := rl.RecordFailure(ctx, "user:1"); err != nil { t.Fatalf("RecordFailure: %v", err) } } allowed, err := rl.Allowed(ctx, "user:1") if err != nil || allowed { t.Fatalf("after 3 failures: allowed=%v err=%v, want false", allowed, err) } // a different key is unaffected allowed2, _ := rl.Allowed(ctx, "user:2") if !allowed2 { t.Fatal("user:2 should be unaffected by user:1's failures") } } func TestRateLimiterReset(t *testing.T) { rdb := newTestRedis(t) rl := redisx.NewRateLimiter(rdb, "test:fail:", 2, time.Hour) ctx := context.Background() rl.RecordFailure(ctx, "user:1") rl.RecordFailure(ctx, "user:1") if allowed, _ := rl.Allowed(ctx, "user:1"); allowed { t.Fatal("should be locked before reset") } if err := rl.Reset(ctx, "user:1"); err != nil { t.Fatalf("Reset: %v", err) } if allowed, err := rl.Allowed(ctx, "user:1"); err != nil || !allowed { t.Fatalf("after reset: allowed=%v err=%v", allowed, err) } } ``` `redisx/nonce_test.go`: ```go package redisx_test import ( "context" "testing" "time" "github.com/wangjia/codes/redisx" ) func TestNonceCheckerDedup(t *testing.T) { rdb := newTestRedis(t) nc := redisx.NewNonceChecker(rdb, "test:nonce:") ctx := context.Background() dup1, err := nc.SeenOrStore(ctx, "n1", time.Minute) if err != nil || dup1 { t.Fatalf("first: dup=%v err=%v", dup1, err) } dup2, err := nc.SeenOrStore(ctx, "n1", time.Minute) if err != nil || !dup2 { t.Fatalf("second (replay): dup=%v err=%v, want true", dup2, err) } } ``` - [ ] **Step 2: 跑测试确认失败** Run: `cd ~/code/codes && go get github.com/redis/go-redis/v9@latest github.com/alicebob/miniredis/v2@latest && go test ./redisx/... -v` Expected: 编译失败——`redisx` 包不存在。 - [ ] **Step 3: 写实现** `redisx/ratelimit.go`: ```go // Package redisx provides Redis-backed implementations of codes.RateLimiter // and codes.NonceChecker. This is the ONLY package in the module that // imports a Redis client — hosts that don't import redisx never pull Redis // into their dependency graph. package redisx import ( "context" "fmt" "time" "github.com/redis/go-redis/v9" ) // RateLimiter implements codes.RateLimiter with a per-key failure counter + // TTL, ported from pangolin's redeem lockout // (internal/codes/service.go: redisKeyFail/isLocked/recordFail/clearFail). type RateLimiter struct { rdb *redis.Client prefix string failMax int lockDur time.Duration } func NewRateLimiter(rdb *redis.Client, prefix string, failMax int, lockDur time.Duration) *RateLimiter { if failMax <= 0 { failMax = 5 } if lockDur <= 0 { lockDur = time.Hour } if prefix == "" { prefix = "codes:redeem:fail:" } return &RateLimiter{rdb: rdb, prefix: prefix, failMax: failMax, lockDur: lockDur} } func (r *RateLimiter) key(k string) string { return r.prefix + k } func (r *RateLimiter) Allowed(ctx context.Context, key string) (bool, error) { val, err := r.rdb.Get(ctx, r.key(key)).Int() if err == redis.Nil { return true, nil } if err != nil { return false, fmt.Errorf("redisx.RateLimiter.Allowed: %w", err) } return val < r.failMax, nil } func (r *RateLimiter) RecordFailure(ctx context.Context, key string) error { k := r.key(key) pipe := r.rdb.Pipeline() pipe.Incr(ctx, k) pipe.Expire(ctx, k, r.lockDur) if _, err := pipe.Exec(ctx); err != nil { return fmt.Errorf("redisx.RateLimiter.RecordFailure: %w", err) } return nil } func (r *RateLimiter) Reset(ctx context.Context, key string) error { if err := r.rdb.Del(ctx, r.key(key)).Err(); err != nil { return fmt.Errorf("redisx.RateLimiter.Reset: %w", err) } return nil } ``` `redisx/nonce.go`: ```go package redisx import ( "context" "fmt" "time" "github.com/redis/go-redis/v9" ) // NonceChecker implements codes.NonceChecker via Redis SET NX — atomic // check-and-store, safe across multiple webhook-handler instances. Ported // from pangolin's webhook.go: checkAndStoreNonce. type NonceChecker struct { rdb *redis.Client prefix string } func NewNonceChecker(rdb *redis.Client, prefix string) *NonceChecker { if prefix == "" { prefix = "codes:webhook:nonce:" } return &NonceChecker{rdb: rdb, prefix: prefix} } func (c *NonceChecker) SeenOrStore(ctx context.Context, nonce string, ttl time.Duration) (bool, error) { set, err := c.rdb.SetNX(ctx, c.prefix+nonce, "1", ttl).Result() if err != nil { return false, fmt.Errorf("redisx.NonceChecker.SeenOrStore: %w", err) } return !set, nil // SetNX returns true when newly set (not a duplicate) } ``` - [ ] **Step 4: 跑测试确认通过 + 全量** Run: `cd ~/code/codes && go mod tidy && go build ./... && go test ./...` Expected: 全 `ok`;根包(不 import `redisx`)编译产物不含 Redis 客户端符号。 - [ ] **Step 5: Commit** ```bash cd ~/code/codes git add redisx/ go.mod go.sum git commit -m "feat(redisx): 可选 Redis 限流+去重实现(miniredis 测试,免 docker;根包零 Redis 依赖)" ``` --- ### Task 8: webhook 灌码 — 通用 HMAC 签名 + 去重 + 通用权益负载 → Mint **Files:** - Create: `webhook.go` - Test: `webhook_test.go` **Interfaces:** - Consumes: `Store`/`Mint`(Task3/4)、`Canonicalize`/`Hash`(Task2)、`NonceChecker`/`InMemoryNonceChecker`(Task6)。 - Produces: - `func VerifyWebhookSignature(secret []byte, system, timestamp, nonce string, rawBody []byte, gotSig string) error` - `type MintPayload struct{ Code, Channel string; Entitlement Entitlement; Note string }` - `type WebhookHandler struct{...}` · `func NewWebhookHandler(store *Store, nonces NonceChecker, system, secret string, tolerance, nonceTTL time.Duration) *WebhookHandler`(实现 `http.Handler`) **签名选型说明**:pangolin 现有 webhook(`internal/codes/webhook.go`)只对 body 做 HMAC,timestamp/nonce 通过独立请求头校验、不进 MAC。本库改用 **pay-contract 既有的双向签名惯例**(`sign = base64(HMAC_SHA256(secret, system+"\n"+timestamp+"\n"+nonce+"\n"+rawBody))`,见 `~/code/pay-contract/README.md` §3)——把 system/timestamp/nonce 也纳入 MAC,防止头部被篡改而签名仍验证通过;同时让"codes 灌码"与"pay 回调"这两类跨产品 webhook 用同一套验签心智模型,降低多产品接入的认知负担。这是本任务对 pangolin 原实现的一处**有意偏离**,已在 Self-Review 中记录。 - [ ] **Step 1: 写失败测试** `webhook_test.go`: ```go package codes import ( "context" "crypto/hmac" "crypto/sha256" "encoding/base64" "encoding/json" "net/http" "net/http/httptest" "strconv" "strings" "testing" "time" ) func signRequest(t *testing.T, secret, system, ts, nonce string, body []byte) string { t.Helper() mac := hmac.New(sha256.New, []byte(secret)) mac.Write([]byte(system + "\n" + ts + "\n" + nonce + "\n")) mac.Write(body) return base64.StdEncoding.EncodeToString(mac.Sum(nil)) } func newSignedRequest(t *testing.T, secret, system, nonce string, body []byte) *http.Request { t.Helper() ts := strconv.FormatInt(time.Now().Unix(), 10) sig := signRequest(t, secret, system, ts, nonce, body) req := httptest.NewRequest(http.MethodPost, "/webhook/codes", strings.NewReader(string(body))) req.Header.Set("X-Pay-Timestamp", ts) req.Header.Set("X-Pay-Nonce", nonce) req.Header.Set("X-Pay-Sign", sig) return req } func TestWebhookMintsCodeOnValidRequest(t *testing.T) { db := openTestDB(t) s := NewStore(db, DialectSQLite) h := NewWebhookHandler(s, nil, "card-store", "s3cret", 5*time.Minute, time.Hour) ent := mustDuration(t, "pro", 30) payload, _ := json.Marshal(MintPayload{Code: "ABCDEFGHJKMNPQR0", Channel: "store", Entitlement: ent}) req := newSignedRequest(t, "s3cret", "card-store", "nonce-1", payload) rec := httptest.NewRecorder() h.ServeHTTP(rec, req) if rec.Code != http.StatusCreated { t.Fatalf("status = %d, body = %s", rec.Code, rec.Body.String()) } canonical, _ := Canonicalize("ABCDEFGHJKMNPQR0") row, err := s.FindByHash(context.Background(), Hash(canonical)) if err != nil || row == nil { t.Fatalf("code not stored: row=%v err=%v", row, err) } } func TestWebhookReplayedNonceIsIgnored(t *testing.T) { db := openTestDB(t) s := NewStore(db, DialectSQLite) h := NewWebhookHandler(s, nil, "card-store", "s3cret", 5*time.Minute, time.Hour) ent := mustDuration(t, "pro", 30) payload, _ := json.Marshal(MintPayload{Code: "ABCDEFGHJKMNPQR0", Channel: "store", Entitlement: ent}) req1 := newSignedRequest(t, "s3cret", "card-store", "nonce-dup", payload) rec1 := httptest.NewRecorder() h.ServeHTTP(rec1, req1) if rec1.Code != http.StatusCreated { t.Fatalf("first request status = %d", rec1.Code) } req2 := newSignedRequest(t, "s3cret", "card-store", "nonce-dup", payload) rec2 := httptest.NewRecorder() h.ServeHTTP(rec2, req2) if rec2.Code != http.StatusOK { t.Fatalf("replayed nonce status = %d, want 200", rec2.Code) } if !strings.Contains(rec2.Body.String(), "duplicate_ignored") { t.Fatalf("body = %s", rec2.Body.String()) } } func TestWebhookRejectsBadSignature(t *testing.T) { db := openTestDB(t) s := NewStore(db, DialectSQLite) h := NewWebhookHandler(s, nil, "card-store", "s3cret", 5*time.Minute, time.Hour) ent := mustDuration(t, "pro", 30) payload, _ := json.Marshal(MintPayload{Code: "ABCDEFGHJKMNPQR0", Channel: "store", Entitlement: ent}) req := newSignedRequest(t, "WRONG-secret", "card-store", "nonce-2", payload) rec := httptest.NewRecorder() h.ServeHTTP(rec, req) if rec.Code != http.StatusUnauthorized { t.Fatalf("status = %d, want 401", rec.Code) } } func TestWebhookRejectsStaleTimestamp(t *testing.T) { db := openTestDB(t) s := NewStore(db, DialectSQLite) h := NewWebhookHandler(s, nil, "card-store", "s3cret", 5*time.Minute, time.Hour) ent := mustDuration(t, "pro", 30) payload, _ := json.Marshal(MintPayload{Code: "ABCDEFGHJKMNPQR0", Channel: "store", Entitlement: ent}) staleTS := strconv.FormatInt(time.Now().Add(-time.Hour).Unix(), 10) sig := signRequest(t, "s3cret", "card-store", staleTS, "nonce-3", payload) req := httptest.NewRequest(http.MethodPost, "/webhook/codes", strings.NewReader(string(payload))) req.Header.Set("X-Pay-Timestamp", staleTS) req.Header.Set("X-Pay-Nonce", "nonce-3") req.Header.Set("X-Pay-Sign", sig) rec := httptest.NewRecorder() h.ServeHTTP(rec, req) if rec.Code != http.StatusUnauthorized { t.Fatalf("status = %d, want 401", rec.Code) } } func TestWebhookRejectsInvalidEntitlement(t *testing.T) { db := openTestDB(t) s := NewStore(db, DialectSQLite) h := NewWebhookHandler(s, nil, "card-store", "s3cret", 5*time.Minute, time.Hour) payload, _ := json.Marshal(MintPayload{Code: "ABCDEFGHJKMNPQR0", Channel: "store"}) // empty Entitlement req := newSignedRequest(t, "s3cret", "card-store", "nonce-4", payload) rec := httptest.NewRecorder() h.ServeHTTP(rec, req) if rec.Code != http.StatusBadRequest { t.Fatalf("status = %d, want 400", rec.Code) } } ``` - [ ] **Step 2: 跑测试确认失败** Run: `cd ~/code/codes && go test . -run TestWebhook -v` Expected: 编译失败——`WebhookHandler`/`MintPayload`/`VerifyWebhookSignature` 未定义。 - [ ] **Step 3: 写实现** `webhook.go`: ```go package codes import ( "context" "crypto/hmac" "crypto/sha256" "encoding/base64" "encoding/json" "fmt" "io" "net/http" "strconv" "time" ) // VerifyWebhookSignature checks the pay-contract HMAC convention: // // sign = base64(HMAC_SHA256(secret, system+"\n"+timestamp+"\n"+nonce+"\n"+rawBody)) // // shared with pay's own callback signing (~/code/pay-contract §3), so every // cross-product inbound webhook is verified the same way. Binding // system/timestamp/nonce into the MAC (unlike pangolin's original body-only // HMAC) means a tampered header invalidates the signature too. func VerifyWebhookSignature(secret []byte, system, timestamp, nonce string, rawBody []byte, gotSig string) error { mac := hmac.New(sha256.New, secret) mac.Write([]byte(system + "\n" + timestamp + "\n" + nonce + "\n")) mac.Write(rawBody) want := base64.StdEncoding.EncodeToString(mac.Sum(nil)) if !hmac.Equal([]byte(want), []byte(gotSig)) { return fmt.Errorf("codes: webhook signature mismatch") } return nil } func verifyTimestamp(tsStr string, tolerance time.Duration) error { ts, err := strconv.ParseInt(tsStr, 10, 64) if err != nil { return fmt.Errorf("codes: invalid webhook timestamp: %w", err) } diff := time.Since(time.Unix(ts, 0)) if diff < 0 { diff = -diff } if diff > tolerance { return fmt.Errorf("codes: webhook timestamp outside tolerance") } return nil } // MintPayload is the JSON body an external card store posts to mint one // code. Entitlement is the generic descriptor (entitlement.go) — the // webhook never hardcodes plan/days, so the same endpoint serves duration // and quota products alike. type MintPayload struct { Code string `json:"code"` Channel string `json:"channel"` Entitlement Entitlement `json:"entitlement"` Note string `json:"note,omitempty"` } // WebhookHandler implements POST /webhook/codes ingestion from a card // store. Headers follow pay-contract naming: X-Pay-Timestamp / X-Pay-Nonce / // X-Pay-Sign. type WebhookHandler struct { store *Store nonces NonceChecker secret []byte system string timestampTolerance time.Duration nonceTTL time.Duration createdBy string } // NewWebhookHandler creates a handler. Pass nonces=nil to use the // single-process InMemoryNonceChecker default; multi-instance deployments // should pass a codes/redisx.NonceChecker instead. func NewWebhookHandler(store *Store, nonces NonceChecker, system, secret string, tolerance, nonceTTL time.Duration) *WebhookHandler { if nonces == nil { nonces = NewInMemoryNonceChecker() } return &WebhookHandler{ store: store, nonces: nonces, system: system, secret: []byte(secret), timestampTolerance: tolerance, nonceTTL: nonceTTL, createdBy: "webhook:" + system, } } func (h *WebhookHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) { if r.Method != http.MethodPost { http.Error(w, "method not allowed", http.StatusMethodNotAllowed) return } body, err := io.ReadAll(io.LimitReader(r.Body, 64*1024)) if err != nil { http.Error(w, "bad request", http.StatusBadRequest) return } ts := r.Header.Get("X-Pay-Timestamp") nonce := r.Header.Get("X-Pay-Nonce") sig := r.Header.Get("X-Pay-Sign") if ts == "" || nonce == "" || sig == "" { http.Error(w, "missing signature headers", http.StatusBadRequest) return } if err := VerifyWebhookSignature(h.secret, h.system, ts, nonce, body, sig); err != nil { http.Error(w, "signature mismatch", http.StatusUnauthorized) return } if err := verifyTimestamp(ts, h.timestampTolerance); err != nil { http.Error(w, "stale timestamp", http.StatusUnauthorized) return } ctx := r.Context() dup, err := h.nonces.SeenOrStore(ctx, nonce, h.nonceTTL) if err != nil { http.Error(w, "internal error", http.StatusInternalServerError) return } if dup { writeJSON(w, http.StatusOK, map[string]string{"status": "duplicate_ignored"}) return } var payload MintPayload if err := json.Unmarshal(body, &payload); err != nil { http.Error(w, "bad payload", http.StatusBadRequest) return } if payload.Code == "" || payload.Channel == "" { http.Error(w, "missing code/channel", http.StatusBadRequest) return } if err := payload.Entitlement.Validate(); err != nil { http.Error(w, "invalid entitlement: "+err.Error(), http.StatusBadRequest) return } canonical, err := Canonicalize(payload.Code) if err != nil { http.Error(w, "invalid code format", http.StatusBadRequest) return } h.mintOrAck(ctx, w, canonical, payload) } // mintOrAck writes one code (one batch per webhook call, mirroring // pangolin's original behavior) and responds; ErrDuplicate is treated as an // idempotent no-op ack, not an error. func (h *WebhookHandler) mintOrAck(ctx context.Context, w http.ResponseWriter, canonical string, payload MintPayload) { batchID, err := h.store.CreateBatch(ctx, payload.Channel, payload.Entitlement, h.createdBy, payload.Note) if err != nil { http.Error(w, "internal error", http.StatusInternalServerError) return } err = h.store.CreateCode(ctx, Hash(canonical), batchID, payload.Entitlement) if err == ErrDuplicate { writeJSON(w, http.StatusOK, map[string]string{"status": "already_exists"}) return } if err != nil { http.Error(w, "internal error", http.StatusInternalServerError) return } writeJSON(w, http.StatusCreated, map[string]string{"status": "created"}) } func writeJSON(w http.ResponseWriter, status int, v any) { w.Header().Set("Content-Type", "application/json; charset=utf-8") w.WriteHeader(status) _ = json.NewEncoder(w).Encode(v) } ``` - [ ] **Step 4: 跑测试确认通过 + 全量** Run: `cd ~/code/codes && go build ./... && go test ./... -v` Expected: 全部任务的测试(Task1–8)一并跑绿。 - [ ] **Step 5: Commit** ```bash cd ~/code/codes git add webhook.go webhook_test.go git commit -m "feat: webhook 灌码(pay-contract 式通用 HMAC 签名 + 去重 + 通用权益负载 → Mint)" ``` --- ## Self-Review **Spec coverage(用户 P7 范围逐条核对):** - 独立 Go module/包 + 选型理由 → 「部署与模块选型」章节 ✓(独立仓 `github.com/wangjia/codes`,非 pay 子包/非 pangolin 内嵌,理由:依赖隔离 + 设计文档 §9.1 方案 A)。 - 码模型 + 状态机 + 生成器(Crockford Base32+校验位,crypto/rand)+ 哈希存储(SHA-256,明文不落库) → Task1(状态机/错误)+ Task2(生成器,移植 pangolin idgen)+ Task3(Store,`code_hash` 唯一约束,明文只在 `Mint`/webhook 请求体经过内存,从不写库/写日志)✓。 - 兑换事务骨架 `Redeem(ctx, tx, codeHash, grantFn)` → Task5,签名对齐用户给出的形态(`Redeem[T any](ctx, store, tx, codeHash, redeemerRef, grant)`——多出的 `store`/`redeemerRef` 是必要的接收者与幂等键,`grant` 即 `grantFn`),锁(`FindByHashForUpdate`+dialect)、CAS(`MarkRedeemed` 的 `AND status='unused'`)、幂等(同 `redeemerRef` 短路)三者齐全,`TestRedeemGrantFailureRollsBackWholeTx` 专门验证"宿主本地事务"的原子性承诺 ✓。 - 批次 + 审计 → Task3(`CreateBatch`/`WriteAudit`)+ Task4(`Mint` 内的批次生成)✓。 - 发卡店 webhook 灌码(HMAC) → Task8,选用 pay-contract 既有多产品签名惯例(而非原样照抄 pangolin 的 body-only HMAC),偏离已在 Task8 开头注明理由 ✓。 - 通用权益描述符(不硬编码 plan+days,支持时长/额度) → Task1 `Entitlement{Kind,Payload}` + `DurationPayload`/`QuotaPayload`,对应设计文档 §12 的两种 entitlement 形态 ✓。 - Redis 限流(可选,标注) → Task6(接口 + 零依赖默认值)+ Task7(`redisx` 子包,唯一 import Redis 的地方,不引用就不产生依赖)✓,明确标注"可选"。 **未覆盖 / 有意排除(见 Global Constraints 末尾"本计划范围之外"):** admin 批次列表/CSV 导出(pangolin 已有实现,宿主可自行在 `Store` 基础方法上拼,不进本库以保持库精简);pangolin/jiu 迁移到 import 本库(独立后续任务,本计划只交付库本身);独立服务化方案 B、reseller 门户、优惠券变体(设计文档标注 later)。这些都不是用户列出的 P7 范围条目。 **Placeholder scan:** 全部 8 个任务均给出完整 Go 实现 + 完整测试,无 TODO/占位;唯一需要人工确认的是 Task1 Step 0 的 Gitea 建仓(网络操作,不属于代码)。 **Type consistency 关键点:** - `Entitlement`(Task1)→ 贯穿 `Code.Entitlement`(Task3)、`MintRequest.Entitlement`/`MintResult.Entitlement`(Task4)、`GrantFunc[T]` 的 `code Code` 参数(Task5)、`MintPayload.Entitlement`(Task8),全程同一类型,无中途转换丢信息。 - `Status`(Task1)三态与 `store.go`/`redeem.go` 的 SQL `status` 列字符串值(`'unused'`/`'redeemed'`/`'void'`)逐字一致。 - `Redeem`/`GuardedRedeem` 的泛型签名 `[T any]` 在 Task5→Task6(`GuardedRedeem` 包一层)→ 测试(`grantDuration(days int) GrantFunc[time.Time]`)全程一致,未出现 `any` 断言噩梦。 - `Dialect`(Task3)贯穿 `Store`/`FindByHashForUpdate`/`ApplyMigrations`,mysql/sqlite 两分支的 SQL 均已给出(mysql 分支未在 CI 用真实 MySQL 验证——本计划测试全跑 sqlite `:memory:`,mysql 语法只做静态审阅;这与 pangolin 现有 `run_mysql_test.sh` 需要 docker 的取舍一致,MySQL 集成验证留给宿主接入时用真实 MySQL 跑一次 `ApplyMigrations`)。 **一处需要宿主在真正 import 时注意(非本库缺陷,写进这里防止遗忘)**:`Redeem`/`GuardedRedeem` 要求 `tx` 与 `store` 底层 `*sql.DB` 同源,且宿主的 `grant` 回调里的写操作必须使用**传入的同一个 `tx`**(而不是另开一个 `store.db.Exec(...)`)——否则会静默丢失"本地事务"的原子性保证,退化成两个独立事务。这一点在 `GrantFunc` 的类型签名(强制传入 `*sql.Tx` 而非允许拿到 `*sql.DB`)里已经做了预防,但仍建议后续给宿主的接入文档里用大写加粗强调一次。 --- ## 后续阶段(接续 P1 末尾"后续阶段"列表) - P2–P6:见 `2026-07-10-pay-v2-p1-core-model.md` 末尾(Provider 抽象/首批渠道/退款/多账户路由/对账 job)。 - **P7(本计划)**:codes 共享库,独立仓 `github.com/wangjia/codes`,不改动 pay/pangolin/jiu 任何现有代码。 - **P8(later)**:订阅/recurring(4 类 kind)、拒付 chargeback(见设计文档 §5.1)。 - **未编号后续(brain todo,不在 pay 的 P1–P8 序列里)**:pangolin `server/internal/codes/` 迁移为 import `github.com/wangjia/codes`(替换 `plan_id+duration_days` 为 `Entitlement`,`grantFn` 实现 pangolin 的订阅叠加算法);jiu 门店 license 接入同一个库;codes 优惠券变体(设计文档 §7)。均待本计划落地验证后再排期。