开发者指南 · Zikaron
仓库结构与分层
判断由核做出，界面负责呈现。先弄清各层的职责，再确定改动的位置。
目录
| 路径 | 内容 |
|---|---|
crates/zikaron | zikaron/1 的核：规范字节、条目、签名、审计。 |
crates/zikaron-kit | zikaron.kit/1 的核：文书、凭证载荷、记录包、读数、授权六项核验。 |
crates/zikaron-store | 账本的磁盘读写，仅用标准库。 |
crates/zikaron-anchor | 链上操作：扫描上链记录、JSON-RPC、发送上链交易。 |
crates/zikaron-cli | 命令行 zikaron。 |
crates/zikaron-glue | 记录包导出与各处共用的约定。 |
crates/zikaron-ui | 控件库与外观。 |
crates/app | 桌面应用。 |
base/ | 冻结的两部法文及其参照实现、一致性语料、登记合约。 |
contracts/ | 测试上链路径所用的合约变体。 |
packaging/ | macOS 与 Linux 的打包脚本、图标。 |
docs/manual/ | 使用手册，中英文各一份。 |
CLI-SCHEMA.md | 命令行的输出格式、退出码、拒绝原因与参数。 |
四层结构
- 基底（
base/）。法文、冻结核、语料、合约、链面夹具，作为其余一切的参照。其中冻结核由法文写明的摘要钉住，合约由代码哈希钉住；其余是工装，可以重建、替换或删除。 - 核与存取（
zikaron、zikaron-kit、zikaron-store、zikaron-anchor）。全部判断在此做出。 - 对接（
zikaron-cli、zikaron-glue）。组装输入、调用核、原样传出结果。 - 界面（
zikaron-ui、app）。呈现与交互。
依赖自上而下：上层调用下层的公开接口，下层独立于上层。各 crate 都依据法文独立写成，与 base/ 之间零路径依赖。
五条规则
- 界面只呈现
- 条目是否合法、授权是否有效，由核给出结论，界面负责呈现。界面中出现自行判断语法的代码，应移入核。
- 对接层只组装
- 命令行与胶水代码把参数组装成输入、调用核、选定退出码；核写出的字节原样传出，键名与取值保持不变。
- 判据原样
- 两个冻结核由法文里的摘要钉住，登记合约由代码哈希钉住，这些字节保持原样。对其有异议，请提交议题，见兼容与演进。
- 核验页只读
- 核验授权与核验记录两页，权限限于读取输入与链上数据。
- 身份密钥只签账本
- 应用里的密钥只用于签署条目、为导入连署，以及发送上链交易；付款、钱包、委托等功能交由其他软件。
一处实现，处处复用
同一判断只实现一次。授权的六项核验由 zikaron-kit 提供，核验页、命令行与「我的授权」的定期复核共用这一实现，读数亦然。因此同一输入在任何入口都得到同一结论。
每一种账本条目都有对应的写入子命令。为应用新增操作时，先在命令行中跑通，再做界面。
注释中的法条引用
代码注释以 law §N 指 zikaron/1 的条文（kit 一侧的代码里也写作 parent law §N），以 kit law §N 指 zikaron.kit/1 的条文。修改一段实现之前，先读它所引的条文。