refactor(payment): 渠道抽象成 Channel 接口 —— 接新渠道=加 adapter 不动骨架

PAYMENT_DESIGN §3 承诺的 internal/payment/channel.go 适配器接口此前不存在,微信硬编码在
manager/handler 里。补齐抽象:

- channel.go:Channel 接口(Name/CreatePay/QueryOrder/VerifyCallback)+ 统一 PayIntent/PayResult
  + 渠道名常量。入参用基本类型不吃 *store.PaymentOrder,payment 包不反依赖 store。
- Wechat 实现 Channel(编译期断言 var _ Channel);QueryResult 归一为 PayResult;CreatePay 返回 PayIntent。
- Manager 从「持一个 *Wechat」改为渠道注册表:Get(name)/Available()/Status(name)/ReloadWechat;
  按渠道名持有已装配实例,热重载不变。
- 回调路由收敛 /billing/callback/wechat → /billing/callback/:channel 按名路由(旧 notify URL 仍匹配);
  查单/掉单补偿据 order.Channel 路由,不再写死微信。下单支持可选 channel(缺省 wechat)。
- 支付宝/Stripe 现在真·只差一个 adapter+注册。唯一未泛化:回调 ack 应答格式(现微信态,注释标明)。
- payment 包首个测试:Manager 注册表 4 用例(空/注册摘除/空配置/配置不全)。build/vet/test/lint 全绿。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

sundynix-gateway/internal/payment/channel.go

@@ -0,0 +1,44 @@
+package payment
+
+import (
+	"context"
+	"net/http"
+)
+
+// Channel 是一个「真渠道」充值适配器（设计见 PAYMENT_DESIGN.md §3）。
+// 兑换码不走这里（无「待支付」态，核销即入账）；本接口面向需要下单-回调/查单确认的渠道。
+// 接新渠道（支付宝/Stripe）= 实现这四个方法 + 在 Manager 注册，不动上层充值/入账骨架。
+//
+// 刻意用基本类型入参（orderID/amountFen）而非 *store.PaymentOrder：让 payment 包不反向依赖
+// store，渠道适配层保持纯粹。金额一律以「分」为单位、服务端锁定值，绝不信任客户端。
+type Channel interface {
+	// Name 渠道名，与 store.Channel*（"wechat"/"alipay"/"stripe"）一致，用于按订单渠道路由。
+	Name() string
+	// CreatePay 依据订单生成支付凭据（微信 Native 出 code_url；支付宝/Stripe 可出跳转 URL）。
+	CreatePay(ctx context.Context, orderID, description string, amountFen int64) (PayIntent, error)
+	// QueryOrder 主动查单（前端轮询确认 + 掉单补偿共用）。
+	QueryOrder(ctx context.Context, orderID string) (PayResult, error)
+	// VerifyCallback 验签并解析渠道回调 → 统一结果。验签失败必须返回 error（回调路由公开，签名是唯一门）。
+	VerifyCallback(req *http.Request) (PayResult, error)
+}
+
+// 渠道名常量（与 store.Channel* 取值一致；此处独立定义以免 payment 反依赖 store）。
+const (
+	ChannelWechat = "wechat"
+	ChannelAlipay = "alipay" // 预留：未实现
+	ChannelStripe = "stripe" // 预留：未实现
+)
+
+// PayIntent 是下单后给前端的支付凭据（不同渠道形态不同，按需取用）。
+type PayIntent struct {
+	CodeURL string // 微信 Native：二维码内容。其它渠道可放跳转 URL / client_secret。
+}
+
+// PayResult 是查单/回调验签解析后的统一结果（各渠道适配器把自家响应归一到这里）。
+type PayResult struct {
+	OrderID    string // 商户订单号（out_trade_no）
+	ChannelTxn string // 渠道流水号（transaction_id），入账时落库备查
+	Paid       bool   // 支付成功
+	Closed     bool   // 关单/撤销/支付失败等终态
+	AmountFen  int64  // 用户实付（分）；供与订单金额核对，防金额被篡改
+}

sundynix-gateway/internal/payment/manager.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"log"
 	"os"
+	"sort"
 	"strings"
 	"sync"
 )
@@ -63,25 +64,42 @@ func ConfigFromEnv() Config {
 	}
 }
 
-// Manager 持有当前微信渠道实例，支持 admin 改配置后热重载（学 prompt 控制面：改完即生效，
-// 不重启 gateway）。所有业务路径经 Current() 取用——nil 即渠道隐藏。
+// Manager 是充值渠道注册表：按渠道名持有已装配的 Channel 实例，支持 admin 改配置后热重载
+// （学 prompt 控制面：改完即生效，不重启 gateway）。业务路径经 Get(name) 按订单渠道取用——
+// 取到 nil 即该渠道未启用/隐藏。接新渠道（支付宝/Stripe）= 加一个 ReloadXxx + 各自 Channel 实现。
 type Manager struct {
-	mu     sync.RWMutex
-	w      *Wechat
-	reason string // 未启用原因（给 admin 状态面看）
+	mu       sync.RWMutex
+	channels map[string]Channel // 渠道名 → 实例（仅含已成功装配的）
+	reasons  map[string]string  // 渠道名 → 未启用原因（给 admin 状态面看，含未启用的）
 }
 
 func NewManager() *Manager {
-	return &Manager{reason: "未配置"}
+	return &Manager{
+		channels: map[string]Channel{},
+		reasons:  map[string]string{ChannelWechat: "未配置"},
+	}
 }
 
-// Reload 按给定配置重建渠道实例。失败只降级为隐藏并记录原因，绝不 panic/拖垮服务。
-func (m *Manager) Reload(ctx context.Context, c Config) error {
-	w, reason, err := build(ctx, c)
+// register 装配结果登记：成功则入表、失败则从表移除并记原因（内部用，调用方持有意图日志）。
+func (m *Manager) register(name string, ch Channel, reason string) {
 	m.mu.Lock()
-	m.w = w
-	m.reason = reason
-	m.mu.Unlock()
+	defer m.mu.Unlock()
+	if ch != nil {
+		m.channels[name] = ch
+	} else {
+		delete(m.channels, name)
+	}
+	m.reasons[name] = reason
+}
+
+// ReloadWechat 按给定配置重建微信渠道。失败只降级为隐藏并记录原因，绝不 panic/拖垮服务。
+func (m *Manager) ReloadWechat(ctx context.Context, c Config) error {
+	w, reason, err := buildWechat(ctx, c)
+	var ch Channel
+	if w != nil {
+		ch = w
+	}
+	m.register(ChannelWechat, ch, reason)
 	if w != nil {
 		log.Printf("[payment] 微信支付 Native 渠道已启用 (mchid=%s)", c.MchID)
 	} else if !c.Empty() {
@@ -90,22 +108,35 @@ func (m *Manager) Reload(ctx context.Context, c Config) error {
 	return err
 }
 
-// Current 当前渠道实例；nil = 未配置/配置失败（渠道隐藏）。
-func (m *Manager) Current() *Wechat {
+// Get 按渠道名取实例；nil = 未配置/配置失败（渠道隐藏）。
+func (m *Manager) Get(name string) Channel {
 	m.mu.RLock()
 	defer m.mu.RUnlock()
-	return m.w
+	return m.channels[name]
 }
 
-// Status 给 admin 状态面：是否启用 + 未启用原因。
-func (m *Manager) Status() (bool, string) {
+// Available 返回已启用的渠道名（供前端展示可选渠道）。
+func (m *Manager) Available() []string {
 	m.mu.RLock()
 	defer m.mu.RUnlock()
-	return m.w != nil, m.reason
+	out := make([]string, 0, len(m.channels))
+	for name := range m.channels {
+		out = append(out, name)
+	}
+	sort.Strings(out)
+	return out
 }
 
-// build 装配渠道实例；返回 (实例, 未启用原因, 错误)。配置为空不算错。
-func build(ctx context.Context, c Config) (*Wechat, string, error) {
+// Status 给 admin 状态面：某渠道是否启用 + 未启用原因。
+func (m *Manager) Status(name string) (bool, string) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	_, ok := m.channels[name]
+	return ok, m.reasons[name]
+}
+
+// buildWechat 装配微信渠道实例；返回 (实例, 未启用原因, 错误)。配置为空不算错。
+func buildWechat(ctx context.Context, c Config) (*Wechat, string, error) {
 	if c.Empty() {
 		return nil, "未配置", nil
 	}

sundynix-gateway/internal/payment/manager_test.go

@@ -0,0 +1,96 @@
+package payment
+
+import (
+	"context"
+	"net/http"
+	"testing"
+)
+
+// stubChannel 是测试用的假渠道，验证 Manager 注册表逻辑（不打真渠道网络）。
+type stubChannel struct{ name string }
+
+func (s stubChannel) Name() string { return s.name }
+func (s stubChannel) CreatePay(_ context.Context, _, _ string, _ int64) (PayIntent, error) {
+	return PayIntent{CodeURL: "stub://" + s.name}, nil
+}
+func (s stubChannel) QueryOrder(_ context.Context, _ string) (PayResult, error) {
+	return PayResult{}, nil
+}
+func (s stubChannel) VerifyCallback(_ *http.Request) (PayResult, error) {
+	return PayResult{}, nil
+}
+
+// 空 Manager：Get 任意渠道为 nil，Available 为空，Status 报未配置。
+func TestManager_EmptyRegistry(t *testing.T) {
+	m := NewManager()
+	if m.Get(ChannelWechat) != nil {
+		t.Error("未注册渠道 Get 应为 nil")
+	}
+	if len(m.Available()) != 0 {
+		t.Errorf("空注册表 Available 应为空，得 %v", m.Available())
+	}
+	if ok, reason := m.Status(ChannelWechat); ok || reason == "" {
+		t.Errorf("空注册表 wechat 应未启用且有原因，得 ok=%v reason=%q", ok, reason)
+	}
+}
+
+// register 生效：注册后 Get 取到、Available 含之、Status 启用；置 nil 则摘除并留原因。
+func TestManager_RegisterAndRemove(t *testing.T) {
+	m := NewManager()
+	m.register(ChannelWechat, stubChannel{name: ChannelWechat}, "")
+
+	if got := m.Get(ChannelWechat); got == nil || got.Name() != ChannelWechat {
+		t.Fatalf("注册后应能 Get 到 wechat，得 %v", got)
+	}
+	if ok, _ := m.Status(ChannelWechat); !ok {
+		t.Error("注册后 Status 应启用")
+	}
+	avail := m.Available()
+	if len(avail) != 1 || avail[0] != ChannelWechat {
+		t.Errorf("Available 应含 wechat，得 %v", avail)
+	}
+
+	// 再注册第二个渠道 → Available 有序返回两个。
+	m.register(ChannelAlipay, stubChannel{name: ChannelAlipay}, "")
+	if avail := m.Available(); len(avail) != 2 || avail[0] != ChannelAlipay || avail[1] != ChannelWechat {
+		t.Errorf("Available 应有序含 alipay,wechat，得 %v", avail)
+	}
+
+	// 置 nil（配置变坏/清空）→ 摘除，Get 为 nil、Status 未启用且保留原因。
+	m.register(ChannelWechat, nil, "配置不全，缺: mchid")
+	if m.Get(ChannelWechat) != nil {
+		t.Error("摘除后 Get 应为 nil")
+	}
+	if ok, reason := m.Status(ChannelWechat); ok || reason != "配置不全，缺: mchid" {
+		t.Errorf("摘除后应未启用且保留原因，得 ok=%v reason=%q", ok, reason)
+	}
+}
+
+// ReloadWechat 空配置：不算错、渠道保持隐藏、原因为「未配置」。
+func TestManager_ReloadWechat_Empty(t *testing.T) {
+	m := NewManager()
+	if err := m.ReloadWechat(context.Background(), Config{}); err != nil {
+		t.Errorf("空配置 ReloadWechat 不应报错，得 %v", err)
+	}
+	if m.Get(ChannelWechat) != nil {
+		t.Error("空配置不应启用渠道")
+	}
+	if ok, reason := m.Status(ChannelWechat); ok || reason != "未配置" {
+		t.Errorf("空配置应报未配置，得 ok=%v reason=%q", ok, reason)
+	}
+}
+
+// ReloadWechat 配置不全：返回错误、渠道隐藏、原因列出缺失字段。
+func TestManager_ReloadWechat_Incomplete(t *testing.T) {
+	m := NewManager()
+	err := m.ReloadWechat(context.Background(), Config{MchID: "123"}) // 只填一个字段
+	if err == nil {
+		t.Error("配置不全应返回错误")
+	}
+	if m.Get(ChannelWechat) != nil {
+		t.Error("配置不全不应启用渠道")
+	}
+	if _, reason := m.Status(ChannelWechat); reason == "" {
+		t.Error("配置不全应给出缺失原因")
+	}
+}

sundynix-gateway/internal/payment/wechat.go

@@ -33,6 +33,12 @@ type Wechat struct {
 	pubKeyID  string
 }
 
+// 编译期断言：Wechat 实现 Channel 接口。
+var _ Channel = (*Wechat)(nil)
+
+// Name 渠道名（用于按订单渠道路由查单/回调）。
+func (w *Wechat) Name() string { return ChannelWechat }
+
 // New 按完整配置装配微信渠道（商户私钥/微信支付公钥都从磁盘路径加载；调用方保证字段齐全）。
 // 验签体系钉死「微信支付公钥」模式（WithWechatPayPublicKeyAuthCipher）：本项目商户
 // 2025-09 开户，只有公钥体系；老商户的平台证书模式（AutoAuthCipher）不支持。
@@ -58,7 +64,7 @@ func New(ctx context.Context, c Config) (*Wechat, error) {
 }
 
 // CreatePay Native 下单：返回 code_url（前端渲染成二维码）。金额取订单锁定值。
-func (w *Wechat) CreatePay(ctx context.Context, orderID, description string, amountFen int64) (string, error) {
+func (w *Wechat) CreatePay(ctx context.Context, orderID, description string, amountFen int64) (PayIntent, error) {
 	resp, _, err := w.svc.Prepay(ctx, native.PrepayRequest{
 		Appid:       core.String(w.appID),
 		Mchid:       core.String(w.mchID),
@@ -68,25 +74,16 @@ func (w *Wechat) CreatePay(ctx context.Context, orderID, description string, amo
 		Amount:      &native.Amount{Total: core.Int64(amountFen), Currency: core.String("CNY")},
 	})
 	if err != nil {
-		return "", err
+		return PayIntent{}, err
 	}
 	if resp.CodeUrl == nil || *resp.CodeUrl == "" {
-		return "", errors.New("微信未返回 code_url")
+		return PayIntent{}, errors.New("微信未返回 code_url")
 	}
-	return *resp.CodeUrl, nil
+	return PayIntent{CodeURL: *resp.CodeUrl}, nil
 }
 
-// QueryResult 查单/回调解析后的统一结果。
-type QueryResult struct {
-	OrderID    string // out_trade_no
-	ChannelTxn string // transaction_id
-	Paid       bool   // TradeState == SUCCESS
-	Closed     bool   // CLOSED/REVOKED/PAYERROR 等终态失败
-	AmountFen  int64  // 用户实付（分）；回调/查单都带，供金额核对
-}
-
-func fromTransaction(t *payments.Transaction) QueryResult {
-	r := QueryResult{}
+func fromTransaction(t *payments.Transaction) PayResult {
+	r := PayResult{}
 	if t.OutTradeNo != nil {
 		r.OrderID = *t.OutTradeNo
 	}
@@ -110,28 +107,28 @@ func fromTransaction(t *payments.Transaction) QueryResult {
 }
 
 // QueryOrder 主动查单（本地开发确认到账、生产掉单补偿共用）。
-func (w *Wechat) QueryOrder(ctx context.Context, orderID string) (QueryResult, error) {
+func (w *Wechat) QueryOrder(ctx context.Context, orderID string) (PayResult, error) {
 	t, _, err := w.svc.QueryOrderByOutTradeNo(ctx, native.QueryOrderByOutTradeNoRequest{
 		OutTradeNo: core.String(orderID),
 		Mchid:      core.String(w.mchID),
 	})
 	if err != nil {
-		return QueryResult{}, err
+		return PayResult{}, err
 	}
 	return fromTransaction(t), nil
 }
 
 // VerifyCallback 验签 + 解密支付回调（微信支付公钥验签 + APIv3 密钥 AES-GCM 解密资源）。
 // 验签失败一律拒绝——回调路由是公开的，签名是唯一的门。
-func (w *Wechat) VerifyCallback(req *http.Request) (QueryResult, error) {
+func (w *Wechat) VerifyCallback(req *http.Request) (PayResult, error) {
 	h, err := notify.NewRSANotifyHandler(w.apiv3Key,
 		verifiers.NewSHA256WithRSAPubkeyVerifier(w.pubKeyID, *w.pubKey))
 	if err != nil {
-		return QueryResult{}, fmt.Errorf("回调处理器初始化失败: %w", err)
+		return PayResult{}, fmt.Errorf("回调处理器初始化失败: %w", err)
 	}
 	txn := new(payments.Transaction)
 	if _, err := h.ParseNotifyRequest(req.Context(), req, txn); err != nil {
-		return QueryResult{}, err
+		return PayResult{}, err
 	}
 	return fromTransaction(txn), nil
 }