app-renderer-systems

功能系统

systems/<domain>/ 模块负责其领域面向 UI 的适配器、数据访问、钩子、组件和公共导出文件。扩展现有系统；仅创建功能实际需要的层。修改局部组件并不意味着要搭建 CRUD 适配器、store、上下文提供程序，也不意味着每一层都要编写测试。

需要了解文件放置方式或如何新建系统时，请阅读 references/directory-layout.md；需要了解变更后的 API、查询或钩子模式时，请阅读 references/patterns.md。相关技能按需使用：组件或钩子行为涉及 React，Query、Router 或 Form 涉及 TanStack，store API 涉及 XState Store；编辑测试时，遵循现有测试运行器的指南。遇到尚未解决的故障时再参考调试指南，无需在每次系统修改时都查看。

• 依赖方向应指向较低层：组件使用钩子，钩子使用查询选项和适配器；适配器不导入 UI。跨系统的使用方通过公共导出文件访问。
• 在适配器和查询缓存中保留 API 封装；在读取边界将数据扁平化为组件视图模型。根据公共契约派生类型，并在负责该边界的层验证不可信输入。
• 在加载器、钩子、变更操作和流写入器中复用规范的查询选项和键。包含稳定的作用域和筛选条件；对于无限查询，续页游标应放在 pageParam 中。
• 通过适配器传递 AbortSignal，并使用项目的类型化错误契约表示错误。在请求边界处理缺失的作用域；仅有 enabled 并不能证明使用非空断言时值不为 null。
• 遵循现有的数据新鲜度默认设置。通过规范键协调变更；仅当所属读取模型需要重新读取服务端数据时才使缓存失效。只有存在乐观更新契约时才添加乐观回调；取消冲突的读取、完整快照状态，并在失败时恢复。
• 仅在需要通过子树共享状态时添加上下文。某些上下文适合使用允许为空的必需提供程序模式；只有在所有权或更新频率方面确有依据时，才拆分提供程序。
• 将服务端状态保留在 Query 中。使用 XState Store 管理事件驱动的本地数据；显式生命周期模式或守卫有时更适合状态机。不要仅仅因为系统包含异步调用就引入 store。
• 在导出文件中显式导出受支持的操作。复用负责维护各项变更不变量的现有测试套件，不要照着目录树为每一层都添加测试。