61 lines
2.4 KiB
Markdown
61 lines
2.4 KiB
Markdown
# 字段说明规则
|
||
|
||
适用于 **Dto / Vo / Entity / Model** 四类模型类的变更通知。
|
||
字段变更采用 **引用块 + 单行合并 + font 颜色**，遵循企微 `markdown` v1（不支持列表）。
|
||
|
||
## 说明提取优先级
|
||
|
||
| 优先级 | 来源 |
|
||
|:------:|------|
|
||
| 1 | `@Schema(description = "...")` / `@Schema(title = "...")` |
|
||
| 2 | `@ApiModelProperty(value = "...")` / `@ApiModelProperty(notes = "...")` |
|
||
| 3 | `/** ... */` 字段注释 |
|
||
| 4 | 空串 |
|
||
|
||
类级说明优先级：`@Schema(description/title)` → `@ApiModel(description/value)` → 类 Javadoc。
|
||
|
||
## 字段变更行格式
|
||
|
||
每条变更占**一行**，标签、说明、类型横向排列，冒号后两空格：
|
||
|
||
```
|
||
> **共 <font color="warning">2</font> 项变更**
|
||
|
||
> <font color="warning">[重命名]</font> <font color="comment">taskId</font> → <font color="info">taskIds</font> 说明: <font color="comment">流程主键</font>
|
||
|
||
> <font color="info">[新增]</font> `applyUserList` 说明: <font color="comment">申请人员集合</font> 类型: <font color="info">List<String></font>
|
||
|
||
> <font color="warning">[删除]</font> `applyUser1` 说明: <font color="comment">申请人员</font> 类型: <font color="warning">Integer</font>
|
||
```
|
||
|
||
| 操作 | 标签 | 类型段 |
|
||
|------|------|--------|
|
||
| 新增 | info `[新增]` | 始终展示，绿色 `info` |
|
||
| 删除 | warning `[删除]` | 始终展示，橙色 `warning` |
|
||
| 修改 | warning `[修改]` | 始终展示，旧类型 warning → 新类型 info |
|
||
| 重命名 | warning `[重命名]` | 始终展示；仅改名时单色 info，改类型时 old → new |
|
||
|
||
### 重命名配对规则
|
||
|
||
- 删除+新增且**类型相同、说明相同**（非空）→ `[重命名]`
|
||
- 删除+新增且**说明相同但类型不同** → `[重命名]` + 类型行
|
||
- 说明均为空时也可配对
|
||
- 说明不同则不配对，保持删除+新增
|
||
|
||
- 统计行加粗，数字用 warning（橙色），文案为「共 N 项变更」（不含「字段」）
|
||
- 多条变更之间用**空行**分隔
|
||
- 说明为空时显示 `<font color="comment">（无说明）</font>`
|
||
- 头部四行加粗，用 `quoteKvBold`；不要在 `<font>` 内嵌 `**bold**`
|
||
|
||
## 接口行格式
|
||
|
||
```
|
||
> <font color="info">POST</font> `/apply/clockIn`
|
||
```
|
||
|
||
## 实现
|
||
|
||
- `ClassFieldParser.extractFieldLabel()`
|
||
- `FieldDiffEngine` — 类型变化产生 `[修改]`，说明匹配的删除+新增合并为 `[重命名]`
|
||
- `WeComNotifier.formatFieldChange()`
|