日期:2026-10-11。工作区没有 Git 仓库,本轮为文档纠偏与手写源码注释完善,API 0.3.0、engine_version=1、schema_version=1 保持不变。最新业务修复与完整测试成绩仍见测试完善报告;本轮单独记录验证,不覆盖旧原始日志/源码摘要/性能成绩。
1. 文档变化#
对现有 22 份 Markdown 完成一致性审阅,新增三份使用手册及本报告,共 26 份。
| 变更 | 解决的问题 |
|---|---|
| 接口使用指南 | 注册/登录联调、写操作权限与幂等、两种序号、min_seq、游标、未知结果、WS 协议及 HTTP 状态 |
| 数据生命周期 | 三库权威、初始化/恢复、历史增长、全历史维护成本、checkpoint、备份/恢复/投影替换中断 |
| 故障排查手册 | 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。所有手写 Go 函数/方法均有紧邻中文说明(共享 benchmark 入口也补齐)。原有关键资金算例与不变量保持;生成 TS、lockfile、依赖目录、历史发布包与原始证据不手工改写。
3. 验证方法与结果#
验证原始输出位于 evidence-documentation ↗,本轮结果如下。注释基线在开始修改前复制到独立 /tmp 目录,不是 Git 提交。
| 检查 | 方法与结果 |
|---|---|
| Go 行为不变 | scanner 去注释 token/字面量比较,保留 go 指令比较;37 个 Go 文件一致;结果见 go-semantic.json |
| 前端行为不变 | TypeScript AST 的节点类型/字面量与 CSS 去注释节点比较;13 个前端文件一致(含生成物未变);结果见 frontend-semantic.json |
| 脚本/配置行为不变 | Python AST(含原有 docstring)与 shell/Docker/YAML/systemd 去整行注释后的有效内容比较;12 个文件一致,见 script-config-semantics.json |
| 常规回归 | scripts/verify.sh 通过:模块校验、六窗口收集门槛、vet、全 Go 测试与 race、34 个前端单元、生成契约/格式/build、3 个 CGO=0 二进制及成功回包后 SIGKILL 恢复;输出见 verify.txt |
| 文档与配置 | 本地链接/锚点/代码块、Python 示例语法、shell 语法、Compose 解析及 Go 函数注释完整性;26 份 Markdown、317 个本地链接/锚点、42 个围栏代码块、1 个 Python 联调示例语法、206 个 Go 函数注释检查通过;Compose 解析通过,结果见 document-checks.json |
| 当前源码/文档摘要 | 独立 source-SHA256SUMS 与 documentation-SHA256SUMS,不覆盖测试完善阶段摘要 |
这是对本轮行为未变和适用回归的证据,不是新的业务测试集、性能上限或生产正确性证明。TS AST 检查覆盖类型与 JSX 字面量;Go token 检查保留字符串/数值与指令,避免简单正则去注释破坏字符串内容。
4. 历史与剩余边界#
未重新打包现有 v0.3.0 发布包、改写 verified 镜像、重跑性能或部署云服务器。旧短时 4000 档性能、容器和发布证据仍为相应历史版本,源码注释摘要变化不把旧产物升级成当前产物。远程 CI、在线标准镜像构建、真实断电/存储硬件、长期生产混合负载、完整弱网/跨浏览器仍需独立环境验收;Redis/分区/快照/高可用/真实资金不属本轮范围。
后续功能增量:Windows 一键启动新增本地管理员/登录契约等行为,本文“语义未变”与源码摘要只对应本轮当时快照,不延伸到后续功能修改。