1. 系统目标与历史动机#
说明系统为什么出现，受什么系统、论文、工程问题或行业变化启发，想替代、补充或改进谁。
2. 目标 workload 与用户需求#
说明系统面向的 workload、用户群体和核心需求。
3. 整体架构模型图#
放置官方架构图、官方论文/博客/演讲图、高质量第三方图，或根据公开资料整理的 Mermaid 图。
图后解释：
- 计算层在哪里。
- 存储层在哪里。
- 日志层在哪里。
- 事务层在哪里。
- 元数据层在哪里。
- 复制层在哪里。
- 缓存层在哪里。
4. 存储模型#
说明底层数据如何组织，例如 B+Tree、LSM、列存、对象存储文件、page、SST、segment、tablet、region、partition、倒排索引或向量索引。
5. 写入路径#
说明写请求如何进入系统，是否支持 batch、group commit、日志聚合，写入是否经过 WAL、redo log、raft log 或 binlog，何时可见，何时持久化。
6. 读取路径#
说明点查、范围查、snapshot read、index lookup、remote read、cache miss 后的路径，以及读路径如何处理可见性和缓存。
7. 日志、恢复、CDC#
至少回答：
- 日志记录什么。
- 日志如何写入、读取、分段、截断、删除和回收。
- checkpoint 与日志回收如何关联。
- 崩溃恢复从哪里开始。
- CDC 读取哪类日志或变更流。
- BLOB 或大对象如何进入日志或被日志引用。
8. 事务、MVCC、batch、并发控制#
说明时间戳、snapshot、可见性、冲突检测、锁、latch、长事务、大事务、失败恢复、批量写入原子性和并发安全。
9. 复制与分布式一致性#
说明复制对象是什么，采用主从、Raft、Paxos、quorum、lease 或其他机制，leader 如何选举，副本如何追赶，learner、follower read、read replica 如何工作。
10. 元数据管理#
说明 catalog、schema、table、index、tablet、region、shard、partition、version、manifest、snapshot 等元数据如何管理，以及 master、PD、meta service 或 catalog service 的职责。
11. 二级索引与约束维护#
说明二级索引如何编码、写入、维护一致性，唯一索引、异步索引、索引回填、索引 GC 和约束检查如何处理。
12. 缓存、后台任务、资源隔离#
覆盖 buffer pool、block cache、page cache、metadata cache、result cache；flush、compaction、vacuum、GC、checkpoint；以及竞争规避、资源隔离和后台任务调度。
13. 插件、生态补丁与变相方案#
区分：
| 层次 | 含义 | 示例 |
|---|---|---|
| 原生能力 | 系统内核直接支持 | PostgreSQL 的 SQL、MVCC、B+Tree |
| 官方或主流扩展 | 插件补能力 | pgvector、PostGIS、TimescaleDB、Citus |
| 外围系统组合 | 靠别的系统配合 | PostgreSQL + Elasticsearch、MySQL + Canal + ClickHouse |
| 变通方案 | 能做但不舒服 | 用 JSONB 模拟文档库，用关系表模拟队列 |
结论必须判断“能做”和“适合做”的区别。
14. 我的问题#
记录当前不理解的问题、需要源码验证的问题、工程实践相关问题、已解决问题和当前结论。
15. badcase 与架构边界#
按模块组织 badcase，至少关注日志、事务、元数据、缓存、分布式一致性、索引、后台任务、成本和多租户。
16. 工程启发#
总结哪些设计值得借鉴，哪些复杂性被转移，哪些方案看似优雅但工程代价高，哪些 badcase 对存储系统设计有警示意义。
17. 参考来源与引用#
记录所有参考来源。开源系统必须先 clone 到本地源码目录，默认路径为 D:\program\<repo-name>；如果本地已存在则复用，并记录实际源码路径、关键目录、关键文件、类或函数。闭源系统记录官方公开资料来源。架构图必须注明来源；自绘图注明“根据公开资料整理”。如果开源系统暂时无法 clone，必须记录阻塞原因，并且不能写源码级结论。