pangolin/docs/superpowers/plans/2026-07-10-pangolin-codes-lib-integration.md

# pangolin · codes 共享库接入(激活码逻辑迁移)Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development(推荐)或 superpowers:executing-plans 逐任务实现本计划。步骤用 `- [ ]` checkbox 追踪。

> **设计文档(全景蓝图):** pay 仓 `~/code/pay/docs/pay-v2-unified-gateway-design.html` §9(codes 兑换内核边界)/ §9.1(部署选型 A:共享库嵌入宿主进程,权益表与码表同库同事务)。**上游计划:** pay 仓 `~/code/pay/docs/superpowers/plans/2026-07-10-pay-v2-p7-codes-lib.md`(P7,已完成——库已建成并 push 到 `ssh://git@git.51yanmei.com:2222/wangjia/codes.git`,HEAD=`c772d525679441d0579df6e309deba2d60254ab5`)。**宿主约束:** 本仓 `CLAUDE.md`「数据层:多数据库」节(DB_DRIVER=mysql|sqlite 双方言、迁移分两套、golang-migrate、禁 MySQL 专属构造)。

**Goal:** 把 pangolin `server/internal/codes/` 的激活码逻辑(铸码/兑换状态机/webhook 灌码/防爆破锁)迁移到共享库 `github.com/wangjia/codes` 上,pangolin 作为该库的**第一个真实宿主**完成验证。迁移是**验证优先**的:全部工作在新分支 `feat/codes-lib-integration` 上进行,以本地验证(build + 全量测试 + 行为等价测试)收尾,**不合并、不部署**——合并等用户验收后另行处理。

**Architecture:** `internal/codes` 包**保留原 import 路径与全部公共 API**(`NewStore`/`NewService`/`RedeemRequest`/`BatchRequest`/`NewRedeemHandler`/`NewWebhookHandler`/`CtxKeyUserID`/`PlanCode`/`BatchChannel`/`ExportCSV`…),内部改为薄适配层:兑换走 `codes.GuardedRedeem`(宿主事务 + grant 回调在**同一个 `*sql.Tx`** 里复刻现有订阅叠加算法),铸码走 `codes.Mint`,防爆破走 `codes/redisx.RateLimiter`,webhook 保留现有 `X-Pangolin-*` HMAC 协议作为薄壳直调库的铸码原语。plan_id+duration_days 语义映射为 `codes.Entitlement{Kind:duration, Payload:{plan:"<plans.code>", days:N}}`——**库保持通用,适配在 pangolin 侧**。旧表更名封存 + 库自建新表 + Go 侧幂等回填,双方言(mysql/sqlite)全覆盖。

---

## 关键决策(已定,含依据)

| 决策点 | 结论 | 依据 |
|---|---|---|
| **模块引入方式** | `require github.com/wangjia/codes v0.0.0-20260710045055-c772d5256794`(pin 到 gitea HEAD `c772d52` 的伪版本),**不用 `replace`** | 用 replace 指 `~/code/codes` 会让 CI(容器内无此路径)必挂,且掩盖「真实宿主拉真实版本」的验证目标。代价:`github.com/wangjia/codes` 实际托管在 gitea,需一次性 git `insteadOf` 精确映射 + `GOPRIVATE`(见 Task 0;已实测无此配置时 `go list -m` 直接失败) |
| **schema 策略** | 方案 (a):**旧表更名封存(`codes`→`legacy_codes`、`code_batches`→`legacy_code_batches`,pangolin 迁移 000020)→ 库自建新表(`codes.ApplyMigrations`,由 `cmd/migrate up` 在 golang-migrate 之后调)→ Go 侧幂等回填**。旧表数据封存不删(retire 留到验收后的 cleanup) | 库拥有自己的 schema(嵌入迁移文件,表名 `codes`/`codes_batches`/`codes_audit_log`)——**库的 `codes` 表与 pangolin 现有 `codes` 表同名冲突**,必须先更名让位。改库适配旧表不可行(库不暴露表名定制) |
| **回填形态** | **Go 函数**(`internal/codes/backfill.go`),非 SQL 迁移文件 | 回填要做 plan_id→plans.code 字符串映射 + JSON payload 构造 + `redeemed_by BIGINT`→`"user:<id>"` 格式化,SQL 双方言各写一套 JSON 拼接极易漂移;Go 一份代码天然双方言、可单测、可幂等重跑 |
| **webhook** | **保留 pangolin 现有端点与 HMAC 协议**(`POST /v1/webhook/store/codes`,`X-Pangolin-Signature: sha256=<hex>` 仅对 body 做 MAC),改为薄壳直调库的铸码原语(`CreateBatchTx`+`CreateCodeTx` 单事务)。**不采用**库的 `NewWebhookHandler`(pay-contract 式 `system\nts\nnonce\nbody` MAC) | 调用方是**外部发卡店**(用 `WEBHOOK_SECRET` 按旧协议签名;仓内 grep `X-Pangolin-Signature` 只有测试命中,说明签名方实现在仓外)。验证分支上换签名协议 = 强迫外部调用方同步升级,是 breaking change,超出验证范围。**后续**若接 pay v2 生态再在新路径挂库 handler、与发卡店协调切换(标注于 Task 6) |
| **admin 面**(batch 列表/CSV/void) | 留在宿主侧(P7 计划明确排除进库),`ListBatches`/`VoidBatch` SQL 改指新表,行为不变 | `admin/services.go` 已经隔着 `CodesService` 接口消费,改动被封在 `internal/codes` 内 |
| **审计双写** | grant 回调内继续写旧 `audit_log`(admin 审计页数据源);库自身在同事务写 `codes_audit_log`(增量,不冲突) | `admin/store.go:188,197` 读 `audit_log`——不双写则 admin 审计页丢兑换记录,破坏行为等价 |

## 已知行为差异(有意为之,验收时说明)

1. **防爆破 Redis key 变化**:`redeem:fail:<uid>` → `redeem:fail:user:<uid>`(redisx.RateLimiter 以 redeemerRef 为 key)。部署瞬间在途失败计数清零,无安全影响。
2. **幂等重放现在会清零失败计数**(GuardedRedeem 对 Idempotent 成功也 Reset;旧代码幂等路径提前 return 不清零,service.go:162-171)。合法用户重放清计数,无害。
3. **MarkRedeemed 有 CAS 校验了**(库 store.go:171-200 检查 RowsAffected;旧实现 store.go:159-168 不检查,竞态输家会静默双发订阅)。严格更安全。
4. **CreateBatch 全成或全无**(库 Mint 单事务;旧实现 batch 行先落库、后续失败留孤儿 batch,service.go:342-345)。严格更干净。webhook 同理(旧 I2:重复码留孤儿 batch,webhook.go:145-158;新壳单事务无孤儿)。
5. **依赖版本抬升**:`modernc.org/sqlite` 1.18.1→1.38.2、`go-redis/v9` 9.20.1→9.21.0(MVS 取库要求的高版本)。全量测试守门(Task 9)。

## Global Constraints

- **分支**:所有 commit 落在 `feat/codes-lib-integration`(从 `main` 切出)。**终点是本地验证通过,不 merge / 不 push 部署 / 不动 pangolin1**。
- **公共 API 冻结**:`internal/codes` 对外的类型与构造函数签名**一个不改**——`cmd/server/main.go:296-300`、`cmd/codegen/main.go:81-87`、`internal/admin/router.go:56-57`、`internal/admin/services.go:53-110`、`internal/auth/middleware.go:45`、`internal/usage/handler.go:19` 六处调用点**零改动、原样编译**。
- **双方言铁律**(本仓 CLAUDE.md 数据层节):新增 SQL 一律 `?` 占位、时间 Go 端算好传参、不用 `NOW()`/`FIELD()`/`UTC_TIMESTAMP()`;pangolin 自己的迁移双方言各一套(`server/migrations/{mysql,sqlite}/000020_*`);行为测试优先 sqlite `:memory:`(免 docker、进普通 CI),mysql 走既有 `-tags integration`。
- **明文码不落库不进日志**(两边库都遵守,迁移不得破坏)。
- 每个 Task 结束:`cd /Users/wangjia/code/pangolin/server && go build ./... && go vet ./... && go test ./...` 全绿再 commit(遵循「每刀提交」惯例)。
- **不改机器/CI 配置**:Task 0 的 git 全局配置仅限**本开发机**一条精确映射;CI runner(nas)主机的同款配置是**用户协调项**(见 Task 0 Step 4 与 Self-Review),本计划不代做。
- **范围外**:客户端改动、部署、删除 legacy 表、webhook 协议切换到 pay-contract、jiu/dudu 接入。

---

## Task 0: Preflight — 现状锚点 + 分支 + 模块接线

**目的**:把后续任务依赖的「现状事实」钉死(全部已在 2026-07-10 逐文件核实,执行者可抽查),建分支,打通 `go get github.com/wangjia/codes`。

### 现状锚点(cite file:line,执行前抽查 2-3 条确认没漂移)

**旧表(迁移对象)**
- `server/migrations/mysql/000003_codes.up.sql` / `server/migrations/sqlite/000003_codes.up.sql`:`code_batches`(channel ENUM/CHECK `store|tg|line|manual`, created_by, note, created_at)+ `codes`(code_hash CHAR(64) UNIQUE, **plan_id FK plans**, **duration_days INT**, batch_id FK, status ENUM, **redeemed_by BIGINT(用户 id)**, redeemed_at;**无 created_at、无 void_reason**)。
- 当前迁移最高号 **000019**(`server/internal/store/sqlite_migrate_test.go:33` 断言 `version = 19`)→ 本计划新增 **000020**。
- pangolin 已存哈希:`codes.code_hash` = SHA-256 hex(`internal/codes/generator.go:33-37`);库的 `internal/idgen` 正是从 pangolin `internal/idgen` 移植(同 16 字符 Crockford Base32 + 校验字符、同 `HashCode`)→ **code_hash 原样 passthrough,零转换**。

**旧实现(行为基准)**
- 兑换:`server/internal/codes/service.go:116-226`(`Redeem`:锁检查→canonicalize→ReadCommitted 事务→SELECT FOR UPDATE→幂等短路→MarkRedeemed→applySubscription→audit→commit→清失败计数)。
- **时长叠加算法**(grant 回调必须逐字复刻):`service.go:235-287` `applySubscription` —— 同 plan 有活跃订阅 → 取该 plan 最晚到期的一条,`expires_at = max(expires_at, now) + days`(`store.go:214-233 ExtendSubscription`,Go 端算日期);无同 plan 活跃订阅 → 新建一行,`expires_at = max(now, latestSamePlan) + days`,`source='code'`(`store.go:238-261 CreateSubscription`)。
- 防爆破:`service.go:60-102`(Redis key `redeem:fail:<uid>`,INCR+EXPIRE,`val >= failMax` 即锁;rdb==nil 时全部 no-op)。
- 审计:`service.go:199-208` 写 `audit_log`(actor=`user:<id>`,action=`redeem`,target=`code_hash:<前16>...`,meta={plan,duration_days,batch_id,sub_id}),**失败不中断事务**。
- webhook:`server/internal/codes/webhook.go:72-167`(挂载于 `cmd/server/main.go:363` `POST /v1/webhook/store/codes`;HMAC 仅对 body,`X-Pangolin-Signature: sha256=<hex>`,webhook.go:172-195;时间窗 ±tolerance webhook.go:199-218;nonce Redis SETNX **先存后铸**,webhook.go:103-113;payload `{code,plan,duration_days,note}`)。**仓内无调用方代码**(grep `X-Pangolin-Signature` 仅测试文件命中)→ 调用方为外部发卡店。
- admin 面:`internal/codes/admin_support.go:25-70 ListBatches`(code_batches LEFT JOIN codes 聚合计数)、`:74-85 VoidBatch`;经 `internal/admin/services.go` 的 `CodesService` 接口消费。
- CSV:`internal/codes/export.go`(纯内存转换,不碰表,**零改动**)。

**装配点(必须原样编译)**
- `cmd/server/main.go:296-300`(NewStore/NewService/NewRedeemHandler/NewWebhookHandler)、`:363`(webhook 路由)。
- `cmd/codegen/main.go:81-87`(NewStore + NewService(store, **nil**, …) + CreateBatch —— **rdb 为 nil 必须继续可用**)。
- `internal/admin/router.go:56-57`、`internal/auth/middleware.go:45`(`codes.CtxKeyUserID`)、`internal/usage/handler.go:19`。

**测试资产(守门物)**
- `internal/codes/generator_test.go`(无 tag,纯算法)——委托给库后必须原样通过。
- `internal/codes/webhook_test.go`(无 tag,签名/时间戳/nonce 拒绝路径,不碰 DB)——薄壳保留协议后必须原样通过。
- `internal/codes/service_test.go`(`//go:build integration`,mysql testcontainers)——`applySchema`(:95-)自建旧表 DDL,需改为「plans/subscriptions/users/audit_log DDL + `codes.ApplyMigrations`」(Task 8)。
- `internal/store/sqlite_migrate_test.go:33,38`(version=19、表清单含 `code_batches`,`codes`)与 `internal/store/sqlite_stores_test.go:193-260`(`TestSQLite_CodesRedeemFlow` 直调旧 Store 方法)——Task 1 / Task 7 更新。
- CI:`.gitea/workflows/ci.yml:123-143`(go build+vet+test 在 `golang:1.25` 容器,挂宿主缓存 `$HOME/.cache/pangolin-ci/gomod`)、`:172-183`(integration 直接跑在 runner 宿主机)→ **两处都要能解析新依赖**(见 Step 4)。

**库 API(已逐文件核实,任务代码按此签名写)**
- `codes.ApplyMigrations(ctx, db *sql.DB, dialect codes.Dialect) error`;`codes.DialectMySQL`/`codes.DialectSQLite`。
- `codes.NewStore(db *sql.DB, dialect codes.Dialect) *codes.Store`;Store 方法:`BeginTx(ctx)`、`CreateBatchTx(ctx, tx, channel string, ent Entitlement, createdBy, note string) (int64, error)`、`CreateCodeTx(ctx, tx, codeHash string, batchID int64, ent Entitlement) error`、`FindByHash`、`Void`、`WriteAudit`。
- `codes.Mint(ctx, store, MintRequest{Channel string; Entitlement; Count int; CreatedBy, Note string}) (*MintResult{BatchID; Codes []string; …}, error)`。
- `codes.Redeem[T any](ctx, store, tx, codeHash, redeemerRef string, grant GrantFunc[T]) (*RedeemResult[T]{Idempotent bool; Code; Grant T}, error)`;`GrantFunc[T] func(ctx, tx *sql.Tx, code Code) (T, error)`;`codes.GuardedRedeem[T](ctx, store, limiter RateLimiter, tx, hash, ref, grant)`(limiter 传 nil → Noop)。
- `codes.NewDurationEntitlement(plan string, days int) (Entitlement, error)`;`Entitlement.DecodeDuration() (DurationPayload{Plan string; Days int}, error)`。
- 哨兵错误:`codes.ErrDuplicate/ErrCodeNotFound/ErrCodeRedeemed/ErrCodeVoid/ErrInvalidCode/ErrLocked/ErrNotVoidable`。
- `codes.GenerateCode() (string, error)` / `codes.Canonicalize(string) (string, error)` / `codes.Hash(string) string`。
- `redisx.NewRateLimiter(rdb *redis.Client, prefix string, failMax int, lockDur time.Duration) *RateLimiter`(实现 `codes.RateLimiter`;`Allowed` 为 `val < failMax`)/ `redisx.NewNonceChecker(rdb, prefix) *NonceChecker`(`SeenOrStore(ctx, nonce, ttl) (seen bool, err error)`,SETNX)。
- 库表结构(`migrations/{mysql,sqlite}/000001_codes.up.sql`):`codes_batches(id, channel, entitlement_kind, entitlement_payload, created_by, note, created_at)`;`codes(id, code_hash UNIQUE, batch_id, entitlement_kind, entitlement_payload, status, redeemed_by VARCHAR/TEXT, redeemed_at, void_reason, created_at)`;`codes_audit_log(id, actor, action, target, meta, at)`;自带追踪表 `codes_schema_migrations`。

### Steps

- [ ] **Step 1: 切分支**

```bash
cd /Users/wangjia/code/pangolin
git checkout main && git pull
git checkout -b feat/codes-lib-integration
```

- [ ] **Step 2: 本机一次性 go 模块解析配置**(精确映射单仓,不映射整个 `github.com/wangjia/`,避免误伤真 GitHub 仓库)

```bash
git config --global url."ssh://git@git.51yanmei.com:2222/wangjia/codes.git".insteadOf "https://github.com/wangjia/codes"
go env -w GOPRIVATE=github.com/wangjia/codes
# 验证可解析(应打印 v0.0.0-20260710045055-c772d5256794 或更新):
cd /Users/wangjia/code/pangolin/server && go list -m github.com/wangjia/codes@c772d525679441d0579df6e309deba2d60254ab5
```

- [ ] **Step 3: pin 依赖**

```bash
cd /Users/wangjia/code/pangolin/server
go get github.com/wangjia/codes@c772d525679441d0579df6e309deba2d60254ab5
go mod tidy
go build ./... && go test ./...   # 依赖抬升(modernc.org/sqlite 1.38.2)后的全量回归,先于任何代码改动
```

若 `go test` 因 sqlite 抬升出现回归:**停下修复/上报**,不带病继续。

- [ ] **Step 4: CI 协调项(登记,不执行)**——在 PR 描述/交付说明里写明:CI runner(nas)宿主机需要同款 Step 2 两条配置 + 一次 `GOMODCACHE="$HOME/.cache/pangolin-ci/gomod" go mod download github.com/wangjia/codes`(预热容器挂载的模块缓存;`go.sum` 已入库,容器内命中缓存后无需再联网)。**未配置前,推分支的 CI go jobs 会失败——这是预期,验收时说明。**

- [ ] **Step 5: commit**

```bash
git add server/go.mod server/go.sum
git commit -m "feat(server): 接入 github.com/wangjia/codes 共享库依赖(pin c772d52)(#codes-lib)"
```

---

### Task 1: 迁移 000020 — 旧码表更名封存(双方言)

**Files:**
- Create: `server/migrations/mysql/000020_codes_lib_legacy_rename.up.sql` / `.down.sql`
- Create: `server/migrations/sqlite/000020_codes_lib_legacy_rename.up.sql` / `.down.sql`
- Modify: `server/internal/store/sqlite_migrate_test.go`

**Interfaces:** 无 Go 接口;schema 事件:`codes`→`legacy_codes`、`code_batches`→`legacy_code_batches`(为库的同名 `codes` 表让位)。

- [ ] **Step 1: 先改测试(失败先行)** —— `sqlite_migrate_test.go`:
  - `:33` 附近 `if v != 19` → `if v != 20`(错误消息同步)。
  - `:38` 表清单里 `"code_batches", "codes"` → `"legacy_code_batches", "legacy_codes"`。

```bash
cd /Users/wangjia/code/pangolin/server && ./run_sqlite_test.sh   # 预期 FAIL(version=19、legacy 表不存在)
```

- [ ] **Step 2: 写迁移**

`server/migrations/mysql/000020_codes_lib_legacy_rename.up.sql`:
```sql
-- 旧激活码表更名封存:共享库 github.com/wangjia/codes 拥有自己的 `codes` 表(同名冲突),
-- 新表由 codes.ApplyMigrations 建(cmd/migrate up 内),数据经 Go 侧幂等回填(internal/codes/backfill.go)。
-- legacy_* 只封存不删,retire 留到验收后的 cleanup。
RENAME TABLE codes TO legacy_codes;
RENAME TABLE code_batches TO legacy_code_batches;
```

`.down.sql`:
```sql
RENAME TABLE legacy_code_batches TO code_batches;
RENAME TABLE legacy_codes TO codes;
```

`server/migrations/sqlite/000020_codes_lib_legacy_rename.up.sql`:
```sql
-- 同 mysql 版注释;sqlite ≥3.25 的 RENAME 会自动更新其他表 FK 引用。
ALTER TABLE codes RENAME TO legacy_codes;
ALTER TABLE code_batches RENAME TO legacy_code_batches;
```

`.down.sql`:
```sql
ALTER TABLE legacy_code_batches RENAME TO code_batches;
ALTER TABLE legacy_codes RENAME TO codes;
```

- [ ] **Step 3: 验证 + commit**

```bash
cd /Users/wangjia/code/pangolin/server && ./run_sqlite_test.sh && go build ./... && go test ./internal/store/
git add server/migrations server/internal/store/sqlite_migrate_test.go
git commit -m "feat(server): 迁移000020 旧码表更名封存 legacy_*(为 codes 库表让位)(#codes-lib)"
```

> 注意:`TestSQLiteMigrateUpDown` 同时验证 down 干净回滚——000020 down 是纯 RENAME 回去,天然可逆。库自建的 `codes_*` 新表不归 golang-migrate 管(down 不删它们),这是有意的:库拥有自己的 schema 生命周期。

---

### Task 2: cmd/migrate 接线 — golang-migrate 之后跑库迁移

**Files:**
- Modify: `server/internal/store/migrate.go`(新增 `ApplyCodesLibMigrations`)
- Modify: `server/cmd/migrate/main.go`(`up` 分支追加调用)
- Test: `server/internal/store/codes_lib_migrate_test.go`(新)

**Interfaces:**
- Produces: `func ApplyCodesLibMigrations(ctx context.Context, database *sql.DB, driver string) error`

- [ ] **Step 1: 失败测试** `server/internal/store/codes_lib_migrate_test.go`:

```go
package store_test

import (
	"context"
	"testing"

	"github.com/wangjia/pangolin/server/internal/config"
	"github.com/wangjia/pangolin/server/internal/store"
)

// TestApplyCodesLibMigrations verifies the shared codes library's tables are
// created on top of a fully-migrated pangolin sqlite DB (post-000020, the
// legacy tables are renamed away so the lib's `codes` table name is free).
func TestApplyCodesLibMigrations(t *testing.T) {
	ctx := context.Background()
	db, err := store.Open(&config.Config{Driver: "sqlite", DSN: ":memory:"})
	if err != nil {
		t.Fatalf("open: %v", err)
	}
	defer db.Close()
	if err := store.MigrateUp(db, "sqlite"); err != nil {
		t.Fatalf("MigrateUp: %v", err)
	}

	if err := store.ApplyCodesLibMigrations(ctx, db, "sqlite"); err != nil {
		t.Fatalf("ApplyCodesLibMigrations: %v", err)
	}
	// 幂等:重复调用不报错(库自带 codes_schema_migrations 追踪表)。
	if err := store.ApplyCodesLibMigrations(ctx, db, "sqlite"); err != nil {
		t.Fatalf("ApplyCodesLibMigrations 2nd: %v", err)
	}

	for _, tbl := range []string{"codes", "codes_batches", "codes_audit_log", "codes_schema_migrations"} {
		var name string
		if err := db.QueryRow(
			`SELECT name FROM sqlite_master WHERE type='table' AND name=?`, tbl,
		).Scan(&name); err != nil {
			t.Errorf("lib table %q missing: %v", tbl, err)
		}
	}
}
```

```bash
cd /Users/wangjia/code/pangolin/server && go test ./internal/store/ -run TestApplyCodesLibMigrations   # FAIL:undefined
```

- [ ] **Step 2: 实现** —— `server/internal/store/migrate.go` 追加(import 加 `"context"`、`libcodes "github.com/wangjia/codes"`):

```go
// ApplyCodesLibMigrations creates/updates the shared codes library's own
// tables (codes / codes_batches / codes_audit_log, tracked by the lib's
// codes_schema_migrations). Runs AFTER pangolin's golang-migrate set — 000020
// must have renamed the legacy `codes` table away first. Idempotent.
func ApplyCodesLibMigrations(ctx context.Context, database *sql.DB, driver string) error {
	d := libcodes.DialectMySQL
	if db.Normalize(driver) == "sqlite" {
		d = libcodes.DialectSQLite
	}
	return libcodes.ApplyMigrations(ctx, database, d)
}
```

`server/cmd/migrate/main.go` 的 `case "up":` 在 `store.MigrateUp` 成功后追加(import 加 `"context"`):

```go
	case "up":
		if err := store.MigrateUp(db, driver); err != nil {
			log.Fatalf("migrate up: %v", err)
		}
		if err := store.ApplyCodesLibMigrations(context.Background(), db, driver); err != nil {
			log.Fatalf("migrate up (codes lib): %v", err)
		}
		log.Println("migrate: up — done")
```

- [ ] **Step 3: 验证 + commit**

```bash
cd /Users/wangjia/code/pangolin/server && go build ./... && go test ./internal/store/ && bash ../scripts/e2e-smoke.sh   # e2e 冒烟里 migrate up 会真跑到新代码
git add server/internal/store/migrate.go server/internal/store/codes_lib_migrate_test.go server/cmd/migrate/main.go
git commit -m "feat(server): cmd/migrate up 接入 codes 库自建迁移(ApplyCodesLibMigrations)(#codes-lib)"
```

(若 e2e-smoke 本地跑不了 openssl/python 依赖,允许跳过、在 Task 9 终验时补;go test 必须绿。)

---

### Task 3: 幂等回填 — legacy_* → 库新表

**Files:**
- Create: `server/internal/codes/backfill.go`
- Test: `server/internal/codes/backfill_test.go`(新,无 build tag,sqlite `:memory:`)
- Modify: `server/cmd/migrate/main.go`(`up` 再追加回填调用)

**Interfaces:**
- Produces: `func BackfillLegacy(ctx context.Context, database *sql.DB) (int, error)` —— 返回本次迁移的 code 行数;legacy 表不存在(全新库)→ `(0, nil)`;重复跑 → `(0, nil)`。

**映射规格(硬性)**:

| legacy | 新表 | 规则 |
|---|---|---|
| `legacy_code_batches.id` | `codes_batches.id` | **保留原 id**(admin 面/审计里的 batch_id 引用不断裂;两方言都允许对 AUTO_INCREMENT/AUTOINCREMENT 列显式插 id,后续自增自动越过) |
| `legacy_code_batches.channel` | `codes_batches.channel` | 原样(新列是开放字符串) |
| —(legacy batch 无权益) | `codes_batches.entitlement_*` | 取该 batch **第一条 code** 的 plan/days 合成 `{"plan":"<plans.code>","days":N}`;空 batch 合成 `{"plan":"unknown","days":0}`(batch 级权益仅信息性,兑换只读 code 级) |
| `legacy_codes.plan_id` + `duration_days` | `codes.entitlement_kind='duration'` + payload | `plan` = JOIN `plans.code` 得到的字符串(`free`/`pro`/`team`) |
| `legacy_codes.code_hash` | `codes.code_hash` | **passthrough**(同一 idgen 血统,零转换);幂等键 |
| `legacy_codes.status` | `codes.status` | 字符串同值 passthrough(`unused/redeemed/void`) |
| `legacy_codes.redeemed_by BIGINT` | `codes.redeemed_by TEXT` | 非 NULL → `"user:<id>"`(与新兑换路径的 redeemerRef 同格式,幂等判定才能衔接);NULL → NULL |
| —(legacy code 无 created_at) | `codes.created_at` | 取所属 batch 的 `created_at` |
| — | `codes.void_reason` | NULL |

- [ ] **Step 1: 失败测试** `server/internal/codes/backfill_test.go`:

```go
package codes_test

import (
	"context"
	"database/sql"
	"testing"
	"time"

	"github.com/wangjia/pangolin/server/internal/codes"
	"github.com/wangjia/pangolin/server/internal/config"
	"github.com/wangjia/pangolin/server/internal/store"
)

func openMigratedSQLite(t *testing.T) *sql.DB {
	t.Helper()
	db, err := store.Open(&config.Config{Driver: "sqlite", DSN: ":memory:"})
	if err != nil {
		t.Fatalf("open: %v", err)
	}
	t.Cleanup(func() { _ = db.Close() })
	if err := store.MigrateUp(db, "sqlite"); err != nil {
		t.Fatalf("migrate: %v", err)
	}
	if err := store.ApplyCodesLibMigrations(context.Background(), db, "sqlite"); err != nil {
		t.Fatalf("lib migrate: %v", err)
	}
	return db
}

func TestBackfillLegacy(t *testing.T) {
	ctx := context.Background()
	db := openMigratedSQLite(t)

	// 造 legacy 数据(000020 之后 legacy 表空壳存在,直插即可)。plans 已 seed(000007)。
	var proID int64
	if err := db.QueryRow(`SELECT id FROM plans WHERE code='pro'`).Scan(&proID); err != nil {
		t.Fatalf("plan: %v", err)
	}
	batchAt := time.Date(2026, 5, 1, 8, 0, 0, 0, time.UTC)
	if _, err := db.Exec(
		`INSERT INTO legacy_code_batches (id, channel, created_by, note, created_at) VALUES (7, 'manual', 'admin:1', 'may batch', ?)`,
		batchAt); err != nil {
		t.Fatalf("seed batch: %v", err)
	}
	redeemedAt := time.Date(2026, 6, 2, 9, 30, 0, 0, time.UTC)
	seed := []struct {
		id         int64
		hash       string
		status     string
		redeemedBy any
		redeemedAt any
	}{
		{101, "hash-unused-000000000000000000000000000000000000000000000000000001", "unused", nil, nil},
		{102, "hash-redeemed-0000000000000000000000000000000000000000000000000002", "redeemed", int64(42), redeemedAt},
		{103, "hash-void-00000000000000000000000000000000000000000000000000000003", "void", nil, nil},
	}
	for _, c := range seed {
		if _, err := db.Exec(
			`INSERT INTO legacy_codes (id, code_hash, plan_id, duration_days, batch_id, status, redeemed_by, redeemed_at)
			 VALUES (?, ?, ?, 30, 7, ?, ?, ?)`,
			c.id, c.hash, proID, c.status, c.redeemedBy, c.redeemedAt); err != nil {
			t.Fatalf("seed code %d: %v", c.id, err)
		}
	}

	n, err := codes.BackfillLegacy(ctx, db)
	if err != nil {
		t.Fatalf("BackfillLegacy: %v", err)
	}
	if n != 3 {
		t.Fatalf("migrated = %d, want 3", n)
	}

	// batch:id 保留 + 权益合成自第一条 code。
	var kind, payload string
	if err := db.QueryRow(
		`SELECT entitlement_kind, entitlement_payload FROM codes_batches WHERE id=7`).Scan(&kind, &payload); err != nil {
		t.Fatalf("batch row: %v", err)
	}
	if kind != "duration" {
		t.Errorf("batch kind = %q", kind)
	}
	if payload != `{"plan":"pro","days":30}` {
		t.Errorf("batch payload = %s", payload)
	}

	// code:redeemed_by 映射 + created_at 取 batch 时间 + status passthrough。
	var status, rby, cpayload string
	var cat time.Time
	if err := db.QueryRow(
		`SELECT status, redeemed_by, entitlement_payload, created_at FROM codes WHERE code_hash=?`,
		seed[1].hash).Scan(&status, &rby, &cpayload, &cat); err != nil {
		t.Fatalf("code row: %v", err)
	}
	if status != "redeemed" || rby != "user:42" {
		t.Errorf("status=%q redeemed_by=%q", status, rby)
	}
	if cpayload != `{"plan":"pro","days":30}` {
		t.Errorf("code payload = %s", cpayload)
	}
	if !cat.Equal(batchAt) {
		t.Errorf("created_at = %v, want batch created_at %v", cat, batchAt)
	}

	// 幂等:重复跑迁 0 行、不重不错。
	n2, err := codes.BackfillLegacy(ctx, db)
	if err != nil || n2 != 0 {
		t.Fatalf("re-run: n=%d err=%v, want 0,nil", n2, err)
	}
	var cnt int
	if err := db.QueryRow(`SELECT COUNT(*) FROM codes`).Scan(&cnt); err != nil || cnt != 3 {
		t.Fatalf("codes count = %d (err=%v), want 3", cnt, err)
	}
}

func TestBackfillLegacyNoLegacyTables(t *testing.T) {
	// 全新库(未来 legacy 表 retire 后)也不报错。用一个没跑 pangolin 迁移、只有库表的 DB 模拟。
	ctx := context.Background()
	db, err := store.Open(&config.Config{Driver: "sqlite", DSN: ":memory:"})
	if err != nil {
		t.Fatalf("open: %v", err)
	}
	defer db.Close()
	if err := store.ApplyCodesLibMigrations(ctx, db, "sqlite"); err != nil {
		t.Fatalf("lib migrate: %v", err)
	}
	n, err := codes.BackfillLegacy(ctx, db)
	if err != nil || n != 0 {
		t.Fatalf("n=%d err=%v, want 0,nil", n, err)
	}
}
```

```bash
cd /Users/wangjia/code/pangolin/server && go test ./internal/codes/ -run TestBackfill   # FAIL:undefined BackfillLegacy
```

- [ ] **Step 2: 实现** `server/internal/codes/backfill.go`(要点:**先读全量入内存、关游标,再写**——同一事务单连接上边迭代 rows 边 Exec 在 mysql 驱动上会打架;逐行 `SELECT COUNT` 幂等判重,双方言零分叉):

```go
package codes

import (
	"context"
	"database/sql"
	"encoding/json"
	"fmt"
	"time"

	dbx "github.com/wangjia/pangolin/server/internal/db"
)

// BackfillLegacy copies legacy_codes / legacy_code_batches rows (renamed away
// by migration 000020) into the shared library's codes / codes_batches
// tables. Idempotent: batches keyed by preserved id, codes keyed by the
// unique code_hash; rows already present are skipped. Returns the number of
// code rows migrated. If the legacy tables don't exist (fresh install after
// the eventual legacy cleanup), it is a no-op.
func BackfillLegacy(ctx context.Context, database *sql.DB) (int, error) {
	exists, err := legacyTablesExist(ctx, database)
	if err != nil {
		return 0, fmt.Errorf("codes.BackfillLegacy: probe legacy tables: %w", err)
	}
	if !exists {
		return 0, nil
	}

	type legacyBatch struct {
		id        int64
		channel   string
		createdBy string
		note      sql.NullString
		createdAt time.Time
	}
	type legacyCode struct {
		id         int64
		hash       string
		planCode   string
		days       int
		batchID    int64
		status     string
		redeemedBy sql.NullInt64
		redeemedAt sql.NullTime
	}

	// ── 读阶段:全量取出、关闭游标(不能在同事务连接上边迭代边写)──
	var batches []legacyBatch
	rows, err := database.QueryContext(ctx,
		`SELECT id, channel, created_by, note, created_at FROM legacy_code_batches ORDER BY id`)
	if err != nil {
		return 0, fmt.Errorf("codes.BackfillLegacy: read batches: %w", err)
	}
	for rows.Next() {
		var b legacyBatch
		if err := rows.Scan(&b.id, &b.channel, &b.createdBy, &b.note, &b.createdAt); err != nil {
			rows.Close()
			return 0, fmt.Errorf("codes.BackfillLegacy: scan batch: %w", err)
		}
		batches = append(batches, b)
	}
	if err := rows.Err(); err != nil {
		rows.Close()
		return 0, err
	}
	rows.Close()

	var lcodes []legacyCode
	rows, err = database.QueryContext(ctx,
		`SELECT c.id, c.code_hash, p.code, c.duration_days, c.batch_id, c.status, c.redeemed_by, c.redeemed_at
		   FROM legacy_codes c JOIN plans p ON p.id = c.plan_id ORDER BY c.id`)
	if err != nil {
		return 0, fmt.Errorf("codes.BackfillLegacy: read codes: %w", err)
	}
	for rows.Next() {
		var c legacyCode
		if err := rows.Scan(&c.id, &c.hash, &c.planCode, &c.days, &c.batchID, &c.status, &c.redeemedBy, &c.redeemedAt); err != nil {
			rows.Close()
			return 0, fmt.Errorf("codes.BackfillLegacy: scan code: %w", err)
		}
		lcodes = append(lcodes, c)
	}
	if err := rows.Err(); err != nil {
		rows.Close()
		return 0, err
	}
	rows.Close()

	// batch id → (payload, createdAt):batch 权益取其第一条 code 合成。
	batchAt := make(map[int64]time.Time, len(batches))
	batchPayload := make(map[int64]string, len(batches))
	for _, b := range batches {
		batchAt[b.id] = b.createdAt
	}
	for _, c := range lcodes {
		if _, ok := batchPayload[c.batchID]; !ok {
			batchPayload[c.batchID] = durationPayloadJSON(c.planCode, c.days)
		}
	}

	// ── 写阶段:单事务,全成或全无;逐行判重保证幂等。──
	tx, err := database.BeginTx(ctx, nil)
	if err != nil {
		return 0, fmt.Errorf("codes.BackfillLegacy: begin: %w", err)
	}
	defer tx.Rollback()

	for _, b := range batches {
		var n int
		if err := tx.QueryRowContext(ctx,
			`SELECT COUNT(*) FROM codes_batches WHERE id = ?`, b.id).Scan(&n); err != nil {
			return 0, fmt.Errorf("codes.BackfillLegacy: probe batch %d: %w", b.id, err)
		}
		if n > 0 {
			continue
		}
		payload, ok := batchPayload[b.id]
		if !ok {
			payload = durationPayloadJSON("unknown", 0) // 空批次:信息性占位
		}
		var note any
		if b.note.Valid {
			note = b.note.String
		}
		if _, err := tx.ExecContext(ctx,
			`INSERT INTO codes_batches (id, channel, entitlement_kind, entitlement_payload, created_by, note, created_at)
			 VALUES (?, ?, 'duration', ?, ?, ?, ?)`,
			b.id, b.channel, payload, b.createdBy, note, b.createdAt.UTC()); err != nil {
			return 0, fmt.Errorf("codes.BackfillLegacy: insert batch %d: %w", b.id, err)
		}
	}

	migrated := 0
	for _, c := range lcodes {
		var n int
		if err := tx.QueryRowContext(ctx,
			`SELECT COUNT(*) FROM codes WHERE code_hash = ?`, c.hash).Scan(&n); err != nil {
			return 0, fmt.Errorf("codes.BackfillLegacy: probe code %d: %w", c.id, err)
		}
		if n > 0 {
			continue
		}
		var redeemedBy, redeemedAt any
		if c.redeemedBy.Valid {
			redeemedBy = fmt.Sprintf("user:%d", c.redeemedBy.Int64)
		}
		if c.redeemedAt.Valid {
			redeemedAt = c.redeemedAt.Time.UTC()
		}
		createdAt, ok := batchAt[c.batchID]
		if !ok {
			createdAt = time.Now()
		}
		if _, err := tx.ExecContext(ctx,
			`INSERT INTO codes (id, code_hash, batch_id, entitlement_kind, entitlement_payload, status, redeemed_by, redeemed_at, void_reason, created_at)
			 VALUES (?, ?, ?, 'duration', ?, ?, ?, ?, NULL, ?)`,
			c.id, c.hash, c.batchID, durationPayloadJSON(c.planCode, c.days),
			c.status, redeemedBy, redeemedAt, createdAt.UTC()); err != nil {
			return 0, fmt.Errorf("codes.BackfillLegacy: insert code %d: %w", c.id, err)
		}
		migrated++
	}

	if err := tx.Commit(); err != nil {
		return 0, fmt.Errorf("codes.BackfillLegacy: commit: %w", err)
	}
	return migrated, nil
}

func durationPayloadJSON(plan string, days int) string {
	b, _ := json.Marshal(struct {
		Plan string `json:"plan"`
		Days int    `json:"days"`
	}{plan, days})
	return string(b)
}

// legacyTablesExist probes for legacy_codes per dialect (sqlite_master vs
// information_schema) — no error-swallowing "SELECT and see" hacks.
func legacyTablesExist(ctx context.Context, database *sql.DB) (bool, error) {
	var n int
	if dbx.DialectForDB(database).Name() == "sqlite" {
		err := database.QueryRowContext(ctx,
			`SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name='legacy_codes'`).Scan(&n)
		return n > 0, err
	}
	err := database.QueryRowContext(ctx,
		`SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name = 'legacy_codes'`).Scan(&n)
	return n > 0, err
}
```

- [ ] **Step 3: 接进 cmd/migrate** —— `up` 分支在 `ApplyCodesLibMigrations` 之后:

```go
		n, err := codes.BackfillLegacy(context.Background(), db)
		if err != nil {
			log.Fatalf("migrate up (codes backfill): %v", err)
		}
		if n > 0 {
			log.Printf("migrate: codes backfill — %d legacy codes migrated", n)
		}
```

(import 加 `"github.com/wangjia/pangolin/server/internal/codes"`。)

- [ ] **Step 4: 验证 + commit**

```bash
cd /Users/wangjia/code/pangolin/server && go build ./... && go test ./internal/codes/ -run TestBackfill && go test ./...
git add server/internal/codes/backfill.go server/internal/codes/backfill_test.go server/cmd/migrate/main.go
git commit -m "feat(server): legacy 码表 → codes 库新表的幂等回填(Go 双方言)(#codes-lib)"
```

---

### Task 4: Store 换芯 + CreateBatch 走库 Mint + 生成器委托

**Files:**
- Modify: `server/internal/codes/store.go`(Store 挂库 store;删除被库取代的方法)
- Modify: `server/internal/codes/generator.go`(委托库)
- Modify: `server/internal/codes/service.go`(仅 `CreateBatch` 部分)
- Test: `server/internal/codes/service_sqlite_test.go`(新,无 build tag)

**Interfaces:**
- `NewStore(db *sql.DB) *Store` **签名不变**;Store 内部新增字段 `lib *libcodes.Store`。
- `Service.CreateBatch(ctx, BatchRequest) (*BatchResult, error)` **签名不变**,内部走 `libcodes.Mint`。
- `GenerateCode`/`Canonicalize`/`Hash` 委托 `libcodes`;`var ErrDuplicate = libcodes.ErrDuplicate`(别名同一哨兵,`errors.Is` 跨层成立)。
- **本 Task 删除**:`Store.CreateBatch`/`Store.CreateCode`/`Store.CodeExistsByHash`(webhook Task 6 会改用新原语;若删除导致 webhook.go 编译失败,把 webhook.go 里的调用点临时注释性重写放到 Task 6——**不行**,必须每步可编译:因此本 Task 先**保留** `Store.CreateBatch/CreateCode/CodeExistsByHash` 原样(它们写 legacy 表,已无人生产调用但 webhook.go 还引用),Task 6 重写 webhook 后、Task 7 一并删除)。

- [ ] **Step 1: 失败测试** `server/internal/codes/service_sqlite_test.go`(第一批只测 CreateBatch):

```go
package codes_test

import (
	"context"
	"testing"
	"time"

	"github.com/wangjia/pangolin/server/internal/codes"
)

// 依赖 openMigratedSQLite(完整迁移链:pangolin 000001-000020 → 库表)——
// 从 backfill_test.go 挪到共享 helper 文件 sqlite_helper_test.go(见 Step 1 末尾说明)。
func TestCreateBatchViaLib(t *testing.T) {
	ctx := context.Background()
	db := openMigratedSQLite(t)
	store := codes.NewStore(db)
	svc := codes.NewService(store, nil, 5, time.Hour) // rdb=nil:cmd/codegen 的真实用法

	res, err := svc.CreateBatch(ctx, codes.BatchRequest{
		PlanCode: codes.PlanPro, DurationDays: 30, Count: 5,
		Channel: codes.ChannelManual, Note: "t", CreatedBy: "admin:1",
	})
	if err != nil {
		t.Fatalf("CreateBatch: %v", err)
	}
	if len(res.Codes) != 5 || res.BatchID == 0 {
		t.Fatalf("res = %+v", res)
	}

	// 码落在库的新表里,明文不落库,权益为 duration payload。
	var cnt int
	if err := db.QueryRow(`SELECT COUNT(*) FROM codes WHERE batch_id=?`, res.BatchID).Scan(&cnt); err != nil || cnt != 5 {
		t.Fatalf("new codes rows = %d (err=%v), want 5", cnt, err)
	}
	var kind, payload string
	if err := db.QueryRow(`SELECT entitlement_kind, entitlement_payload FROM codes_batches WHERE id=?`, res.BatchID).Scan(&kind, &payload); err != nil {
		t.Fatalf("batch: %v", err)
	}
	if kind != "duration" || payload != `{"plan":"pro","days":30}` {
		t.Fatalf("kind=%q payload=%s", kind, payload)
	}
	for _, plain := range res.Codes {
		var n int
		if err := db.QueryRow(`SELECT COUNT(*) FROM codes WHERE code_hash=?`, codes.Hash(plain)).Scan(&n); err != nil || n != 1 {
			t.Fatalf("hash lookup for %q: n=%d err=%v", plain, n, err)
		}
	}

	// 未知 plan 仍报错(旧行为 service.go:336-339)。
	if _, err := svc.CreateBatch(ctx, codes.BatchRequest{
		PlanCode: "nope", DurationDays: 30, Count: 1, Channel: codes.ChannelManual, CreatedBy: "x",
	}); err == nil {
		t.Fatal("unknown plan should error")
	}
}
```

(把 `openMigratedSQLite` 从 backfill_test.go 挪到共享 helper 文件 `server/internal/codes/sqlite_helper_test.go`,backfill_test.go 与本文件共用,避免重名。)

```bash
cd /Users/wangjia/code/pangolin/server && go test ./internal/codes/ -run TestCreateBatchViaLib   # FAIL:落的是 legacy 表/编译错
```

- [ ] **Step 2: 实现**

`store.go` 头部(import 加 `libcodes "github.com/wangjia/codes"`),Store 与 NewStore 改为:

```go
type Store struct {
	db      *sql.DB
	dialect dbx.Dialect
	lib     *libcodes.Store
}

// NewStore creates a Store backed by the given connection pool (MySQL or SQLite).
func NewStore(db *sql.DB) *Store {
	d := dbx.DialectForDB(db)
	libD := libcodes.DialectMySQL
	if d.Name() == "sqlite" {
		libD = libcodes.DialectSQLite
	}
	return &Store{db: db, dialect: d, lib: libcodes.NewStore(db, libD)}
}

// Lib exposes the shared library store (used by Service / webhook shim).
func (s *Store) Lib() *libcodes.Store { return s.lib }
```

`generator.go`:三个函数体改为委托 `libcodes.GenerateCode()` / `libcodes.Canonicalize(code)` / `libcodes.Hash(canonical)`;`ErrDuplicate` 改 `var ErrDuplicate = libcodes.ErrDuplicate`(删除 `errors.New`,pangolin `internal/idgen` 的 import 从本文件移除——**不删 `internal/idgen` 包本身**,别处可能引用,Task 9 清点)。

`service.go` 的 `CreateBatch`(service.go:332-383)替换为:

```go
// CreateBatch generates Count activation codes via the shared library's Mint
// (all-or-nothing: batch + code hashes commit in one tx) and returns the
// plaintext codes — the only time they ever appear.
func (svc *Service) CreateBatch(ctx context.Context, req BatchRequest) (*BatchResult, error) {
	// 未知 plan 先拒(行为等价:旧实现先查 GetPlanID)。
	if _, err := svc.store.GetPlanID(ctx, req.PlanCode); err != nil {
		return nil, fmt.Errorf("CreateBatch: unknown plan %s: %w", req.PlanCode, err)
	}
	ent, err := libcodes.NewDurationEntitlement(string(req.PlanCode), req.DurationDays)
	if err != nil {
		return nil, fmt.Errorf("CreateBatch: %w", err)
	}
	res, err := libcodes.Mint(ctx, svc.store.Lib(), libcodes.MintRequest{
		Channel:     string(req.Channel),
		Entitlement: ent,
		Count:       req.Count,
		CreatedBy:   req.CreatedBy,
		Note:        req.Note,
	})
	if err != nil {
		return nil, fmt.Errorf("CreateBatch: %w", err)
	}
	return &BatchResult{
		BatchID:      res.BatchID,
		Codes:        res.Codes,
		PlanCode:     req.PlanCode,
		DurationDays: req.DurationDays,
		Channel:      req.Channel,
	}, nil
}
```

(service.go import 加 `libcodes "github.com/wangjia/codes"`。)

- [ ] **Step 3: 验证 + commit**

```bash
cd /Users/wangjia/code/pangolin/server && go build ./... && go test ./internal/codes/ && go test ./...
git add server/internal/codes/
git commit -m "feat(server): CreateBatch/生成器切换到 codes 库(Mint 单事务全成或全无)(#codes-lib)"
```

> `generator_test.go` 必须原样全绿(算法同源);若有失败即库移植有偏差,停下上报。

---

### Task 5: Redeem 换芯 — GuardedRedeem + grant 回调复刻订阅叠加

**Files:**
- Modify: `server/internal/codes/service.go`(Service 结构/NewService/Redeem/applySubscription/grant)
- Modify: `server/internal/codes/store.go`(新增 `GetPlanIDTx`)
- Test: `server/internal/codes/service_sqlite_test.go`(追加兑换用例)

**Interfaces:**
- `NewService(store *Store, rdb *redis.Client, failMax int, lockDur time.Duration) *Service` **签名不变**;内部 rdb!=nil → `redisx.NewRateLimiter(rdb, "redeem:fail:", failMax, lockDur)`,nil → nil(GuardedRedeem 自动 Noop——cmd/codegen 场景)。
- `Service.Redeem(ctx, RedeemRequest) (*RedeemResult, *apierr.Error)` **签名与语义不变**。
- Produces: `func (s *Store) GetPlanIDTx(ctx context.Context, tx *sql.Tx, code PlanCode) (int64, error)`。
- 错误映射表(必须逐条):lib `ErrLocked`→`apierr.ErrLocked`;`ErrCodeNotFound`→`apierr.ErrCodeNotFound`;`ErrCodeRedeemed`→`apierr.ErrCodeRedeemed`;`ErrCodeVoid`→`apierr.ErrCodeVoid`;canonicalize 失败→`apierr.ErrInvalidCode`(+记一次失败);其余→`apierr.ErrInternal`。

- [ ] **Step 1: 失败测试**(追加到 `service_sqlite_test.go`;helper 文件加 seedUser):

`sqlite_helper_test.go` 追加:

```go
func seedUser(t *testing.T, db *sql.DB, id int64) {
	t.Helper()
	if _, err := db.Exec(
		`INSERT INTO users (id, uuid, email, pw_hash, dp_uuid, status, created_at)
		 VALUES (?, ?, ?, 'x', ?, 'active', ?)`,
		id, fmt.Sprintf("u-%d", id), fmt.Sprintf("u%d@example.com", id), fmt.Sprintf("dp-%d", id),
		time.Now().UTC()); err != nil {
		t.Fatalf("seed user: %v", err)
	}
}
```

(import `"database/sql"`, `"fmt"`, `"time"`。)

用例(与 mysql 集成测试 service_test.go:198-449 的断言同源,搬到 sqlite 常跑):

```go
func newRedeemFixture(t *testing.T) (*sql.DB, *codes.Service, string) {
	t.Helper()
	db := openMigratedSQLite(t)
	seedUser(t, db, 1)
	seedUser(t, db, 2)
	store := codes.NewStore(db)
	svc := codes.NewService(store, nil, 5, time.Hour)
	res, err := svc.CreateBatch(context.Background(), codes.BatchRequest{
		PlanCode: codes.PlanPro, DurationDays: 30, Count: 1,
		Channel: codes.ChannelManual, CreatedBy: "t",
	})
	if err != nil {
		t.Fatalf("mint: %v", err)
	}
	return db, svc, res.Codes[0]
}

func TestRedeemCreatesSubscription(t *testing.T) {
	ctx := context.Background()
	db, svc, plain := newRedeemFixture(t)

	r, apiErr := svc.Redeem(ctx, codes.RedeemRequest{UserID: 1, Code: plain})
	if apiErr != nil {
		t.Fatalf("redeem: %v", apiErr)
	}
	if r.Idempotent || r.PlanCode != codes.PlanPro || r.DurationDays != 30 || r.SubscriptionID == 0 {
		t.Fatalf("result = %+v", r)
	}
	wantMin := time.Now().UTC().AddDate(0, 0, 29)
	if r.ExpiresAt.Before(wantMin) {
		t.Errorf("expires %v, want ≥ ~30d out", r.ExpiresAt)
	}
	// 订阅真落库(source='code'),码翻转 + redeemed_by 是 "user:1"。
	var src string
	var exp time.Time
	if err := db.QueryRow(`SELECT source, expires_at FROM subscriptions WHERE id=?`, r.SubscriptionID).Scan(&src, &exp); err != nil || src != "code" {
		t.Fatalf("sub: src=%q err=%v", src, err)
	}
	var status, rby string
	if err := db.QueryRow(`SELECT status, redeemed_by FROM codes WHERE code_hash=?`, codes.Hash(mustCanonical(t, plain))).Scan(&status, &rby); err != nil {
		t.Fatalf("code: %v", err)
	}
	if status != "redeemed" || rby != "user:1" {
		t.Errorf("status=%q redeemed_by=%q", status, rby)
	}
	// 旧式审计行仍写 audit_log(admin 审计页数据源)。
	var audits int
	if err := db.QueryRow(`SELECT COUNT(*) FROM audit_log WHERE action='redeem' AND actor='user:1'`).Scan(&audits); err != nil || audits != 1 {
		t.Errorf("audit_log redeem rows = %d (err=%v), want 1", audits, err)
	}
}

func mustCanonical(t *testing.T, code string) string {
	t.Helper()
	c, err := codes.Canonicalize(code)
	if err != nil {
		t.Fatalf("canonicalize: %v", err)
	}
	return c
}

func TestRedeemIdempotentSameUser(t *testing.T) {
	ctx := context.Background()
	_, svc, plain := newRedeemFixture(t)
	if _, apiErr := svc.Redeem(ctx, codes.RedeemRequest{UserID: 1, Code: plain}); apiErr != nil {
		t.Fatalf("first: %v", apiErr)
	}
	r2, apiErr := svc.Redeem(ctx, codes.RedeemRequest{UserID: 1, Code: plain})
	if apiErr != nil {
		t.Fatalf("second: %v", apiErr)
	}
	if !r2.Idempotent || r2.PlanCode != codes.PlanPro || r2.DurationDays != 30 {
		t.Fatalf("r2 = %+v", r2)
	}
	if !r2.ExpiresAt.IsZero() {
		t.Errorf("idempotent replay must omit ExpiresAt (old contract), got %v", r2.ExpiresAt)
	}
}

func TestRedeemOtherUserRejected(t *testing.T) {
	ctx := context.Background()
	_, svc, plain := newRedeemFixture(t)
	if _, apiErr := svc.Redeem(ctx, codes.RedeemRequest{UserID: 1, Code: plain}); apiErr != nil {
		t.Fatalf("first: %v", apiErr)
	}
	_, apiErr := svc.Redeem(ctx, codes.RedeemRequest{UserID: 2, Code: plain})
	if apiErr == nil || apiErr.Code != "CODE_REDEEMED" {
		t.Fatalf("apiErr = %+v, want CODE_REDEEMED", apiErr)
	}
}

func TestRedeemSamePlanExtends(t *testing.T) {
	ctx := context.Background()
	db, svc, plain := newRedeemFixture(t)
	// 预置同 plan 活跃订阅,到期在未来 10 天 → 兑换后应为 +10+30 天(max(expires,now)+days)。
	var proID int64
	if err := db.QueryRow(`SELECT id FROM plans WHERE code='pro'`).Scan(&proID); err != nil {
		t.Fatalf("plan: %v", err)
	}
	base := time.Now().UTC().AddDate(0, 0, 10).Truncate(time.Second)
	var subID int64
	res, err := db.Exec(`INSERT INTO subscriptions (user_id, plan_id, expires_at, source, created_at) VALUES (1, ?, ?, 'code', ?)`,
		proID, base, time.Now().UTC())
	if err != nil {
		t.Fatalf("seed sub: %v", err)
	}
	subID, _ = res.LastInsertId()

	r, apiErr := svc.Redeem(ctx, codes.RedeemRequest{UserID: 1, Code: plain})
	if apiErr != nil {
		t.Fatalf("redeem: %v", apiErr)
	}
	if r.SubscriptionID != subID {
		t.Fatalf("extended sub id = %d, want %d (extend, not create)", r.SubscriptionID, subID)
	}
	want := base.AddDate(0, 0, 30)
	if !r.ExpiresAt.Equal(want) {
		t.Errorf("expires = %v, want %v", r.ExpiresAt, want)
	}
	var cnt int
	if err := db.QueryRow(`SELECT COUNT(*) FROM subscriptions WHERE user_id=1`).Scan(&cnt); err != nil || cnt != 1 {
		t.Errorf("subs = %d, want 1 (extended in place)", cnt)
	}
}

func TestRedeemCrossPlanCreatesNew(t *testing.T) {
	ctx := context.Background()
	db, svc, plain := newRedeemFixture(t) // 码是 pro
	var teamID int64
	if err := db.QueryRow(`SELECT id FROM plans WHERE code='team'`).Scan(&teamID); err != nil {
		t.Fatalf("plan: %v", err)
	}
	if _, err := db.Exec(`INSERT INTO subscriptions (user_id, plan_id, expires_at, source, created_at) VALUES (1, ?, ?, 'code', ?)`,
		teamID, time.Now().UTC().AddDate(0, 0, 90), time.Now().UTC()); err != nil {
		t.Fatalf("seed team sub: %v", err)
	}
	r, apiErr := svc.Redeem(ctx, codes.RedeemRequest{UserID: 1, Code: plain})
	if apiErr != nil {
		t.Fatalf("redeem: %v", apiErr)
	}
	var cnt int
	if err := db.QueryRow(`SELECT COUNT(*) FROM subscriptions WHERE user_id=1`).Scan(&cnt); err != nil || cnt != 2 {
		t.Fatalf("subs = %d, want 2 (new pro sub beside team)", cnt)
	}
	wantMin := time.Now().UTC().AddDate(0, 0, 29)
	if r.ExpiresAt.Before(wantMin) {
		t.Errorf("new pro sub expires %v, want ~30d (NOT stacked on team's 90d)", r.ExpiresAt)
	}
}

func TestRedeemInvalidFormat(t *testing.T) {
	ctx := context.Background()
	_, svc, _ := newRedeemFixture(t)
	_, apiErr := svc.Redeem(ctx, codes.RedeemRequest{UserID: 1, Code: "not-a-code"})
	if apiErr == nil || apiErr.Code != "INVALID_CODE" {
		t.Fatalf("apiErr = %+v, want INVALID_CODE", apiErr)
	}
}

func TestRedeemNotFound(t *testing.T) {
	ctx := context.Background()
	_, svc, _ := newRedeemFixture(t)
	// 结构合法但不存在的码:生成一个不入库的。
	plain, err := codes.GenerateCode()
	if err != nil {
		t.Fatal(err)
	}
	_, apiErr := svc.Redeem(ctx, codes.RedeemRequest{UserID: 1, Code: plain})
	if apiErr == nil || apiErr.Code != "CODE_NOT_FOUND" {
		t.Fatalf("apiErr = %+v, want CODE_NOT_FOUND", apiErr)
	}
}
```

(`apierr.Error.Code` 字段名以 `internal/apierr/apierr.go:91-115` 为准——`ErrInvalidCode`=INVALID_CODE、`ErrCodeNotFound`=CODE_NOT_FOUND、`ErrCodeRedeemed`=CODE_REDEEMED、`ErrCodeVoid`=CODE_VOID、`ErrLocked` 对应 handler.go:72 里的 `ACCOUNT_LOCKED`,写测试前打开确认常量拼写。)

```bash
cd /Users/wangjia/code/pangolin/server && go test ./internal/codes/ -run 'TestRedeem'   # FAIL:旧实现查 legacy 表(已改名)必炸
```

- [ ] **Step 2: 实现** —— `service.go` 重写 Redeem 相关(保留 RedeemRequest/RedeemResult 原型;删除 redisKeyFail/isLocked/recordFail/clearFail 四个手写 Redis 函数与 auditMeta 的 `cr *CodeRow` 依赖):

```go
import (
	// 原有 imports 基础上:
	"errors"
	"strconv"

	libcodes "github.com/wangjia/codes"
	"github.com/wangjia/codes/redisx"
)

// Service handles activation-code redemption on top of the shared codes lib.
type Service struct {
	store   *Store
	limiter libcodes.RateLimiter // nil → GuardedRedeem 内部 Noop(cmd/codegen 传 rdb=nil 的场景)
}

// NewService creates a Service. failMax/lockDur mirror the old per-user
// redeem lockout (5 次失败锁 1 小时), now backed by codes/redisx.
func NewService(store *Store, rdb *redis.Client, failMax int, lockDur time.Duration) *Service {
	var limiter libcodes.RateLimiter
	if rdb != nil {
		limiter = redisx.NewRateLimiter(rdb, "redeem:fail:", failMax, lockDur)
	}
	return &Service{store: store, limiter: limiter}
}

// grantOutcome is the host-side grant result threaded through Redeem[T].
type grantOutcome struct {
	subID     int64
	expiresAt time.Time
}

func (svc *Service) Redeem(ctx context.Context, req RedeemRequest) (*RedeemResult, *apierr.Error) {
	ref := "user:" + strconv.FormatInt(req.UserID, 10)

	// 1. 锁检查先于格式检查(行为等价:旧 service.go:118-124 顺序)。
	if svc.limiter != nil {
		allowed, err := svc.limiter.Allowed(ctx, ref)
		if err != nil {
			return nil, apierr.ErrInternal
		}
		if !allowed {
			return nil, apierr.ErrLocked
		}
	}

	// 2. Canonicalize;格式错也计一次失败(旧 service.go:127-131)。
	canonical, cerr := Canonicalize(req.Code)
	if cerr != nil {
		if svc.limiter != nil {
			_ = svc.limiter.RecordFailure(ctx, ref)
		}
		return nil, apierr.ErrInvalidCode
	}

	// 3. 宿主事务:码状态翻转 + 订阅授予 + 双审计,一个 tx 原子提交。
	tx, err := svc.store.BeginTx(ctx)
	if err != nil {
		return nil, apierr.ErrInternal
	}
	committed := false
	defer func() {
		if !committed {
			_ = tx.Rollback()
		}
	}()

	res, err := libcodes.GuardedRedeem(ctx, svc.store.Lib(), svc.limiter, tx,
		Hash(canonical), ref, svc.grantSubscription(req.UserID))
	if err != nil {
		switch {
		case errors.Is(err, libcodes.ErrLocked):
			return nil, apierr.ErrLocked
		case errors.Is(err, libcodes.ErrCodeNotFound):
			return nil, apierr.ErrCodeNotFound
		case errors.Is(err, libcodes.ErrCodeRedeemed):
			return nil, apierr.ErrCodeRedeemed
		case errors.Is(err, libcodes.ErrCodeVoid):
			return nil, apierr.ErrCodeVoid
		default:
			return nil, apierr.ErrInternal
		}
	}

	dur, derr := res.Code.Entitlement.DecodeDuration()
	if derr != nil {
		return nil, apierr.ErrInternal
	}

	if res.Idempotent {
		// 只读路径:回滚(旧 service.go:162-171 同款),ExpiresAt 留空由 /v1/me 兜底。
		_ = tx.Rollback()
		committed = true
		return &RedeemResult{
			Idempotent:   true,
			PlanCode:     PlanCode(dur.Plan),
			DurationDays: dur.Days,
		}, nil
	}

	if err := tx.Commit(); err != nil {
		return nil, apierr.ErrInternal
	}
	committed = true

	return &RedeemResult{
		Idempotent:     false,
		PlanCode:       PlanCode(dur.Plan),
		DurationDays:   dur.Days,
		ExpiresAt:      res.Grant.expiresAt,
		SubscriptionID: res.Grant.subID,
	}, nil
}

// grantSubscription returns the GrantFunc executed by the lib INSIDE the same
// tx as the code flip. It reproduces the old applySubscription semantics
// byte-for-byte (service.go:235-287 pre-migration) and writes the legacy
// audit_log row the admin audit page reads (non-fatal, old behavior).
func (svc *Service) grantSubscription(userID int64) libcodes.GrantFunc[grantOutcome] {
	return func(ctx context.Context, tx *sql.Tx, code libcodes.Code) (grantOutcome, error) {
		dur, err := code.Entitlement.DecodeDuration()
		if err != nil {
			return grantOutcome{}, err
		}
		planID, err := svc.store.GetPlanIDTx(ctx, tx, PlanCode(dur.Plan))
		if err != nil {
			return grantOutcome{}, err
		}
		subID, expiresAt, err := svc.applySubscription(ctx, tx, userID, planID, dur.Days)
		if err != nil {
			return grantOutcome{}, err
		}

		// 旧式审计(数据源:admin/store.go:188,197 读 audit_log);失败不中断。
		meta, _ := json.Marshal(map[string]any{
			"plan":          dur.Plan,
			"duration_days": dur.Days,
			"batch_id":      code.BatchID,
			"sub_id":        subID,
		})
		_ = svc.store.WriteAuditLog(ctx, tx,
			fmt.Sprintf("user:%d", userID), "redeem",
			"code_hash:"+code.CodeHash[:16]+"...", string(meta))

		return grantOutcome{subID: subID, expiresAt: expiresAt}, nil
	}
}

// applySubscription:同 plan 有活跃订阅 → 取最晚到期那条 max(expires,now)+days
// 原地延长;否则新建一行 max(now, latestSamePlan)+days。算法体与迁移前完全一致,
// 仅签名从 (*CodeRow, *apierr.Error) 改为 (planID, days, error)。
func (svc *Service) applySubscription(
	ctx context.Context, tx *sql.Tx, userID, planID int64, durationDays int,
) (int64, time.Time, error) {
	subs, err := svc.store.GetActiveSubscriptions(ctx, tx, userID)
	if err != nil {
		return 0, time.Time{}, err
	}
	var samePlanSub *SubscriptionRow
	var latestSamePlan time.Time
	for i := range subs {
		if subs[i].PlanID == planID {
			if samePlanSub == nil || subs[i].ExpiresAt.After(samePlanSub.ExpiresAt) {
				samePlanSub = &subs[i]
			}
			if subs[i].ExpiresAt.After(latestSamePlan) {
				latestSamePlan = subs[i].ExpiresAt
			}
		}
	}
	now := time.Now().UTC()
	if samePlanSub != nil {
		if err := svc.store.ExtendSubscription(ctx, tx, samePlanSub.ID, durationDays); err != nil {
			return 0, time.Time{}, err
		}
		base := samePlanSub.ExpiresAt
		if now.After(base) {
			base = now
		}
		return samePlanSub.ID, base.AddDate(0, 0, durationDays), nil
	}
	newSubID, err := svc.store.CreateSubscription(ctx, tx, userID, planID, durationDays, latestSamePlan)
	if err != nil {
		return 0, time.Time{}, err
	}
	base := now
	if latestSamePlan.After(now) {
		base = latestSamePlan
	}
	return newSubID, base.AddDate(0, 0, durationDays), nil
}
```

`store.go` 追加(`GetPlanID` 原样保留):

```go
// GetPlanIDTx is GetPlanID inside a transaction (grant callback runs inside
// the redeem tx and must not touch the pool).
func (s *Store) GetPlanIDTx(ctx context.Context, tx *sql.Tx, code PlanCode) (int64, error) {
	var id int64
	if err := tx.QueryRowContext(ctx, `SELECT id FROM plans WHERE code=?`, string(code)).Scan(&id); err != nil {
		return 0, fmt.Errorf("store.GetPlanIDTx(%s): %w", code, err)
	}
	return id, nil
}
```

同时删除 `store.go` 的 `FindCodeByHashForUpdate`/`MarkRedeemed`/`CodeRow`(已被库取代;`sqlite_stores_test.go` 会编译失败——**在本 Task 顺手改**:删掉 `internal/store/sqlite_stores_test.go` 的 `TestSQLite_CodesRedeemFlow`(:193-260),它测的是被删的低层方法;等价覆盖由本 Task 的 Service 级 sqlite 用例接管,且更接近真实调用面)。`Store.BeginTx` 保留原实现(ReadCommitted,store.go:308-310——modernc sqlite 在既有测试下接受该选项,保持不动)。

- [ ] **Step 3: 验证 + commit**

```bash
cd /Users/wangjia/code/pangolin/server && go build ./... && go vet ./... && go test ./...
git add server/internal/codes/ server/internal/store/sqlite_stores_test.go
git commit -m "feat(server): Redeem 换芯 GuardedRedeem——grant 回调同事务复刻订阅叠加+双审计(#codes-lib)"
```

---

### Task 6: webhook 薄壳 — 保留 X-Pangolin HMAC 协议,铸码走库原语

**Files:**
- Modify: `server/internal/codes/webhook.go`
- Modify: `server/internal/codes/store.go`(新增 `MintOne`)
- Test: 既有 `server/internal/codes/webhook_test.go` 原样通过;追加 1 个 sqlite 铸码落库用例到 `service_sqlite_test.go`

**Interfaces:**
- `NewWebhookHandler(store *Store, rdb *redis.Client, secret string, timestampTolerance, nonceTTL time.Duration) *WebhookHandler` **签名不变**(main.go:299 原样编译)。
- 协议**逐字节不变**:`X-Pangolin-Signature: sha256=<hex>`(HMAC 仅对 body)、`X-Pangolin-Timestamp`(±tolerance)、`X-Pangolin-Nonce`(Redis SETNX 去重,key 前缀 `webhook:nonce:` 不变,**先存后铸的旧顺序保留**——`duplicate_ignored` 语义与 mysql 集成测试 TestWebhookNonceReplay 依赖它;库的 nonce 后置改良留给未来切 pay-contract handler 时一并采纳)、payload `{code,plan,duration_days,note}`、响应 `created`/`already_exists`/`duplicate_ignored` 三态。
- Produces: `func (s *Store) MintOne(ctx context.Context, codeHash string, ent libcodes.Entitlement, channel BatchChannel, createdBy, note string) error`(单事务 batch+code,重复码回 `ErrDuplicate` 且**不留孤儿 batch**)。

- [ ] **Step 1: 失败测试** —— 追加到 `service_sqlite_test.go`:

```go
func TestWebhookMintsIntoLibTables(t *testing.T) {
	// 直接测 Store.MintOne(webhook 铸码核心):落库新表 + 权益 payload + 重复码无孤儿 batch。
	ctx := context.Background()
	db := openMigratedSQLite(t)
	store := codes.NewStore(db)

	plain, err := codes.GenerateCode()
	if err != nil {
		t.Fatal(err)
	}
	canonical := mustCanonical(t, plain)
	ent, err := libcodesEnt("pro", 30)
	if err != nil {
		t.Fatal(err)
	}
	if err := store.MintOne(ctx, codes.Hash(canonical), ent, codes.ChannelStore, "webhook", "n1"); err != nil {
		t.Fatalf("MintOne: %v", err)
	}
	var batches, ccount int
	if err := db.QueryRow(`SELECT COUNT(*) FROM codes_batches`).Scan(&batches); err != nil || batches != 1 {
		t.Fatalf("batches = %d (err=%v)", batches, err)
	}
	if err := db.QueryRow(`SELECT COUNT(*) FROM codes WHERE code_hash=?`, codes.Hash(canonical)).Scan(&ccount); err != nil || ccount != 1 {
		t.Fatalf("codes = %d (err=%v)", ccount, err)
	}

	// 同 hash 再灌:ErrDuplicate 且 batch 数不变(无孤儿——旧实现的 I2 缺陷在此修复)。
	err = store.MintOne(ctx, codes.Hash(canonical), ent, codes.ChannelStore, "webhook", "n2")
	if !errors.Is(err, codes.ErrDuplicate) {
		t.Fatalf("err = %v, want ErrDuplicate", err)
	}
	if err := db.QueryRow(`SELECT COUNT(*) FROM codes_batches`).Scan(&batches); err != nil || batches != 1 {
		t.Fatalf("batches after dup = %d, want 1 (no orphan)", batches)
	}
}

// libcodesEnt:测试侧小工具,避免测试文件 import 库包名与宿主包名混淆。
func libcodesEnt(plan string, days int) (libcodes.Entitlement, error) {
	return libcodes.NewDurationEntitlement(plan, days)
}
```

(测试文件 import 加 `"errors"`、`libcodes "github.com/wangjia/codes"`。)

```bash
cd /Users/wangjia/code/pangolin/server && go test ./internal/codes/ -run TestWebhookMints   # FAIL:undefined MintOne
```

- [ ] **Step 2: 实现**

`store.go` 追加:

```go
// MintOne writes one externally-generated code (card-store webhook ingestion)
// as one batch + one code row in a single transaction. A duplicate code_hash
// returns ErrDuplicate with NOTHING committed — no orphan batch (the old
// two-statement implementation leaked one batch row per duplicate delivery).
func (s *Store) MintOne(ctx context.Context, codeHash string, ent libcodes.Entitlement, channel BatchChannel, createdBy, note string) error {
	tx, err := s.lib.BeginTx(ctx)
	if err != nil {
		return fmt.Errorf("store.MintOne: begin: %w", err)
	}
	defer tx.Rollback()

	batchID, err := s.lib.CreateBatchTx(ctx, tx, string(channel), ent, createdBy, note)
	if err != nil {
		return fmt.Errorf("store.MintOne: batch: %w", err)
	}
	if err := s.lib.CreateCodeTx(ctx, tx, codeHash, batchID, ent); err != nil {
		return err // ErrDuplicate passes through; defer 回滚保证无孤儿
	}
	if err := tx.Commit(); err != nil {
		return fmt.Errorf("store.MintOne: commit: %w", err)
	}
	return nil
}
```

`webhook.go`:结构体/构造函数/verifySignature/verifyTimestamp/checkAndStoreNonce/redisKeyNonce **全部原样不动**;仅 ServeHTTP 的「插码段」(webhook.go:136-166)替换:

```go
	// --- Idempotent code insertion (via shared lib primitives) ---
	ctx := r.Context()

	// 未知 plan 先拒(行为不变,旧 webhook.go:138-142)。
	if _, err := h.store.GetPlanID(ctx, PlanCode(strings.ToLower(payload.Plan))); err != nil {
		apierr.WriteJSON(w, http.StatusBadRequest, apierr.ErrBadRequest)
		return
	}
	ent, err := libcodes.NewDurationEntitlement(strings.ToLower(payload.Plan), payload.DurationDays)
	if err != nil {
		apierr.WriteJSON(w, http.StatusBadRequest, apierr.ErrBadRequest)
		return
	}

	err = h.store.MintOne(ctx, hash, ent, ChannelStore, "webhook", payload.Note)
	if errors.Is(err, ErrDuplicate) {
		w.Header().Set("Content-Type", "application/json; charset=utf-8")
		w.WriteHeader(http.StatusOK)
		_ = json.NewEncoder(w).Encode(map[string]string{"status": "already_exists"})
		return
	}
	if err != nil {
		apierr.WriteJSON(w, http.StatusInternalServerError, apierr.ErrInternal)
		return
	}

	w.Header().Set("Content-Type", "application/json; charset=utf-8")
	w.WriteHeader(http.StatusCreated)
	_ = json.NewEncoder(w).Encode(map[string]string{"status": "created"})
```

(import 加 `"errors"`、`libcodes "github.com/wangjia/codes"`。)

> **协调标注(未来项,不在本计划)**:切换到库的 `NewWebhookHandler`(pay-contract 式 `system\nts\nnonce\nbody` MAC,`X-Pay-*` 头)是 breaking change,需要与外部发卡店协调签名端升级;届时在新路径(如 `/v1/webhook/codes`)并行挂库 handler、双轨过渡。

- [ ] **Step 3: 验证 + commit**

```bash
cd /Users/wangjia/code/pangolin/server && go build ./... && go test ./internal/codes/    # webhook_test.go 旧用例必须原样全绿
git add server/internal/codes/
git commit -m "feat(server): webhook 薄壳化——保留 X-Pangolin HMAC 协议,铸码走库单事务原语(#codes-lib)"
```

---

### Task 7: admin 面改指新表 + 死代码清理

**Files:**
- Modify: `server/internal/codes/admin_support.go`(ListBatches/VoidBatch 指向 `codes_batches`/`codes`)
- Modify: `server/internal/codes/store.go`(删除遗留的 `CreateBatch`/`CreateCode`/`CodeExistsByHash`/`isDuplicateKey`)
- Test: `server/internal/codes/admin_support_sqlite_test.go`(新)

**Interfaces:** `ListBatches(ctx, limit, offset) ([]BatchInfo, int, error)` / `VoidBatch(ctx, batchID) (int64, error)` 签名与 `BatchInfo` 字段不变(admin 的 `CodesService` 接口零改动)。

- [ ] **Step 1: 失败测试** `admin_support_sqlite_test.go`:

```go
package codes_test

import (
	"context"
	"testing"
	"time"

	"github.com/wangjia/pangolin/server/internal/codes"
)

func TestListBatchesAndVoidBatchOnLibTables(t *testing.T) {
	ctx := context.Background()
	db := openMigratedSQLite(t)
	store := codes.NewStore(db)
	svc := codes.NewService(store, nil, 5, time.Hour)

	res, err := svc.CreateBatch(ctx, codes.BatchRequest{
		PlanCode: codes.PlanPro, DurationDays: 30, Count: 3,
		Channel: codes.ChannelManual, Note: "n", CreatedBy: "admin:1",
	})
	if err != nil {
		t.Fatalf("mint: %v", err)
	}

	infos, total, err := store.ListBatches(ctx, 50, 0)
	if err != nil {
		t.Fatalf("ListBatches: %v", err)
	}
	if total != 1 || len(infos) != 1 {
		t.Fatalf("total=%d len=%d", total, len(infos))
	}
	bi := infos[0]
	if bi.ID != res.BatchID || bi.Channel != codes.ChannelManual || bi.CreatedBy != "admin:1" ||
		bi.Note != "n" || bi.Total != 3 || bi.Unused != 3 || bi.Redeemed != 0 || bi.Void != 0 {
		t.Fatalf("BatchInfo = %+v", bi)
	}

	n, err := store.VoidBatch(ctx, res.BatchID)
	if err != nil || n != 3 {
		t.Fatalf("VoidBatch = %d, %v", n, err)
	}
	infos, _, err = store.ListBatches(ctx, 50, 0)
	if err != nil || infos[0].Void != 3 || infos[0].Unused != 0 {
		t.Fatalf("after void: %+v (err=%v)", infos[0], err)
	}
	// 二次 void:0 行(只动 unused)。
	if n, err := store.VoidBatch(ctx, res.BatchID); err != nil || n != 0 {
		t.Fatalf("re-void = %d, %v", n, err)
	}
}
```

```bash
cd /Users/wangjia/code/pangolin/server && go test ./internal/codes/ -run TestListBatches   # FAIL:查的还是 code_batches(已更名)
```

- [ ] **Step 2: 实现** —— `admin_support.go` 两处 SQL 换表名:
  - `ListBatches`:`SELECT COUNT(*) FROM code_batches` → `codes_batches`;主查询 `FROM code_batches b LEFT JOIN codes c ON c.batch_id = b.id` → `FROM codes_batches b LEFT JOIN codes c ON c.batch_id = b.id`(聚合表达式 `SUM(c.status='redeemed')` 等在两方言下不变,保留)。
  - `VoidBatch`:`UPDATE codes SET status = 'void', void_reason = 'batch_void' WHERE batch_id = ? AND status = 'unused'`(新表有 void_reason 列,补上语义)。

  `store.go` 删除 `CreateBatch`/`CreateCode`/`CodeExistsByHash` 和 `isDuplicateKey`(库内部自带判重);`BatchRow` 类型如无引用一并删。确认 `grep -rn "store\.CreateCode\|store\.CreateBatch\|CodeExistsByHash" server --include='*.go'` 零命中(webhook 已改走 MintOne)。

- [ ] **Step 3: 验证 + commit**

```bash
cd /Users/wangjia/code/pangolin/server && go build ./... && go vet ./... && go test ./...
git add server/internal/codes/
git commit -m "feat(server): admin 批次列表/作废改指 codes 库新表,清理被取代的旧 store 方法(#codes-lib)"
```

---

### Task 8: mysql 集成测试对齐(行为等价的另一半)

**Files:**
- Modify: `server/internal/codes/service_test.go`(applySchema + 表名引用)

**要点**:该文件带 `//go:build integration`(testcontainers,mysql:8)。改动最小化——测试用例的断言**不动**,只把环境搭建对齐新 schema:

- [ ] **Step 1:** `applySchema`(service_test.go:95-)里删除 `code_batches` 与 `codes` 两段 DDL(:105-125),保留 plans/users/subscriptions/audit_log 等其余 DDL,函数末尾追加:

```go
	if err := libcodes.ApplyMigrations(context.Background(), db, libcodes.DialectMySQL); err != nil {
		return fmt.Errorf("apply codes lib migrations: %w", err)
	}
```

(import 加 `libcodes "github.com/wangjia/codes"`。)

- [ ] **Step 2:** 全文件 grep 直查表名的 SQL:`FROM code_batches`/`INTO code_batches` → `codes_batches`;直查 `codes` 表的列断言若涉及 `plan_id`/`duration_days`(旧列,新表没有)→ 改为断言 `entitlement_payload`(如 TestCSVExportNoPlaintextInDB 检查明文不在库里:改查 `SELECT COUNT(*) FROM codes WHERE code_hash=?`,语义不变)。TestWebhookSameHashIdempotent 若断言了「重复灌码会多一个 batch」(旧 I2 行为)→ 改为断言 **batch 数不变**(新行为,无孤儿),并注明这是有意的行为改良。TestRedeemFailLock/TestRedeemConcurrentSingleWinner/TestSamePlanExtension 等的断言逻辑保持原样(公共 API 未变,应直接编译通过)。

- [ ] **Step 3: 验证 + commit**(需要本机 docker;不可用则明确记录「待 Task 9 终验跑」)

```bash
cd /Users/wangjia/code/pangolin/server && go vet -tags integration ./... && go test -tags integration -count=1 -p 1 -run 'TestRedeem|TestSamePlan|TestCrossPlan|TestAudit|TestCSV|TestWebhook' ./internal/codes/
git add server/internal/codes/service_test.go
git commit -m "test(server): mysql 集成测试对齐 codes 库新表(断言不变,环境搭建换 ApplyMigrations)(#codes-lib)"
```

---

### Task 9: 终验 — 全量本地验证 + 迁移彩排

- [ ] **Step 1: 全量测试矩阵**

```bash
cd /Users/wangjia/code/pangolin/server
go build ./... && go vet ./...
go test ./...                       # 单测 + sqlite 真库(含新的 backfill/service/admin sqlite 用例)
./run_sqlite_test.sh                # 迁移 up/down + store 方言
go test -tags integration -count=1 -p 1 ./...   # mysql+redis testcontainers(需 docker;Task 8 若已跑可只跑失败项)
bash ../scripts/e2e-smoke.sh        # 进程级端到端:migrate up(含 ApplyCodesLibMigrations+Backfill)+ server 真起
```

- [ ] **Step 2: 迁移彩排(生产数据形状)** —— 用 sqlite 文件库模拟「有存量数据的升级」:

```bash
cd /Users/wangjia/code/pangolin/server
rm -f /tmp/pg-rehearsal.db
# ① 装出一个 000019 时代的库:先 checkout main 的 migrations 跑 up?——不必:直接用本分支
#    migrate up 到底,再手工把 legacy 表填上模拟旧数据、清空库表、重跑 up 验证幂等即可:
DB_DRIVER=sqlite DB_DSN=/tmp/pg-rehearsal.db go run ./cmd/migrate up
sqlite3 /tmp/pg-rehearsal.db "INSERT INTO legacy_code_batches (id,channel,created_by,created_at) VALUES (1,'manual','rehearsal',datetime('now'));
INSERT INTO legacy_codes (id,code_hash,plan_id,duration_days,batch_id,status,redeemed_by) SELECT 1,'rehearsalhash0000000000000000000000000000000000000000000000000000',id,30,1,'redeemed',77 FROM plans WHERE code='pro';"
DB_DRIVER=sqlite DB_DSN=/tmp/pg-rehearsal.db go run ./cmd/migrate up    # 应打印 codes backfill — 1 legacy codes migrated
sqlite3 /tmp/pg-rehearsal.db "SELECT code_hash,status,redeemed_by FROM codes;"   # 期望 rehearsalhash…|redeemed|user:77
DB_DRIVER=sqlite DB_DSN=/tmp/pg-rehearsal.db go run ./cmd/migrate up    # 三跑:0 migrated,幂等
```

- [ ] **Step 3: 调用点零改动复核**

```bash
cd /Users/wangjia/code/pangolin
git diff main --stat -- server/cmd/server/main.go server/cmd/codegen/main.go \
  server/internal/admin/ server/internal/auth/ server/internal/usage/
# 期望:全部 0 行改动(公共 API 冻结的证明)
```

- [ ] **Step 4: 收尾 commit(如有零散修正)+ 汇总**——向用户报告:分支名、测试矩阵结果、两条协调项(CI runner 主机 go 模块配置;webhook 未来切 pay-contract 需发卡店协调)、已知行为差异清单(见文首)。**到此为止,不 merge。**

---

## Self-Review Checklist(执行完逐条打勾)

- [ ] `git log main..feat/codes-lib-integration` 每刀一 commit,信息可读。
- [ ] `go build ./... && go vet ./... && go test ./...` 与 `./run_sqlite_test.sh` 全绿;integration + e2e-smoke 至少各完整跑过一次。
- [ ] 六个调用点文件 `git diff main` 为零(公共 API 冻结兑现)。
- [ ] 明文码搜不到落库/日志路径:`grep -rn "res.Codes\|result.Codes" server --include='*.go'` 逐处目检仍只流向 CSV/HTTP 响应。
- [ ] 回填三跑幂等(Task 9 Step 2 彩排通过);`redeemed_by` 全部 `user:<id>` 格式(新旧幂等判定衔接)。
- [ ] webhook 协议逐字节兼容:旧 `webhook_test.go` 未改一行且全绿。
- [ ] 行为差异 1-5(文首清单)都已在交付说明里向用户列明,没有偷偷夹带第 6 条。
- [ ] 遗留项登记:① legacy_* 表 retire(验收后 cleanup 计划);② CI runner 主机 go 模块解析配置(用户执行);③ webhook 切 pay-contract(需外部协调);④ 本计划的 HTML 阅读版 + `docs/index.html` 登记(定稿后按仓规矩补)。

## 风险清单(执行者注意)

1. **依赖抬升回归**(最可能踩):`modernc.org/sqlite` 1.18.1→1.38.2 跨 20 个小版本,时间解析/锁行为若有细微变化会在 `internal/store` 既有测试暴露——Task 0 Step 3 特意在任何代码改动前先全量测试,炸了先修/上报,不带病往下走。
2. **模块解析是环境性的**:`github.com/wangjia/codes` 直连 GitHub 必失败(已实测),本机靠 insteadOf+GOPRIVATE,CI 靠 runner 主机同款配置+缓存预热——**推分支前 CI 会红是预期**,别误判为代码问题。
3. **表名 `codes` 一名两用有时间窗**:000020 之前的 SQL 指旧表、之后指库的新表;任何绕过本计划直查 `codes` 表的旁路代码(当前 grep 无,除 internal/codes 与两个测试)若在执行期间被并行分支引入,会静默读错表——终验 Step 3 的 diff 复核兜底。
4. **mysql 显式插 id 回填**:AUTO_INCREMENT 会自动越过回填的最大 id(mysql 8 行为),但若未来改用 MariaDB/其他分支需复验;sqlite AUTOINCREMENT 序列同样自动抬升,已由回填测试覆盖。