[CSCITech]

问题与结果

现有 SQLite 配置及恢复测试主要从当前模型生成 schema，尚未验证已发布 pre3 的完整旧库能否通过真实启动迁移并保留财务与日志幂等记录。本变更加入固定历史 schema 的升级验收及双语操作指引；未确认需要修改生产迁移或资金逻辑的缺陷。

• model/testdata/sqlite/pre3_schema.sql 来自 MAX-API v2.0.0-smartops.pre3 固定提交 48260ce6517a9ab68851a7ac499477981d78da63 的实际 InitDB/InitLogDB 执行，39 张表、160 个索引。fixture 仅包含 schema，合成状态在测试中建立；不包含用户数据、密钥或二进制。
• model/sqlite_upgrade_test.go 在 16 个独立进程中执行当前主节点启动迁移和恢复，验证共享、旧 local、已有独立日志目标及结算完成后的新空目标。冷启动保持资金快照；恢复只应用原定正／零／负差额一次，明确零费用保留零日志和一次请求计数。原资金／Token／订阅周期、手工与未知状态、跨周期阻止、旧 receipt、64 位余额和目标文件的日志回填均验证。
• LF／Windows CRLF fixture 均实际建立相同完整 schema，并以规范化后固定 hash 防止历史输入被当前模型悄悄替换。
• docs/installation/sqlite-upgrade.md 说明隔离备份副本验收、资金与日志恢复、成套备份和回退边界。新日志目标不自动搬迁历史，先完成原库 effects 并一起保留日志与 receipt；新空目标只验证已完成这些准备的场景。

本变更不修改生产代码、金融 schema／SQL、费率、表达式、操作身份、Relay／权限或依赖。对照 New API 的迁移和数据库初始化行为后独立编写 MAX 验收，没有移植上游源码、模块或插件，LICENSE／NOTICE／署名保持。

验证

• 升级与格式专项：240 通过／0 失败／0 跳过。
• 四组私有 Go overlay 敏感性对照检出预期断言失败：CRLF 未规范化、未执行主迁移、未执行 pending recovery、保留旧日志但缺失 receipt。原生产／测试文件未被控制修改；这些是测试有效性对照，不是生产缺陷。
• 第一次合成 fixture 省略唯一 aff_code，导致真实 pre3 unique index 报错；改用不同合成值，原失败保留，没有删除或放宽索引。
• 全仓 quick 通过：57 个 Go 测试包（模型包本次实际47.578秒，其余56缓存），535项Bun通过／0失败，32个独立前端进程；vet、JSON113、TypeScript、358＋2镜像同步、独立build:check／2CSS通过。包间并发-p1，默认期限和测试内部并发保持。当前HEAD CI后端、前端与PR检查均通过；日志确认57个Go测试包（2缓存）、535项Bun通过／0失败、32个独立进程及2CSS构建。

交付范围与限制

这是基于 cscitech 的独立小 PR，承接父 PR #56 已验证的 98709043；父 PR 的 98 个文件和审查 HEAD 不由本变更改动。

更老版本、实际部署的旧镜像／用户库、MySQL／PostgreSQL及混合引擎、Redis多节点、真实渠道／Vertex、浏览器／人工、race／实盘掉电、在线切库与保留清理未运行。历史 Windows 时序／前端超时／OOM 和完整 lint69错误／9警告保留。P0.3／pre4实际环境验收仍开放；下一包为 Windows 测试时序定位。

复审与观察

全量复审覆盖提交1bc3f4a07bc466d2724123f0e5a6484d126bf0a5，与当前HEAD一致，3文件全部处理；Additional3确认通过，inline／outside0。G301测试目录位于0700私有TempDir，G204执行固定当前测试程序，无shell或API输入，均不构成有效安全缺陷。私有helper注释覆盖率10%／80%提示保留为非必要风格建议。

稳定观察2026-10-14T10:54:26.434+08:00至2026-10-14T11:25:21.972+08:00，实际1855.538秒，重启0。起止完整检查的HEAD、base、覆盖、全部评论及编辑、CI均无变化；期间单次原生挂起1800.0575秒，无轮询，不声称排除了瞬时事件。未合并、发布或部署。

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 7b7f431e-70fb-4c9d-bd3b-07bf48536680

📥 Commits

Reviewing files that changed from the base of the PR and between 9870904 and 1bc3f4a.

📒 Files selected for processing: 3

• docs/installation/sqlite-upgrade.md
• model/sqlite_upgrade_test.go
• model/testdata/sqlite/pre3_schema.sql

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 1 remain after this review.

📜 Recent review details

🧰 Additional context used

🪛 golangci-lint (2.13.2)

model/sqlite_upgrade_test.go

[medium] 125-125: G301: Expect directory permissions to be 0750 or less

(gosec)

[medium] 301-301: G204: Subprocess launched with a potential tainted input or cmd arguments

(gosec)

🔇 Additional comments: 3

model/testdata/sqlite/pre3_schema.sql: 1

1-625: LGTM!

model/sqlite_upgrade_test.go: 1

1-504: LGTM!

docs/installation/sqlite-upgrade.md: 1

13-15: 🎯 Functional Correctness

The linked file exists at docs/installation/sqlite-log-database.md, so both relative links resolve correctly.

📝 Summary

Summary by CodeRabbit

• Documentation
  • Added bilingual guidance for upgrading SQLite databases, including backup preparation, migration checks, recovery, and rollback.
  • Clarified that WAL files and historical billing effects and receipts should be preserved during an upgrade, and that existing reconciliation states do not become successful automatically.
• Tests
  • Added coverage for upgrades from an earlier database version across shared and separate log database setups, including checks that financial records remain consistent during startup and recovery.

The documentation adds bilingual SQLite upgrade, separate-log, and rollback guidance. The test suite checks startup and recovery against a historical schema fixture across four SQLite log modes.

Changes: SQLite Upgrade Acceptance

Layer / File(s)	Summary
Historical schema and fixture cases model/testdata/sqlite/pre3_schema.sql, model/sqlite_upgrade_test.go	A pinned pre3 schema snapshot and synthetic records provide fixtures for four SQLite log modes.
Startup and recovery checks model/sqlite_upgrade_test.go, docs/installation/sqlite-upgrade.md	Cold-process tests repeat startup and recovery, then check financial snapshots, settlement effects, logs, receipts, and retry markers. The documentation describes the automated coverage and its limits.
Operator preparation and rollback guidance docs/installation/sqlite-upgrade.md	Bilingual guidance covers backups, WAL files, separate log targets, pre-switch preparations, and rollback requirements.

Priority: ⬇️ Low

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 1bc3f

This change adds SQLite upgrade acceptance tests and operator guidance and does not modify production code. No outstanding issues block merging. Normal CI confirmation is still needed.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 10.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 10 functions across 1 files. (2 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Title check		The title clearly summarizes the main change: verifying pre3 SQLite startup and settlement recovery through tests.
Description check		The description is directly related to the changeset and explains the fixed pre3 schema, upgrade and recovery coverage, documentation, validation results, and known limits.

Full details: Docstring Coverage

Explanation

Docstring coverage is 10.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 10 functions across 1 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit checks the WAL at night,
And keeps the old receipts in sight.
The schema rests, the tests run through,
Four log modes get checks anew.
Then hops back home with backups tight.}

_{Comment @coderabbitai help to get the list of available commands.}

[CSCITech]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.