✨ feat(ui): 增强表格构建器并完善组件模型文档 (#2048)

* ✨ feat(table): 添加 ComponentCell 以支持表格单元格中嵌入可渲染组件

* ✨ feat(ui): 增强表格构建器并完善组件模型文档

- 增强 `TableBuilder`，新增 `_normalize_cell` 辅助方法，支持自动将原生数据类型（如 `str`, `int`, `Path`）转换为 `TableCell` 模型，简化了表格行的创建。
- 完善 `zhenxun/ui/models` 目录下所有组件模型字段的 `description` 属性和文档字符串，显著提升了代码可读性和开发者体验。
- 优化 `shop/_data_source.py` 中 `gold_rank` 函数的平台路径判断格式，并统一 `my_props` 函数中图标路径的处理逻辑。

* 🚨 auto fix by pre-commit hooks

---------

Co-authored-by: webjoin111 <455457521@qq.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

zhenxun/ui/models/components/alert.py

@@ -14,9 +14,13 @@ class Alert(RenderableComponent):
     type: Literal["info", "success", "warning", "error"] = Field(
         default="info", description="提示框的类型，决定了颜色和图标"
     )
+    """提示框的类型，决定了颜色和图标"""
     title: str = Field(..., description="提示框的标题")
+    """提示框的标题"""
     content: str = Field(..., description="提示框的主要内容")
+    """提示框的主要内容"""
     show_icon: bool = Field(default=True, description="是否显示与类型匹配的图标")
+    """是否显示与类型匹配的图标"""
 
     @property
     def template_name(self) -> str:

zhenxun/ui/models/components/avatar.py

@@ -12,8 +12,11 @@ class Avatar(RenderableComponent):
 
     component_type: Literal["avatar"] = "avatar"
     src: str = Field(..., description="头像的URL或Base64数据URI")
+    """头像的URL或Base64数据URI"""
     shape: Literal["circle", "square"] = Field("circle", description="头像形状")
+    """头像形状"""
     size: int = Field(50, description="头像尺寸（像素）")
+    """头像尺寸（像素）"""
 
     @property
     def template_name(self) -> str:
@@ -25,10 +28,13 @@ class AvatarGroup(RenderableComponent):
 
     component_type: Literal["avatar_group"] = "avatar_group"
     avatars: list[Avatar] = Field(default_factory=list, description="头像列表")
+    """头像列表"""
     spacing: int = Field(-15, description="头像间的间距（负数表示重叠）")
+    """头像间的间距（负数表示重叠）"""
     max_count: int | None = Field(
         None, description="最多显示的头像数量，超出部分会显示为'+N'"
     )
+    """最多显示的头像数量，超出部分会显示为'+N'"""
 
     @property
     def template_name(self) -> str:

zhenxun/ui/models/components/badge.py

@@ -12,10 +12,12 @@ class Badge(RenderableComponent):
 
     component_type: Literal["badge"] = "badge"
     text: str = Field(..., description="徽章上显示的文本")
+    """徽章上显示的文本"""
     color_scheme: Literal["primary", "success", "warning", "error", "info"] = Field(
         default="info",
         description="预设的颜色方案",
     )
+    """预设的颜色方案"""
 
     @property
     def template_name(self) -> str:

zhenxun/ui/models/components/divider.py

@@ -12,9 +12,13 @@ class Divider(RenderableComponent):
 
     component_type: Literal["divider"] = "divider"
     margin: str = Field("2em 0", description="CSS margin属性，控制分割线上下的间距")
+    """CSS margin属性，控制分割线上下的间距"""
     color: str = Field("#f7889c", description="分割线颜色")
+    """分割线颜色"""
     style: Literal["solid", "dashed", "dotted"] = Field("solid", description="线条样式")
+    """线条样式"""
     thickness: str = Field("1px", description="线条粗细")
+    """线条粗细"""
 
     @property
     def template_name(self) -> str:
@@ -26,9 +30,13 @@ class Rectangle(RenderableComponent):
 
     component_type: Literal["rectangle"] = "rectangle"
     height: str = Field("50px", description="矩形的高度 (CSS value)")
+    """矩形的高度 (CSS value)"""
     background_color: str = Field("#fdf1f5", description="背景颜色")
+    """背景颜色"""
     border: str = Field("1px solid #fce4ec", description="CSS border属性")
+    """CSS border属性"""
     border_radius: str = Field("8px", description="CSS border-radius属性")
+    """CSS border-radius属性"""
 
     @property
     def template_name(self) -> str:

zhenxun/ui/models/components/kpi_card.py

@@ -12,17 +12,23 @@ class KpiCard(RenderableComponent):
 
     component_type: Literal["kpi_card"] = "kpi_card"
     label: str = Field(..., description="指标的标签或名称")
+    """指标的标签或名称"""
     value: Any = Field(..., description="指标的主要数值")
+    """指标的主要数值"""
     unit: str | None = Field(default=None, description="数值的单位，可选")
+    """数值的单位，可选"""
     change: str | None = Field(
         default=None, description="与上一周期的变化，例如 '+15%' 或 '-100'"
     )
+    """与上一周期的变化，例如 '+15%' 或 '-100'"""
     change_type: Literal["positive", "negative", "neutral"] = Field(
         default="neutral", description="变化的类型，用于决定颜色"
     )
+    """变化的类型，用于决定颜色"""
     icon_svg: str | None = Field(
         default=None, description="卡片中显示的可选图标 (SVG path data)"
     )
+    """卡片中显示的可选图标 (SVG path data)"""
 
     @property
     def template_name(self) -> str:

zhenxun/ui/models/components/progress_bar.py

@@ -12,12 +12,16 @@ class ProgressBar(RenderableComponent):
 
     component_type: Literal["progress_bar"] = "progress_bar"
     progress: float = Field(..., ge=0, le=100, description="进度百分比 (0-100)")
+    """进度百分比 (0-100)"""
     label: str | None = Field(default=None, description="显示在进度条上的可选文本")
+    """显示在进度条上的可选文本"""
     color_scheme: Literal["primary", "success", "warning", "error", "info"] = Field(
         default="primary",
         description="预设的颜色方案",
     )
+    """预设的颜色方案"""
     animated: bool = Field(default=False, description="是否显示动画效果")
+    """是否显示动画效果"""
 
     @property
     def template_name(self) -> str:

zhenxun/ui/models/components/timeline.py

@@ -11,10 +11,15 @@ class TimelineItem(BaseModel):
     """时间轴中的单个事件点。"""
 
     timestamp: str = Field(..., description="显示在时间点旁边的时间或标签")
+    """显示在时间点旁边的时间或标签"""
     title: str = Field(..., description="事件的标题")
+    """事件的标题"""
     content: str = Field(..., description="事件的详细描述")
+    """事件的详细描述"""
     icon: str | None = Field(default=None, description="可选的自定义图标SVG路径")
+    """可选的自定义图标SVG路径"""
     color: str | None = Field(default=None, description="可选的自定义颜色，覆盖默认")
+    """可选的自定义颜色，覆盖默认"""
 
 
 class Timeline(RenderableComponent):
@@ -24,6 +29,7 @@ class Timeline(RenderableComponent):
     items: list[TimelineItem] = Field(
         default_factory=list, description="时间轴项目列表"
     )
+    """时间轴项目列表"""
 
     @property
     def template_name(self) -> str:

zhenxun/ui/models/components/user_info_block.py

@@ -12,11 +12,15 @@ class UserInfoBlock(RenderableComponent):
 
     component_type: Literal["user_info_block"] = "user_info_block"
     avatar_url: str = Field(..., description="用户头像的URL")
+    """用户头像的URL"""
     name: str = Field(..., description="用户的名称")
+    """用户的名称"""
     subtitle: str | None = Field(
         default=None, description="显示在名称下方的副标题 (如UID或角色)"
     )
+    """显示在名称下方的副标题 (如UID或角色)"""
     tags: list[str] = Field(default_factory=list, description="附加的标签列表")
+    """附加的标签列表"""
 
     @property
     def template_name(self) -> str: