OrisumiOverview
ADR 记录 Orisumi 的架构决定及其理由
ADR（Architecture Decision Record）记录一项架构决定和它的理由。规则写在 Core、API、Storage 和 Observers 中，ADR 解释为什么。
何时写 ADR
三类决定写成 ADR：
- 责任归哪个组件。
- 协议的语义。
- 某类数据的权威位置。
较小的决定写在对应的类型页、规则页或契约中。只涉及单个 Observer 的决定写在该 Observer 的文档中，模块的运行说明写在模块 README 中。
结构
| 部分 | 内容 |
|---|---|
| 背景 | 需要作出决定的问题 |
| 决定 | 确定的做法，每条一句 |
| 理由 | 为什么这样做，放弃了哪些方案 |
| 代价 | 接受了哪些成本或限制 |
| 规则位置 | 承载具体规则的文档 |
条件、例外和细节写在规则中，ADR 链接过去。流程类决定在 Core 中没有页面，这类 ADR 在“决定”之后加一节“规则”，例如文档的权威与传播。写法见 Core · Conventions。
命名
ADR 用英文 slug 命名，例如 entity-model.mdx，没有编号。引用时写标题并链接，例如 ADR · 实体模型；代码注释写 ADR entity-model。按侧边栏顺序读，每篇只依赖排在它前面的 ADR。
- 重写期间，ADR 直接改成当前的决定。合并、拆分或改名时，同时更新所有引用。
- 重写完成后，slug 固定。决定被取代时，新写一篇 ADR，并在旧 ADR 开头链接新的。
目录
| 分组 | ADR | 决定 |
|---|---|---|
| Foundation | 定位与边界 | Orisumi 保存一个人经历了什么，记录以用户为主体，独立于采集和使用它的软件 |
| Foundation | 文档的权威与传播 | 文档是唯一权威，分为四层，更新只能从模型向实现前向传播 |
| Model | 实体模型 | 实体表达身份，不可变的版本保存完整内容，引用固定到版本，只引用已保存的版本 |
| Model | Observer 与输入集 | Observer 是对观测负责的实体，按负责的陈述划分；一次处理实际使用的版本由可共享的 InputSet 列出 |
| Model | 身份、时间与更新 | 业务规则决定身份和粒度，每个版本有自己的保存时间，更新形成新版本，独立的陈述形成新观测 |
| Model | 提交与 SDK | 程序实例的身份持久不变，Observer 的业务代码按业务规则形成事实，平台 SDK 按依赖顺序可靠提交 |
| Model | 删除 | 删除以实体为单位，只移除选中实体的全部版本，删除后不可复活 |
| Backend | 后端运行与本地环境 | 四个后端项目组成一个进程，Aspire 编排本地环境，NGINX 提供同源入口 |
| Backend | 实体 API | 接口按身份寻址，所有类型共用一组路由，一次提交是一组有序的版本，内容按 JSON 的值比较，错误带规则编号 |
| Backend | 实体存储 | 所有版本以 jsonb 保存在一张表中，查询走以类型开头的索引，删除留下墓碑，所有操作串行执行 |
| Clients | 桌面客户端 | 菜单栏客户端托管本机的桌面 Observer，负责启停、状态和设置，只读展示它们当天的数据；陈述由各 Observer 负责 |
| Verification | 开发验证与测试证据 | Orisumi.Dev 组织验证并保存证据，原生测试报告是测试结果的权威来源 |
| Verification | 开发环境的启动与隔离 | Orisumi.Dev 是启动环境的统一入口，每个检出目录运行一套环境，数据卷可选，服务按需启动 |
| Verification | 文档站的发布 | 文档站构建为静态文件，GitHub Actions 从 main 构建并发布到 GitHub Pages，测试报告随发布固定 |
