# API 参数变更通知模版

对应 `11.py` → `build_markdown_notification()` 中参数变更分支 + `_format_endpoint_block()`。  
适用：**URI 与 HTTP 方法均未变**，仅入参发生变化。

---

## 完整示例

```
# 【API参数变更通知】
- **修改人：** dongzi
- **修改时间：** 2026-06-08 16:30:00

- **变更类型：** <font color="warning">**修改参数**</font>
- **URI：** **POST** `/apply/clockIn`
- **路径：** <font color="info">**jnpf-ftb/jnpf-ftb-biz/src/main/java/jnpf/workflow/controller/ApplyClockInController.java**</font>

---------------------------------------

#### 【接口参数变动详情】

**类对象变更（一级字段）**

共 **1** 个类对象 · **2** 项字段变更

**applyAttendanceChangeDto** · `ApplyAttendanceChangeDto`

├─ `taskIds` · `List<String>` · 必填  [新增]
>   说明：流程主键集合
└─ `applyUser1` · `Integer`  [删除]
>   说明：申请人员

**普通参数变更**

共 **1** 项变更

1. `id` · `String` · 路径参数  [新增]
>   说明：主键
```

---

## 示例（仅普通参数，无 RequestBody）

```
# 【API参数变更通知】
- **修改人：** dongzi
- **修改时间：** 2026-06-08 16:30:00

- **变更类型：** <font color="warning">**修改参数**</font>
- **URI：** **GET** `/apply/clockIn/{id}`
- **路径：** <font color="info">**jnpf-ftb/.../ApplyClockInController.java**</font>

---------------------------------------

#### 【接口参数变动详情】

**普通参数变更**

共 **1** 项变更

1. `pageSize` · `Integer` · 查询参数  [新增]
```

---

## 参数分类与检测

| 来源注解 | `source` 字段 | diff 粒度 |
|----------|---------------|-----------|
| `@RequestBody` | `body` | Dto **一级字段**（复用 `FieldDiffEngine`） |
| `@PathVariable` | `path` | 参数名、类型、增删 |
| `@RequestParam` | `query` | 参数名、类型、required、增删 |
| 无注解 | `simple` | 待确认是否纳入 |

### 排除的框架参数（建议默认开启）

`HttpServletRequest`、`HttpServletResponse`、`BindingResult`、`Principal`、`Authentication`、`Model`、`ModelMap`、`UriComponentsBuilder` 等。

---

## ParameterChange 数据结构（对齐 11.py）

| 字段 | 说明 |
|------|------|
| `param_name` | 当前参数名 / 字段名 |
| `old_name` | 重命名前名称 |
| `param_type` | 类型字符串，如 `List<String>` |
| `description` | 说明（@Schema / 注释） |
| `source` | `body` / `path` / `query` |
| `body_param_name` | `@RequestBody` 形参名 |
| `parent_dto` | Dto 简单类名 |
| `change_type` | `added` / `removed` / `modified` / `renamed` |
| `detail` | 类型变化等详情 |

---

## 与路径变更的拆分规则（11.py 约定）

| 同一次改动 | 通知策略 |
|------------|----------|
| 仅参数变 | 本模版 |
| 路径变 + 参数变 | **拆两条**：先路径通知，再参数通知 |
| 方法变 + 参数变 | **拆两条**：先方法通知，再参数通知 |
| 新增接口 + 带参数 | 路径通知可**附带**参数详情区块 |

---

## JavaParser 实现要点

1. **EndpointSnapshotParser**：遍历 `MethodDeclaration.getParameters()`，读参数注解
2. **@RequestBody**：取 Dto 类型 → `ClassFieldParser.parseFields()` 得字段列表
3. **ParameterDiffEngine**：旧/新快照按方法指纹对齐后 diff
4. **ApiChangeNotifier**：渲染本模版；泛型类型展示规则与类变更通知一致（`<>` 不 HTML 转义）

## 实现

- `ParameterDiffEngine`
- `ApiChangeNotifier.formatEndpointBlock()`
- 复用 `FieldDiffEngine` / `WeComNotifier` 中的字段行格式（可选统一）