# 文档与代码注释审阅记录

日期：2026-10-11。工作区没有 Git 仓库，本轮为文档纠偏与手写源码注释完善，API 0.3.0、engine_version=1、schema_version=1 保持不变。最新业务修复与完整测试成绩仍见[测试完善报告](2026-10-11-test-hardening.md)；本轮单独记录验证，不覆盖旧原始日志/源码摘要/性能成绩。

## 1. 文档变化

对现有 22 份 Markdown 完成一致性审阅，新增三份使用手册及本报告，共 26 份。

| 变更 | 解决的问题 |
| --- | --- |
| [接口使用指南](../03-development/api-guide.md) | 注册/登录联调、写操作权限与幂等、两种序号、min_seq、游标、未知结果、WS 协议及 HTTP 状态 |
| [数据生命周期](../05-deployment/data-lifecycle.md) | 三库权威、初始化/恢复、历史增长、全历史维护成本、checkpoint、备份/恢复/投影替换中断 |
| [故障排查手册](../05-deployment/operations-runbook.md) | ready/认证/过载/投影/WS/磁盘排查、指标口径、容器网络命名空间诊断与证据保存 |
| 架构/认证/选型/规范 | 标准 ServeMux、未引入 decimal.js/client_golang/Go 生成、用户分页、绝对会话期限、实际元数据与编译期规则 |
| 阅读/部署/面试/测试/计划/目标/入口 | 真实调用顺序、响应深拷贝、故障收集更正、历史性能与当前修复的区别、同版本打包限制 |
| 早期设计/审计/历史报告 | 增加阅读说明与后续链接，保留原始内容及当时结果，不倒填新的执行成绩 |

纠正细节包括：Timestamp/schema/摘要由 Submit 设置，writer 只分配 seq 并提交 commands；WS 首次 tick 发送，前端只在首次挂载拉 REST；snapshot 同 seq 成交是文本 ID 排序，完整成交分页另用 rowid；标准 Dockerfile 为 Debian slim，离线 runtime 为 scratch；离线重建不修改权威业务记录，但 checkpoint 会改变物理文件字节，多个 rename 不是一个原子事务。

## 2. 注释覆盖

后端补模块职责、Runtime 字段归属、固定恢复批/在线聚批差异、前缀 Apply 与投影跳过、额度归还、响应/去重/投影对象隔离、价档减旧加新、余额完整覆盖、首次结果与最新状态、游标探测行、绝对会话过期和管理员初始化分支。

前端补组件/state/ref 所有权、并行请求非同瞬间快照、首次 REST 与 WS 的竞争、pending 先存后发与跨标签页边界、编译期类型不作运行时校验、CSS 展示比例与布局约束。测试补各文件证明范围与运行层次，工具/脚本/部署补磁盘/临时数据预算、固定证据路径、发布包内容与非原子 tar 发布、镜像差异、systemd 环境解析和诊断访问。

此次修改 54 个现有源码/配置文件（均为注释或格式），详情见 [changed-files.json](evidence-documentation/changed-files.json)。所有手写 Go 函数/方法均有紧邻中文说明（共享 benchmark 入口也补齐）。原有关键资金算例与不变量保持；生成 TS、lockfile、依赖目录、历史发布包与原始证据不手工改写。

## 3. 验证方法与结果

验证原始输出位于 [evidence-documentation](evidence-documentation/)，本轮结果如下。注释基线在开始修改前复制到独立 /tmp 目录，不是 Git 提交。

| 检查 | 方法与结果 |
| --- | --- |
| Go 行为不变 | scanner 去注释 token/字面量比较，保留 go 指令比较；37 个 Go 文件一致；结果见 [go-semantic.json](evidence-documentation/go-semantic.json) |
| 前端行为不变 | TypeScript AST 的节点类型/字面量与 CSS 去注释节点比较；13 个前端文件一致（含生成物未变）；结果见 [frontend-semantic.json](evidence-documentation/frontend-semantic.json) |
| 脚本/配置行为不变 | Python AST（含原有 docstring）与 shell/Docker/YAML/systemd 去整行注释后的有效内容比较；12 个文件一致，见 [script-config-semantics.json](evidence-documentation/script-config-semantics.json) |
| 常规回归 | scripts/verify.sh 通过：模块校验、六窗口收集门槛、vet、全 Go 测试与 race、34 个前端单元、生成契约/格式/build、3 个 CGO=0 二进制及成功回包后 SIGKILL 恢复；输出见 [verify.txt](evidence-documentation/verify.txt) |
| 文档与配置 | 本地链接/锚点/代码块、Python 示例语法、shell 语法、Compose 解析及 Go 函数注释完整性；26 份 Markdown、317 个本地链接/锚点、42 个围栏代码块、1 个 Python 联调示例语法、206 个 Go 函数注释检查通过；Compose 解析通过，结果见 [document-checks.json](evidence-documentation/document-checks.json) |
| 当前源码/文档摘要 | 独立 [source-SHA256SUMS](evidence-documentation/source-SHA256SUMS) 与 [documentation-SHA256SUMS](evidence-documentation/documentation-SHA256SUMS)，不覆盖测试完善阶段摘要 |

这是对本轮行为未变和适用回归的证据，不是新的业务测试集、性能上限或生产正确性证明。TS AST 检查覆盖类型与 JSX 字面量；Go token 检查保留字符串/数值与指令，避免简单正则去注释破坏字符串内容。

## 4. 历史与剩余边界

未重新打包现有 v0.3.0 发布包、改写 verified 镜像、重跑性能或部署云服务器。旧短时 4000 档性能、容器和发布证据仍为相应历史版本，源码注释摘要变化不把旧产物升级成当前产物。远程 CI、在线标准镜像构建、真实断电/存储硬件、长期生产混合负载、完整弱网/跨浏览器仍需独立环境验收；Redis/分区/快照/高可用/真实资金不属本轮范围。


后续功能增量：[Windows 一键启动](2026-10-11-windows-launcher.md)新增本地管理员/登录契约等行为，本文“语义未变”与源码摘要只对应本轮当时快照，不延伸到后续功能修改。
