第15章 · 支付服务设计（正式版）

读者点击打赏
   ↓
webook 创建支付订单（本地先落一条「待支付」记录）
   ↓
webook 调用微信 Prepay 下单（在微信那边也创建一张订单）
   ↓
微信返回 code_url → 前端渲染成二维码展示给读者
   ↓
读者扫码支付（注意：这一步全程在微信里，webook 完全不参与）
   ↓
微信异步回调 webook 的 notify_url，通知支付结果
   ↓
webook 验签 → 更新订单状态 → 分账 → 返回 200

// internal/payment/service/payment.go
package payment

// PrepayReq 预支付请求：只暴露业务方该关心的字段
type PrepayReq struct {
    BizTradeNO  string // 业务方唯一凭证，用于去重
    Description string // 商品描述
    Amount      int64  // 金额，单位：分
}

// PrepayResp 预支付响应
type PrepayResp struct {
    CodeURL string // 微信返回的二维码链接
}

// PaymentService 支付服务接口
// 如果将来接入支付宝，可以拆成 WePayment 和 AliPayment，
// 两者有公共字段可以组合 basePayment
type PaymentService interface {
    Prepay(ctx context.Context, req PrepayReq) (PrepayResp, error)
}

// internal/payment/service/payment.go
// NativePaymentService 微信 native 支付实现
type NativePaymentService struct {
    client    *native.NativeApiService // 微信官方 SDK 的客户端
    appid     string                   // 小程序/公众号 ID
    mchid     string                   // 商户号
    notifyURL string                   // 回调地址
    db        PaymentDAO
}

func (s *NativePaymentService) Prepay(ctx context.Context, req PrepayReq) (PrepayResp, error) {
    // 步骤 1：先初始化一条支付记录——目的是去重
    // 即便不去重，BizTradeNO 透传给微信，微信也会用它去重
    err := s.db.Insert(ctx, Payment{
        BizTradeNO: req.BizTradeNO,
        Status:     StatusInit,
        Amount:     req.Amount,
    })
    if err != nil {
        // 唯一索引冲突说明已经创建过，可以直接查询返回 code_url
        // 这里简化处理，实际要区分是重复还是真的 DB 错误
    }
    // 步骤 2：调用微信下单接口
    resp, err := s.client.Prepay(ctx, native.PrepayRequest{
        Appid:       core.String(s.appid),
        Mchid:       core.String(s.mchid),
        Description: core.String(req.Description),
        OutTradeNo:  core.String(req.BizTradeNO),
        NotifyUrl:   core.String(s.notifyURL),
        Amount: &native.Amount{
            Total:    core.Int64(req.Amount),
            Currency: core.String("CNY"),
        },
    })
    if err != nil {
        return PrepayResp{}, err
    }
    // 步骤 3：返回微信给的二维码链接
    return PrepayResp{CodeURL: *resp.CodeUrl}, nil
}

-- scripts/payment_simple.sql
CREATE TABLE `payment` (
    `id`           BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
    `biz_trade_no` VARCHAR(64) NOT NULL COMMENT '业务方唯一凭证',
    `status`       TINYINT NOT NULL COMMENT '支付状态：0初始 1成功 2失败',
    `amount`       BIGINT NOT NULL COMMENT '金额，单位分',
    `txn_id`       VARCHAR(64) DEFAULT '' COMMENT '微信支付订单号',
    `ctime`        DATETIME NOT NULL,
    `utime`        DATETIME NOT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_biz_trade_no` (`biz_trade_no`) -- 关键：唯一索引保证去重
);

// internal/payment/web/notify.go
package web

// WechatHandler 微信回调处理器
type WechatHandler struct {
    handler *notify.Handler // 微信官方 SDK：验签 + 解密一步到位
    svc     *NativePaymentService
}

func (h *WechatHandler) ServeHTTP(w http.ResponseWriter, req *http.Request) {
    // 步骤 1：微信 SDK 帮我们验签 + 解密
    transaction := new(native.Transaction)
    _, err := h.handler.ParseNotifyRequest(req.Context(), req, transaction)
    if err != nil {
        w.WriteHeader(http.StatusInternalServerError) // 验签失败：可能是伪造请求
        return
    }
    // 步骤 2：在 Web 层把微信状态转成内部状态
    var internalStatus int8
    switch *transaction.TradeState {
    case native.TRADESTATE_SUCCESS:                     // 支付成功
        internalStatus = StatusSuccess
    case native.TRADESTATE_CLOSED, native.TRADESTATE_REVOKED: // 已关闭/已撤销
        internalStatus = StatusFailed
    default:
        internalStatus = StatusInit
    }
    // 步骤 3：更新本地状态，并告诉微信已收到（否则微信会重试）
    err = h.svc.HandleCallback(req.Context(), *transaction.OutTradeNo,
        *transaction.TransactionId, internalStatus)
    if err != nil {
        w.WriteHeader(http.StatusInternalServerError)
        return
    }
    w.WriteHeader(http.StatusOK)
}

// internal/payment/service/payment.go
// SyncOrderStatus 主动查询微信订单状态，更新本地
func (s *NativePaymentService) SyncOrderStatus(ctx context.Context, bizTradeNO string) error {
    // 步骤 1：调用微信查询接口
    resp, err := s.client.QueryOrderByOutTradeNo(ctx, native.QueryOrderByOutTradeNoRequest{
        OutTradeNo: core.String(bizTradeNO),
        Mchid:      core.String(s.mchid),
    })
    if err != nil {
        return err
    }
    // 步骤 2：转换状态并更新本地（和回调处理共用同一个转换逻辑）
    var status int8
    switch *resp.TradeState {
    case native.TRADESTATE_SUCCESS:
        status = StatusSuccess
    case native.TRADESTATE_CLOSED, native.TRADESTATE_REVOKED:
        status = StatusFailed
    default:
        status = StatusInit
    }
    return s.db.UpdateStatus(ctx, bizTradeNO, *resp.TransactionId, status)
}

// internal/payment/service/reconcile.go
// ScheduleReconcile 定时对账任务
// 借助分布式锁可以让任务全局唯一，但没特别大必要
func (s *NativePaymentService) ScheduleReconcile() {
    // 步骤 1：找 2 小时 1 分钟前的订单（Prepay 超时 2 小时，多留 1 分钟缓冲）
    orders, err := s.db.FindTimeoutOrders(context.Background(), 121*time.Minute)
    if err != nil {
        return
    }
    // 步骤 2：逐单主动去微信查状态并更新本地
    for _, o := range orders {
        _ = s.SyncOrderStatus(context.Background(), o.BizTradeNO)
    }
}

// internal/post/web/article.go
// Reward 打赏接口（放在 ArticleHandler 下，因为是打赏文章）
func (h *ArticleHandler) Reward(ctx *gin.Context) {
    // 步骤 1：查询文章信息，获得作者、标题
    art, err := h.articleSvc.GetById(ctx, req.Aid)
    // 步骤 2：构建打赏请求
    resp, err := h.rewardSvc.Reward(ctx, reward.RewardReq{
        Biz:    "article",
        BizId:  req.Aid,
        Uid:    req.Uid,
        Amount: 1, // 打赏一分钱（抠门示例，正常应是用户输入金额）
        Title:  art.Title,
        Author: art.AuthorId,
    })
    // 步骤 3：返回二维码 + rid
    ctx.JSON(http.StatusOK, gin.H{
        "codeURL": resp.CodeURL,
        "rid":     resp.Rid,
    })
}

// api/proto/reward/v1/reward.proto
service RewardService {
    // 打赏接口：返回支付二维码和打赏记录 ID
    rpc Reward(RewardReq) returns (RewardResp);
    // 查询打赏结果
    rpc GetReward(GetRewardReq) returns (GetRewardResp);
}

message RewardReq {
    string biz = 1;       // 业务标识，如 "article"
    int64  biz_id = 2;    // 业务 ID，如文章 ID
    int64  uid = 3;       // 打赏者 UID
    int64  amount = 4;    // 金额，单位分
    string title = 5;     // 文章标题（用于微信商品描述）
    int64  author = 6;    // 创作者 UID
}

message RewardResp {
    string code_url = 1;  // 支付二维码链接
    int64  rid = 2;       // 打赏记录 ID
}

// internal/reward/service/reward.go
func (s *RewardService) Reward(ctx context.Context, req *RewardReq) (*RewardResp, error) {
    // Step 1: 查询是否有缓存的二维码
    // 如果有，说明用户之前准备打赏但没支付，直接复用
    codeURL, err := s.cache.GetCodeURL(ctx, req.Uid, req.Biz, req.BizId)
    if err == nil && codeURL != "" {
        rid, _ := s.cache.GetRid(ctx, req.Uid, req.Biz, req.BizId)
        return &RewardResp{CodeUrl: codeURL, Rid: rid}, nil
    }

    // Step 2: 创建打赏记录
    rid, err := s.dao.Create(ctx, Reward{
        Biz:    req.Biz,
        BizId:  req.BizId,
        Uid:    req.Uid,
        Amount: req.Amount,
        Status: StatusPending,
        Author: req.Author,
    })
    if err != nil {
        return nil, err
    }

    // Step 3: 调用 Payment 服务获得二维码
    // BizTradeNO 用 rid 编码，保证唯一性
    bizTradeNO := fmt.Sprintf("reward:%d", rid)
    prepay, err := s.paymentSvc.Prepay(ctx, payment.PrepayReq{
        BizTradeNO:  bizTradeNO,
        Description: fmt.Sprintf("打赏文章:%s", req.Title),
        Amount:      req.Amount,
    })
    if err != nil {
        return nil, err
    }

    // Step 4: 缓存二维码，避免重复调用支付
    _ = s.cache.SetCodeURL(ctx, req.Uid, req.Biz, req.BizId, prepay.CodeURL, 2*time.Hour)
    _ = s.cache.SetRid(ctx, req.Uid, req.Biz, req.BizId, rid, 2*time.Hour)

    return &RewardResp{CodeUrl: prepay.CodeURL, Rid: rid}, nil
}

// internal/reward/service/reward.go
// GetReward 查询打赏结果
// uid 往后传是为了让 Reward 服务校验：rid 是不是这个登录用户创建的
// 打赏的人和查询的人必须是同一个人
func (s *RewardService) GetReward(ctx context.Context, req *GetRewardReq) (*GetRewardResp, error) {
    // 步骤 1：查本地打赏记录
    r, err := s.dao.GetById(ctx, req.Rid)
    if err != nil {
        return nil, err
    }
    // 步骤 2：权限校验——rid 必须属于该 uid
    if r.Uid != req.Uid {
        return nil, ErrPermissionDenied
    }

    // 步骤 3：快慢路径。pending 时主动查 Payment（慢路径）
    if r.Status == StatusPending {
        // 正常可以触发降级时跳过此查询
        status, err := s.paymentSvc.GetStatus(ctx, r.BizTradeNO)
        if err == nil && status != StatusPending {
            _ = s.dao.UpdateStatus(ctx, r.Id, status)
            r.Status = status
        }
    }

    return &GetRewardResp{Status: r.Status}, nil
}

// internal/payment/service/callback.go
func (s *NativePaymentService) HandleCallback(ctx context.Context,
    bizTradeNO, txnID string, status int8) error {
    // 步骤 1：更新本地状态
    err := s.db.UpdateStatus(ctx, bizTradeNO, txnID, status)
    if err != nil {
        return err
    }
    // 步骤 2：发送消息到 Kafka
    err = s.producer.Produce(ctx, PaymentEvent{
        BizTradeNO: bizTradeNO,
        Status:     status,
        TxnID:      txnID,
    })
    // 关键问题：处理结果成功，但发送消息失败怎么办？
    // 解决思路：重试 + 监控 + 告警 + 异步补偿（本地消息表）
    return err
}

// internal/reward/consumer/payment_event.go
func (c *RewardConsumer) Consume(msg *PaymentEvent) error {
    // 步骤 1：从 bizTradeNO 解析出 rid，例如 "reward:123" → 123
    parts := strings.Split(msg.BizTradeNO, ":")
    if len(parts) != 2 || parts[0] != "reward" {
        return nil // 不是打赏的消息，跳过
    }
    rid, _ := strconv.ParseInt(parts[1], 10, 64)

    // 步骤 2：更新本地状态——这个操作是幂等的
    return c.dao.UpdateStatus(context.Background(), rid, msg.Status)
}

// api/proto/account/v1/account.proto
service AccountService {
    // 分账：把一笔账分成多笔
    rpc Split(SplitReq) returns (SplitResp);
}

message SplitReq {
    string biz = 1;               // 业务标识
    int64  biz_id = 2;            // 业务 ID
    int64  total = 3;             // 总金额
    repeated SplitItem items = 4; // 分账明细
}

message SplitItem {
    int64  uid = 1;               // 账号 UID
    int64  amount = 2;            // 分到的金额
    string account_type = 3;      // 账号类型：收入/支出
}

-- scripts/account.sql：Account 表（账号余额）
CREATE TABLE `account` (
    `id`         BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
    `uid`        BIGINT NOT NULL,
    `balance`    BIGINT NOT NULL COMMENT '余额，单位分',
    `currency`   VARCHAR(8) NOT NULL DEFAULT 'CNY' COMMENT '币种',
    `ctime`      DATETIME NOT NULL,
    `utime`      DATETIME NOT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_uid_currency` (`uid`, `currency`)
);

-- scripts/account.sql：AccountActivity 表（账号变动记录，即"流水"）
CREATE TABLE `account_activity` (
    `id`            BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
    `uid`           BIGINT NOT NULL,
    `biz`           VARCHAR(32) NOT NULL,
    `biz_id`        BIGINT NOT NULL,
    `amount`        BIGINT NOT NULL COMMENT '变动金额，正数收入负数支出',
    `balance_after` BIGINT NOT NULL COMMENT '变动后余额，便于审计',
    `ctime`         DATETIME NOT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_biz_bizid_uid` (`biz`, `biz_id`, `uid`) -- 关键：幂等保证
);

// internal/account/service/account.go
func (s *AccountService) Split(ctx context.Context, req *SplitReq) (*SplitResp, error) {
    // 步骤 1：开启事务
    tx, err := s.db.BeginTx(ctx, nil)
    if err != nil {
        return nil, err
    }
    defer tx.Rollback() // 失败时回滚

    for _, item := range req.Items {
        // 步骤 2：更新账号余额
        _, err := tx.ExecContext(ctx,
            "UPDATE account SET balance = balance + ?, utime = NOW() "+
                "WHERE uid = ? AND currency = 'CNY'",
            item.Amount, item.Uid)
        if err != nil {
            return nil, err
        }

        // 步骤 3：记录账号活动（唯一索引保证幂等：biz+bizId+uid 唯一）
        var balanceAfter int64
        _ = tx.QueryRowContext(ctx,
            "SELECT balance FROM account WHERE uid = ?", item.Uid).
            Scan(&balanceAfter)
        _, err = tx.ExecContext(ctx,
            "INSERT INTO account_activity "+
                "(uid, biz, biz_id, amount, balance_after, ctime) "+
                "VALUES (?, ?, ?, ?, ?, NOW())",
            item.Uid, req.Biz, req.BizId, item.Amount, balanceAfter)
        if err != nil {
            // 唯一索引冲突说明已经分过账，直接返回（幂等）
            return nil, err
        }
    }

    // 步骤 4：提交事务
    if err = tx.Commit(); err != nil {
        return nil, err
    }
    return &SplitResp{Success: true}, nil
}

// internal/reward/service/reward.go
func (s *RewardService) handlePaymentSuccess(ctx context.Context, rid int64) error {
    // 步骤 1：查出打赏记录
    r, err := s.dao.GetById(ctx, rid)
    if err != nil {
        return err
    }
    // 步骤 2：计算分成：作者 80%，平台 20%（示例比例）
    authorAmount := r.Amount * 8 / 10
    platformAmount := r.Amount - authorAmount

    // 步骤 3：调用账号服务分账
    // 注意：这里没有处理幂等——是作业中的一个选项
    _, err = s.accountSvc.Split(ctx, &account.SplitReq{
        Biz:   "reward",
        BizId: r.Id,
        Total: r.Amount,
        Items: []*account.SplitItem{
            {Uid: r.Author, Amount: authorAmount, AccountType: "income"},
            {Uid: PlatformUID, Amount: platformAmount, AccountType: "income"},
        },
    })
    return err
}

// key=cart:{uid}，field=skuId，value=数量|选中态 —— 一人一车，全 hash
rdb.HSet(ctx, "cart:1001", "sku:9001", "2|1")   // 加购 2 件、选中
rdb.HIncrBy(ctx, "cart:1001", "sku:9001", 1)    // 改数量：HINCRBY 原子自增
rdb.HDel(ctx, "cart:1001", "sku:9001")          // 删除

-- scripts/payment.sql
CREATE DATABASE IF NOT EXISTS `payment_db` DEFAULT CHARACTER SET utf8mb4;
USE `payment_db`;

CREATE TABLE `payment` (
    `id`             BIGINT UNSIGNED NOT NULL COMMENT '雪花ID，代码里生成',
    `payment_no`     VARCHAR(64) NOT NULL COMMENT '支付单号，透传给微信当 out_trade_no',
    `order_no`       VARCHAR(64) NOT NULL COMMENT '业务订单号，业务方传入',
    `user_id`        BIGINT NOT NULL COMMENT '支付用户',
    `amount`         INT NOT NULL COMMENT '金额，单位分（见上文 3.3 节）',
    `currency`       VARCHAR(8) NOT NULL DEFAULT 'CNY' COMMENT '币种',
    `pay_channel`    TINYINT NOT NULL DEFAULT 1 COMMENT '1微信 2支付宝',
    `status`         TINYINT NOT NULL DEFAULT 1 COMMENT '1待支付 2支付中 3成功 4失败 5已退款 6已关闭',
    `client_ip`      VARCHAR(64) NOT NULL DEFAULT '' COMMENT '下单时客户端IP，风控用',
    `paid_at`        DATETIME DEFAULT NULL COMMENT '支付成功时间',
    `transaction_id` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '微信支付订单号，回调后回填',
    `created_at`     DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    `updated_at`     DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_order_no` (`order_no`),            -- CreatePayment 幂等的根基
    UNIQUE KEY `uk_payment_no` (`payment_no`),
    KEY `idx_status_created` (`status`, `created_at`) -- 对账扫超时单用
) ENGINE=InnoDB COMMENT='支付订单';

-- scripts/payment.sql（续）
CREATE TABLE `refund` (
    `id`             BIGINT UNSIGNED NOT NULL,
    `refund_no`      VARCHAR(64) NOT NULL COMMENT '退款单号，重复退款的去重凭证',
    `payment_no`     VARCHAR(64) NOT NULL COMMENT '关联的原支付单',
    `amount`         INT NOT NULL COMMENT '退款金额，单位分',
    `reason`         VARCHAR(255) NOT NULL DEFAULT '' COMMENT '退款原因',
    `status`         TINYINT NOT NULL DEFAULT 1 COMMENT '1退款中 2成功 3失败',
    `refunded_at`    DATETIME DEFAULT NULL COMMENT '退款完成时间',
    `transaction_id` VARCHAR(64) NOT NULL DEFAULT '',
    `created_at`     DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    `updated_at`     DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_refund_no` (`refund_no`), -- 退款幂等的根基
    KEY `idx_payment_no` (`payment_no`)
) ENGINE=InnoDB COMMENT='退款单';

docker exec -i mysql mysql -uroot -proot < scripts/payment.sql
docker exec mysql mysql -uroot -proot -e "SHOW TABLES IN payment_db;"
# 预期输出：payment、refund 两行

// internal/payment/repository/payment.go
package repository

import (
    "context"
    "errors"
    "fmt"
    "time"

    "gorm.io/gorm"
)

// 支付状态机：只单向流转，终态（3/4/5/6）不再变更（纪律见上文 3.3 节）
const (
    StatusPending    int8 = 1 // 待支付
    StatusProcessing int8 = 2 // 支付中
    StatusSuccess    int8 = 3 // 支付成功（终态）
    StatusFailed     int8 = 4 // 支付失败（终态）
    StatusRefunded   int8 = 5 // 已退款
    StatusClosed     int8 = 6 // 已关闭（终态）
)

// Payment 支付订单（字段与第 1 步的表一一对应）
type Payment struct {
    ID            int64  `gorm:"primaryKey"`
    PaymentNo     string // 我方支付单号 = 微信侧 out_trade_no
    OrderNo       string // 业务订单号：幂等凭证
    UserID        int64
    Amount        int // 单位：分
    Currency      string
    PayChannel    int8 // 1=微信
    Status        int8
    ClientIP      string
    PaidAt        *time.Time
    TransactionID string // 微信支付订单号
    CreatedAt     time.Time
    UpdatedAt     time.Time
}

func (Payment) TableName() string { return "payment" }

type PaymentRepository struct{ db *gorm.DB }

func NewPaymentRepository(db *gorm.DB) *PaymentRepository {
    return &PaymentRepository{db: db}
}

// internal/payment/repository/payment.go（续）
// CreateOrGet 幂等创建：order_no 撞唯一索引时不报错，改查旧记录返回。
func (r *PaymentRepository) CreateOrGet(ctx context.Context, p *Payment) (
    old *Payment, created bool, err error) {
    err = r.db.WithContext(ctx).Create(p).Error
    if err == nil {
        return nil, true, nil
    }
    if errors.Is(err, gorm.ErrDuplicatedKey) { // 需开 TranslateError 才能识别
        var exist Payment
        if e := r.db.WithContext(ctx).
            Where("order_no = ?", p.OrderNo).First(&exist).Error; e != nil {
            return nil, false, fmt.Errorf("query existed payment: %w", e)
        }
        return &exist, false, nil
    }
    return nil, false, fmt.Errorf("create payment: %w", err) // 其余错误才是真故障
}

// internal/payment/repository/payment.go（续）
// UpdateStatusIfPaying 条件更新：只有非终态才允许改。
// 返回 false = 已是终态（重复回调）或单号不存在，调用方据此跳过后续动作
func (r *PaymentRepository) UpdateStatusIfPaying(ctx context.Context,
    paymentNo string, status int8, txnID string) (bool, error) {
    res := r.db.WithContext(ctx).Model(&Payment{}).
        Where("payment_no = ? AND status IN (?)", paymentNo,
            []int8{StatusPending, StatusProcessing}).
        Updates(map[string]any{"status": status, "transaction_id": txnID})
    if res.Error != nil {
        return false, fmt.Errorf("update payment status: %w", res.Error)
    }
    return res.RowsAffected == 1, nil
}

// GetByPaymentNo 回调后按支付单号取记录（拿 order_no 组装事件用）
func (r *PaymentRepository) GetByPaymentNo(ctx context.Context,
    paymentNo string) (*Payment, error) {
    var p Payment
    if err := r.db.WithContext(ctx).
        Where("payment_no = ?", paymentNo).First(&p).Error; err != nil {
        return nil, fmt.Errorf("get payment by no: %w", err)
    }
    return &p, nil
}

// FindTimeoutOrders 对账用：找出超时仍非终态的订单
func (r *PaymentRepository) FindTimeoutOrders(ctx context.Context,
    olderThan time.Duration) ([]Payment, error) {
    var list []Payment
    err := r.db.WithContext(ctx).
        Where("status IN (?) AND created_at < ?",
            []int8{StatusPending, StatusProcessing},
            time.Now().Add(-olderThan)).
        Limit(100).Find(&list).Error // 每轮最多 100 单，别一次拖垮库
    if err != nil {
        return nil, fmt.Errorf("find timeout orders: %w", err)
    }
    return list, nil
}

// internal/payment/wechatpay/sdk.go
package wechatpay

import (
    "context"
    "errors"
    "fmt"
    "sync"
    "time"
)

// WechatPaySDK 只抽象"我们用到的"微信能力（真实实现接官方 SDK）
type WechatPaySDK interface {
    // NativePrepay native 扫码下单，返回 code_url（正文 3.3 节流程的环节①）
    NativePrepay(ctx context.Context, outTradeNo, description string,
        amount int) (codeURL string, err error)
    // QueryOrderByOutTradeNo 按商户单号查微信侧状态（对账兜底，正文 3.4 节）
    QueryOrderByOutTradeNo(ctx context.Context,
        outTradeNo string) (tradeState, txnID string, err error)
    // CloseOrder 关闭超时未支付的订单
    CloseOrder(ctx context.Context, outTradeNo string) error
}

// 微信侧交易状态（真实 SDK 里是 native.TRADESTATE_*）
const (
    TradeStateSuccess = "SUCCESS" // 支付成功
    TradeStateClosed  = "CLOSED"  // 已关闭
    TradeStateNotPay  = "NOTPAY"  // 未支付
)

// internal/payment/wechatpay/sdk.go（续）
// MockWechatPay 内存版"微信"：不联网，用时间差模拟用户扫码付款
type MockWechatPay struct {
    mu         sync.Mutex
    orders     map[string]mockOrder // key: out_trade_no
    txnSeq     int                  // 自增的假微信订单号
    PayLatency time.Duration        // 下单后多久"用户支付完成"
}

type mockOrder struct {
    codeURL   string
    amount    int
    createdAt time.Time
}

func NewMockWechatPay() *MockWechatPay {
    return &MockWechatPay{
        orders:     map[string]mockOrder{},
        PayLatency: 30 * time.Second,
    }
}

func (m *MockWechatPay) NativePrepay(_ context.Context,
    outTradeNo, _ string, amount int) (string, error) {
    m.mu.Lock()
    defer m.mu.Unlock()
    if o, ok := m.orders[outTradeNo]; ok {
        // 复刻微信真实行为：重复单号返回同一 code_url（正文 3.4 节）
        return o.codeURL, nil
    }
    codeURL := fmt.Sprintf("weixin://wxpay/bizpayurl?pr=%s", outTradeNo)
    m.orders[outTradeNo] = mockOrder{
        codeURL: codeURL, amount: amount, createdAt: time.Now(),
    }
    return codeURL, nil
}

// internal/payment/wechatpay/sdk.go（续）
func (m *MockWechatPay) QueryOrderByOutTradeNo(_ context.Context,
    outTradeNo string) (string, string, error) {
    m.mu.Lock()
    defer m.mu.Unlock()
    o, ok := m.orders[outTradeNo]
    if !ok {
        return "", "", errors.New("order not found") // 模拟微信查无此单
    }
    if time.Since(o.createdAt) >= m.PayLatency {
        // 超过延迟视为"用户已扫码付款"
        m.txnSeq++
        return TradeStateSuccess, fmt.Sprintf("4200%08d", m.txnSeq), nil
    }
    return TradeStateNotPay, "", nil
}

func (m *MockWechatPay) CloseOrder(_ context.Context, outTradeNo string) error {
    m.mu.Lock()
    defer m.mu.Unlock()
    delete(m.orders, outTradeNo)
    return nil
}

// api/proto/payment/v1/payment.proto
service PaymentService {
    // 创建支付：返回二维码链接；对同一 order_no 幂等
    rpc CreatePayment (CreatePaymentReq) returns (CreatePaymentResp);
}

message CreatePaymentReq {
    string order_no = 1;    // 业务订单号（幂等凭证，如 reward:42:1001:1760000000）
    int64  user_id = 2;     // 支付用户
    int32  amount = 3;      // 金额，单位分
    string description = 4; // 商品描述，展示在微信收银台
}

message CreatePaymentResp {
    string payment_no = 1; // 我方支付单号
    string code_url = 2;   // 二维码链接，渲染成二维码是前端的活儿
}

// internal/payment/service/payment.go
package service

// 导入：context/errors/fmt + sarama + snowflake + zap
//        + 项目内 repository/wechatpay 包

// ErrOrderAlreadyPaid 已支付订单再次发起支付
var ErrOrderAlreadyPaid = errors.New("订单已支付，不能重复发起")

// PaymentService 支付领域服务：repo 挡重复创建，wx 是可替换的微信实现
type PaymentService struct {
    repo     *repository.PaymentRepository
    wx       wechatpay.WechatPaySDK
    producer sarama.SyncProducer // 第07章的同步生产者，第 5 步发事件用
    topic    string              // payment-events
    idGen    *snowflake.Node     // 第06章同款雪花库，生成支付单号
    logger   *zap.Logger
}

func NewPaymentService(repo *repository.PaymentRepository,
    wx wechatpay.WechatPaySDK, producer sarama.SyncProducer,
    topic string, logger *zap.Logger) *PaymentService {
    node, _ := snowflake.NewNode(15) // worker ID=15；多实例部署时改成配置
    return &PaymentService{repo: repo, wx: wx, producer: producer,
        topic: topic, idGen: node, logger: logger}
}

// internal/payment/service/payment.go（续）
// CreatePayment 创建支付单并调微信下单
func (s *PaymentService) CreatePayment(ctx context.Context,
    orderNo string, userID int64, amount int, desc string) (
    string, string, error) {
    id := s.idGen.Generate().Int64()
    p := &repository.Payment{
        ID:         id,
        PaymentNo:  fmt.Sprintf("PAY%d", id), // 支付单号 = 雪花ID，天然唯一
        OrderNo:    orderNo,
        UserID:     userID,
        Amount:     amount,
        Currency:   "CNY",
        PayChannel: 1, // 1=微信
        Status:     repository.StatusPending,
    }
    old, created, err := s.repo.CreateOrGet(ctx, p)
    if err != nil {
        return "", "", err
    }
    if !created { // 重复请求：按旧单状态走三分支
        switch old.Status {
        case repository.StatusSuccess:
            return "", "", ErrOrderAlreadyPaid
        case repository.StatusFailed, repository.StatusClosed,
            repository.StatusRefunded:
            return "", "", fmt.Errorf(
                "订单已终结(状态=%d)，请换单号重新发起", old.Status)
        default: // 待支付/支付中：返回原单参数（微信 Prepay 自身幂等）
            codeURL, e := s.wx.NativePrepay(ctx, old.PaymentNo, desc, old.Amount)
            if e != nil {
                return "", "", fmt.Errorf("wechat prepay(repeat): %w", e)
            }
            return old.PaymentNo, codeURL, nil
        }
    }
    codeURL, err := s.wx.NativePrepay(ctx, p.PaymentNo, desc, p.Amount)
    if err != nil {
        return "", "", fmt.Errorf("wechat prepay: %w", err)
    }
    return p.PaymentNo, codeURL, nil
}

// internal/payment/service/callback.go
// 导入：context/encoding-json/fmt/time + sarama + zap
//        + 项目内 repository/wechatpay 包

// PaymentEvent 发到 Kafka(topic=payment-events) 的支付结果事件
type PaymentEvent struct {
    EventID       string `json:"event_id"` // 消费端幂等凭证（确定性拼接，见下方坑）
    PaymentNo     string `json:"payment_no"`
    OrderNo       string `json:"order_no"` // 业务方靠它认领自己的单
    Status        int8   `json:"status"`
    TransactionID string `json:"transaction_id"`
    PaidAt        int64  `json:"paid_at"` // unix 秒
}

// HandleCallback 回调与对账共用的状态推进入口：
// 条件更新保幂等，首次生效才发事件
func (s *PaymentService) HandleCallback(ctx context.Context,
    paymentNo, txnID, wxState string) error {
    status := mapWxStatus(wxState)
    affected, err := s.repo.UpdateStatusIfPaying(ctx, paymentNo, status, txnID)
    if err != nil {
        return fmt.Errorf("update status: %w", err)
    }
    if !affected {
        s.logger.Info("重复回调，跳过", zap.String("payment_no", paymentNo))
        return nil // 幂等：已处理过也回成功，微信才会停止重试
    }
    if status != repository.StatusSuccess && status != repository.StatusFailed {
        return nil // 非终态不发事件，消费端只关心最终结果
    }
    p, err := s.repo.GetByPaymentNo(ctx, paymentNo)
    if err != nil {
        return err
    }
    payload, _ := json.Marshal(PaymentEvent{
        EventID:       paymentNo + ":" + txnID, // 确定性 ID：重试也不会变
        PaymentNo:     paymentNo,
        OrderNo:       p.OrderNo,
        Status:        status,
        TransactionID: txnID,
        PaidAt:        time.Now().Unix(),
    })
    _, _, err = s.producer.SendMessage(&sarama.ProducerMessage{
        Topic: s.topic,
        Key:   sarama.StringEncoder(paymentNo), // 同单同分区，保证顺序
        Value: sarama.ByteEncoder(payload),
    })
    if err != nil {
        // 可靠性兜底：本地消息表（第五节工程实践）
        return fmt.Errorf("produce payment event: %w", err)
    }
    return nil
}

// internal/payment/service/callback.go（续）
// mapWxStatus 微信交易状态 → 我方状态机
func mapWxStatus(s string) int8 {
    switch s {
    case wechatpay.TradeStateSuccess:
        return repository.StatusSuccess
    case "CLOSED", "REVOKED", "PAYERROR":
        return repository.StatusFailed
    default:
        return repository.StatusProcessing
    }
}

// internal/payment/web/notify.go
// 导入：net/http + gin + zap + 项目内 service 包

// NotifyRequest 微信回调（解密后）的精简结构；
// 真实验签+解密用官方 SDK，见正文 3.3 节
type NotifyRequest struct {
    OutTradeNo    string `json:"out_trade_no"` // 即我方 payment_no
    TransactionID string `json:"transaction_id"`
    TradeState    string `json:"trade_state"`
}

type NotifyHandler struct {
    svc    *service.PaymentService
    logger *zap.Logger
}

func NewNotifyHandler(svc *service.PaymentService,
    logger *zap.Logger) *NotifyHandler {
    return &NotifyHandler{svc: svc, logger: logger}
}

// WechatNotify POST /api/payment/wechat/notify
func (h *NotifyHandler) WechatNotify(ctx *gin.Context) {
    var req NotifyRequest
    if err := ctx.ShouldBindJSON(&req); err != nil {
        ctx.JSON(http.StatusBadRequest, gin.H{"code": 1, "msg": "参数错误"})
        return
    }
    if err := h.svc.HandleCallback(ctx, req.OutTradeNo,
        req.TransactionID, req.TradeState); err != nil {
        h.logger.Error("回调处理失败",
            zap.String("payment_no", req.OutTradeNo), zap.Error(err))
        // 返回 5xx 让微信重试，配合第 6 步对账兜底
        ctx.JSON(http.StatusInternalServerError,
            gin.H{"code": 1, "msg": "处理失败"})
        return
    }
    ctx.JSON(http.StatusOK, gin.H{"code": 0, "return_code": "SUCCESS"})
    // 铁律：成功必须回 200
}

// internal/payment/service/reconcile.go
// 导入：context/time + zap + 项目内 wechatpay/repository 包

// ScheduleReconcile 对账兜底：扫超时单 → 查微信 → 补单/关单
func (s *PaymentService) ScheduleReconcile() {
    ctx := context.Background()
    // 二维码默认 2 小时过期，留 1 分钟缓冲
    orders, err := s.repo.FindTimeoutOrders(ctx, 121*time.Minute)
    if err != nil {
        s.logger.Error("对账：查超时单失败", zap.Error(err))
        return
    }
    for _, o := range orders {
        state, txnID, err := s.wx.QueryOrderByOutTradeNo(ctx, o.PaymentNo)
        if err != nil {
            s.logger.Error("对账：查微信失败",
                zap.String("payment_no", o.PaymentNo), zap.Error(err))
            continue // 单条失败不中断整轮
        }
        switch state {
        case wechatpay.TradeStateSuccess:
            // 回调丢了但钱已付 → 补单：推进状态 + 补发事件
            if err := s.HandleCallback(ctx, o.PaymentNo, txnID, state); err == nil {
                s.logger.Info("对账：补单成功",
                    zap.String("payment_no", o.PaymentNo))
            }
        case wechatpay.TradeStateNotPay:
            // 一直没人付 → 关单
            if affected, err := s.repo.UpdateStatusIfPaying(ctx,
                o.PaymentNo, repository.StatusClosed, ""); err == nil && affected {
                _ = s.wx.CloseOrder(ctx, o.PaymentNo)
                s.logger.Warn("对账：超时关单",
                    zap.String("payment_no", o.PaymentNo))
            }
        }
    }
}

// internal/post/service/reward.go（只列本章新增核心）
// Reward 发起打赏：按手册规则拼 order_no，调 payment-service
func (s *RewardService) Reward(ctx context.Context,
    uid, postId int64, amount int, title string) (string, error) {
    orderNo := fmt.Sprintf("reward:%d:%d:%d", postId, uid, time.Now().Unix())
    resp, err := s.paymentClient.CreatePayment(ctx,
        &paymentv1.CreatePaymentReq{
            OrderNo:     orderNo,
            UserId:      uid,
            Amount:      int32(amount),
            Description: fmt.Sprintf("打赏帖子《%s》", title), // 展示在微信收银台
        })
    if err != nil {
        return "", fmt.Errorf("create payment: %w", err)
    }
    // 生产上还要：落一条待确认的打赏记录、
    // 把 codeURL 缓存 2 小时复用（正文 3.5 节）
    return resp.GetCodeUrl(), nil
}

// internal/post/consumer/payment_event.go
// （消息体字段同 PaymentEvent 的 JSON 契约）
// Consume 消费 payment-events：event_id 去重 + 只认领打赏单
func (c *RewardConsumer) Consume(ctx context.Context, e PaymentEventMsg) error {
    // 幂等第一层：event_id 去重（Redis SETNX，24 小时过期兜底）
    ok, err := c.redis.SetNX(ctx,
        "dedup:payment-evt:"+e.EventID, 1, 24*time.Hour).Result()
    if err == nil && !ok {
        return nil // 重复投递/重复消费：处理过，跳过
    }
    // 只认领打赏单：order_no 前缀 reward: 且支付成功（3）
    if !strings.HasPrefix(e.OrderNo, "reward:") || e.Status != 3 {
        return nil // 其他业务方的单各取所需，互不影响
    }
    // 幂等第二层（兜底）：按 order_no 条件更新打赏记录，
    // 重复消费不会重复记账
    // TODO(框架)：更新 reward 记录状态 → 更新帖子打赏数/金额冗余字段
    //             → 通知作者 → 分账（正文 3.7 节）
    c.logger.Info("打赏支付成功", zap.String("order_no", e.OrderNo))
    return nil
}

# configs/config.yaml 追加 payment 段
payment:
  grpc:
    port: 9100     # gRPC：对内提供 CreatePayment
  http:
    port: 8100     # HTTP：接收微信回调（生产须公网可达）
  db:
    dsn: "root:root@tcp(localhost:3306)/payment_db?charset=utf8mb4&parseTime=True"
  kafka:
    addrs: ["localhost:9092"]
    topic: "payment-events"
  wechat:
    mock: true     # 开发用 Mock；生产改 false 走真实 SDK

// cmd/payment/main.go（通用初始化见文件头注释，同构部分不重复贴）
func main() {
    var wx wechatpay.WechatPaySDK = wechatpay.NewMockWechatPay() // 开发环境 Mock
    if !viper.GetBool("payment.wechat.mock") {
        panic("真实微信实现按正文 3.3 节接官方 SDK 后替换这里")
    }
    svc := service.NewPaymentService(repo, wx, producer,
        viper.GetString("payment.kafka.topic"), logger)

    // gRPC 9100：先 Listen 再注册（顺序反了的后果见第12章）
    lis, err := net.Listen("tcp",
        fmt.Sprintf(":%d", viper.GetInt("payment.grpc.port")))
    if err != nil {
        panic(err)
    }
    grpcServer := grpc.NewServer() // 生产挂第10章日志 + 第14章治理拦截器
    paymentv1.RegisterPaymentServiceServer(grpcServer,
        grpc.NewPaymentServer(svc))

    ins := &registry.ServiceInstance{ // 注册 ETCD：复用第12章 pkg/registry
        ServiceName: "payment-service",
        InstanceID: fmt.Sprintf("payment-service-%s:%d",
            registry.GetOutboundIP(), 9100),
        Address: registry.GetOutboundIP(), Port: 9100,
        Protocol: "grpc", Weight: 100,
        Metadata: map[string]string{"version": "v1.0.0", "env": "dev"},
    }
    reg := registry.NewRegistry(etcdClient, logger)
    if err := reg.Register(ins); err != nil {
        panic(err) // fail-fast：注册不上就退出（第12章）
    }

// cmd/payment/main.go（续）
    // HTTP 8100：微信回调专用端口
    engine := gin.Default()
    engine.POST("/api/payment/wechat/notify",
        web.NewNotifyHandler(svc, logger).WechatNotify)

    // 对账 cron：第09章调度套路；多实例部署再加分布式锁防重复扫
    c := cron.New(cron.WithSeconds())
    c.AddJob("@every 1m", cron.FuncJob(svc.ScheduleReconcile))
    c.Start()

    go func() {
        _ = engine.Run(
            fmt.Sprintf(":%d", viper.GetInt("payment.http.port")))
    }()
    go func() { _ = grpcServer.Serve(lis) }()

    quit := make(chan os.Signal, 1)
    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
    <-quit
    _ = reg.Deregister()   // 优雅停机：先注销再停服（第12章套路）
    grpcServer.GracefulStop()
}

go run ./cmd/payment   # 日志出现 ETCD 注册成功 + 双端口监听

# ① 注册进 ETCD 了吗？
etcdctl get /services/payment-service/ --prefix
# 预期：能查到本实例

# ② 幂等下单：同一 order_no 连调两次
grpcurl -plaintext -import-path ./api/proto/payment/v1 -proto payment.proto \
  -d '{"order_no":"reward:42:1001:1760000000","user_id":1001,"amount":100,"description":"打赏帖子《Go入门》"}' \
  localhost:9100 payment.v1.PaymentService/CreatePayment
# 预期：{"paymentNo":"PAY...","codeUrl":"weixin://..."}
# 同参数再发一次，两次 codeUrl 完全一致（幂等生效）

# ③ 回调幂等：模拟微信回调两次
curl -X POST localhost:8100/api/payment/wechat/notify \
  -d '{"out_trade_no":"上一步的 paymentNo","transaction_id":"4200000001","trade_state":"SUCCESS"}'
# 预期：{"code":0,...}；立刻重复 curl 一次，日志出现「重复回调，跳过」

# ④ 事件不重复
kafka-console-consumer --bootstrap-server localhost:9092 \
  --topic payment-events --from-beginning
# 预期：只收到一条支付成功事件（回调幂等生效，事件没有重复发）

content-community/
├── api/proto/payment/v1/payment.proto   # ★ CreatePayment 接口定义（生成代码在 api/gen/payment/v1）
├── cmd/payment/main.go                  # ★ payment-service 启动入口
├── configs/config.yaml                  # ▲ 追加 payment 段
├── scripts/payment.sql                  # ★ 建库建表脚本
└── internal/
    ├── payment/                         # ★ 本章主战场
    │   ├── repository/payment.go        # 模型 + 幂等创建/条件更新/超时查询
    │   ├── wechatpay/sdk.go             # WechatPaySDK 接口 + MockWechatPay
    │   ├── service/payment.go           # CreatePayment 幂等三分支
    │   ├── service/callback.go          # 回调幂等 + Kafka 事件
    │   ├── service/reconcile.go         # 对账定时任务
    │   ├── grpc/server.go               # gRPC 薄壳
    │   └── web/notify.go                # 微信回调 Handler
    └── post/
        ├── service/reward.go            # ▲ 发起打赏：调 CreatePayment
        └── consumer/payment_event.go    # ▲ 消费 payment-events（event_id 幂等）