# 开发规范

当前 v0.6 增加独立发售与 RabbitMQ，见[发售架构](../02-architecture/flash-sale-design.md)和[本轮验证](../04-testing/sale-testing.md)。下方 v0.3/v0.5 为既有核心的规范背景。

发售库存、资格、请求去重与 outbox 必须同一 SQL 事务提交；Redis 只做准入。消息发布经 RabbitMQ confirm 后才标记 outbox，消费经 SQL inbox/签名任务提交后才 ack，重投保持原业务 ID。持久凭证不能因重试改变正文或 deadline。过期回收必须基于同一已确认块的 hash、timestamp 和链上 consumed 状态，禁止按本机倒计时释放库存。前端在未知结果时恢复原请求/交易，不生成第二次购买。

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

> 历史 v0.4 变更记录（当前增量见页首 v0.5）：链模式新代码仍需充分中文注释：整数tick/lot/原子单位、pending与filled、raw交易持久化顺序、对象所有权、取消竞态及恢复边界。Engine禁止SQL/JSON/RPC/时钟/随机/业务锁，由架构测试守护；手写OpenAPI经生成TS检查，生成文件不手改。未知广播保留原nonce/raw，禁止用Redis锁冒充资金或exactly-once。 当前链实现见[v0.5架构](../07-history/v0.5-design.md)，操作见[开发](web3-development.md)、[测试](../04-testing/web3-testing.md)、[部署](../05-deployment/web3-deployment.md)，证据见[本轮报告](../reports/2026-10-12-v0.4.md)。


状态：开发规范，更新 2026-10-11。适用于当前及后续业务代码、测试、前端、配置和文档；架构变更以[架构设计](../02-architecture/architecture.md)为准。

第 8 节充分注释已落实到现有源码，阅读入口见[代码阅读指南](code-reading-guide.md)。v0.2 已落实 OpenAPI/生成 TS、订单游标分页/数据集标识；v0.3 完成用户/审计/成交分页、loopback 指标/pprof、schema 校验、离线运维/对账、验证脚本与 CI 文件。Go 生成路由按 ADR 不采用；业务语义升级仍需单独历史 fixture。当前能力以实现和报告为准。

## 1. 领域与并发边界

1. `engine`、`orderbook`、领域金额代码只做内存业务运算。禁止 import SQL 驱动、HTTP/WebSocket、文件操作、观测输出包；禁止 `time.Now`、`rand`、`sync.Mutex/RWMutex`。
2. 一个核心 goroutine 执行全部 `Apply`；新市场不能自行引入另一写者。核心拥有树、链表、订单、账户、去重状态，外围不读取这些对象。
3. DTO、日志命令、核心结果必须有明确定义的所有权。跨队列后不复用 slice/map/指针；禁止把 `OrderRef` 暴露给 transport。
4. 核心业务错误返回错误码。内部不变量破坏可以触发外围监督停机，禁止 recover 后继续撮合；不得把整个命令中途回滚交给 panic。
5. 所有外围任务有生命周期、有限资源、超时与错误回传。禁止每条请求无限创建后台工作、无限队列、忽略 goroutine 错误。
6. 接入后 HTTP context 取消不取消业务命令；关闭、背压和恢复分别由 runtime 协调。

## 2. 金额与 ID

- 价格、数量、余额、成交额为 decimal；解析仅从受限十进制字符串，禁止 `NewFromFloat` 和金额 float 中转。
- 使用 decimal 方法比较与四则运算，不用 Go `==` 比较内部表示。展示除法明确精度，不能以展示均价结算。
- 精度、tick、step、上限由已版本化市场配置定义；超精度拒绝，不能悄悄截断。
- 只有索引用受控 `int64 price_ticks`，转换经过整除及溢出校验；金额数据库列为 TEXT。
- API 的 seq/ID 为字符串；日志 INTEGER 限制有符号 64 位，拒绝溢出。
- ID、事件索引、受理时间在输入确定后固定。恢复过程中不重新取时间、生成 UUID 或更改市场配置。

## 3. 数据与恢复协议

输入日志先提交再撮合，JournalWriter 只能发送已提交前缀；投影不能超前。投影的业务更新和 `applied_seq` 同一事务，不能先更新水位再补余额。

各数据库连接初始化连接级 pragma，验证实际值。Journal/Projector/迁移/备份/checkpoint 都在外围，有明确的写者或维护锁协调，不在运行期间多进程操作同一个数据目录。

命令包含 `schema_version`，恢复遇到未知版本拒绝启动并说明需要的程序版本。变更引擎业务行为须验证历史 fixture；字段迁移和业务语义变更分开记录。生产数据的恢复、升级命令默认不删除原目录。

当前元数据保存 engine_version/dataset_id；市场规则是与引擎版本绑定的编译期常量，初始化资金以 CREDIT 输入日志并按系统保留键去重。未实现可热改的交易规则配置表。相同数据目录重启不重新注资、不自动挂演示单、不重置序号。

## 4. 接口规范

OpenAPI 是字段名、枚举、金额字符串和错误码的契约源；生成代码头注明不可手改，检查重新生成无差异。当前源为 api/openapi.json，TS 由 openapi-typescript 生成，Go 仍手写且以 kin-openapi 真实响应测试对照；已提供 workflow 和本地 verify 脚本，未远程执行，不把文件存在称为远程 CI 通过。

接口使用 `side:BUY/SELL`，不继承 `bid` 布尔的歧义。未知字段、未知枚举、非法字段组合、超长载荷在接入层拒绝；资金和订单归属由核心验证。

写接口幂等键须限制长度和字符集，相同业务内容规范化后摘要一致；不把 request_id、received_at、seq 纳入摘要。响应保留 `processed_seq/result_seq` 的区别。

错误统一 JSON envelope，业务冲突与系统故障分开。日志与网络客户端必须检查返回值，客户端关闭 response body、配置 deadline、不把 4xx/5xx 解码为成功 DTO。列表限制 limit/depth，采用稳定复合游标，SQL 参数绑定避免拼接。

## 5. 日志与观测

核心输出业务结果和统计增量，外围生成 slog 日志与 Prometheus 指标。区分 request_id、command_seq、order_id、trade_id；指标 label 使用有限枚举，不使用订单 ID、幂等键或完整账户作高基数字段。

当前指标包含 journal/Apply/投影阶段累计次数、累计与最大耗时，队列/在途占用、受理/容量拒绝/失败计数、三水位及投影 lag、恢复时长、订单/去重规模、堆/GC/goroutine。计时边界见 observability.go/runtime.go；批阶段 count 是批次数，core count 是命令数。尚无 HTTP 端到端/排队直方图、按业务原因拆分计数、告警平台；这些是后续观测目标，max 不得解释成 p99。

不记录原项目示例私钥，不在日志输出全部业务 payload。调试 pprof 和 metrics 仅在独立 loopback 监听；远程采样经受控 SSH 转发或容器网络命名空间访问，标准接口和错误响应不泄露堆栈。

## 6. 前端规范

所有资金输入保留字符串；目前不做前端结算计算，未引入 decimal.js；将来需要预估时先引入经过核验的十进制库，不能用 JS Number 下结算结论。最终状态来自真实响应和查询，不写假成功或 mock 盘口替代联调。

引用 Carbon 色彩 token，禁止渐变、圆角方框，保持简短一致的文案与明确买卖标签。所有表单含 label、键盘操作、可见 focus 和不依赖颜色的状态；小屏正常操作。

GSAP 使用 `@gsap/react/useGSAP`、组件 ref scope、回调 contextSafe、卸载清理。优先 transform/opacity，盘口动画只处理可见数据并可中断，避免每条消息新建大量 tween；支持 reduced-motion。

网络断开后保留未明确结果的原内容和幂等键。v0.2 在发请求前保存 sessionStorage，按 dataset/账户/操作隔离；存储不可用则阻止发送。同标签页刷新可恢复，不承诺关标签/清存储后恢复。查询投影未赶上时保持“更新中”；不能拿旧余额覆盖最新下单反馈。接口重试区分幂等写和无副作用查询。

## 7. 代码、依赖与交付

- Go 执行 gofmt，使用可读的领域命名；依赖以接口围绕外部边界定义，不为每个结构体创建空泛接口。
- Go modules、前端 lockfile、代码生成工具固定版本；Go/Node 构建镜像固定补丁标签，Debian 运行层为系列标签，尚未锁定 digest；README 主分支描述不等于发布版 API。
- 引入依赖前核对许可证、release、兼容性及维护状态；保留归属，执行适用漏洞检查。
- 测试优先验证业务性质与故障保证；低影响文案修改不增加镜像实现的机械测试。核心算法、恢复与资金变更必须有针对性测试。
- 纯函数/单核心测试不启动业务服务；持久化和权限测试使用临时真实 SQLite/HTTP，前端纯函数用 Node test，hook/交互用真实浏览器。通过 `scripts/test.sh` 分层执行，新增业务测试同步[用例目录](../04-testing/test-cases.md)。
- 以每条命令后的数量/冻结/供给、价树/FIFO/索引和对象所有权为断言；测试不得只验证“无错误”。Go 覆盖率报告标注语句口径、未覆盖入口和子进程限制，不用提高百分比替代故障/权限验证。
- 提交按可审阅单元组织：契约/领域、撮合、日志、投影、接口、前端、部署。变更说明写明问题、结果、验证与剩余限制。
- 实现或决策变更同步更新架构、测试和部署；实验报告包含环境与原始命令，禁止只写“测试通过”。

每阶段完成定义：必要代码完成、相关测试通过、生成文件一致、文档更新、没有未解释的数据或恢复风险；不以“页面能打开”作为整个项目完成。

## 8. 代码注释要求（2026-10-10 新增）

用户要求“完善代码的注释，越全越好”。将充分注释作为交付要求，适用于 Go/TypeScript、测试、脚本和部署配置。

- 每个模块说明职责、依赖边界和关联文档；导出类型/函数及非平凡内部函数解释用途、输入输出和调用限制。
- 并发代码标明可变状态的唯一所有者、队列生产者/消费者、阻塞点、关闭顺序、失败停机与重放行为；区分外围锁与核心无业务锁。
- 撮合/资金解释价格时间优先、预扫描、自成交策略、冻结/释放与精确结算公式，给出人工可核对示例，注明数量/资金不变量。
- 认证解释密码哈希、会话摘要、Cookie/CSRF/Origin、RBAC、管理员初始化和停用语义；不能把前端按钮隐藏描述为权限保证。
- 持久化说明提交屏障、原子投影、水位、幂等、恢复、数据集/版本边界，明确哪些文件可重建。
- 前端解释异步状态、请求取消、未知结果保留原幂等键、WS 重连、动画范围与卸载清理；仅展示用 Number 转换注明不参与结算。
- 测试说明触发条件、为何断言能证明业务保证；部署脚本解释权限、卷、环境变量和不可逆动作。
- 注释与实际行为一致，修改代码时同步修改。保留易读格式，以说明原因和边界为主，不机械逐行复述赋值，也不虚构尚未实现的保证。

审阅检查：从注册到下单、日志提交、核心撮合、资金变化、查询投影和重启恢复，读者可沿注释理解完整链路；剩余限制与文档一致。

当前落实位置：[模块说明](../../backend/doc.go)、[撮合及资金](../../backend/engine.go)、[流水线](../../backend/runtime.go)、[存储恢复](../../backend/store.go)、[认证](../../backend/auth.go)、[接口](../../backend/http.go)、[前端](../../frontend/src/App.tsx)、[测试证明点](../../backend/integration_test.go)、[部署配置](../../deploy/compose.yaml)。配套[代码阅读指南](code-reading-guide.md)提供调用链和人工可算例子。维护时优先更新源码旁说明，再同步指南/架构及验证报告，避免只有文档宣称充分注释。

## 9. v0.3 运行与维护规范

诊断只用独立回环监听，固定阶段标签，禁止账号/key 高基数标签；核心不读时钟，外围计时。metrics max 不可写成 p99。常规 `bash scripts/verify.sh` 不修改源码/依赖，失败立即停止；CI 文件需远程实际执行才能称为 CI 通过。

离线维护取得服务相同 flock；backup/restore 拒绝覆盖目标，manifest/正规文件/摘要校验，金额逐表对账不走 SQL REAL。rebuild-views 保留原坏文件，不改 journal/auth。历史日志与去重不按 TTL 静默淘汰。新代码继续提供充分中文模块/函数/所有权/失败与资源注释。

新命令 schema_version=1，旧省略字段兼容 0；业务摘要排除格式版本/序号/时间，升级不破坏原键确认。未知格式/摘要错误/序号不一致直接拒绝恢复。Go 最低补丁 1.26.9；依赖升级同步 sum/构建/恢复与认证回归、govulncheck，模块未调用漏洞与可达漏洞分开记录。

## 10. 文档与注释的验收

以源码、公开契约、真实测试为事实源。架构/认证解释保证，接口指南说明客户端流程，数据生命周期与排障手册说明维护动作，历史报告保留当时证据。当前结论变化时增加更正或新报告，不覆盖旧原始日志/摘要/性能成绩。

注释只修改轮次应检查去注释后的 Go/TS 语法结构和脚本有效内容未变，再做格式、构建、契约与适用回归。生成 TS、lockfile、构建产物、依赖目录和历史发布包不手工加注释。Markdown 链接、代码块、命令参数与环境变量均需核对；文档中的命令注明执行环境与资源影响。

## Windows 本地工具补充

本地演示凭证由用户明确指定，脚本只启用回环本地管理员例外，不放宽公开注册或常规部署。PowerShell 5.1 保留 UTF-8 BOM/CRLF、路径引用、原生命令退出码检查、进程环境恢复与生命周期；Windows npm 安装与 WSL node_modules 隔离。行为变更须测试别名/密码/RBAC/配置边界并同步契约，见[Windows 指南](../05-deployment/windows-local-run.md)。

## v0.4 交付规则与注释审查

每个新增顶层函数/类型提供用途和边界注释；状态字段解释单位或含义。特别核对：Price/Quantity的tick/lot、raw交易与链nonce、pending守恒、签名v必须27/28与EVM一致、旧域/未知版本拒绝、专用锁连接不可自动重连、confirmed取消竞态、日志与投影不同回包时机、React当前钱包每次复核、脚本固定端口不得连接别人的链。注释解释原因，避免只重复代码。

标准门槛包含chaintrade的单元/SQL/HTTP/架构测试、链OpenAPI生成一致性和真实schema校验。独立合约/浏览器/中间件/容器的环境条件与实际执行记录分开，参考[链测试手册](../04-testing/web3-testing.md)。接口修订不手改生成文件，证据和源码摘要不得由历史发布包推定。

## v0.5 持续规范

新增模块必须注释数值单位、事务边界、游标条件、旧数据未知时间、错误分类与回滚边界。数据库结构改动用事务显式版本；任务读后更新必须 CAS，禁止终态回退和签名交易换 nonce。公开返回使用 TaskView，禁止 raw/密钥。对账只读，不实现“发现差异就自动补发”。

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