architecture

架构

随着代码库不断扩展，保持其易于浏览的原则。应结合项目自身的约定来应用这些原则——它们只是默认做法，不会覆盖已有文档说明的项目结构。

按领域组织，而非按层组织

按代码所服务的能力分组，以便通过探索一个区域就能理解某项功能：

features/
  bookings/      ← services, data access, UI, tests for bookings
  availability/  ← services, data access, UI, tests for availability

避免使用顶层技术分层（controllers/、services/、repositories/），以免同一领域的变更分散到多个目录中。如果能让功能更易于浏览，在功能内部设置局部技术子目录也可以。

通过公共 API 交互

一个功能只能通过另一个功能的公共入口点导入它，不能直接访问其内部文件：

// ❌ reaching into internals
import { calculateSlots } from "features/availability/services/internal/slotCalculator";

// ✅ through the public API
import { getAvailability } from "features/availability";

将与领域无关的实用工具（日志记录、身份验证、通用辅助工具）放在共享的底层模块中；将共享的 UI 基础组件放在共享 UI 模块中。在工具链允许的情况下，使用 lint 规则强制执行导入边界。

保持依赖图无环

依赖关系应沿一个方向流动，从较低层的共享代码指向较高层的应用入口点：

shared utils → shared domain modules → features → transport/API → app entry

较低层不得导入较高层。导入某项功能的实用工具，或相互导入的两个功能，都会形成循环依赖——这会导致构建失败、类型错误，并使代码结构无法再反映依赖关系。通过将共享部分提取到更低层来打破循环依赖。

保持传输层精简

HTTP 处理程序、RPC 路由器、CLI 命令、队列使用者和 UI 事件处理程序都是交付机制。它们应验证输入，将其转换为应用数据，调用领域／应用代码，再将结果转换回去。

不要让传输边界成为业务决策、持久化细节或复杂编排不断累积的地方。如果另一种传输方式也需要相同行为，就应将其移到面向领域的接口之后。

在请求路径上进行授权

这与本技能中的其他原则一样，是一项放置决策：守卫应位于它实际保护的边界，而不是位于外层某级、让人以为已覆盖却无法保证覆盖的地方。

将授权检查放在每个请求都能确切经过的路径上——也就是保护资源本身的处理程序。共享的外层壳层（继承布局、包装装饰器，或某些入口点会跳过的中间件）都可能被绕过，只要请求能够不经过它而到达受保护的资源。读取任何受限数据之前，先验证身份和角色，并采用默认拒绝的策略：拒绝未授权请求，或重定向、提前返回。

完成标准

此变更遵守现有边界：新文件与其服务的能力放在一起；跨模块导入通过公共入口点进行；没有导入引入循环依赖或从较低层指向较高层；传输代码保持精简；任何授权检查都位于受保护请求路径上，而非可绕过的包装层中。只要有一项不符合，就不算达标。