docs(models): 模型字段行尾注释迁移为 Field(description)，补全 OpenAPI 字段说明

app/gateway/models.py

@@ -380,32 +380,42 @@ class CatalogedOrder(BaseModel):
     已经规范化了的稳定契约字段（见 §12 说明）。
     """
 
-    order_number: str
-    shop_id: str | None = None
-    shop_name: str = ""
-    order_date: str | None = None
-    delivery_status: str | None = None
-    order_state: str | None = None
-    discovered_at: str
-    detail_fetched_at: str | None = None
-    last_seen_at: str
+    order_number: str = Field(description="站点注文番号，编目与下单任务表对账的天然键")
+    shop_id: str | None = Field(default=None, description="店铺 ID；列表扫描未给出为 null")
+    shop_name: str = Field(default="", description="店铺名（站点原文）")
+    order_date: str | None = Field(default=None, description="下单日期（站点原文）；列表扫描未给出为 null")
+    delivery_status: str | None = Field(
+        default=None,
+        description="站点配送阶段的结构化枚举码（如 CHECKING_ORDER），原样带给上游对账；"
+        "未识别时为 null 或 stepper 兜底文本",
+    )
+    order_state: str | None = Field(
+        default=None, description="worker 规范化上报的订单状态（OrderState 词汇表）；映射不到为 null"
+    )
+    discovered_at: str = Field(description="首次编目时间（ISO8601 UTC）")
+    detail_fetched_at: str | None = Field(
+        default=None, description="最近一次取到订单详情的时间（ISO8601 UTC）；从未取过为 null"
+    )
+    last_seen_at: str = Field(description="最近一次列表扫描见到该订单的时间（ISO8601 UTC）")
 
 
 class CatalogOrderListData(BaseModel):
     """编目订单列表（GET /api/account/orders）"""
 
-    items: list[CatalogedOrder]
-    total: int
-    limit: int
-    offset: int
+    items: list[CatalogedOrder] = Field(description="编目订单列表，按最近出现（last_seen_at）倒序")
+    total: int = Field(description="符合筛选条件的总条数")
+    limit: int = Field(description="本次分页大小")
+    offset: int = Field(description="本次分页偏移")
 
 
 class TriggerDiscoveryData(BaseModel):
     """手动触发一轮下派的响应"""
 
-    query_id: str  # 本轮 order_list 下派的单号
-    status: QueryStatus
-    created: bool  # 本轮扫描是否新建了一张 order_list 单（False=已有一张在飞/已入队）
+    query_id: str = Field(description="本轮 order_list 下派的查询单号")
+    status: QueryStatus = Field(description="该查询单当前状态")
+    created: bool = Field(
+        description="本轮扫描是否新建了一张 order_list 单（False=已有一张在飞/已入队）"
+    )
 
 
 # ---- GET /health ----
@@ -414,18 +424,18 @@ class TriggerDiscoveryData(BaseModel):
 class WorkerHealthEntry(BaseModel):
     """单个 worker 的健康指标"""
 
-    worker_id: str
-    last_seen_at: str
-    last_seen_seconds: int
+    worker_id: str = Field(description="worker 标识")
+    last_seen_at: str = Field(description="最近一次心跳时间（ISO8601 UTC）")
+    last_seen_seconds: int = Field(description="距上次心跳的秒数，超过 300 秒（5 分钟）判失联")
 
 
 class QueuedAlertEntry(BaseModel):
     """长时间无人领的任务告警项"""
 
-    task_id: str
-    site: str
-    created_at: str
-    age_seconds: int
+    task_id: str = Field(description="任务 ID")
+    site: str = Field(description="站点标识（rakuten）")
+    created_at: str = Field(description="任务创建时间（ISO8601 UTC）")
+    age_seconds: int = Field(description="从创建到现在的秒数，超过阈值即视为长时间无人领")
 
 
 class GatewayHealthData(BaseModel):
@@ -435,12 +445,20 @@ class GatewayHealthData(BaseModel):
     不在网关——本地机 7×24 在线，那套逻辑放本地。
     """
 
-    status: str  # "ok" 或 "degraded"
-    queued_count: int
+    status: str = Field(description="整体健康状态：ok=无告警，degraded=有 worker 失联或任务长时间无人领")
+    queued_count: int = Field(description="等待领取的下单任务数量（status=queued）")
     # 等待本地 worker 领取的账号只读查询单数量。查询没有「无人领即告警」这条
     # 规则（它有自己的 TTL 会自动 expired），这里只是给运维一个可见的积压信号。
-    queued_query_count: int = 0
-    active_tasks: list[TaskDetail] = Field(default_factory=list)
-    workers: list[WorkerHealthEntry] = Field(default_factory=list)
-    offline_workers: list[WorkerHealthEntry] = Field(default_factory=list)
-    stale_queued_tasks: list[QueuedAlertEntry] = Field(default_factory=list)
+    queued_query_count: int = Field(default=0, description="等待领取的账号只读查询单数量（积压信号，不参与告警）")
+    active_tasks: list[TaskDetail] = Field(
+        default_factory=list, description="当前 leased/running 的下单任务详情列表"
+    )
+    workers: list[WorkerHealthEntry] = Field(
+        default_factory=list, description="全部已知 worker 的健康指标"
+    )
+    offline_workers: list[WorkerHealthEntry] = Field(
+        default_factory=list, description="失联 worker（距上次心跳超过 300 秒），非空即 degraded"
+    )
+    stale_queued_tasks: list[QueuedAlertEntry] = Field(
+        default_factory=list, description="长时间无人领的 queued 任务告警项，非空即 degraded"
+    )