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

项目级代码架构

本规范适用于仓库内所有 workspace 包和代码层，是项目级规范的稳定入口；具体包的目录名称和运行时边界由包级规范补充。

1. Scope / Trigger

以下场景必须先应用本文及其主题规范：新增或重构业务功能、入口、适配器、模型、工具或常量；提升函数、类型或常量的共享层级；判断能力属于基础设施、共享领域概念还是单一功能实现；修改手写源文件、模块出口、格式化配置或缺失值补偿逻辑；评审文件职责、依赖方向、类型所有权和目录归属。

核心原则是按“变化原因”组织代码，而不是按文件长度或技术类型组织。会因不同需求独立变化的代码必须拆开，会始终一起变化的代码应留在同一模块；不要只移动函数或增加文件名而不改变职责边界。

2. 主题导航

主题	Canonical 文档	旧章节映射	负责内容
模块组织	module-organization.md	Signatures / Roles、3.1–3.8；原 4–7 中模块相关规则、案例、测试和反例	文件角色、功能聚合、共享层级、上下文适配、职责和拆分时机
类型所有权与模块出口	module-ownership.md	3.10；原 4–7 中类型出口相关规则、案例、测试和反例	类型唯一所有者、canonical import path、公共 facade 与 re-export
异步流程与状态管理	async-state-boundaries.md	新增项目约束	状态唯一 owner、等待后重新确认、一次性完成和安全重构
源文件约定	source-file-conventions.md	3.9、3.12；原 4–7 中文件排列和函数风格相关规则、案例、测试和反例	bottom-up、main-last、文件头/主函数注释、箭头函数和 fail 收窄
格式化	formatting.md	3.11；原 4–7 中格式化相关规则、案例和测试	Oxfmt、VSCode 保存、.editorconfig 与提交/CI 一致性
缺失值与默认值	missing-values.md	3.13 全部七段；原 4–7 中缺失值相关规则、案例、测试和反例	缺失值补偿、BUILD_HASH 单一生成点和边界错误契约
结构化值等价性	structured-value-equality.md	新增项目约束	事实等价、快照/集合/序列关系与序列化边界
数据库查询组合	database-query-composition.md	新增项目约束	SQL JOIN 禁止默认、受限查询与内存组合、例外证据门槛

3. 阅读顺序

1. 先读本文，确定适用范围和评审边界。
2. 涉及目录、职责、共享或拆分时读 模块组织。
3. 涉及类型定义、导入路径或 re-export 时读 类型所有权与模块出口。
4. 涉及跨 await 的状态、重复请求、延迟回执，或写入、发送、ACK、发布等最终动作时读 异步流程与状态管理。
5. 涉及源文件排列、注释、函数语法或类型收窄时读 源文件约定。
6. 涉及保存格式化或提交门禁时读 格式化。
7. 涉及配置、环境变量、协议 payload、构建标识或默认值时读 缺失值与默认值。
8. 涉及去重、幂等、持久化回读、回执核验、缓存命中或结构化 payload 等价判断时读 结构化值等价性。
9. 涉及 SQL/ORM 查询、关系数据读取或投影组合时读 数据库查询组合。
10. 最后阅读目标包和目标层的规范；包级规范可以补充但不能降低本项目级要求。

4. 跨主题检查

• 能否从目录结构直接看出入口、功能和业务分支，且每个文件只有一个主要变化原因？
• 入口和分发器是否只组合、判断和委派，分支是否各自在独立模块中处理自己的输入形态？
• 公共领域契约、转换和类型是否各自只有一个规范所有者，导入是否使用 canonical path？
• 跨 await 后，是否重新确认操作仍有效，并在确认后立刻执行写入、发送、ACK 或发布等最终动作？
• 每个关键可变状态、请求去重和状态转换是否有唯一 owner；重构是否避免夹带结果、重试、资源清理或事件顺序的变更？
• 跨功能共享概念是否位于真实消费者的最近共同父目录，且没有跨包内部引用、反向依赖或循环依赖？
• utils.ts 是否仍不含业务流程、重要类型、业务常量或领域守卫？重要常量是否靠近所有者？
• 外部上下文读取、上下文一致性判断和功能错误映射是否保持边界分离？
• 手写源文件是否满足文件头职责注释、主函数注释、main-last 和函数语法约定？
• 编辑器保存、提交钩子和 CI 是否产生同一份 Oxfmt 结果，缩进是否统一为 4 个空格且无 Tab？
• 必填边界是否显式失败，补偿默认值是否有证据？BUILD_HASH 是否只有 workspace 根命令生成？
• 结构化值的比较是否先声明身份、完整快照、集合或序列关系；是否避免把 JSON 文本或对象键顺序当作业务语义？
• 关系数据是否先按各自 scope/key 受限读取、再按完整事实键在内存组合？若使用 SQL JOIN，是否有本次用户明确要求或可复核的例外证据？
• 结构调整后是否完成目标测试、严格类型检查/构建（适用时）、pnpm format:check 和导入/链接审计？