trade-message-center/.trellis/spec/project/index.md

项目级开发规范

本目录记录所有 workspace 包共同遵守的代码组织约束。包级规范可以补充框架、运行时和业务边界，但不能降低这里的要求。

规范目录

文档	内容	状态
代码架构入口	适用范围、主题导航、阅读顺序和跨主题检查	已建立约束
模块组织	文件角色、功能聚合、共享层级、职责、上下文边界和拆分时机	已建立约束
类型所有权与模块出口	类型唯一所有者、canonical import path、公共 facade 与 re-export	已建立约束
异步流程与状态管理	状态唯一 owner、等待后重新确认、一次性完成和安全重构	已建立约束
源文件约定	bottom-up、main-last、注释、箭头函数和 fail 类型收窄	已建立约束
格式化	Oxfmt、VSCode 保存、.editorconfig 与 CI 一致性	已建立约束
缺失值与默认值	缺失值、默认值、BUILD_HASH 和补偿逻辑的边界契约	已建立约束
结构化值等价性	结构化快照、身份、集合与序列的等价边界	已建立约束
数据库查询组合	SQL JOIN 禁止默认、受限查询与内存组合、例外证据门槛	已建立约束
Git 分支管理	main 同步、开发分支 rebase、--force-with-lease 与快进合并	已建立约束

开始前检查

1. 任何包开始写代码前，先阅读 代码架构入口，再按任务涉及的主题阅读对应 canonical 文档和目标包/层规范。
2. 先搜索已有实现，确认概念的真实所有者和共享范围，再新增文件、工具或抽象。
3. 涉及跨 await 的状态、重复请求、延迟回执或最终动作时，必须阅读 异步流程与状态管理。
4. 包级规范与项目级规范冲突时，先修正文档或明确例外，不能静默选择更宽松的规则。
5. 涉及配置、环境变量、协议字段、构建标识或默认值时，必须阅读 缺失值与默认值。
6. 涉及去重、幂等、持久化回读、回执核验、缓存命中或结构化 payload 的等价判断时，必须阅读 结构化值等价性。
7. 涉及 SQL/ORM 查询、关系数据读取或投影组合时，必须阅读 数据库查询组合。
8. 任务涉及多个 Git 分支、更新 main 或合入主干时，先阅读 Git 分支管理。