# 链上限量发售架构与实现（v0.6）

本页对应 flashsale/、cmd/saleserver/、FlashSale.sol 和活动页。发售与二级交易统一使用 RabbitMQ；早期 Kafka 架构审阅是历史资料。操作见[验收手册](../04-testing/sale-acceptance.md)，验证见[测试说明](../04-testing/sale-testing.md)。

## 业务与权威

固定价发售已有标准 ERC20 MWETH/MUSDT：owner 预存 MWETH，用户用 MUSDT 购买，买方支付 Gas。每钱包每场至多一个资格，过期后本钱包不能重领，其他钱包可以领取回收额度。不支持 NFT、部分购买、资格转让、代付、跨链、退款或真人唯一识别。

1 lot = 10^14 base 原子单位 = 0.0001 MWETH；售价 10^6 quote 原子单位 = 1 MUSDT。uint256 以规范十进制字符串传输。合约 owner 与模拟管理员无自动关联。

```mermaid
sequenceDiagram
    participant U as 钱包 / 页面
    participant A as 发售 API
    participant D as SQL 权威
    participant Q as RabbitMQ
    participant W as 签名 Worker
    participant C as FlashSale
    participant I as 已确认索引
    U->>A: 一次性签名登录
    U->>A: quantity=1 + 请求键
    A->>D: 库存、资格、请求键、outbox 同事务
    D-->>A: commit
    A-->>U: 202 SIGN_PENDING
    D->>Q: persistent + mandatory + confirm
    Q->>W: delivery（手动 ack）
    W->>D: inbox/job commit
    W->>Q: ack
    W->>D: 固定 digest 签名 / CAS
    U->>A: 查询 CLAIMABLE 凭证
    U->>C: approve / purchase
    C-->>U: 收款与交付原子完成
    I->>C: 固定确认块 hash 拉取 Purchased
    I->>D: 事件、资格、库存、块、游标同事务
    A-->>U: CONFIRMED
```

发售独立进程、连接池和调度；二级撮合仍是单写者/FULL 日志，不向 Engine 引入 SQL 或网络。默认 SQLite 是显式本地演示；完整模式的库存权威是 PG。Redis 只限制入口，RabbitMQ 只分发任务，资金事实在合约。

## 数据与事务

schema 1 包含 sale_metadata、sale_activities、sale_reservations、sale_requests、sale_outbox、sale_inbox、sale_sign_jobs、sale_message_errors、sale_events、sale_blocks/cursor、sale_challenges/sessions、sale_tx_observations、sale_audits。库绑定 chainId/contract/assets/signer/owner/confirmations/startBlock，跨域拒绝复用。

不变量：total = available + held + confirmed，三项非负。购买由 (9,1,0) 变为 (9,0,1)；未用资格过期由 (9,1,0) 变为 (10,0,0)。SQL CHECK、条件 UPDATE 与对账一起约束。

先锁活动行，再查请求键与活动钱包唯一资格，生成不可变正文、扣可用/加占用、写请求与 outbox，同事务提交。成功点只有 commit。同钱包换键仍返回原资格；同键指向不同活动返回 409。请求键作用域为数据集数据库内 (wallet,key)，不是仅单活动。PG 单活动是热点行；SQLite 先写锁再读，避免读事务升级竞争。多活动事件按稳定 ID 顺序取锁；跨活动同键竞争由唯一约束兜底，失败事务整体回滚。

## 身份与接口

一次性 EIP191 登录文本绑定域名、URI、chainId、随机 nonce、签发与过期时间。挑战 5 分钟，会话 1 小时，数据库只存 token 摘要。Cookie 为 HttpOnly/SameSite Strict，HTTPS 下 Secure；所有写请求校验精确 Origin/dataset，登录后写另校验 CSRF。完整资格只能由所属钱包查询；当前只支持 EOA。

契约 api/sale-openapi.json，通过 /api/web3/sale-openapi.json 公开，前端类型由 openapi-typescript 生成。以下路径统一加 /api/web3：

| 方法与路径 | 用途 |
| --- | --- |
| GET /sale-config、/sale-status、/sales | 域、健康、活动 |
| POST /auth/challenges、/auth/sessions | 挑战与登录 |
| GET /auth/session；POST /auth/logout | 会话恢复/退出 |
| POST /sales/{id}/reservations | quantity=1、Idempotency-Key |
| GET /sales/{id}/reservation | 当前钱包资格恢复，未领取为 null |
| GET /sale-reservations/{id} | 所属钱包私有查询 |
| POST /sale-reservations/{id}/transactions | hash 观察，不能确认成交 |
| POST /admin/sales | owner 导入已确认、预存、未售出的链活动 |

owner 先独立创建链活动，确认后才能导入 SQL；没有完整活动编辑后台。配置开放后冻结，重复导入不重置库存。重启既有活动从 SQL 恢复，不要求再次满足零售出。

## RabbitMQ 交付与恢复

共享 messaging.Queue 使用官方 amqp091-go；默认交换机直接路由到持久 quorum 队列。交易/发售不同前缀，队列名追加 dataset。发布/消费 channel 分离，prefetch=16，消息 persistent，mandatory 路由，publisher confirm 后才标记 published。

confirm 前崩溃 outbox 重发；confirm 后、published 前崩溃可能重复。消费者提交 inbox/job 或稳定结算任务后才手动 ack；ack 前断连 broker 重投。连接重建声明相同队列，不删除消息。业务幂等来自 SQL 唯一键、稳定 ID 和合约 consumed/settled，不依赖 deliveryTag，也不承诺跨系统 exactly-once。

发售坏消息先写 sale_message_errors 再 ack；交易永久 JSON/签名错误 Nack 至持久 .dead 队列。SQL 暂时故障保持当前未 ack delivery 重试。quorum 的 delivery-limit=-1，避免临时重投次数导致有效任务被自动丢弃。死信不能触发释放库存或修改资金；重放需人工核对原域与 ID。

开发只有一个 RabbitMQ 节点和持久卷，不具有跨节点容灾。新增广播订阅者需要独立队列/交换机绑定；当前不是通用广播事件总线，也没有 Kafka offset/分区/group 语义。AMQP deliveryTag 仅在当前 channel 内有效。旧 broker 消息没有在线自动迁移工具。

## 状态与合约

SIGN_PENDING → CLAIMABLE → CONFIRMED；两个非终态均可经过确认核验变为 EXPIRED。深重组采用数据集级持久冻结，停止新资格并保留查询；不会自动把每条资格改为 REVIEW_REQUIRED。Worker 不改正文/deadline，不复活过期资格。

EIP712 域 GoExchangeSale / 1 / chainId / FlashSale，正文含 activityId、reservationId、buyer、baseToken、quoteToken、quantityLots、totalQuoteAtomic、deadline、configVersion。合约校验调用者 buyer、固定 signer、活动条款、未 consumed、钱包限购、库存和严格大于块时间的 deadline。

合约采用 OpenZeppelin ReentrancyGuard/SafeERC20。创建要求真实收到足额标准 base；购买先写标记再收 quote/交付 base，任一步失败整笔回滚。owner 仅活动结束后一次提取剩余库存；暂停不绕过结束时间。合约不可升级、签名角色不可轮换，密钥轮换与授权撤销是后续工作。

## 索引与安全过期

独立 startBlock、确认深度、连续父块与固定 blockHash 日志；每轮最多 64 块。事件/资格/库存/块/游标同事务，重复同 hash 幂等，未知资格或金额矛盾冻结。确认深度不等于所有 EVM 的协议级 finalized。

本地倒计时到零只停止发送新交易。必须已索引确认块 timestamp >= deadline，同 hash consumed=false，再核对该高度的规范块 hash，SQL 验证锚点 hash/timestamp 且无 Purchased 事件后才能 CAS 回收。RPC 不可用、不支持 EIP1898、索引滞后或锚点变化时不释放。

前端上报 hash 只作观察，终态来自扫描器。刷新通过钱包资格恢复；sessionStorage 按数据集/钱包/资格保存原键和交易观察。买方交易由钱包发出，后端不代为替换或取消。

## 资源与运维

HTTP 并发 128，本地每 IP 100/s，Redis 每钱包 5/s，请求体 16 KiB。调用有超时，扫描批次有界。冻结、索引故障、确认块时间落后本地超过 20 秒、outbox 超过 500 时停止新资格；既有资格仍可查看和原键确认。不承诺严格 FIFO 公平或容量 SLA。

回环 /check 比较同一个 SQL 快照与同块 hash 的合约 sold；/metrics 展示索引高度、outbox/job、隔离消息、差异和 Worker 错误。无自动修资产或解除冻结工具。恢复要协调 SQL、已签凭证、未发布 outbox 和链锚点，落后备份不能直接恢复准入。

下一阶段：运营 UI、生产密钥、RabbitMQ TLS/权限/多节点、备份恢复演练、长期压测、公共测试网及合约独立审计。实际覆盖以本轮报告为准。
