# 01｜先看懂项目在做什么

前一站：[入门目录](README.md) · 下一站：[Web3 基础](02-web3-basics.md)

## 1. 从一个具体故事开始

运营方准备发售 10 份 MWETH。每份是 0.0001 MWETH，价格固定为 1 MUSDT。A 和 B 都想买，网站让他们先领取资格，再在有效时间内完成链上购买。A 买到之后，还可以把这份资产挂到二级市场，B 用 MUSDT 接单。

这里有两个业务：一级发售是“向运营方按固定价格买”；二级交易是“用户之间按订单簿价格交换”。“秒杀”主要解决第一类业务中大量用户同时抢有限资格的问题。“Web3”体现在身份由钱包签名证明、资产交付由合约执行、最终资金变化发生在链上。

当前项目还保留了更早的模拟交易模式，它用数据库里的模拟账户记账，不把赠送余额变成链上代币。这套模式适合学习撮合、资金冻结与日志恢复。

## 2. 三种模式不要混在一起

| 模式 | 入口 | 谁记资产 | 用途 |
| --- | --- | --- | --- |
| 模拟交易 | `run-windows.cmd`，默认 8080 | Go 模拟账户状态，经日志恢复并投影到 SQL | 学传统交易后端、注册/管理员、冻结/成交 |
| 钱包二级交易 | `run-web3-windows.cmd`，默认 8081 | MWETH/MUSDT 代币合约；Go 记录订单与结算过程 | 学钱包签单、链下撮合、链上结算 |
| 限量发售 + 二级交易 | `run-sale-windows.cmd`，8082 + 8081 | 发售合约交付测试币，结算合约做后续交换 | 完整跑通秒杀资格、购买、再交易 |

初学者优先选第三行，一键准备两个服务和同一条本地链。不要把模拟管理员的注资当成给钱包转币，也不要把发售资格数据库当成交易订单簿。

## 3. 页面、Go 和合约分别做什么

页面负责显示和收集操作。React 显示活动、余额、资格倒计时和交易状态；ethers 负责和钱包、RPC、合约交互。页面可以提交交易和观察结果，却没有权力直接把一份 SQL 资格改成“资产到账”。

Go 后端负责网站业务。`saleserver` 处理钱包登录、资格、SQL 库存、凭证签发、链索引和回收；`web3server` 处理签名订单、撮合、结算任务及历史；原 `server` 服务模拟交易。后台 Worker 是持续处理任务的代码，不一定是另一台机器。

合约负责链上规则。`FlashSale` 检查凭证并收款交货；`Settlement` 检查双方签名和订单约束，原子交换两种资产；Mock 代币合约记录测试余额和授权。它们都运行在 Anvil 提供的本地 EVM 中。

```mermaid
flowchart TD
    A[用户与钱包] --> UI[React 页面]
    UI --> SALE[Go 发售服务 8082]
    SALE --> SQL[SQL 库存 资格 任务]
    SQL --> MQ[RabbitMQ 分发]
    MQ --> W[Go 签名 Worker]
    W --> SQL
    UI --> RPC[Anvil RPC 8545]
    RPC --> FS[FlashSale 购买合约]
    FS --> TOKEN[MWETH 与 MUSDT 合约]
    UI --> TRADE[Go 交易服务 8081]
    TRADE --> SET[结算任务与 relayer]
    SET --> RPC
    RPC --> SC[Settlement 交易合约]
    SC --> TOKEN
```

Redis 未画进主要资金路径：完整中间件模式中它做入口限流/缓存，不能决定哪笔资产已经成交。

## 4. 这是哪一种“去中心化”

资产转移规则在合约上可检查，钱包私钥不需要交给交易后端，但订单接入、排序和发售资格仍由中心化 Go 服务管理。发售还依赖签名服务为资格签发凭证。因此系统具有明确的运营方与服务可用性依赖，不能仅因使用区块链就声称全流程去中心化。

二级交易本金在用户钱包；买卖双方事先给结算合约额度，由指定 relayer 提交结算。发售不同：运营方先把待售库存放进合约。买家实际购买时，支付代币交给 owner，待售币从合约交给买家。两者的保管边界不同。

## 5. 目录就是系统地图

| 目录 | 初学者可以怎么理解 |
| --- | --- |
| `backend/` | 模拟交易的规则、账户、日志、HTTP 和测试 |
| `chaintrade/` | 钱包签单、纯撮合核心、任务/raw 交易、索引、对账 |
| `flashsale/` | 发售资格、库存事务、登录、凭证、链确认和回收 |
| `messaging/` | 两种业务共享的 RabbitMQ 运输层 |
| `contracts/src/` | Solidity 链上规则 |
| `cmd/` | 各 Go 程序的启动入口 |
| `frontend/src/` | 模拟页、钱包交易页、发售页与恢复逻辑 |
| `api/` | OpenAPI 接口契约，描述请求响应 |
| `scripts/` | 启动、部署 fixture、检查和验收自动化 |
| `deploy/` | 容器、服务配置和监控模板 |
| `docs/` | 按主题分类的说明；报告和证据单独保留 |

## 6. 本地测试“真实”在哪里

Anvil 真正执行合约字节码、验证签名、记录交易回执和改变代币余额，因此不是前端直接显示“购买成功”的假流程。但这条链由本机控制，可以重建、快进和制造故障，没有公共链的经济价值、共识环境或容量结论。

相关代码入口：[发售服务](../../cmd/saleserver/main.go)、[交易服务](../../cmd/web3server/main.go)、[部署脚本](../../scripts/sale-dev.mjs)。整体能力和未完成项看[当前进度](../00-overview/current-progress.md)。

## 7. 自测

问：为什么网站显示资格已领取，但钱包余额没有增加？

答：领取只占用 SQL 中的购买额度，还没有调用合约支付和交付。拿到凭证后还要授权、购买并等待链确认。

问：为什么不能用模拟管理员加 1 ETH，再去发售页支付？

答：模拟资金与链上资产属于不同状态系统，管理员 CREDIT 只改变模拟账本；本地钱包的测试币由 fixture 部署时准备。
