harness engineering is the idea that anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent will not make that mistake again in the future.

—— Mitchell Hashimoto

控制工程的思想是，每当你发现一个代理犯了错误，你就花时间设计一个解决方案，这样代理将来就不会再犯同样的错误。

# CLAUDE.md - 项目上下文与开发规范

## 1. 系统提示指引
- 本文件是项目命令、技术栈和编码规范的绝对真理源（Source of Truth）。
- 每次会话开始时自动加载，请务必严格遵守，不得违反以下任何规则。
- 回复请保持简明、直接、聚焦于代码实现，拒绝任何客套话与废话。

## 2. 技术栈与环境
- **前后端/语言:** Node.js (v20+), TypeScript (严格模式)
- **核心框架:** Next.js (App Router) / NestJS
- **数据库:** PostgreSQL (通过 Prisma ORM 驱动)
- **包管理器:** `pnpm` (严禁使用 npm 或 yarn)

## 3. 核心开发命令
执行项目操作时，必须使用以下确切命令：
- **本地启动:** `pnpm dev`
- **生产构建:** `pnpm build`
- **代码规范与格式化:** `pnpm lint` / `pnpm format`
- **类型检查:** `pnpm type-check`
- **运行单元测试:** `pnpm test`
- **运行 E2E 测试:** `pnpm test:e2e`
- **数据库迁移:** `pnpm prisma db push` / `pnpm prisma migrate dev`

## 4. 目录与架构约定
- `src/core/` - 全局单例与共享公共模块。**除非有明确指令，否则严禁修改此目录**。
- `src/modules/` - 领域驱动的功能模块（如 auth, orders, users）。
- 组件仅负责纯渲染；所有业务逻辑必须抽离到自定义 Hooks 或 Services 中。
- 文件命名：所有文件和目录一律使用短横线命名法（如 `user-profile.controller.ts`）。

## 5. 编码强制约束
- **TypeScript:** 绝对禁止使用 `any`。必须使用 `unknown` 或明确的 types/interfaces。
- **异步处理:** 异步操作必须包裹在 `try/catch` 块中，严禁漏掉未捕获的 Promise。
- **错误处理:** 统一使用全局 `AppError` 类，严禁直接抛出原生 `Error` 对象。
- **函数体量:** 单个函数最大不得超过 50 行，优先编写纯函数。
- **路径导入:** 必须使用别名绝对路径（如 `@/core/services/log`），严禁使用相对路径（`../../`）。

## 6. 防幻觉与错误防复发（AI 避坑指南）
- **禁止盲猜 API:** 如对第三方库的方法签名不确定，请提示用户或查阅项目知识库。
- **状态管理:** 禁止直接修改（Mutate）状态，必须通过 Hooks 或 Reducers 变更。
- **拒绝占位代码:** 修改文件时，严禁留下 `// TODO: 稍后实现` 或缺失的代码块。

## 7. Git 提交规范
- 严格遵循 Angular 提交信息规范: `<type>(<scope>): <subject>`
- 允许的类型（Type）包括: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`
- 示例: `feat(auth): 增加 argon2 密码哈希加密`

# .clauderules - AI 行为与交互铁律

## 1. 交互与回复红线（绝对不嘴碎）
- **禁止废话**：严禁输出“好的，我明白了”、“没问题，接下来我将...”等任何客套话。
- **直接行动**：收到指令后，直接开始思考并输出核心结果，不进行无意义的开场白。
- **严禁过度解释**：除非用户主动提问，否则严禁长篇大论解释显而易见的代码逻辑。
- **语言限制**：除非用户用英文提问，或者在编写代码中的注释，否则一律使用**简体中文**回复。

## 2. 代码输出规范（精准增删）
- **严禁占位符**：输出代码时必须完整，绝对禁止使用 `// ... 保持原样`、`// TODO: 实现其余部分` 等占位符污染文件。
- **最小化改动**：只修改与需求直接相关的代码。严禁为了重构而重构，严禁无故改动不相关的上下文。
- **精确 diff 意识**：在提供文件修改方案时，必须清晰指出目标文件路径。如果是局部修改，确保提供足够的上下文供用户定位。

## 3. 思考路径与防御性编程
- **全自动审视**：在编写任何代码前，必须自动检索并严格遵守根目录 `CLAUDE.md` 中的命令与技术规范。
- **副作用拦截**：在执行涉及文件删除、破坏性覆盖、依赖大版本升级等高风险操作前，必须主动向用户确认（布尔确认），不得擅自动手。
- **边界与异常思考**：编写业务逻辑时，必须强制思考异常分支、空值（null/undefined）处理以及边界条件，并在代码中体现防御性设计。

## 4. 格式与美学
- **Markdown 严格规范**：所有代码块必须指定正确的语言标记（如 ```typescript, ```bash）。
- **专业与克制**：保持专业、理性的工程师口吻。严禁在回复中使用任何情绪化词汇或无意义的表情符号（🎨、🚀 等）。

### Requirement: User Authentication
系统 SHALL 在用户登录成功时签发 JWT Token<websource>source_group_web_1</websource>。

#### Scenario: Valid credentials (凭证有效)
- **GIVEN** 一个拥有正确账号密码的用户
- **WHEN** 用户提交登录表单
- **THEN** 系统返回 JWT token
- **AND** 用户被重定向到首页

#### Scenario: Invalid credentials (凭证无效)
- **GIVEN** 用户输入了错误的密码
- **WHEN** 用户提交登录表单
- **THEN** 系统显示“账号或密码错误”的提示
- **AND** 不签发任何 token

.context/
├── CONTEXT.md                        # 全局唯一的“地图首页”（人类和AI的第一入口）
│
├── global/                           # 【全局通用规范】只放真正全库通用的东西
│   ├── danger-zones.md               # 全局高危区（如：分布式锁、公共中间件高压线）
│   └── process/                      # 全局工程流程（原封不动保留原有4个文件）
│       ├── dev.md                    # 本地开发和构建
│       ├── cr.md                     # MR/CR 规则
│       ├── test.md                   # 测试和回归策略
│       └── release.md                # 发布、灰度、回滚
│
├── domain-order/                     # 【订单领域】独立上下文文件夹
│   ├── README.md                     # 订单域的“一页纸读懂”（人看的大长篇）
│   ├── business/                     # 订单业务细节（完全保留原有4个文件）
│   │   ├── overview.md               # 服务业务定位
│   │   ├── scenario-flow.md          # 核心交易流程
│   │   ├── rules.md                  # 关键业务规则
│   │   └── terms.md                  # 服务内术语
│   ├── contract/                     # 订单契约（完全保留原有6个文件）
│   │   ├── api.md                    # HTTP/RPC API 契约
│   │   ├── event.md                  # MQ/事件契约
│   │   ├── status.md                 # 状态机、枚举语义
│   │   ├── idempotency.md            # 幂等、重试、补偿
│   │   ├── error-code.md             # 错误码语义
│   │   └── compatibility.md          # 兼容和演进策略
│   ├── architecture/                 # 订单架构（完全保留原有3个文件，danger-zones移至global）
│   │   ├── modules.md                # 模块边界
│   │   ├── dependencies.md           # 上下游依赖
│   │   ├── runtime.md                # 环境、配置、中间件
│   │   └── data-flow.md              # 数据流
│   └── history/                      # 订单历史与复盘（完全保留原有4项）
│       ├── adr/                      # 决策记录：为什么这样设计
│       ├── postmortems/              # 事故复盘：出过什么问题
│       ├── cases/                    # 典型需求、MR、事故案例
│       └── lessons.md                # 轻量踩坑记录
│
├── domain-payment/                   # 【支付领域】独立上下文文件夹（示例扩展）
│   ├── README.md                     # 支付域“一页纸读懂”
│   ├── business/                     # 支付业务细节（同订单域结构）
│   │   ├── overview.md               
│   │   ├── scenario-flow.md          
│   │   ├── rules.md                  
│   │   └── terms.md                  
│   ├── contract/                     # 支付契约（同订单域结构）
│   │   ├── api.md                    
│   │   ├── event.md                  
│   │   ├── status.md                 
│   │   ├── idempotency.md            
│   │   ├── error-code.md             
│   │   └── compatibility.md          
│   ├── architecture/                 # 支付架构（同订单域结构）
│   │   ├── modules.md                
│   │   ├── dependencies.md           
│   │   ├── runtime.md                
│   │   └── data-flow.md              
│   └── history/                      # 支付历史与复盘（同订单域结构）
│       ├── adr/                      
│       ├── postmortems/              
│       ├── cases/                    
│       └── lessons.md                
│
└── requirements/                     # 【活跃需求】仅保留当前迭代的需求（上线后归档/删除）
    └── REQ-YYYYMMDD-xxx/             # （完全保留原有6个文件）
        ├── requirement.md            # 需求摘要
        ├── impact-analysis.md        # 影响面分析
        ├── solution.md               # 技术方案
        ├── test-plan.md              # 测试计划
        ├── release-note.md           # 发布说明
        └── summary.md                # 上线后总结

# 🎯 多领域核心上下文 (Multi-Domain Core Context)

> ⚠️ **AI 编码前必读指引**：
> - 本系统采用 **严格的多领域限界上下文 (Bounded Contexts) 隔离架构**。
> - 在开展任何 `spec/` 新需求设计或代码重构前，必须全自动装载并通读本全景图。
> - 必须确保每一行代码都落入其所属的正确领域和分层中，**严禁跨领域强耦合调用**。

---

## 1. 业务领域全景图与限界上下文 (Domain Bounded Contexts)
本服务/大仓包含以下核心业务领域，AI 必须严格对齐各自的职责边界：

### 👤 A. 用户域 (User Domain) - `src/domain/user/`
- **核心聚合根**: `User` (用户)
- **核心职责**: 管理用户生命周期、核心资质审查、账户安全状态。
- **解耦红线**: 属于基础支撑域，严禁依赖任何上游交易或营销领域。

### 📦 B. 商品域 (Catalog Domain) - `src/domain/catalog/`
- **核心聚合根**: `Product` (商品), `Inventory` (库存)
- **核心职责**: 商品类目上下架、多仓库存锁定与扣减逻辑。
- **解耦红线**: 纯内存库存计算，扣减逻辑必须由聚合根控制，严禁直接暴露 DB 扣减接口。

### 🛒 C. 订单交易域 (Trade Domain) - `src/domain/trade/`
- **核心聚合根**: `Order` (订单)
- **核心职责**: 处理提单、计价引擎、订单状态机流转。
- **解耦红线**: 订单域调用【商品域】或【营销域】时，必须通过自身领域内的 **防腐层 (ACL, Anti-Corruption Layer)** 接口进行隔离，严禁直接 import 对方的应用服务。

### 🎫 D. 营销域 (Marketing Domain) - `src/domain/marketing/`
- **核心聚合根**: `Coupon` (优惠券), `Campaign` (营销活动)
- **核心职责**: 营销资损控制、满减/折扣算法引擎、优惠券核销。
- **解耦红线**: 营销计算只接受入参数据流，严禁在营销域内部反向查询订单状态。

- **多领域细节索引**: 
  - 深度核对各领域的底线业务规则: [关键业务规则](./business/rules.md)
  - 对齐各领域的统一语言，严禁混淆字段: [领域标准术语表](./business/terms.md)

---

## 2. 跨领域交互与解耦铁律 (Cross-Domain Interaction)
为了防止多领域系统退化为“大泥潭”，AI 必须严格执行以下交互规范：
1. **同步调用（左向右）**: 仅允许上游核心域（如 `Trade`）通过 **防腐层 (ACL)** 接口，同步调用下游支撑域（如 `User`, `Catalog`）。
2. **异步通信（右向左）**: 当下游或平行域需要感知上游变更时（例如订单支付成功后，营销域要核销优惠券），必须且只能通过 **领域事件 (Domain Events) + MQ** 进行异步解耦通信。
3. **严禁循环依赖**: 领域 A 引用了领域 B 的 ACL，则领域 B 的任何地方绝对禁止出现领域 A 的任何包/类导入。

- **交互细节导航**: [模块边界与纵向分层定义](./architecture/modules.md) | [上下游依赖与防腐层(ACL)设计](./architecture/dependencies.md)

---

## 3. 单领域内部：严格代码分层约束 (Architectural Layering)
在任何一个独立领域内部，AI 必须严格按照以下四个技术层级编写代码，严禁职责错位：
- **接口层 (`src/interface/`)**: 仅负责协议转换与基础入参校验（DTO），**严禁包含任何业务逻辑**。
- **应用服务层 (`src/application/`)**: 负责**流程编排**（如：开启事务、调用各领域的 Repository、发送领域事件），**不管业务规则**。
- **核心领域层 (`src/domain/`)**: 包含聚合根、实体、值对象和领域服务。它是纯粹的**业务核心，纯内存操作，外部零依赖**（严禁依赖 ORM、Redis、HTTP）。
- **基础设施层 (`src/infrastructure/`)**: 负责 Repository 的持久化实现、MQ 驱动、以及外部接口的 ACL 具体实现。

---

## 4. 核心契约与语义
- **对外原语**: 本服务整体对外暴露的对外能力，必须与根目录 `spec/` 中的 `spec.md` / `design.md` 保持 100% 绝对一致。
- **契约细节索引**:
  - 跨领域异步消息格式与幂等去重设计: [MQ事件契约与幂等设计](./contract/event.md)
  - 分层错误码转换（各领域私有异常转换为全局错误码）: [错误码语义与异常拦截](./contract/error-code.md)

---

## 5. 警惕：多领域退化血泪史 (AI 重点防御)
- **防止跨领域对象污染**: 历史发生过 AI 直接把【商品域】的实体对象作为【订单域】接口的入参，导致两块业务产生强物理耦合（见 [history/lessons.md](./history/lessons.md)）。
- **防御原则**: 跨领域传输数据，必须在各自领域的应用服务层转换成纯粹的 **DTO** 或 **值对象 (Value Object)**，严禁领域实体（Entity）跨界。
- **历史细节索引**: [ADR 架构决策记录（多领域解耦规范）](./history/adr/) | [跨领域踩坑复盘](./history/lessons.md)

                    【 1. 接收指令：触发规范 】
                                │
                                ▼
[ .clauderules ] ──► 自动激活底层过滤器（规范表达，禁止废话）
                                │
                                ▼
[   CLAUDE.md  ] ──► 加载内存上下文（获取技术栈规范、常用指令）
                                │
                                ▼
                    【 2. 编写 OpenSpec 蓝图 】
AI 在 `spec/feat-coupon/` 目录下创建并完善两个核心文件：
 ├─► 1. 编写 `spec.md`：明确用户满减券的计算规则与 Given/When/Then 验收场景。
 └─► 2. 结合【.context/】历史资产（参考旧的计价逻辑与 danger-zones 高风险区）
        编写 `design.md`：设计优惠券表的 Schema 和扣减接口。
                                │
                                ▼
                    【 3. 人类评审（Grilling）】
人类阅读并确认 `spec/` 下的 `spec.md` 和 `design.md` 符合预期。
                                │
                                ▼
                    【 4. AI 严格按照蓝图开始 Code 】
AI 编写实际业务代码。此时由于有了详细的 design.md 约束，AI 绝不会乱写和猜想。
                                │
                                ▼
                    【 5. 归档与闭环 】
测试通过准备上线。AI 自动将本次优惠券开发的核心技术决策归档至 `.context/history/adr/`，
并将踩坑记录沉淀至 `.context/history/lessons.md`。

你的项目根目录/
├── CLAUDE.md              # 顶层：入口与命令指南
├── rules/                 # 顶层：底线与行为约束
├── spec/                  # 中层：当前正在做的需求
└── .context/              # 底层：外挂大脑（上下文仓库）
    ├── README.md          # 告诉 AI：这里面每个文件的检索规则是什么
    ├── domain-models/     # 1. 业务领域模型层（如：用户状态机、订单生命周期图解）
    ├── architecture/      # 2. 技术架构层（如：核心中间件拓扑、分库分表路由规则）
    ├── pitfall-archive/   # 3. 历史死坑血泪史（如：某年某月因异步线程产生的线上Bug记录）
    └── scripts/           # 4. 动态上下文脚本（如：运行后能一键生成最新 API 字典的工具）

                    【 混合 AI 编码工作流 】
                              │
         ┌────────────────────┴────────────────────┐
         ▼                                         ▼
【使用 Claude Code 的规则体系】           【使用 OpenSpec 的领域知识库】
  - 管控 AI 的“工作态度”                    - 管控 AI 的“业务大脑”
  - 配置代码风格、Lint 规则、Git 提交规范    - 维护项目当前业务现状(openspec/specs/)
  - 处理零碎的 Bug 修复和工具函数编写       - 处理跨模块重构、复杂新功能落地

“我们的分布式锁以前在高并发下偶尔会出问题，所以后来大家达成共识，改成了用 Redisson。后续修改这块代码的时候，大家尽量多注意一下死锁的情况。”

**[约束]** 核心交易模块（`src/trade/`）必须且只能使用 **Redisson 分布式锁**。
**[高风险区]** 严禁在持有 Redis 锁的上下文内发起 HTTP 同步网络请求。
**[原因]** 历史事故（见 `history/postmortems/20251101`）：网络延迟会导致锁超时释放，从而引发多节点并发写入死锁。

### 术语对照表
- **领域词 (Domain Term)**: `FreezeBalance` (资产冻结)
  - **代码表现**: 对应 `UserAccount.frozen_amount` 字段
  - **业务含义**: 用户下单后、未扣款前，暂时锁定其可用额度，防止超卖。
  - **注意点**: 冻结金额在任何情况下都不能为负数。