ds2api/CLAUDE.local.md

# Claude Code 行为准则

> 本文件定义 Claude Code 在本项目中的强制执行规则。所有规则均为**必须执行**，不可跳过。

---

## 一、核心原则（九荣九耻）

| 耻 | 荣 |
|---|---|
| ❌ 瞎猜接口 | ✅ 认真查询源码 |
| ❌ 模糊执行 | ✅ 寻求用户确认 |
| ❌ 臆想业务 | ✅ 复用现有实现 |
| ❌ 创造接口 | ✅ 主动测试验证 |
| ❌ 跳过验证 | ✅ 等待人类确认 |
| ❌ 破坏架构 | ✅ 遵循项目规范 |
| ❌ 假装理解 | ✅ 诚实说"不确定" |
| ❌ 盲目修改 | ✅ 谨慎重构 |
| ❌ 画蛇添足 | ✅ 按需实现 |

---

## 二、代码生成前置检查

### 【强制】生成代码前必须完成的 4 项检查

在生成**任何代码**之前，必须逐条确认以下检查项，**缺一不可**：

| # | 检查项 | 未通过则 |
|---|--------|---------|
| 1 | 是否已读取 CLAUDE.md 中的编码规范？ | ❌ 禁止生成代码 |
| 2 | 是否已搜索项目中类似实现作为参考？ | ❌ 禁止生成代码 |
| 3 | 是否有不确定的地方需要询问用户？ | ⚠️ 先询问再继续 |
| 4 | 是否复用了现有的实体类/工具类？ | ❌ 禁止新建已存在的类 |

---

## 三、"参照 XX 写"执行规则

当用户说"参照XX写"、"仿照XX实现"、"按照XX的方式"时，**必须严格执行**以下步骤：

### 步骤清单

| # | 步骤 | 必须完成的动作 |
|---|------|--------------|
| 1 | 完整阅读参照对象 | 读取 Controller、Service、Mapper、Entity **所有相关文件**，不能只看部分 |
| 2 | 列出关键对照点 | 向用户列出：接口路径、参数格式、返回值格式、Service 调用方式、业务逻辑 |
| 3 | 严格对照实现 | ❌ 禁止"优化"或"改进"参照对象，❌ 禁止偏离参照对象的风格 |

### 完成后自检

| # | 自检问题 | 答案必须是"是" |
|---|---------|--------------|
| 1 | 我的实现和参照对象的实现方式是否一致？ | 否则必须修正 |
| 2 | 有没有任何地方是我"自作主张"改的？ | 有则必须告知用户 |

**如果有任何偏离，必须告知用户并说明原因，由用户决定是否采用。**

---

## 四、批量保存接口设计规范

### 【强制】设计前必须列出用户操作场景

| 用户操作 | 数据特征 | 处理方式 |
|---------|---------|---------|
| 新增一条数据 | 传入的数据没有 id | INSERT |
| 修改一条数据 | 传入的数据有 id | UPDATE |
| 删除一条数据 | **数据库有但传入列表中没有** ← 容易遗漏！ | DELETE |
| 不做任何改动 | 原样传回 | 不处理 |

### 正确实现步骤

```
1. 查询数据库中该主体已有的所有数据 ID
2. 对比传入列表中的 ID，找出需要删除的（数据库有但传入没有）
3. 删除不在传入列表中的数据
4. 新增或更新传入列表中的数据
```

### 完成后自检

| # | 自检问题 | 答案必须是"是" |
|---|---------|--------------|
| 1 | 新增、更新、删除——三种情况都覆盖了吗？ | |
| 2 | 如果用户删除了一条已有数据，保存后这条数据会消失吗？ | |

---

## 五、文档解析规则

### 【强制】解析步骤（按顺序执行，不可跳过）

| # | 步骤 | 必须完成的动作 | 中断条件 |
|---|------|--------------|---------|
| 1 | 多方式解析 | Word/PDF 必须尝试 ≥2 种解析方式（段落、表格、文本框、XML 等） | |
| 2 | 完整性检查 | 检查是否只看到类名而没有属性定义？ | ⚠️ **是则停止，询问用户** |
| 3 | 列出清单 | 向用户列出：类数量+名称、每个类的属性数量+名称、方法数量+签名 | ⚠️ **等待用户确认** |
| 4 | 生成代码 | 只有用户明确确认后才能继续 | |

### 绝对禁止

| # | 禁止行为 |
|---|---------|
| 1 | ❌ 禁止在用户确认前生成任何代码 |
| 2 | ❌ 禁止自行补充或猜测文档中未明确写出的内容 |
| 3 | ❌ 禁止只用一种方式解析就认为解析完成 |
| 4 | ❌ 禁止看到类名/接口名却没有属性定义时继续执行 |

---

## 六、接口与参数分析规则

### 触发条件
- 分析接口映射关系（标准接口 → 内部接口）
- 分析参数映射关系
- 编写 DTO/Entity 字段定义

### 【强制】执行步骤

| # | 步骤 | 必须完成的动作 |
|---|------|--------------|
| 1 | 确认接口映射 | 阅读标准接口功能 → 搜索后端代码找**功能匹配**的内部接口（不是名称匹配！）→ 读 Controller 确认功能 |
| 2 | 确认参数映射 | 找到 @RequestBody 的类 → 读源码（含父类）→ 逐一列出字段 → 对比建立映射 |

### 映射可信度标注（必须标注）

| 标注 | 含义 |
|-----|------|
| ✅ 已验证 | 已阅读源码确认 |
| ⚠️ 待验证 | 需要进一步确认 |
| ❌ 需新建接口 | 需要编写复杂业务逻辑（组合调用多个接口等） |

### 绝对禁止

| # | 禁止行为 |
|---|---------|
| 1 | ❌ 禁止凭接口名称相似就认为可以映射 |
| 2 | ❌ 禁止直接使用 Postman/Swagger 参数定义，必须与源码核对 |
| 3 | ❌ 禁止凭"合理推测"编写参数映射 |
| 4 | ❌ 禁止使用模糊表述如"需要扩展"、"可能需要调用额外接口" |

---

## 七、Postman 文档规范

### 核心原则

| 位置 | 内容 |
|-----|------|
| `description` 字段 | Markdown 格式，展示完整参数说明（带注释的 JSON 代码块） |
| `body.raw` 字段 | 纯净 JSON（无注释），可直接发送请求 |

### description 格式模板

```json
{
  "description": "接口功能说明。\n\n**请求参数示例：**\n```json\n{\n  \"字段名\": \"示例值\",  // 字段说明\n}\n```\n\n**响应示例：**\n```json\n{\n  \"code\": 0,\n  \"data\": {}\n}\n```"
}
```

### 自检清单

| # | 检查项 | 要求 |
|---|--------|-----|
| 1 | body.raw 是否有注释？ | ❌ 禁止，会导致 JSON 格式错误 |
| 2 | description 是否展示了参数格式？ | ✅ 必须有带注释的 JSON 示例 |
| 3 | 是否包含响应示例？ | ✅ 每个接口都必须有 |
| 4 | Long 类型 ID 是否展示为 String？ | ✅ 如 `"id": "123456789"` |

---

## 八、设计文档编写规范

### 核心原则
设计文档的目标是：**开发人员可以直接照着写代码**，不是概念性说明。

### 【强制】文档必须包含的内容

| # | 内容 | 要求 |
|---|------|-----|
| 1 | 数据库表 DDL | 可直接执行的 CREATE TABLE |
| 2 | 枚举类代码 | 可直接复制使用 |
| 3 | 实体类代码 | 包括所有字段和注解 |
| 4 | Mapper 代码 | 包括 Provider 中的完整 SQL |
| 5 | Service 代码 | 接口定义和实现类 |
| 6 | Controller 代码 | 接口路径、请求体、响应格式 |
| 7 | 实现清单 | 新模块接入时的检查表 |
| 8 | 常见问题 FAQ | 解答可能的疑惑 |

### 代码示例要求

| # | 要求 |
|---|------|
| 1 | 代码必须**完整可用**，不是片段或伪代码 |
| 2 | 必须包含**完整的 import 语句** |
| 3 | SQL 必须**完整可执行**，不能用 `...` 省略 |

### 完成后自检

| # | 自检问题 | 答案必须是"是" |
|---|---------|--------------|
| 1 | 新人开发者能否只看这份文档就完成开发？ | |
| 2 | 文档中的代码能否直接复制到项目中使用？ | |
| 3 | 是否有"等"、"..."、"类似"等模糊表述？ | 有则删除 |

---

## 九、方法重载规范

### 规则

| # | 规则 | 说明 |
|---|------|-----|
| 1 | 全量参数方法承载所有逻辑 | 是唯一的实现体 |
| 2 | 少参数方法只做委托调用 | 传 `null` 给新增参数，方法体只有一行 `return` |
| 3 | ❌ 禁止两个重载方法各写一份逻辑 | 即使逻辑相同也不行 |
| 4 | ❌ 禁止反向委托 | 全量方法不能调用少参数方法 |

### 正确示例

```java
// ✅ 少参数方法委托全量方法
public Object foo(Req req, Request request, Response response) {
    return foo(req, request, response, null);
}

public Object foo(Req req, Request request, Response response, Function<String, String> lineConverter) {
    // 所有逻辑在这里
    if (lineConverter != null) {
        // 有转换器时的处理
    }
}
```

---

## 十、工作偏好

| # | 偏好 |
|---|------|
| 1 | 始终使用**简体中文**回复 |
| 2 | 长任务必须记录详细进度 |
| 3 | 提交代码时**不要**附带 `Co-Authored-By: Claude` |
| 4 | 对所有工具操作自动同意，无需额外确认 |
| 5 | 不用执行编译和测试 |
| 6 | 编写构建脚本时尽量使用 mjs 编写带菜单的脚本 |
| 7 | 尽量使用 Python 连接数据库 |
| 8 | 联网搜索时**禁止**使用 csdn.net、阿里云/腾讯云/华为云社区等内容农场 |

---

## 十一、代码生成规则

| # | 规则 |
|---|------|
| 1 | 提供实体类/模板/文档时，必须**完整复制所有属性和方法**，禁止省略 |
| 2 | 生成代码前，先列出文档中所有属性数量和名称，确认无遗漏后再生成 |
| 3 | 属性超过 20 个时，分批列出确认 |
| 4 | 禁止因为"优化"或"简化"而删减任何属性 |
| 5 | 生成完成后，对比源文档属性数量是否一致 |