---
name: typescript-backend-boundaries
description: 设计与审查 TypeScript 后端各层的职责、类型归属和依赖方向。适用于后端分层设计、架构重构、Core、Database、Infra、API Contract、Shared 与 Server 的边界审查，以及判断 Model、Record、Mapper 等类型应放在哪一层。不用于不涉及这些边界的局部功能改动。
---

# TypeScript 后端职责与边界

将 `Core` 作为后端中不依赖框架的契约权威。业务 Model、持久化 Record Contract、纯 Mapper、
Repository/Use Case Contract、Port 和纯规则放入 Core；具体框架、驱动与 SDK 放在 Core 之外。

进行架构修改，或类型归属、命名不明确时，先阅读
[references/architecture.md](references/architecture.md)。

## 工作流程

1. 提出结构前，检查仓库约定、包清单、既有依赖方向和相关测试。
2. 将每个概念归类为 Model、Record Contract、Mapper、Repository Contract、Use Case Contract、
   Port、纯 Rule、Database 实现、Infra 实现、API Contract、前后端 Shared 或 Server 适配。
3. 保持以下依赖方向：

   ```text
   Database ──► Core ◄── Infra
                   ▲
                   │
   API Contract ─► Server ◄── Shared
         ▲                       ▲
         └────── Frontend ───────┘
   ```

4. Core 不得依赖 Drizzle、数据库驱动、Redis 客户端、HTTP 框架、队列 SDK 或具体 AI SDK。
5. 使用纯 TypeScript 定义持久化 Record Contract。即使当前字段几乎相同，也要与 Model 保持
   不同的名称和职责。
6. 确定性的 Model/Record 转换放在 Core 的纯 Mapper 中；显式处理 `undefined`/`null`、
   readonly/mutable 数组、JSON 日期与可辨识联合。
7. Database 用 Schema、查询、事务、连接和 migration 实现 Repository Contract；Infra 为
   Redis、签名、AI Provider、存储等外部能力实现 Port。
8. 将 JSON DTO 和 HTTP Validator 放在独立 API Contract；优先用普通 `interface` 表达契约，
   配套编写显式 `validateXxx()` 纯函数。只把共用字段检查等确定性纯函数放入 Shared。
   不要让 Frontend 依赖整个 Core。
9. 在语言和 ORM 支持时，为 ORM 推导出的查询 Record 与 Core Record Contract 添加编译期
   双向兼容检查。
10. 先运行最小相关校验，再运行所有受影响包的 type check、build、test 与 migration/schema
   一致性检查。
11. 汇报边界决策、兼容性影响与验证证据。

## 约束

- 不要把每条数据库记录都称为 Domain Entity。Record Contract 可以位于 Core，但它仍是持久化
  契约，不因此成为业务实体。
- 不要仅因为实现需要缓存键、锁、租约、防重放标记、migration 记录或短期任务状态，就创建
  持久化 Model；只需要能力时应定义 Port。
- 单纯的架构审查不代表获得重命名包、移动公开 API 或修改 Schema 的授权。除非用户明确要求，
  应说明取舍并保持兼容。
- 不要将 ORM 推导类型导入 Core；应在 Database 包中用具体 Schema 校验 Core Contract。
- 不要把 HTTP 请求/响应格式放入持久化 Record 或 Core Model；共享传输 DTO 放入 API
  Contract，框架适配留在 Application 或 Server 边界。
- 不要把 Shared 当作无法分类代码的收容目录；只有无环境依赖、无 I/O 且前后端确实共同使用
  的代码才能进入 Shared。
- 每个业务模块只保留模块根目录的 `index.ts` 作为公开出口。`model/`、`record/`、`mapper/`、
  `ports/`、`rules/`、`support/` 等内部目录不创建 barrel `index.ts`；模块根 `index.ts` 直接导出
  具体文件，模块内部也直接引用具体文件。只有必须维持既有公开 API 兼容时才保留嵌套入口。
- 不要为了同时产生类型和 Validator 而建立 Zod 风格 Schema DSL。保持 interface 为主要阅读
  入口；OpenAPI 可以在构建期从 interface 和 JSDoc 约束生成。
- 保留用户已有修改和项目命名惯例，除非它们违反明确的依赖不变量。

## 预期结果

产出的代码应由 Core 约束整个系统而不依赖具体实现，并提供能在实现偏离契约时失败的检查。