docs(gateway): 补齐任务/查询接口的 docstring 与请求响应字段描述

orders.py / queries.py 各接口补响应状态码（6001/6002/6003/6005/6006）、查询
单两种 kind（order_list / order_detail）结果结构、窗口未覆盖/体积上限等边界
说明；models.py 给 Pydantic 请求/响应模型补 Field 描述并与 Query 参数文档对齐。
纯文档与元数据改动，不含逻辑变更；gateway 相关测试全绿。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

app/gateway/models.py

@@ -23,17 +23,40 @@ class SubmitOrderRequest(BaseModel):
     不新建任务，返回既有任务且 created=false。
     """
 
-    task_id: str | None = None
-    site: str
-    intent: dict[str, Any]
+    task_id: str | None = Field(
+        default=None,
+        description="幂等键。不传则服务端生成；同一 task_id 重复提交不新建任务，"
+        "返回既有任务（created=false）——上游重发不会变成两单",
+        examples=["po-20260727-0001"],
+    )
+    site: str = Field(
+        description="站点标识。交易服务只覆盖乐天市场，固定 rakuten",
+        examples=["rakuten"],
+    )
+    intent: dict[str, Any] = Field(
+        description=(
+            "下单意图原文。网关不解释内容，原样存库并透传给本地 worker，结构由 trading 侧定义："
+            "item_url（必填，商品页 URL）；quantity（可选，默认 1）；"
+            "variant_id（多规格商品必填，取自 /api/item_detail 的 variants，不传时 worker 自动选第一个非售罄规格）；"
+            "choice（可选，商品选项，如 \"颜色:赤\"，可传字符串或字符串列表）；"
+            "max_total_yen（可选，本次金额上限：确认页实际应付超过即中止并报 needs_human，"
+            "缺省用服务端 RAKUTEN_ORDER_MAX_TOTAL_YEN）"
+        ),
+        examples=[{
+            "item_url": "https://item.rakuten.co.jp/shop/code/",
+            "quantity": 1,
+            "variant_id": "1001",
+            "max_total_yen": 30000,
+        }],
+    )
 
 
 class SubmitOrderData(BaseModel):
     """提交响应"""
 
-    task_id: str
-    status: TaskStatus
-    created: bool  # True=本次新建，False=命中既有任务（幂等）
+    task_id: str = Field(description="任务 ID（幂等键），后续查询与 worker 回报都用它")
+    status: TaskStatus = Field(description="任务状态，新建恒为 queued")
+    created: bool = Field(description="True=本次新建，False=命中既有任务（幂等重发）")
 
 
 # ---- GET /api/orders/lease ----
@@ -46,12 +69,20 @@ class LeaseData(BaseModel):
     领取（stale → reclaim），worker 必须先核对站点订单列表，见 runner 主循环。
     """
 
-    task_id: str
-    site: str
-    intent: dict[str, Any]
-    lease_expires_at: str  # ISO8601 UTC
-    lease_count: int
-    known_state: OrderState | None  # 之前上报过的最新订单状态；首次领取为 null
+    task_id: str = Field(description="任务 ID（幂等键）")
+    site: str = Field(description="站点标识（rakuten）")
+    intent: dict[str, Any] = Field(description="下单意图原文，与提交时一致")
+    lease_expires_at: str = Field(
+        description="租约过期时间（ISO8601 UTC）。TTL 由 RAKUTEN_LEASE_TTL_SECONDS 控制"
+        "（默认 300 秒）；执行中每 60 秒调 renew 续租"
+    )
+    lease_count: int = Field(
+        description="该任务被领取过的次数。>1 表示恢复领取（stale → reclaim）：worker 执行前"
+        "必须先核对站点订单列表确认这单下没下，核对不出结论报 needs_human，绝不直接重新下单"
+    )
+    known_state: OrderState | None = Field(
+        description="之前上报过的最新订单状态；首次领取为 null。恢复领取时是核对的重要线索"
+    )
 
 
 # ---- POST /api/orders/{id}/renew ----
@@ -60,15 +91,15 @@ class LeaseData(BaseModel):
 class RenewRequest(BaseModel):
     """续租请求"""
 
-    worker_id: str
+    worker_id: str = Field(description="worker 标识，必须是当前租约持有者，否则 6002")
 
 
 class RenewData(BaseModel):
     """续租响应"""
 
-    task_id: str
-    lease_expires_at: str
-    lease_count: int
+    task_id: str = Field(description="任务 ID")
+    lease_expires_at: str = Field(description="续租后的新过期时间（ISO8601 UTC）")
+    lease_count: int = Field(description="领取次数，续租不改变")
 
 
 # ---- POST /api/orders/{id}/report ----
@@ -81,23 +112,39 @@ class ReportRequest(BaseModel):
     不产生第二条记录。terminal=true 时释放租约并把任务推到终态。
     """
 
-    worker_id: str
-    state: OrderState
-    payable_yen: int | None = None
-    pay_deadline: str | None = None  # ISO8601
-    site_order_id: str | None = None
-    evidence_ref: str | None = None  # 本地相对路径，不含扩展名
-    detail: str = ""
-    terminal: bool = False
-    terminal_status: TaskStatus | None = None  # terminal=true 时指定终态，缺省按 state 推断
+    worker_id: str = Field(description="worker 标识，必须是当前租约持有者，否则 6002")
+    state: OrderState = Field(
+        description="本次上报的订单状态：created / in_cart / ordered / awaiting_payment / "
+        "paid / shipped / delivered / cancelled"
+    )
+    payable_yen: int | None = Field(default=None, description="实际应付金额（日元），进入确认页后上报")
+    pay_deadline: str | None = Field(default=None, description="付款期限（ISO8601），コンビニ払い 常见三天")
+    site_order_id: str | None = Field(default=None, description="站点侧订单号（注文番号），下单成功后上报")
+    evidence_ref: str | None = Field(
+        default=None,
+        description="本地证据相对路径，如 po-20260727-0001/03-order-confirm（不含扩展名）。"
+        "证据原文（HTML/截图）留在本地，不回传",
+    )
+    detail: str = Field(default="", description="补充说明，如付款方式与单号、失败原因")
+    terminal: bool = Field(
+        default=False,
+        description="True 表示任务到此结束：释放租约并推到终态。缺省按 state 推断终态："
+        "paid→succeeded，cancelled→failed，其余（如 awaiting_payment 搁置）→needs_human",
+    )
+    terminal_status: TaskStatus | None = Field(
+        default=None,
+        description="terminal=true 时显式指定终态（succeeded / failed / needs_human），缺省按 state 推断",
+    )
 
 
 class ReportData(BaseModel):
     """回报响应"""
 
-    task_id: str
-    status: TaskStatus
-    recorded: bool  # False=同 (task_id, state) 已存在，本次为幂等覆盖；True=新写入
+    task_id: str = Field(description="任务 ID")
+    status: TaskStatus = Field(description="回报后的任务状态")
+    recorded: bool = Field(
+        description="True=新写入一条状态记录；False=同 (task_id, state) 已存在，本次为幂等覆盖"
+    )
 
 
 # ---- POST /api/orders/{id}/reclaim ----
@@ -106,58 +153,66 @@ class ReportData(BaseModel):
 class ReclaimRequest(BaseModel):
     """把 stale 任务重新租给 worker"""
 
-    worker_id: str
+    worker_id: str = Field(
+        description="worker 标识。reclaim 是显式恢复动作——正常 lease 永远拿不到 stale 任务"
+    )
 
 
 class ReclaimData(BaseModel):
     """reclaim 响应，结构与 LeaseData 一致，但 lease_count 必然 > 1"""
 
-    task_id: str
-    site: str
-    intent: dict[str, Any]
-    lease_expires_at: str
-    lease_count: int
-    known_state: OrderState | None
+    task_id: str = Field(description="任务 ID（幂等键）")
+    site: str = Field(description="站点标识（rakuten）")
+    intent: dict[str, Any] = Field(description="下单意图原文，与提交时一致")
+    lease_expires_at: str = Field(description="新租约的过期时间（ISO8601 UTC）")
+    lease_count: int = Field(
+        description="必然 > 1：worker 执行前必须先核对站点订单列表，确认这单到底下没下"
+    )
+    known_state: OrderState | None = Field(
+        description="租约丢失前上报过的最新订单状态，恢复核对时的重要线索"
+    )
 
 
 # ---- GET /api/orders/{id} 与 GET /api/orders ----
 
 
 class ReportEntry(BaseModel):
-    """task_reports 单行"""
+    """task_reports 单行：一次状态上报（append-only，最新一条即当前状态）"""
 
-    state: OrderState
-    payable_yen: int | None = None
-    pay_deadline: str | None = None
-    site_order_id: str | None = None
-    evidence_ref: str | None = None
-    detail: str = ""
-    reported_at: str
+    state: OrderState = Field(description="上报的订单状态")
+    payable_yen: int | None = Field(default=None, description="实际应付金额（日元）")
+    pay_deadline: str | None = Field(default=None, description="付款期限（ISO8601）")
+    site_order_id: str | None = Field(default=None, description="站点侧订单号（注文番号）")
+    evidence_ref: str | None = Field(default=None, description="本地证据相对路径（不含扩展名）")
+    detail: str = Field(default="", description="补充说明")
+    reported_at: str = Field(description="上报时间（ISO8601 UTC）")
 
 
 class TaskDetail(BaseModel):
     """单个任务详情"""
 
-    task_id: str
-    site: str
-    intent: dict[str, Any]
-    status: TaskStatus
-    lease_owner: str | None = None
-    lease_expires_at: str | None = None
-    lease_count: int = 0
-    created_at: str
-    updated_at: str
-    latest_state: OrderState | None = None
-    reports: list[ReportEntry] = Field(default_factory=list)
+    task_id: str = Field(description="任务 ID（幂等键）")
+    site: str = Field(description="站点标识（rakuten）")
+    intent: dict[str, Any] = Field(description="下单意图原文")
+    status: TaskStatus = Field(
+        description="任务状态：queued / leased / running / succeeded / failed / needs_human / stale"
+    )
+    lease_owner: str | None = Field(default=None, description="当前租约持有者（worker_id）；无租约为 null")
+    lease_expires_at: str | None = Field(default=None, description="租约过期时间（ISO8601 UTC）；无租约为 null")
+    lease_count: int = Field(default=0, description="被领取过的次数，>1 即发生过恢复")
+    created_at: str = Field(description="创建时间（ISO8601 UTC）")
+    updated_at: str = Field(description="最近更新时间（ISO8601 UTC）")
+    latest_state: OrderState | None = Field(default=None, description="最新一次上报的订单状态；从未上报为 null")
+    reports: list[ReportEntry] = Field(default_factory=list, description="完整状态历史（append-only）")
 
 
 class TaskListData(BaseModel):
     """任务列表"""
 
-    items: list[TaskDetail]
-    total: int
-    limit: int
-    offset: int
+    items: list[TaskDetail] = Field(description="任务详情列表，按创建时间倒序")
+    total: int = Field(description="符合筛选条件的总条数")
+    limit: int = Field(description="本次分页大小")
+    offset: int = Field(description="本次分页偏移")
 
 
 # ---- 账号只读查询通道（见 docs/order-gateway.md §11）----
@@ -172,18 +227,34 @@ class SubmitQueryRequest(BaseModel):
     - order_detail：`{"order_number": "306087-20260813-0863947697"}`
     """
 
-    query_id: str | None = None
-    site: str = "rakuten"
-    kind: AccountQueryKind
-    params: dict[str, Any] = Field(default_factory=dict)
+    query_id: str | None = Field(
+        default=None,
+        description="幂等键。不传则服务端生成；同一 query_id 重复提交返回既有单（created=false）",
+        examples=["aq-20260816-0001"],
+    )
+    site: str = Field(default="rakuten", description="站点标识，固定 rakuten")
+    kind: AccountQueryKind = Field(
+        description="查询类型：order_list=按时间窗口翻页扫描订单列表；"
+        "order_detail=读单笔注文番号的详情（配送阶段等）"
+    )
+    params: dict[str, Any] = Field(
+        default_factory=dict,
+        description=(
+            "查询参数，网关原样透传给 worker。order_list：since（可选，ISO8601 窗口下界，"
+            "缺省不设下界）、max_pages（可选，1..20，缺省用服务端 "
+            "RAKUTEN_ACCOUNT_QUERY_DEFAULT_MAX_PAGES=3）；"
+            "order_detail：order_number（必填，站点注文番号）"
+        ),
+        examples=[{"order_number": "306087-20260813-0863947697"}],
+    )
 
 
 class SubmitQueryData(BaseModel):
     """提交响应。纯异步：这里只拿到单号，结果去 GET /api/account/queries/{id} 取"""
 
-    query_id: str
-    status: QueryStatus
-    created: bool  # True=本次新建，False=命中既有单（幂等）
+    query_id: str = Field(description="查询单 ID（幂等键），取结果时用它")
+    status: QueryStatus = Field(description="查询单状态，新建恒为 queued")
+    created: bool = Field(description="True=本次新建，False=命中既有单（幂等重发）")
 
 
 class QueryLeaseData(BaseModel):
@@ -194,12 +265,15 @@ class QueryLeaseData(BaseModel):
     不需要为此改变行为（只读，重跑安全）。
     """
 
-    query_id: str
-    site: str
-    kind: AccountQueryKind
-    params: dict[str, Any]
-    lease_expires_at: str  # ISO8601 UTC
-    attempt: int
+    query_id: str = Field(description="查询单 ID")
+    site: str = Field(description="站点标识（rakuten）")
+    kind: AccountQueryKind = Field(description="查询类型（order_list / order_detail）")
+    params: dict[str, Any] = Field(description="查询参数原文，与提交时一致")
+    lease_expires_at: str = Field(
+        description="租约过期时间（ISO8601 UTC）。TTL 由 RAKUTEN_QUERY_LEASE_TTL_SECONDS 控制"
+        "（默认 180 秒），过期自动重投"
+    )
+    attempt: int = Field(description="第几次被领取。>1 表示上一轮超时被重投（只读，重跑安全）")
 
 
 class QueryResultRequest(BaseModel):
@@ -209,25 +283,31 @@ class QueryResultRequest(BaseModel):
     （沿用 shared.errors 的错误码，便于上游按同一张表分支）。
     """
 
-    worker_id: str
-    success: bool
-    result: dict[str, Any] | None = None
-    error_code: int | None = None
-    error_message: str = ""
+    worker_id: str = Field(description="worker 标识，必须是当前租约持有者，否则 6006")
+    success: bool = Field(description="站点读取是否成功")
+    result: dict[str, Any] | None = Field(
+        default=None,
+        description="success=true 时必填：规范化字段 + 站点原始 JSON，结构按 kind 见 "
+        "GET /api/account/queries/{id} 的说明。体积上限 RAKUTEN_QUERY_RESULT_MAX_BYTES（默认 1MB）",
+    )
+    error_code: int | None = Field(
+        default=None, description="success=false 时的错误码，沿用统一错误码表（如 5001 掉登录）"
+    )
+    error_message: str = Field(default="", description="success=false 时必填，失败原因")
 
 
 class QueryResultData(BaseModel):
     """回报响应"""
 
-    query_id: str
-    status: QueryStatus
+    query_id: str = Field(description="查询单 ID")
+    status: QueryStatus = Field(description="回报后的查询单状态（succeeded / failed）")
 
 
 class QueryError(BaseModel):
     """查询失败的原因"""
 
-    code: int | None = None
-    message: str = ""
+    code: int | None = Field(default=None, description="错误码（沿用统一错误码表），可能为 null")
+    message: str = Field(default="", description="失败原因")
 
 
 class QueryDetail(BaseModel):
@@ -236,28 +316,34 @@ class QueryDetail(BaseModel):
     result 是 worker 回的原文（站点原始 JSON + 规范化字段），网关不解释内容。
     """
 
-    query_id: str
-    site: str
-    kind: AccountQueryKind
-    params: dict[str, Any]
-    status: QueryStatus
-    lease_owner: str | None = None
-    lease_expires_at: str | None = None
-    attempts: int = 0
-    created_at: str
-    updated_at: str
-    completed_at: str | None = None
-    result: dict[str, Any] | None = None
-    error: QueryError | None = None
+    query_id: str = Field(description="查询单 ID（幂等键）")
+    site: str = Field(description="站点标识（rakuten）")
+    kind: AccountQueryKind = Field(description="查询类型（order_list / order_detail）")
+    params: dict[str, Any] = Field(description="查询参数原文")
+    status: QueryStatus = Field(
+        description="查询单状态：queued / leased / succeeded / failed / expired"
+    )
+    lease_owner: str | None = Field(default=None, description="当前租约持有者（worker_id）；无租约为 null")
+    lease_expires_at: str | None = Field(default=None, description="租约过期时间（ISO8601 UTC）；无租约为 null")
+    attempts: int = Field(default=0, description="已被领取的次数，用尽（默认 3 次）置 failed")
+    created_at: str = Field(description="创建时间（ISO8601 UTC）")
+    updated_at: str = Field(description="最近更新时间（ISO8601 UTC）")
+    completed_at: str | None = Field(default=None, description="到达终态的时间（ISO8601 UTC）；未终结为 null")
+    result: dict[str, Any] | None = Field(
+        default=None,
+        description="status=succeeded 时的结果：规范化字段 + 站点原始 JSON，结构按 kind "
+        "见接口说明；未成功为 null",
+    )
+    error: QueryError | None = Field(default=None, description="status=failed/expired 时的失败原因；否则为 null")
 
 
 class QueryListData(BaseModel):
     """查询单列表（运维排查用）"""
 
-    items: list[QueryDetail]
-    total: int
-    limit: int
-    offset: int
+    items: list[QueryDetail] = Field(description="查询单详情列表，按创建时间倒序")
+    total: int = Field(description="符合筛选条件的总条数")
+    limit: int = Field(description="本次分页大小")
+    offset: int = Field(description="本次分页偏移")
 
 
 # ---- 定时下派通道：账号订单编目（docs/order-gateway.md §12）----