# 05｜一次秒杀购买，从点击到到账

前一站：[第一次运行](04-first-run.md) · 下一站：[后端与中间件](06-backend-reliability.md)

## 1. 把“买一份”拆成几个事实

你在页面只需点几次按钮，但系统必须分别记录：钱包身份可信、资格已经占用、凭证已经签好、用户已经授权、购买交易已经广播、资产已经在链上交换、确认索引已经处理。把这些步骤混成一个“成功”状态，断网或崩溃后就无法判断下一步。

本章用首发活动总量 10、A 领取一份来串起源码。源码阅读入口是 [flashsale](../../flashsale/types.go) 与 [FlashSale](../../contracts/src/FlashSale.sol)，完整规则见[发售架构](../02-architecture/flash-sale-design.md)。

## 2. 活动上线前：库存真的已经放进去

运营方 owner 先创建链上活动，并向 FlashSale 预存足额 MWETH。例如每份 1 lot、10 份，需要预存 `10 × 10^14` 原子单位，也就是 0.001 MWETH。合约校验实际收到的数量，因此不是只写一行“库存=10”。

随后后端导入已确认的活动，核对合约、代币、签名者、条款和库存，建立 SQL 活动。当前本地启动脚本会代为准备，没有完整运营后台。你在页面看到的可领取数量是 SQL 准入库存，链上 `sold` 只统计成功购买；`totalUnits - sold` 可能还包含已被资格占住的份数，不能直接当可抢数量。

## 3. 连接并登录：证明 A 控制钱包

浏览器向后端申请一次性挑战，后端给出绑定钱包、网站、链、随机数和时间的文本。A 用钱包签名，Go 恢复签名地址并确认与挑战相同；成功后消费挑战并创建登录会话。

会话通过 HttpOnly Cookie 交给浏览器，数据库保存 token 摘要；写请求还校验 Origin、dataset 和 CSRF。这样后端知道“这是当前 A 的请求”，而不是相信请求 JSON 随手写的一个地址。

登录不等于购买授权。退出会话不会删除资格，也不能撤回已经广播到链上的交易。

## 4. 领取资格：所有关键变化一起提交

A 点击领取，页面带上 `Idempotency-Key` 和 `quantity=1`。Go 校验身份、活动、健康和请求预算，然后在一个 SQL 事务里完成：

1. 锁定活动，检查请求键与该钱包原有资格。
2. 确定不可变的 reservationId、买方、数量、价格和 deadline。
3. 可用数量减 1，占用数量加 1。
4. 保存资格、原请求映射和待发布 outbox 记录。
5. 提交事务；失败则整组变化回滚。

PG 使用行锁，SQLite 本地模式先取得写入协调。最后只剩 1 份时，A/B 的资格裁决必须经过同一个活动库存事务，而不能分别读取缓存的 1 后都宣布抢到。

| 时刻 | available 可领取 | held 已占用 | confirmed 已购买 |
| --- | --- | --- | --- |
| 初始 | 10 | 0 | 0 |
| A 领取提交后 | 9 | 1 | 0 |
| A 链上购买并被索引确认后 | 9 | 0 | 1 |
| 如果 A 未购买而安全过期 | 10 | 0 | 0 |

始终保持 `total = available + held + confirmed`。只有领取事务 commit 后才算受理，HTTP 网络响应丢失不意味着事务没提交。

同一个键、相同业务应恢复原资格；同键跨活动冲突返回 409。即使 A 换一个新键，同钱包本场的唯一约束也会指向原资格，不能再扣一份。当前过期后 A 也不能重新领同一场，回收额度留给其他未参加的钱包。

## 5. 签名任务：先保证可恢复，再慢慢执行

outbox 和资格一起落库后，发布器将稳定 ID 的任务发到 RabbitMQ。收到 broker 发布确认才把 outbox 标成已发布；消费者先把 inbox 和签名 job 持久化，再 ack。

此时 ack 只表示“任务已经由业务数据库可靠接手”，不表示签名已经完成，更不表示用户已经付款。后台任务读取固定正文签名，再保存凭证，把资格由 SIGN_PENDING 改成 CLAIMABLE。

本地模式使用直接 outbox 调度，不走真实 RabbitMQ，状态协议仍有持久化恢复；若要观察 broker 确认和重投，必须用 `-Middleware`。

## 6. 凭证：发售服务给合约的授权书

凭证包含 activityId、reservationId、buyer、两种代币、quantityLots、totalQuoteAtomic、deadline、configVersion，并由服务端 signer 做 EIP-712 签名。合约认可的是这些完整字段及其域，不能只凭一个“我抢到了”的截图购买。

签名任务重试也必须签同一正文，不得每次延长 deadline；否则旧签名仍可能在链上有效，而库存已经按新逻辑回收，造成矛盾。

## 7. 授权和购买：资产在这一刻真正移动

A 先给 FlashSale 授予支付 MUSDT 的额度，再调用 `purchase(voucher, signature)`。这笔交易由买方发送和支付 Gas。合约检查：

- 当前未暂停、活动存在且在有效窗口内。
- 调用者正是 buyer，资格未 consumed，本钱包本场未 purchased。
- 当前块时间严格小于凭证 deadline，数量、金额和版本符合固定条款。
- 库存足够，签名由配置 signer 产生，域指向本链本合约。

通过后，合约标记消费，再从买家收 MUSDT 给 owner、从预存库存交付 MWETH 给买家；任一步出错，整笔调用回滚。使用先更新状态再外部调用及重入保护，可以减少外部代币调用再次进入同一逻辑的风险，但不代表支持所有奇异代币。

## 8. 页面显示 hash 后，为什么还没结束

页面可以上报交易 hash，后端只把它记作观察信息。不能因为客户端说“我买了”就改 confirmed；也不能仅看到 receipt 就忽略确认策略。

发售扫描器按确认深度读取区块、Purchased 事件和块 hash。校验字段与资格匹配后，把事件、资格、库存、块记录和游标放在同一 SQL 事务提交。重复扫描同一事件不会再次加 confirmed；金额或未知资格矛盾会触发保守冻结。

```mermaid
sequenceDiagram
    participant U as A/页面
    participant API as Go API
    participant DB as SQL
    participant MQ as RabbitMQ/Worker
    participant C as FlashSale
    participant I as 确认索引
    U->>API: 登录后领取，原请求键
    API->>DB: 库存+资格+请求+outbox 同事务
    DB-->>U: SIGN_PENDING
    DB->>MQ: 发布并确认
    MQ->>DB: inbox/job 持久化，随后 ack
    MQ->>DB: 固定凭证签名，CLAIMABLE
    U->>C: approve 后 purchase
    C-->>U: 交易回执与资产变化
    I->>C: 固定确认块读取 Purchased
    I->>DB: 事件+库存+资格+游标 同事务
    DB-->>U: CONFIRMED
```

## 9. 倒计时到零，为何还要等

页面倒计时按本地观察给用户提示，不足以证明链已经不能购买。RPC 可能断开，确认索引可能落后，最后一刻的交易可能已入块但还未被网站确认。

释放库存前，后端必须确认：已索引的确认块时间达到 deadline；同一个块 hash 下 `consumed=false`；该块仍是规范链上的对应块；SQL 锚点和事件没有矛盾。条件不全就保留 held，不为尽快恢复库存而猜结果。

## 10. 状态自测

正常路径：`SIGN_PENDING → CLAIMABLE → CONFIRMED`；前两个非终态可在链证据充分时进入 `EXPIRED`。深重组是数据集级冻结，不是把所有资格随意改成另一个购买结果。

问：SQL 中 held=1，RabbitMQ Ready=0，是否一定卡住？

答：不一定。消费者可能已经把任务持久化、签名完成，正在等 A 支付。Ready 只表示 broker 队列当前等待投递的消息数量。

问：领取返回超时，能否再生成一个键？

答：先恢复原资格/原请求。事务可能已提交，随意换键会让未知结果更难追踪；页面为此保存原上下文并使用钱包唯一资格恢复。
