# 链模式开发与本地运行

v0.6 已新增发售入口和 RabbitMQ；完整运行按[手动验收](../04-testing/sale-acceptance.md)，当前边界见[进度](../00-overview/current-progress.md)。下文交易 dev 命令只启动二级市场；发售使用 run-sale-windows.cmd 同时启动两个服务。

> 当前基线：模拟 v0.3 保留，独立链模式升级为 v0.5。新增完整历史查询、任务版本保护、已确认事件索引、只读对账和基础告警，见 [设计](../07-history/v0.5-design.md)、[执行报告](../reports/2026-10-12-v0.5.md)。历史报告与证据保留原版本。

适用 v0.5 独立钱包模式，原模拟模式运行方式见项目README。本模式不使用管理员账户余额，注册/登录功能继续保留在模拟服务。范围、状态和权威见[v0.5架构](../07-history/v0.5-design.md)。

## 从干净依赖开始

需要Go 1.26.9、Node22+、npm、浏览器；下面命令在项目根目录执行。只连接本次Anvil，首次下载需要网络。标准代理不可用时可单条命令指定 `GOPROXY=https://goproxy.cn,direct`，不改全局设置。

```bash
go mod download
npm --prefix contracts ci
npm --prefix contracts run compile
npm --prefix frontend ci
npm --prefix frontend run build
npm --prefix contracts run dev
```

访问 http://127.0.0.1:8081/?mode=web3 。脚本部署MockWETH、MockUSDT、Settlement；生成 `bin/web3-dev/config.json`，每次新建时间戳数据目录，不覆盖旧数据。Ctrl+C停止本次Go/Anvil子进程。端口8545/8081须空闲。每次Anvil新历史，旧数据不能复用，即使地址与chainID相同；数据库任务域还含dataset。

钱包增加本地RPC `http://127.0.0.1:8545`、链ID31337。仅导入 `contracts/scripts/local.mjs` 中公开Anvil测试key对应账户1和2；账户0专供relayer。这三个key属于公开fixture，不可用于公共链真实资产。两个测试钱包各有10MockWETH与100000MockUSDT，部署脚本已授权合约；页面授权按钮可重新授权。用不同钱包卖2WETH@100、买3WETH@105：先见pending2，再见filled2，实际支付200USDT；剩余1WETH买单可链上撤销。

Windows双击 `run-web3-windows.cmd`。脚本在 `bin/windows-web3` 安装独立平台依赖并构建页面，避免使用WSL的node_modules；原 `run-windows.cmd` 的pinkode管理员与data-windows保持独立。新脚本本轮未在Windows原生环境实测。

## 连接真实开发中间件

先设置开发数据库密码，再启动指定compose的三个服务（不会创建应用容器）。开发端口均向回环绑定。

```bash
export WEB3_DB_PASSWORD='local-web3-password'
docker compose -f deploy/web3-compose.yaml up -d redis postgres rabbitmq
export WEB3_REDIS_URL='redis://127.0.0.1:16379'
export WEB3_POSTGRES_DSN='postgres://exchange:local-web3-password@127.0.0.1:15432/exchange?sslmode=disable'
export WEB3_RABBITMQ_URL='127.0.0.1:5672'
npm --prefix contracts run dev
```

这里密码仅演示；云部署必须另设。第一次库可为空；第二次本地dev重建Anvil与dataset时，创建新的PG数据库并改DSN，保留原库作恢复证据，不能删任务表来绕过域检查。未配置中间件时显式本地模式用独立SQLite任务、直接outbox分发、无Redis共享限流；配置了但故障会拒绝启动。

## 改代码的顺序

1. 修改业务约束时先列出四项数量守恒、重试/取消/未知广播影响，更新设计和用例。
2. 合约改动先跑compile/test；修改签名字段时Go TypedData、Solidity TYPEHASH、前端和契约一起更新，换新合约及数据域。
3. Engine只接收确定命令；新RPC/SQL/密码学放外围。修改Apply后对重放和兼容做判断，不隐式解释旧日志。
4. API先改 `api/web3-openapi.json`，执行 `npm --prefix frontend run web3:generate`，不要手改生成TS。补真实响应校验。
5. 运行 `bash scripts/test.sh web3`，再常规verify和真实中间件用例，按最终证据更新文档。

阅读路径：types→engine→store→tasks/middleware→chain→index/history/reconcile/observability→http→cmd/web3server→Web3App/Web3History→Settlement。新函数和关键字段均需中文注释，解释单位、所有者、恢复及错误边界；测试注释说明证明点，脚本注释说明资源隔离与清理。

## 配置

| 环境变量 | 默认/含义 |
| --- | --- |
| WEB3_CONFIG | bin/web3-dev/config.json：公开链域，必须与合约getter一致 |
| WEB3_DATA_DIR | data-web3：不可复用模拟目录 |
| WEB3_RPC_URL | http://127.0.0.1:8545 |
| WEB3_RELAYER_KEY | 必填，与config relayer相符，只来自受限环境 |
| WEB3_LISTEN_ADDR / WEB3_ALLOWED_ORIGIN | 127.0.0.1:8081 / 对应http Origin |
| WEB3_FRONTEND_DIR | frontend/dist |
| WEB3_DIAGNOSTICS_ADDR | 空关闭；仅允许数值回环，例如127.0.0.1:9091 |
| WEB3_POSTGRES_DSN | 空为显式SQLite任务；非空PG权威 |
| WEB3_REDIS_URL | 空关闭Redis；非空缓存与共享限流 |
| WEB3_RABBITMQ_URL / WEB3_RABBITMQ_QUEUE | AMQP URL；空为显式本地直连；默认队列前缀 exchange-settlements，追加 dataset |

配置confirmations在JSON中为1–128，默认fixture2；修改域或确认策略拒绝复用日志。固定inflight/历史/响应预算见架构；没有声称自动调参或全市场扩容。

## v0.5 历史、对账和升级

钱包页面底部“交易记录”支持四种类型、25条翻页、当前钱包筛选和任务详情。trades 只列 CONFIRMED 意图，刷新首屏才能收录刚确认的旧意图；翻页过程对象状态仍可能变化。

```bash
export WEB3_DIAGNOSTICS_ADDR=127.0.0.1:9091
npm --prefix contracts run dev
# 另一个终端：
curl http://127.0.0.1:9091/check
curl http://127.0.0.1:9091/metrics
curl 'http://127.0.0.1:8081/api/web3/history/orders?limit=25'
```

已有同域 v0.4 数据升级前停机备份，不删库。任务 schema 2 事务迁移并赋 version=0，不改旧 raw/hash/nonce；历史没有记录的时间仍为0。chain-views 补索引表，从创世开始补拉已确认块，索引未追平先显示 lag。日志 schema 与 Domain JSON 不变，确认策略/合约变更仍须新域方案。新结构运行后回退旧二进制会遗漏版本维护，禁止直接回退；恢复停机备份并先人工核对已广播交易。

独立读池：日志/投影的 WAL 读取与唯一写连接分开，每读池1连接；SQLite读池query_only，PG任务Reader独立1连接，owner与任务写池仍分别占用专用/业务连接。TestReadSnapshotDoesNotBlockWriter 保持旧水位快照时仍能完成新命令，避免对账占住唯一写池。查询仍有CPU/磁盘与WAL保留成本，需要超时和后续增量策略。
