用途：用于设计 RPC 风格后端 API，并规范 Controller → Manager → Repository 的分层架构，适合新建 API 端点、设计 API 契约或进行代码评审。
主要能力与约定：URL 采用固定模式，列表用复数如 GET /api/v1/employees，单个资源用单数如 GET /api/v1/employee?id=xxx，创建用 POST /api/v1/employee，更新、删除、恢复分别用 /update、/delete、/restore 动词子路径，动作类用 /sync/employees。硬性规则包括不使用路径参数，统一用 @QueryValue；资源用单数，集合用复数；所有变更操作使用 @Post，读取使用 @Get，不使用 @Put、@Delete、@Patch。
分层职责：Controller 保持轻薄，仅解析查询参数与默认值、委托 Manager、用 .throwOrValue() 解包 Either，不写业务逻辑也不访问 Repository；Manager 承载业务逻辑，返回 Either<ClientException, T>，用 transaction(db.primary) 包裹数据库操作，可编排多个 Repository 并校验业务规则；Repository 仅负责数据访问，返回实体或 null，读用 db.replica、写用 db.primary，并检查 deletedAt.isNull()。
使用要点：响应模型放在 module-client/response/{domain}/ 下，用 companion object 的 fun from(entity)；分页采用基于 offset 的方式，Manager 返回含 items、total、page、limit、hasMore 的列表响应；错误返回 ClientError.NOT_FOUND.asException().left()，不抛异常；用带 @Singleton 方法的 @Factory 类把 Repository 和 db 注入 Manager。
限制与注意：多词 @QueryValue 参数必须显式写 snake_case 名称，如 @QueryValue("project_id") projectId: UUID；Controller 注入 Repository 属于坏味道，应移至 Manager；链式条件用 .andWhere {} 而非第二次 .where {}；每个 Controller 需加 @ExecuteOn(TaskExecutors.IO)，否则 suspend 函数可能挂起或跑错线程池。更完整的控制器、响应模型、分页、错误处理与 Factory Bean 模板见 code-patterns.md。