# 开发计划与过程记录

整理日期：2026-11-02。当前 v0.6 已完成独立发售、RabbitMQ 替换、Windows 一键入口和前端验收，随后补齐中文注释。操作见[手动验收](../04-testing/sale-acceptance.md)，当前能力见[开发进度](current-progress.md)，阶段摘要见[时间线](timeline.md)，实际结果见[报告目录](../reports/README.md)。以下保留历史过程，不以整理日期覆盖原执行日期。

> 版本背景（2026-10-12）：v0.5 增加完整历史、任务版本保护、确认索引、只读对账和基础告警，见[设计](../07-history/v0.5-design.md)与[报告](../reports/2026-10-12-v0.5.md)。全项目现为 v0.6，模拟模式仍保留 v0.3；历史报告和证据按原版本阅读。

> 历史 v0.4 变更记录：当时按业务设计→合约/单写者/日志→可靠任务→真实 Redis/PG/Kafka→钱包页面→故障/浏览器/容器回归→同步文档推进。使用现成 go-ethereum、OpenZeppelin、ethers、Anvil 和客户端，不自研密码学/消息队列。完成范围以 [v0.4 报告](../reports/2026-10-12-v0.4.md)为准，v0.5 补齐本地已确认事件索引，v0.6 改用 RabbitMQ；自动 HA 和公共链仍为后续。

下方 P0–P8 表以 2026-10-11 模拟 v0.3 交付为范围；链交易 v0.4/v0.5 和发售 v0.6 的完成记录见第 3 节对应日期。

## 1. 模拟 v0.3 阶段与完成条件（2026-10-11）

| 阶段 | 实现与文档交付 | 验证门槛 | 该阶段交付状态 |
| --- | --- | --- | --- |
| P0 需求/审计/架构 | 审计、选型、架构、规范、测试/部署与面试 | 对照 goal.md/用户授权持续开发 | 已完成；文档以最终实现同步 |
| P1 契约与领域 | 精确金额、连续 ID/格式版本、错误、OpenAPI/生成 TS | 金额/fuzz 种子/真实响应与生成一致性 | 已完成；Go 路由/DTO 按明确 ADR 保留手写 |
| P2 内存核心 | 单写者、红黑树/FIFO、模拟账户/资金/幂等 | 场景/守恒/随机序列/成交预算/benchmark | 已完成 |
| P3 外围日志与恢复 | FULL 屏障、重放/校验、生命周期 | 提交/执行/投影/恢复精确 SIGKILL、重复恢复 | 已完成可本地验证窗口；真实断电/磁盘满另需硬件环境 |
| P4 投影与接口 | 批原子投影、水位、REST/WS、用户/订单/审计/成交分页、背压 | race、批回滚、拒绝不入日志、取消等待仍执行 | 已完成；资金审计包含执行结论 |
| P5 前端联调 | 认证/交易/管理、Carbon/GSAP、刷新恢复、历史分页 | 8 个真实浏览器场景、移动屏、socket 重连 | 已完成；全网断网/恶劣网络矩阵不由该场景保证 |
| P6 部署与实验 | 云/容器手册、离线 CLI、指标/pprof、发布包、性能证据 | 本地恢复/容器同卷重启及备份恢复、分层实测 | 本地/运行镜像已验证；云实机无资源，在线基础镜像受用户源 DNS 阻断 |
| P7 交付整理 | 充分中文注释、规范/设计/测试/部署/过程/面试、验证脚本/CI 定义 | 已实现能力关联代码/测试/原始证据，明确外部限制 | 已完成；远程 CI 文件需推送 Git 仓库才执行 |
| P8 可选优化 | 快照、Redis、分区、日志替代/内存治理 | 以 profiling/产品需求证明必要，再验证恢复协议 | 不属于模拟 v0.3 完成条件；Redis 后在独立链模式落地，快照/分区等仍为后续 |

用户已授权开发，并追加前后端注册/登录、管理员和充分注释要求。上表记录该阶段交付范围，剩余项与验证报告明确区分。

## 2. 关键风险与应对

| 风险 | 解决思路 | 对应验证 |
| --- | --- | --- |
| 核心独占但外围持有共享对象 | 命令与结果值化、复制，不暴露 OrderRef | race、所有权代码评审 |
| 外围 IO 慢导致积压 | 有界队列/载荷、在途额度、批提交、可观测背压 | 存储延迟/慢客户端实验 |
| 崩溃后业务重复或丢失 | 先日志后核心、确定性序号、幂等、原子投影 | R01–R07 及重放比对 |
| 恢复语义随版本改变 | 固定 engine/schema 和市场配置，历史 fixture | 升级兼容/拒绝未知版本 |
| 金额精度与资产精度不匹配 | tick/step 校验、产品精度明确、无静默舍入 | 金额/冻结守恒测试 |
| 模拟结算变成完整交易所工程 | 首版零手续费和注册用户模拟账户，链上扩展独立 | 范围审阅与阶段交付 |
| 去重和历史数据增长 | 明示演示数据量限制，监控内存/磁盘，后续设计期限协议 | 长时负载和恢复实验 |
| 云资源当前不可用 | 不阻塞本地与容器可验证工作；云实测单列待执行 | 部署记录区分设计/实测 |
| 文档与实现漂移 | 每阶段同步文档、契约生成检查、实验来源链接 | 最终交付交叉核对 |

## 3. 按日期排列的工作记录

### 2026-10-09：需求确认与设计

- 读取更新后的 goal.md，确定 Go 面试项目、原仓库问题审计、优先复用开源、前端联调和文档要求。
- 下载原仓库到临时参考目录，固定提交 `591fa0029c034a0b76fe91b61b2350485ff9fbab`；阅读业务源码与现有测试，形成静态审计；未执行原仓库程序。
- 检索 decimal、GoDS、google/btree、现成撮合项目、WAL/数据库、HTTP/WS、接口生成、Carbon 和 GSAP；发现 btree 归档、现成 orderbook 的文档/module 不一致、SQLite 版本需包含 WAL 修复。
- 根据用户补充，明确全局单核心 goroutine，无业务 mutex，所有 IO/网络/序列化/持久化置外围；设计先日志后核心和异步投影。
- 写入设计、开发规范、测试设计、云主机/容器部署、开发记录、面试初稿；对根 README 和 docs 中全部 Markdown 执行本地相对链接存在性及代码围栏配对检查，通过。另核对架构中的持久化、幂等、投影水位、资金与部署语义，补充在途额度释放时机。

截至该次设计记录，没有业务代码、测试成绩、吞吐成绩或部署实例；后续实现见下方记录。

### 2026-10-10：补充详细面试 Q&A

- 新增[详细面试 Q&A](../06-interview/interview-qa.md) 40 问，展开高可用/防双主、资金与对账、下游隔离、重放升级兼容及长期运维差距。
- 区分连接数、HTTP 并发、可靠在途额度、命令/新订单/成交吞吐；给出阶段容量模型与 Little 定律算例，明确全部示例数字不是压测成绩。
- 讨论外围 Redis 行情缓存、共享限流和网关分发，保留核心与日志权威；说明缓存序号、数据集重置、min_seq、故障回退和去重边界。
- 用市场订单簿与共享 USDT 案例说明多个单写者分区，记录额度划分/资金预留及迁移、路由、幂等复杂度；未改变第一版单核心架构，未安装 Redis 或编写业务实现。

### 2026-10-10：首版实现与认证扩展

- Go 实现 decimal/红黑树/FIFO、订单状态/资金/幂等、外围日志提交与投影/恢复；认证使用独立 auth.db + bcrypt + Cookie/CSRF，管理员由部署配置初始化。
- React 实现注册/登录、交易和管理页，Carbon 配色与 GSAP 清理；普通用户不能调用管理接口，不能以请求 account_id 冒充其他用户。
- 原默认 Go 代理超时，切换可用代理完成依赖安装；SQLite v1.60.1 需要 Go 1.26，升级并在启动检查内嵌 SQLite 修复版本。
- 初版行情查询扫描活动订单，改为事务内增量维护聚合价档；行情采样器共享快照。幂等摘要编码移到外围，核心不做 JSON 编码。
- 浏览器测试发现 label 的单位/option 文字影响可访问名称，补明确 aria-label，端到端通过。依赖审计修复 Vite/Playwright 旧版漏洞。
- 实际测试、容器及崩溃恢复记录见[验证报告](../reports/2026-10-10.md)。目录目前集中在 backend，未实现生成客户端/完整管理 CLI/快照/全量分页/压测，保留后续交付项。

### 2026-10-10：注释要求落地

用户追加“注释越全越好”，已写入 goal.md 和开发规范第 8 节；补充后端/前端/测试/部署注释，覆盖所有权、日志屏障、资金公式、认证权限和恢复边界。该要求持续适用于之后的新代码与修改。增加[代码阅读指南](../03-development/code-reading-guide.md)串联真实调用链；补齐 Go 类型/函数、前端组件/effect、测试证明点、脚本与部署配置说明。

梳理时修复启动错误路径具名返回值被置 nil 后清理 panic，添加未知版本拒绝与锁释放测试；前端补身份/请求顺序与写后读水位保护，避免旧响应覆盖当前数据。最优价缓存与树极值在每条核心测试命令后交叉检查。Go/前端格式化及相关验证结果见报告。

### 2026-10-11：注释与容器复核收尾

最新源码通过 Go 测试/race/vet、前端构建/格式/零漏洞审计、本地与容器两轮浏览器交易联调、真实 SIGKILL 重启及容器持久卷重启一致性；内嵌 SQLite 实读为 3.53.4。测试环境停止后保留独立测试数据与 Docker volume，不删除权威数据。完整在线镜像构建仍受主机镜像源 DNS 故障阻断，未做云实机部署/压测。

### 2026-10-11：v0.2 接口与请求恢复

- 建立 OpenAPI JSON，复用 openapi-typescript 7.8.0 生成 TS、kin-openapi v0.133.0 校验真实响应，明确 Go 手写边界；契约公开嵌入程序，容器构建补 api/。
- 订单改为有水位/游标的页对象，按创建序号 seek、固定首屏上界；新增单笔订单及同账户首次结果查询，增加索引，删除旧固定数组实现。
- journal 生成/保留 dataset_id；分页、写请求、行情和浏览器 pending 均区分数据集，旧库升级不改历史命令。
- sessionStorage 先保存再发送，刷新/重登录当前身份恢复原键/内容；存储故障阻止写，撤单终态仍有确认入口。
- Go 场景/race/vet、生成一致性/build/format/零漏洞审计、真实 SIGKILL 恢复、本地与首版卷升级容器各 6 个浏览器场景通过；见[报告](../reports/2026-10-11-v0.2.md)。容量/云资源等保持独立待完成项。

### 2026-10-11：v0.3 模拟架构完成

- 用户授权持续开发至目前架构完成。补齐用户/资金审计/公共成交分页、loopback 指标与标准 pprof、配置预算、离线 init/check/backup/restore/rebuild-views、批投影/恢复前缀跳过及发布工具。
- 旧日志 schema=0 兼容，新命令 schema=1，摘要保持业务语义；未知格式/缺口/篡改拒绝启动。坏投影保留后可从 journal 重建，身份库不可删除。
- 精确进程崩溃窗口、投影单条/批回滚、背压/取消等待、守恒随机序列、成交预算、WS 清理、序号耗尽和备份对账实测；前端管理分页/资金结果/真实 socket 自动重连加入整套。
- 漏洞审计发现 Go 1.26.0 标准库问题，升至 1.26.9，crypto 0.58.0/sys 0.49.0；当前可达漏洞与模块未调用漏洞分开记录。升级同步 Docker/CI/发布构建要求。
- 完整设计/验证/容量与外部限制见[v0.3 设计](../07-history/v0.3-design.md)、[报告](../reports/2026-10-11-v0.3.md)及保存的 evidence-v0.3 原始结果。P8/真实云/断电/远程 CI 不冒充已完成。

### 2026-10-11：测试完善与发现问题的回归

- 补充后端/前端单元、HTTP/认证事务/离线 CLI/资源/所有权边界，新增逐节点价树/FIFO/索引不变量；提供 test.sh、覆盖率/JSON/HTML、完整手册与用例映射。
- 发现首次 Order 与幂等记忆指针共享、运行时回包与投影切片共享，新增失败/受控窗口回归后分离副本，业务规则与日志版本不变。
- 核对 JSON 用例清单发现旧 crash_windows_test.go 被 GOOS 文件名限定而未在 Linux 收集。改名、增加收集门槛，六个窗口本轮真实执行通过；上方 v0.3 记录中的“精确窗口实测”应按本次更正理解，上一轮普通 SIGKILL 不替代六窗口。
- 结果/覆盖率与外部未执行项见[测试完善报告](../reports/2026-10-11-test-hardening.md)；旧发布包/镜像/性能属于历史版本，没有用文档更新冒充本轮重新打包或压测。

### 2026-10-11：文档与注释审阅

继续按用户要求完善全部手写代码注释与现有文档；统一当前能力与候选/历史边界，补齐[接口使用](../03-development/api-guide.md)、[数据生命周期](../05-deployment/data-lifecycle.md)、[排障手册](../05-deployment/operations-runbook.md)。本轮以解释与纠偏为主，未扩大 P8 或变更交易/认证行为。逐项审阅、行为不变检查与验证结果见[本轮报告](../reports/2026-10-11-documentation.md)。

### 2026-10-11：Windows 一键运行

按用户指定账号实现 CMD/PowerShell 入口、原生构建/依赖隔离/ready 后开浏览器/独立持久数据，并补回环本地管理员八字节密码例外与别名登录；常规注册/管理员规则不变。接口契约、注释与测试同步，见[Windows 说明](../05-deployment/windows-local-run.md)及[本轮执行报告](../reports/2026-10-11-windows-launcher.md)。

### 2026-10-12：从零手把手教程

按最新要求新增[新手教程](../03-development/from-zero-tutorial.md)，23 章从空目录、环境/Go/HTTP基础开始，提供可执行的教学撮合/资金/持久化/身份权限/React/测试完整文件，再逐项升级到最终核心规则、批日志/投影、契约/分页/行情/pending、观测运维与 Windows/容器/云部署。主线为 Windows PowerShell，明确教学版数据不能直接升级成当前日志格式，最终测试脚本的 Linux/WSL 适用范围单列。

本轮新增文档与入口，不改交易、认证或部署实现；教学代码在隔离临时目录验证，原项目历史报告/产物保留。实际范围与结果见[教程验证记录](../reports/2026-10-12-from-zero-tutorial.md)。

### 2026-10-12：链上交易可行性分析

按用户提问核对当前模拟CREDIT、即时成交资金变更、日志/投影及身份边界，新增[链上演进分析](../02-architecture/onchain-feasibility.md)。分别比较链上出入金、链下撮合链上结算、全链上和DEX接入，明确B需重构即时到账、可靠outbox不能与普通可重建投影混用，给出本地/测试网阶段与验证矩阵。仅方案分析，未修改应用或开始链上部署/真实转账，P8仍为可选扩展；外部资料读取遇DNS故障，不报告最新网络/部署数据。

### 2026-10-12：后端为主的 Web3 定位

根据用户希望展示高并发中间件并带少量合约，当时收敛推荐为 B 的受限版本：Go 单写者订单簿＋签名订单＋小型原子结算合约。新增[中间件与开发路线](../02-architecture/backend-web3-roadmap.md)，当时采用 Redis 读缓存/限流、Kafka 外围分发和 PostgreSQL 权威链任务；当前路线页已随 v0.6 改为 RabbitMQ。该历史阶段只完成设计建议，未改应用或开始部署。

### 2026-10-12：v0.4 开发与审阅

按前述路线实现独立链交易，交付范围和当次实际验证见[v0.4 报告](../reports/2026-10-12-v0.4.md)。下列问题在该阶段审阅中处理：

PG锁改专用连接并检测失锁；活动扫描保存块hash且RPC按hash读取；固定有限轮询避免全历史无限RPC；日志恢复验证版本/命令/签名摘要；合约getter防错域；保存raw后广播并恢复验证；当时 Kafka 按 dataset 过滤；Redis高seq水位不随缓存TTL消失。钱包修复首次连接状态闭包与切换校验，拆出原签单恢复纯函数并加10个单元用例。go-ethereum/pgx/gorilla及ethers/solc/tmp依据真实漏洞审计升级。浅重组测试固定sleep假设改为持续挖块观察事实，完整执行见历史报告。

### 2026-10-12：真实业务架构分析

按用户要求仅评估架构，新增[真实业务演进设计](../02-architecture/production-architecture.md)，依据当前源码提出模块化单体、订单全生命周期、链索引/对账、Tx Manager、消息错误分类、权限和运维门槛。业务代码、合约、历史报告未修改；下一版建议先落地闭环和恢复证据，自动HA/金库作为单独决策。

### 2026-10-12：v0.5 开发落点

阶段 A 已实现：history.go 查询与前端 Web3History.tsx；tasks.go schema 2/CAS；index.go confirmed-only 索引；reconcile.go 全量只读检查；observability.go 采样和 Prometheus。新增 production_test.go 覆盖迁移、分页、事务失败、重组和损坏。B–D 保持后续路线，当次验收见[v0.5 报告](../reports/2026-10-12-v0.5.md)。

### 2026-11-02：开发现状核对与限量发售架构

根据本次要求，核对 backend、chaintrade、cmd/web3server、Settlement、前端与契约，新增[当前开发进度](current-progress.md)，更正生产差距表中仍将历史分页、任务迁移/CAS、事件索引和对账列为未完成的描述。模拟 v0.3 / 链模式 v0.5 运行版本保持不变，历史报告和证据保留。

该次新增[链上限量发售与秒杀设计](../02-architecture/flash-sale-design.md)，当时仅为草案；最初选型见[历史审阅报告](../reports/2026-11-02-architecture-review.md)。当前设计页已随后续授权更新为 v0.6 实现，改用 RabbitMQ。标准测试 ERC20、用户自行发送交易、库存预存和独立资格权威的边界保留。

同步 README、文档入口、架构、路线、开发/测试和面试资料；本轮只更新文档及审阅证据，没有实现发售服务或部署合约。实际执行、环境与限制见[审阅报告](../reports/2026-11-02-architecture-review.md)，未来实现按阶段另记证据。

本轮实际前端 44 单元与 Web3 契约检查通过；Windows 离线 Go 回归发现 6 个顶层测试失败并定向复现（目录同步/CLI、恢复子进程、静态资源），链包因缺少依赖未执行。已记为优先修复事项，未修改源码或以历史 Linux 通过结果覆盖失败。

### 2026-11-02：v0.6 后续授权实现与验收

用户随后授权开始开发、提供手动验收与测试文档并优化前端，期间明确改用 RabbitMQ。已完成独立发售、两个业务的消息传输替换、Windows 修复、一键入口、桌面/移动页面与刷新恢复。真实 SQL/RabbitMQ、Anvil、故障、浏览器及购买后交易验证通过，先前 Windows 问题已回归。完整结果和边界见[实现报告](../reports/2026-11-02-sale-v0.6.md)，手动操作见[验收手册](../04-testing/sale-acceptance.md)。

### 2026-11-02：详细中文注释完善

按用户要求补充 29 个源码、测试、脚本和配置文件的中文注释，并展开 5 份紧凑 JavaScript 脚本。说明金额单位、事务/所有权、RabbitMQ confirm/ack、签名/索引/安全回收、前端异步恢复和测试证明点。有效代码比较与相关回归见[注释报告](../reports/2026-11-02-chinese-comments.md)，调用链见[代码阅读指南](../03-development/code-reading-guide.md)；本轮未重跑的外部环境不继承为新成绩。

### 2026-11-02：按内容与时间整理文档

重编[主题目录](../README.md)，新增[版本时间线](timeline.md)与[报告目录](../reports/README.md)，过程记录统一为带日期的阶段标题，记录模板移到末尾。澄清当前 v0.6 与模拟 v0.3 / 链协议 v0.5 的关系；保留历史报告、失败证据和原路径。本次仅调整文档，不修改业务实现或重跑业务测试。

### 2026-11-02：Web3 初学者讲解与文档文件夹分类

按用户“小白从零理解整个项目”的要求新增[10 章讲解](../01-beginner/README.md)，覆盖钱包/链/合约、单位/签名/授权、首次运行、发售、Go 与中间件、二级交易、源码、故障和练习。将 33 份原主题文档实际移入分类文件夹，为每类提供入口与[迁移表](document-migration.md)，同步文档跳转、源码注释和发布脚本路径。历史报告仅修正文档跳转，原始证据不搬动、不改写；本轮没有重新执行业务集成或产生新容量结论。

## 4. 后续记录格式

每个阶段持续补充：

```text
日期 / 阶段 / 代码提交
完成内容：哪些具体行为发生变化
遇到问题：触发条件、证据、影响
解决过程：采用方案、关键取舍、为何排除其他方案
验证：实际命令、环境、结果、报告路径
剩余事项：明确未执行项与下一步
文档变化：架构/规范/测试/部署/面试哪些章节更新
```

实验较长时写入 `docs/reports/`，本文件只保留摘要和链接。设计改变用编号 ADR 记录：背景、候选、决定、后果、验证和状态，避免写几句“已优化”而无证据。

最终面试稿只提炼已实现且可以现场解释的部分，不从计划表抄成履历成果。
