Conventions

pnpm docs:check 按本页检查规则的标题、编号和执行方。

规则的格式

每条规则是一个带编号的标题，例如 ENTITY-4 引用指向版本。标题是几个字的短语，让人一眼知道这条规则管什么。标题下第一段写执行方，例如“执行方：写入方、后端”；只规定含义的规则写“定义”。接着第一句写完整的规则，之后写条件、例外和例子。

执行方	含义	验证方式
后端	后端校验，违反时拒绝写入或按规则处理	Testing Case 通过 API 测试
写入方	形成版本的一方遵守：Observer 的业务代码、SDK 或用户使用的工具	Observer 和 SDK 的测试与评审
读取方	读取和追溯数据的一方遵守	读取方实现的测试
定义	规定含义，由其他规则引用	随引用它的规则验证

类型页写单一类型的规则，规则页写跨类型的规则。

前缀是页面的英文名称，一个前缀对应一个页面。
措辞改变时编号不变。
重写期间可以合并、删除、移动规则并重新编号，同时更新所有引用。重写完成后编号固定：删除的编号不再复用，移到其他页面的规则保留编号。
代码、测试、ADR 和讨论用编号引用规则，例如 IDENTITY-3。锚点是小写的编号，例如 ./rules/identity.mdx#identity-3。pnpm docs:check 也检查 src/ 和 tests/ 下 C# 代码中的编号是否存在。
每条规则只写在一个页面。

写法	含义
陈述句、“必须”、“不得”	要求，不满足就是错误
“可以”	允许

定义不用强度词。约束只写在规则和类型页的成员表、字段表中。介绍、示例、Overview 和 ADR 与约束不一致时，以约束为准。

文档写给第一次读这一页的人：先让读者知道在讲什么，再给约束。

一个概念只用一个词。术语的定义见 Glossary。

用	指	不用
已保存	后端已保存的版本，可以被引用	已经成立、已成立、被接受
本地保存	SDK 在本机持久保存、尚未提交的内容	单独的“保存”
成立	事实为真	用于版本
保存时间	`recordedAt`	记录时间
记录	作名词时只指 Orisumi 为用户保存的全部数据	用来指单个实体、版本或观测
观测	Observation 的中文名	记录、观测记录
粒度	一个实体或一份观测覆盖的范围	记录粒度
来源数据	来源自己提供的数据，例如浏览器的历史条目	来源记录
程序实例	有自己 EntityId 的运行中程序	采集器、实例、采集程序
前台状态 Observer、推断 Observer	某一个程序实例，名字与 Observers 文档一致	前台状态程序、推断程序
Observer 的业务代码	程序实例中 SDK 以外、按业务规则形成观测的部分	Observer 的实现
业务类型	一种业务数据	类型定义
EntitySchema	定义业务类型的 Core 类型，以及它的每个实体	EntitySchema 实体、单独的“Schema”、单独的“定义”
Schema 版本	EntitySchema 的一个版本	EntitySchema 版本、一版定义、结构定义

导航的分区、分组和页面标题用英文。ADR 的标题是一项决定的名称，用中文。正文用中文。