接口类对象解析

.gitea/checker/notifier.py

@@ -5,11 +5,12 @@
 
 import json
 import re
-from typing import List, Optional
+from collections import OrderedDict
+from typing import List, Optional, Tuple
 
 import requests
 
-from comparator import EndpointChangeReport
+from comparator import EndpointChangeReport, ParameterChange
 
 # 企微 Markdown 单条上限 4096 字符，留余量
 MAX_MD_LENGTH = 3800
@@ -22,8 +23,8 @@ def truncate_text(text: str, max_length: int = MAX_MD_LENGTH) -> str:
     return text[:max_length] + "\n\n<font color=\"comment\">... 消息过长，已截断</font>"
 
 
-def _format_param_change_list(changes: List) -> List[str]:
-    """生成企微友好的参数变更列表（卡片式）。"""
+def _format_param_change_list(changes: List[ParameterChange]) -> List[str]:
+    """生成企微友好的普通参数变更列表（卡片式）。"""
     if not changes:
         return ['<font color="comment">无</font>']
     lines = ["", f"共 **{len(changes)}** 项变更", ""]
@@ -34,6 +35,52 @@ def _format_param_change_list(changes: List) -> List[str]:
     return lines
 
 
+def _body_dto_group_key(change: ParameterChange) -> Tuple[str, str]:
+    """类对象变更分组键：(body 参数名, DTO 类名)。"""
+    return (change.body_param_name or "body", change.parent_dto or "")
+
+
+def _format_body_field_line(change: ParameterChange, *, is_last: bool) -> List[str]:
+    """格式化 DTO 一级字段变更行。"""
+    branch = "└─" if is_last else "├─"
+    desc = change.description or change.old_description
+    type_part = f" · `{change.param_type}`" if change.param_type else ""
+    req_part = f" · {change._required_tag()}" if change._required_tag() else ""
+    lines = [f"{branch} `{change.param_name}`{type_part}{req_part}  {change._change_tag()}"]
+    if desc:
+        lines.append(f">   说明：{desc}")
+    if change.change_type.value == "modified" and change.detail:
+        lines.append(f">   变更：{change.detail}")
+    if change.change_type.value == "renamed":
+        lines.append(f">   `{change.old_name}` → `{change.param_name}`")
+    return lines
+
+
+def _format_body_dto_groups(changes: List[ParameterChange]) -> List[str]:
+    """按 DTO 分组展示 @RequestBody 一级字段。"""
+    if not changes:
+        return ['<font color="comment">无</font>']
+
+    groups: OrderedDict[Tuple[str, str], List[ParameterChange]] = OrderedDict()
+    for change in changes:
+        key = _body_dto_group_key(change)
+        groups.setdefault(key, []).append(change)
+
+    lines: List[str] = ["", f"共 **{len(groups)}** 个类对象 · **{len(changes)}** 项字段变更", ""]
+    for (param_name, dto_name), group in groups.items():
+        label = param_name or "body"
+        dto_part = f" · `{dto_name}`" if dto_name else ""
+        lines.append(f"**{label}**{dto_part}")
+        lines.append("")
+        for i, change in enumerate(group):
+            lines.extend(_format_body_field_line(change, is_last=(i == len(group) - 1)))
+        lines.append("")
+
+    if lines and lines[-1] == "":
+        lines.pop()
+    return lines
+
+
 def _format_param_details_section(report: EndpointChangeReport) -> List[str]:
     """生成接口参数变动详情区块。"""
     body_changes = [c for c in report.parameter_changes if c.source == "body"]
@@ -41,12 +88,12 @@ def _format_param_details_section(report: EndpointChangeReport) -> List[str]:
     lines = ["", "---------------------------------------", "", "#### 【接口参数变动详情】", ""]
 
     if body_changes:
-        lines.append("**类对象变更**")
-        lines.extend(_format_param_change_list(body_changes))
+        lines.append("**类对象变更（一级字段）**")
+        lines.extend(_format_body_dto_groups(body_changes))
         lines.append("")
 
     if regular_changes:
-#         lines.append("**普通参数变更**")
+        lines.append("**普通参数变更**")
         lines.extend(_format_param_change_list(regular_changes))
         lines.append("")