字段说明测试

.gitea/checker/comparator.py

@@ -31,48 +31,37 @@ class ParameterChange:
     required: Optional[bool] = None
     old_required: Optional[bool] = None
     detail: Optional[str] = None
+    description: Optional[str] = None
+    old_description: Optional[str] = None
+    source: str = "query"
+
+    def _escape_cell(self, text: str) -> str:
+        """表格单元格转义。"""
+        return text.replace("|", "\\|").replace("\n", " ")
+
+    def _change_label(self) -> str:
+        """变更列文案，对齐 model.md。"""
+        if self.change_type == ChangeType.ADDED:
+            if self.required is False:
+                return "新增可选"
+            return "新增必填"
+        if self.change_type == ChangeType.REMOVED:
+            return "删除"
+        if self.change_type == ChangeType.RENAMED:
+            return f"重命名 {self.old_name} → {self.param_name}"
+        if self.change_type == ChangeType.MODIFIED:
+            return self.detail or "修改"
+        return "-"
+
+    def to_table_row(self) -> str:
+        """格式化为 model.md 参数变更表格行。"""
+        desc = self._escape_cell(self.description or "-")
+        change = self._escape_cell(self._change_label())
+        return f"| `{self.param_name}` | {desc} | {change} |"
 
     def to_markdown_line(self, *, plain: bool = False) -> str:
-        """
-        格式化为企微 Markdown 行。
-        plain=True 时用于新增接口，直接列出参数，不加「新增」前缀。
-        """
-        req_optional = self.required is False
-        req_required = self.required is True
-
-        if plain and self.change_type == ChangeType.ADDED:
-            tag = (
-                '<font color="warning">必填</font>'
-                if req_required
-                else '<font color="comment">可选</font>'
-            )
-            return f'> `{self.param_type}` **{self.param_name}** · {tag}'
-
-        if self.change_type == ChangeType.REMOVED:
-            return (
-                f'<font color="warning">【删除】</font> '
-                f'`{self.param_type}` ~~{self.param_name}~~'
-            )
-        if self.change_type == ChangeType.ADDED:
-            tag = (
-                '<font color="warning">必填</font>'
-                if req_required
-                else '<font color="comment">可选</font>'
-            )
-            return (
-                f'<font color="info">【新增】</font> '
-                f'`{self.param_type}` **{self.param_name}** · {tag}'
-            )
-        if self.change_type == ChangeType.RENAMED:
-            return (
-                f'<font color="comment">【重命名】</font> '
-                f'`{self.old_type}` {self.old_name} → '
-                f'`{self.param_type}` **{self.param_name}**'
-            )
-        if self.change_type == ChangeType.MODIFIED:
-            detail = f' · <font color="comment">{self.detail}</font>' if self.detail else ""
-            return f'<font color="warning">【修改】</font> **{self.param_name}**{detail}'
-        return f'- {self.param_name}'
+        """兼容旧调用，委托至表格行。"""
+        return self.to_table_row()
 
 
 @dataclass
@@ -113,6 +102,11 @@ def _param_key(p: ApiParameter) -> Tuple[str, str]:
     return (p.source, p.name)
 
 
+def _format_type_change(old_type: str, new_type: str) -> str:
+    """类型变更文案。"""
+    return f"类型由{old_type}改为{new_type}"
+
+
 def compare_parameters(
     old_params: List[ApiParameter], new_params: List[ApiParameter]
 ) -> List[ParameterChange]:
@@ -143,9 +137,16 @@ def compare_parameters(
         new_p = new_map[key]
         detail_parts = []
         if old_p.type != new_p.type:
-            detail_parts.append(f"类型 {old_p.type} -> {new_p.type}")
+            detail_parts.append(_format_type_change(old_p.type, new_p.type))
         if old_p.required != new_p.required:
-            detail_parts.append(f"必填 {old_p.required} -> {new_p.required}")
+            req_label = lambda r: "必填" if r else "可选"
+            detail_parts.append(
+                f"必填性由{req_label(old_p.required)}改为{req_label(new_p.required)}"
+            )
+        if old_p.description != new_p.description:
+            detail_parts.append(
+                f"说明由{old_p.description or '-'}改为{new_p.description or '-'}"
+            )
         if detail_parts:
             changes.append(
                 ParameterChange(
@@ -155,6 +156,9 @@ def compare_parameters(
                     required=new_p.required,
                     old_required=old_p.required,
                     detail=", ".join(detail_parts),
+                    description=new_p.description,
+                    old_description=old_p.description,
+                    source=new_p.source,
                 )
             )
 
@@ -183,6 +187,9 @@ def compare_parameters(
                         old_name=r_param.name,
                         old_type=r_param.type,
                         required=a_param.required,
+                        description=a_param.description,
+                        old_description=r_param.description,
+                        source=a_param.source,
                     )
                 )
                 matched_removed.add(r_key)
@@ -197,6 +204,8 @@ def compare_parameters(
                     change_type=ChangeType.REMOVED,
                     param_name=param.name,
                     param_type=param.type,
+                    description=param.description,
+                    source=param.source,
                 )
             )
 
@@ -209,6 +218,8 @@ def compare_parameters(
                     param_name=param.name,
                     param_type=param.type,
                     required=param.required,
+                    description=param.description,
+                    source=param.source,
                 )
             )
 
@@ -365,6 +376,8 @@ def compare_endpoints(
                             param_name=p.name,
                             param_type=p.type,
                             required=p.required,
+                            description=p.description,
+                            source=p.source,
                         )
                         for p in ep.parameters
                     ],