实现下单任务网关与本地 worker

按 docs/order-gateway.md 落地：第三个部署单元 app.gateway（:31109）承担任务队列
+ 状态镜像；本地 worker 在 app.trading.worker 内，按 RAKUTEN_ORDER_GATEWAY_URL
决定是否启动。规格 §5 最关键约束已守：租约过期绝不自动重投，恢复只能 reclaim，
worker 收到 lease_count>1 时先核对站点订单。

站点交互（加购/下单/付款/订单列表反查）按规格 §10 留接口缝，site_interact.py
全部 NotImplementedError，verify.py 恒返回 unknown——等真实账号实测后再填，
不写猜测的提交逻辑。

310 个测试全绿，覆盖规格 §9 验收清单 12 条；架构测试守住三方互不 import。

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

app/gateway/__init__.py

@@ -0,0 +1,12 @@
+"""下单任务网关：第三个部署单元
+
+抓取服务（app.scraping）匿名、无状态、可多开；交易服务（app.trading）带账号、
+有状态、单实例；本网关是任务队列与状态镜像，部署在服务器侧，**独立于两者**：
+
+- 与抓取服务分进程的原因：抓取实例可以多开，而任务队列有状态，多实例会抢同一批
+  任务（同一账号的写操作必须串行）。
+- 与交易服务分进程的原因：交易在本地（NAT 后无公网入口），网关在服务器，本地
+  通过出站长轮询从这里领任务。
+
+完整规格见 docs/order-gateway.md。
+"""

app/gateway/api/__init__.py

@@ -0,0 +1 @@
+"""网关 API 包"""

app/gateway/api/routes/__init__.py

@@ -0,0 +1 @@
+"""网关路由集合"""

app/gateway/api/routes/health.py

@@ -0,0 +1,23 @@
+"""网关健康检查路由"""
+from fastapi import APIRouter, Depends
+
+from app.gateway.container import GatewayContainer
+from app.gateway.models import GatewayHealthData
+from app.shared.api import ApiResponse, get_container
+
+router = APIRouter(tags=["health"])
+
+
+@router.get("/health", response_model=ApiResponse[GatewayHealthData])
+async def health(
+    container: GatewayContainer = Depends(get_container),
+) -> ApiResponse[GatewayHealthData]:
+    """网关健康状态
+
+    只做规格 §4.7 的两条兜底告警：worker 失联、任务长时间无人领。
+    付款期限监控不在网关——本地机 7×24 在线，那套逻辑放本地。
+    """
+    data = await container.task_queue.health_snapshot()
+    return ApiResponse[GatewayHealthData](
+        success=True, msg="success", data=data, code=0
+    )

app/gateway/api/routes/orders.py

@@ -0,0 +1,181 @@
+"""下单任务网关路由
+
+承担规格 §4 的全部接口：
+
+- POST /api/orders              上游提交下单意图（幂等）
+- GET  /api/orders/lease        本地长轮询领取
+- POST /api/orders/{id}/renew   续租
+- POST /api/orders/{id}/report  本地回报状态
+- POST /api/orders/{id}/reclaim 把 stale 任务重新租给 worker（绝不自动重投）
+- GET  /api/orders/{id}         任务详情 + 完整状态历史
+- GET  /api/orders              任务列表（运维与上游对账）
+
+handler 风格与 app/scraping/api/routes/scrape.py 保持一致：不在 handler 里写
+try/except，业务异常通过 AppError 自动套进 register_exception_handlers。
+"""
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Query
+
+from app.gateway.container import GatewayContainer
+from app.gateway.models import (
+    LeaseData,
+    RenewData,
+    ReclaimData,
+    ReportData,
+    SubmitOrderData,
+    SubmitOrderRequest,
+    TaskDetail,
+    TaskListData,
+    RenewRequest,
+    ReclaimRequest,
+    ReportRequest,
+)
+from app.shared.api import ApiResponse, get_container, require_bearer_token
+
+router = APIRouter(prefix="/api/orders", tags=["orders"])
+
+
+@router.post(
+    "",
+    response_model=ApiResponse[SubmitOrderData],
+    dependencies=[Depends(require_bearer_token)],
+)
+async def submit_order(
+    payload: SubmitOrderRequest,
+    container: GatewayContainer = Depends(get_container),
+) -> ApiResponse[SubmitOrderData]:
+    """上游提交下单意图
+
+    重复提交同一 task_id 不新建任务，返回既有任务且 created=false——上游重发
+    不会变成两单。
+    """
+    data = await container.task_queue.submit(
+        task_id=payload.task_id, site=payload.site, intent=payload.intent
+    )
+    return ApiResponse[SubmitOrderData](
+        success=True, msg="success", data=data, code=0
+    )
+
+
+@router.get(
+    "/lease",
+    response_model=ApiResponse[LeaseData | None],
+    dependencies=[Depends(require_bearer_token)],
+)
+async def lease_order(
+    worker_id: str = Query(...),
+    wait: int = Query(default=30, ge=0, le=300),
+    site: str | None = Query(default=None),
+    container: GatewayContainer = Depends(get_container),
+) -> ApiResponse[LeaseData | None]:
+    """本地长轮询领取
+
+    无可领任务时挂起到 wait 秒后返回 data: null，HTTP 仍 200。已有 leased/running
+    任务时立即返回空（全局并发度 1）。
+    """
+    data = await container.task_queue.lease(
+        worker_id=worker_id,
+        wait=wait,
+        site=site,
+        max_wait=container.settings.lease_max_wait_seconds,
+    )
+    return ApiResponse[LeaseData | None](
+        success=True, msg="success", data=data, code=0
+    )
+
+
+@router.post(
+    "/{task_id}/renew",
+    response_model=ApiResponse[RenewData],
+    dependencies=[Depends(require_bearer_token)],
+)
+async def renew_order(
+    task_id: str,
+    payload: RenewRequest,
+    container: GatewayContainer = Depends(get_container),
+) -> ApiResponse[RenewData]:
+    """续租。worker 在长任务中每 60 秒调一次，避免租约 TTL 误判"""
+    data = await container.task_queue.renew(task_id, payload.worker_id)
+    return ApiResponse[RenewData](success=True, msg="success", data=data, code=0)
+
+
+@router.post(
+    "/{task_id}/report",
+    response_model=ApiResponse[ReportData],
+    dependencies=[Depends(require_bearer_token)],
+)
+async def report_order(
+    task_id: str,
+    payload: ReportRequest,
+    container: GatewayContainer = Depends(get_container),
+) -> ApiResponse[ReportData]:
+    """本地回报订单状态
+
+    同一 (task_id, state) 重复上报幂等。terminal=true 时释放租约并推到终态。
+    """
+    data = await container.task_queue.report(
+        task_id,
+        worker_id=payload.worker_id,
+        state=payload.state,
+        payable_yen=payload.payable_yen,
+        pay_deadline=payload.pay_deadline,
+        site_order_id=payload.site_order_id,
+        evidence_ref=payload.evidence_ref,
+        detail=payload.detail,
+        terminal=payload.terminal,
+        terminal_status=payload.terminal_status.value if payload.terminal_status else None,
+    )
+    return ApiResponse[ReportData](success=True, msg="success", data=data, code=0)
+
+
+@router.post(
+    "/{task_id}/reclaim",
+    response_model=ApiResponse[ReclaimData],
+    dependencies=[Depends(require_bearer_token)],
+)
+async def reclaim_order(
+    task_id: str,
+    payload: ReclaimRequest,
+    container: GatewayContainer = Depends(get_container),
+) -> ApiResponse[ReclaimData]:
+    """把 stale 任务重新租给 worker（恢复领取）
+
+    返回体的 lease_count 必然 > 1，worker 必须先核对站点订单列表再决定是否
+    继续执行——核对不出结论时报 needs_human，绝不重新提交。
+    """
+    data = await container.task_queue.reclaim(task_id, payload.worker_id)
+    return ApiResponse[ReclaimData](success=True, msg="success", data=data, code=0)
+
+
+@router.get(
+    "/{task_id}",
+    response_model=ApiResponse[TaskDetail],
+    dependencies=[Depends(require_bearer_token)],
+)
+async def get_order(
+    task_id: str,
+    container: GatewayContainer = Depends(get_container),
+) -> ApiResponse[TaskDetail]:
+    """任务详情 + 完整状态历史"""
+    data = await container.task_queue.get_task_detail(task_id)
+    return ApiResponse[TaskDetail](success=True, msg="success", data=data, code=0)
+
+
+@router.get(
+    "",
+    response_model=ApiResponse[TaskListData],
+    dependencies=[Depends(require_bearer_token)],
+)
+async def list_orders(
+    status: str | None = Query(default=None),
+    site: str | None = Query(default=None),
+    limit: int = Query(default=50, ge=1, le=500),
+    offset: int = Query(default=0, ge=0),
+    container: GatewayContainer = Depends(get_container),
+) -> ApiResponse[TaskListData]:
+    """任务列表（运维与上游对账用）"""
+    data = await container.task_queue.list_tasks(
+        status=status, site=site, limit=limit, offset=offset
+    )
+    return ApiResponse[TaskListData](success=True, msg="success", data=data, code=0)

app/gateway/container.py

@@ -0,0 +1,29 @@
+"""网关容器：集中管理网关侧服务实例，用于依赖注入"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass
+
+from app.gateway.db import GatewayDB
+from app.gateway.task_queue import TaskQueue
+from app.shared.config import Settings
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(slots=True)
+class GatewayContainer:
+    """网关容器
+
+    与抓取/交易容器同样的依赖注入风格，但持有的是任务队列与 SQLite 连接，
+    生命周期由 main.lifespan 管理：start 时打开 DB，close 时关闭。
+
+    `sweep_task` 是常驻后台扫描，把过期的 leased/running 推到 stale。
+    即使没有 lease 请求，过期的任务也会被及时发现（规格 §5 的关键约束）。
+    """
+
+    settings: Settings
+    db: GatewayDB
+    task_queue: TaskQueue
+    sweep_task: asyncio.Task | None = None

app/gateway/db.py

@@ -0,0 +1,356 @@
+"""网关 SQLite 访问层：三张表 + 原生 SQL，无业务逻辑
+
+业务规则（状态机、并发度、幂等）放在 `task_queue.py`，本模块只负责持久化与查询，
+返回 dataclass 行。所有时间戳以 ISO8601 UTC 字符串存储（以 `Z` 结尾），便于
+跨进程对账；时间戳运算在 task_queue 层完成。
+
+写操作由 task_queue 的 asyncio.Lock 串行化（详见该模块），本层不重复加锁，
+因此**调用方必须确保写操作在外层锁的保护下进行**。
+"""
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import aiosqlite
+
+logger = logging.getLogger(__name__)
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS tasks (
+    task_id          TEXT PRIMARY KEY,
+    site             TEXT NOT NULL,
+    intent_json      TEXT NOT NULL,
+    status           TEXT NOT NULL,
+    lease_owner      TEXT,
+    lease_expires_at TEXT,
+    lease_count      INTEGER NOT NULL DEFAULT 0,
+    created_at       TEXT NOT NULL,
+    updated_at       TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_tasks_pending ON tasks(status, created_at);
+
+CREATE TABLE IF NOT EXISTS task_reports (
+    task_id       TEXT NOT NULL,
+    state         TEXT NOT NULL,
+    payable_yen   INTEGER,
+    pay_deadline  TEXT,
+    site_order_id TEXT,
+    evidence_ref  TEXT,
+    detail        TEXT,
+    reported_at   TEXT NOT NULL,
+    PRIMARY KEY (task_id, state)
+);
+
+CREATE TABLE IF NOT EXISTS workers (
+    worker_id    TEXT PRIMARY KEY,
+    last_seen_at TEXT NOT NULL
+);
+"""
+
+
+@dataclass(slots=True)
+class TaskRow:
+    """tasks 表一行的强类型视图"""
+
+    task_id: str
+    site: str
+    intent_json: str
+    status: str
+    lease_owner: str | None
+    lease_expires_at: str | None
+    lease_count: int
+    created_at: str
+    updated_at: str
+
+    @property
+    def intent(self) -> dict[str, Any]:
+        return json.loads(self.intent_json)
+
+
+@dataclass(slots=True)
+class ReportRow:
+    """task_reports 表一行的强类型视图"""
+
+    task_id: str
+    state: str
+    payable_yen: int | None
+    pay_deadline: str | None
+    site_order_id: str | None
+    evidence_ref: str | None
+    detail: str
+    reported_at: str
+
+
+@dataclass(slots=True)
+class WorkerRow:
+    """workers 表一行的强类型视图"""
+
+    worker_id: str
+    last_seen_at: str
+
+
+def _row_to_task(row: aiosqlite.Row) -> TaskRow:
+    return TaskRow(
+        task_id=row["task_id"],
+        site=row["site"],
+        intent_json=row["intent_json"],
+        status=row["status"],
+        lease_owner=row["lease_owner"],
+        lease_expires_at=row["lease_expires_at"],
+        lease_count=row["lease_count"],
+        created_at=row["created_at"],
+        updated_at=row["updated_at"],
+    )
+
+
+def _row_to_report(row: aiosqlite.Row) -> ReportRow:
+    return ReportRow(
+        task_id=row["task_id"],
+        state=row["state"],
+        payable_yen=row["payable_yen"],
+        pay_deadline=row["pay_deadline"],
+        site_order_id=row["site_order_id"],
+        evidence_ref=row["evidence_ref"],
+        detail=row["detail"],
+        reported_at=row["reported_at"],
+    )
+
+
+def _row_to_worker(row: aiosqlite.Row) -> WorkerRow:
+    return WorkerRow(worker_id=row["worker_id"], last_seen_at=row["last_seen_at"])
+
+
+class GatewayDB:
+    """网关 SQLite 访问对象
+
+    单连接 + aiosqlite 的内部线程。生命周期由 `GatewayContainer` 管理：
+    `start()` 在 lifespan 启动时调用，`close()` 在关闭时调用。
+    """
+
+    def __init__(self, db_path: Path):
+        self._db_path = db_path
+        self._conn: aiosqlite.Connection | None = None
+
+    async def start(self) -> None:
+        """打开连接并初始化 schema（IF NOT EXISTS，可重复执行）"""
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn = await aiosqlite.connect(str(self._db_path))
+        self._conn.row_factory = aiosqlite.Row
+        await self._conn.executescript(SCHEMA)
+        await self._conn.commit()
+        logger.info("网关 DB 已就绪：%s", self._db_path)
+
+    async def close(self) -> None:
+        if self._conn is not None:
+            await self._conn.close()
+            self._conn = None
+
+    @property
+    def conn(self) -> aiosqlite.Connection:
+        if self._conn is None:
+            raise RuntimeError("GatewayDB 未启动：先调用 start()")
+        return self._conn
+
+    # ---- tasks ----
+
+    async def get_task(self, task_id: str) -> TaskRow | None:
+        async with self.conn.execute("SELECT * FROM tasks WHERE task_id = ?", (task_id,)) as cur:
+            row = await cur.fetchone()
+            return _row_to_task(row) if row else None
+
+    async def insert_task(self, row: TaskRow) -> bool:
+        """插入新任务。返回 True=新建，False=task_id 已存在（幂等命中）"""
+        try:
+            await self.conn.execute(
+                "INSERT INTO tasks (task_id, site, intent_json, status, "
+                "lease_owner, lease_expires_at, lease_count, created_at, updated_at) "
+                "VALUES (?, ?, ?, ?, NULL, NULL, 0, ?, ?)",
+                (
+                    row.task_id,
+                    row.site,
+                    row.intent_json,
+                    row.status,
+                    row.created_at,
+                    row.updated_at,
+                ),
+            )
+            await self.conn.commit()
+            return True
+        except aiosqlite.IntegrityError:
+            return False
+
+    async def update_task(
+        self,
+        task_id: str,
+        *,
+        status: str | None = None,
+        lease_owner: str | None = None,
+        lease_expires_at: str | None = None,
+        lease_count: int | None = None,
+        updated_at: str | None = None,
+        clear_lease: bool = False,
+    ) -> None:
+        """更新任务字段。clear_lease=True 时把 lease_owner/expires_at 置 NULL"""
+        sets: list[str] = []
+        params: list[Any] = []
+        if status is not None:
+            sets.append("status = ?")
+            params.append(status)
+        if lease_owner is not None:
+            sets.append("lease_owner = ?")
+            params.append(lease_owner)
+        if lease_expires_at is not None:
+            sets.append("lease_expires_at = ?")
+            params.append(lease_expires_at)
+        if lease_count is not None:
+            sets.append("lease_count = ?")
+            params.append(lease_count)
+        if updated_at is not None:
+            sets.append("updated_at = ?")
+            params.append(updated_at)
+        if clear_lease:
+            sets.append("lease_owner = NULL")
+            sets.append("lease_expires_at = NULL")
+        if not sets:
+            return
+        params.append(task_id)
+        await self.conn.execute(
+            f"UPDATE tasks SET {', '.join(sets)} WHERE task_id = ?",
+            params,
+        )
+        await self.conn.commit()
+
+    async def list_tasks(
+        self,
+        *,
+        status: str | None = None,
+        site: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> tuple[list[TaskRow], int]:
+        """分页列出任务，按 created_at 升序"""
+        where = []
+        params: list[Any] = []
+        if status:
+            where.append("status = ?")
+            params.append(status)
+        if site:
+            where.append("site = ?")
+            params.append(site)
+        clause = f"WHERE {' AND '.join(where)}" if where else ""
+
+        async with self.conn.execute(
+            f"SELECT COUNT(*) FROM tasks {clause}",
+            params,
+        ) as cur:
+            total = (await cur.fetchone())[0]
+
+        sql = f"SELECT * FROM tasks {clause} ORDER BY created_at ASC LIMIT ? OFFSET ?"
+        async with self.conn.execute(sql, [*params, limit, offset]) as cur:
+            rows = await cur.fetchall()
+        return [_row_to_task(r) for r in rows], total
+
+    async def list_tasks_in_statuses(self, statuses: tuple[str, ...]) -> list[TaskRow]:
+        """取处于给定状态集合的全部任务（不分页，用于健康检查的 active 列表）"""
+        if not statuses:
+            return []
+        placeholders = ", ".join("?" for _ in statuses)
+        sql = (
+            f"SELECT * FROM tasks WHERE status IN ({placeholders}) "
+            "ORDER BY created_at ASC"
+        )
+        async with self.conn.execute(sql, statuses) as cur:
+            rows = await cur.fetchall()
+        return [_row_to_task(r) for r in rows]
+
+    async def pick_queued_task(self, site: str | None) -> TaskRow | None:
+        """取最早的 queued 任务，可选按站点过滤"""
+        if site:
+            sql = "SELECT * FROM tasks WHERE status = ? AND site = ? ORDER BY created_at ASC LIMIT 1"
+            params: tuple[Any, ...] = ("queued", site)
+        else:
+            sql = "SELECT * FROM tasks WHERE status = ? ORDER BY created_at ASC LIMIT 1"
+            params = ("queued",)
+        async with self.conn.execute(sql, params) as cur:
+            row = await cur.fetchone()
+            return _row_to_task(row) if row else None
+
+    # ---- task_reports ----
+
+    async def upsert_report(self, row: ReportRow) -> bool:
+        """写入一条 report。同一 (task_id, state) 已存在则覆盖（幂等）。
+
+        返回 True=本次新写入，False=覆盖了既有行。
+
+        先 SELECT 再 INSERT OR REPLACE，避免依赖 SQLite rowcount——后者在
+        INSERT OR REPLACE 上即使命中既有行也报 1，无法区分。
+        """
+        async with self.conn.execute(
+            "SELECT 1 FROM task_reports WHERE task_id = ? AND state = ?",
+            (row.task_id, row.state),
+        ) as cur:
+            existed = await cur.fetchone() is not None
+
+        await self.conn.execute(
+            "INSERT OR REPLACE INTO task_reports "
+            "(task_id, state, payable_yen, pay_deadline, site_order_id, "
+            "evidence_ref, detail, reported_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+            (
+                row.task_id,
+                row.state,
+                row.payable_yen,
+                row.pay_deadline,
+                row.site_order_id,
+                row.evidence_ref,
+                row.detail,
+                row.reported_at,
+            ),
+        )
+        await self.conn.commit()
+        return not existed
+
+    async def get_reports(self, task_id: str) -> list[ReportRow]:
+        async with self.conn.execute(
+            "SELECT * FROM task_reports WHERE task_id = ? ORDER BY reported_at ASC",
+            (task_id,),
+        ) as cur:
+            rows = await cur.fetchall()
+        return [_row_to_report(r) for r in rows]
+
+    async def get_latest_state(self, task_id: str) -> str | None:
+        """取该任务最近一次 report 的 state，无 report 返回 None"""
+        async with self.conn.execute(
+            "SELECT state FROM task_reports WHERE task_id = ? "
+            "ORDER BY reported_at DESC LIMIT 1",
+            (task_id,),
+        ) as cur:
+            row = await cur.fetchone()
+            return row["state"] if row else None
+
+    # ---- workers ----
+
+    async def upsert_worker(self, worker_id: str, last_seen_at: str) -> None:
+        await self.conn.execute(
+            "INSERT INTO workers (worker_id, last_seen_at) VALUES (?, ?) "
+            "ON CONFLICT(worker_id) DO UPDATE SET last_seen_at = excluded.last_seen_at",
+            (worker_id, last_seen_at),
+        )
+        await self.conn.commit()
+
+    async def list_workers(self) -> list[WorkerRow]:
+        async with self.conn.execute("SELECT * FROM workers ORDER BY last_seen_at DESC") as cur:
+            rows = await cur.fetchall()
+        return [_row_to_worker(r) for r in rows]
+
+    # ---- 计数 ----
+
+    async def count_by_status(self, status: str) -> int:
+        async with self.conn.execute(
+            "SELECT COUNT(*) FROM tasks WHERE status = ?",
+            (status,),
+        ) as cur:
+            return (await cur.fetchone())[0]

app/gateway/main.py

@@ -0,0 +1,124 @@
+"""下单任务网关入口：FastAPI 应用创建与生命周期管理
+
+部署在服务器侧，与抓取服务（:31107）、交易服务（:31108）并列。本地 worker 通过
+出站长轮询从这里领任务；上游业务系统通过 POST /api/orders 提交下单意图。
+
+为什么必须独立部署单元（不能塞进抓取服务）：抓取无状态可多开，任务队列有状态，
+多实例会抢同一批任务，同一账号的写操作必须串行（详见 docs/order-gateway.md §2）。
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+from app.gateway.api.routes.health import router as health_router
+from app.gateway.api.routes.orders import router as orders_router
+from app.gateway.container import GatewayContainer
+from app.gateway.db import GatewayDB
+from app.gateway.task_queue import TaskQueue
+from app.shared.api import register_exception_handlers
+from app.shared.config import get_settings
+from app.shared.logging_setup import configure_logging
+
+logger = logging.getLogger(__name__)
+
+SWEEP_INTERVAL_SECONDS = 60
+
+
+def build_container() -> GatewayContainer:
+    """构建网关容器：DB + 任务队列"""
+    settings = get_settings()
+    db = GatewayDB(settings.gateway_db_path_resolved)
+    task_queue = TaskQueue(
+        db,
+        lease_ttl_seconds=settings.lease_ttl_seconds,
+        worker_offline_alert_seconds=settings.worker_offline_alert_seconds,
+    )
+    return GatewayContainer(settings=settings, db=db, task_queue=task_queue)
+
+
+async def _sweep_loop(container: GatewayContainer) -> None:
+    """常驻后台任务：每 60 秒扫一次过期租约，把 leased/running 推到 stale
+
+    lease 请求本身也会顺带扫一次，但 worker 退场后没人来 lease，必须靠这个
+    兜底——否则过期的任务永远停在 active 状态，健康检查看不到，stale 任务也
+    取不出来 reclaim。
+    """
+    while True:
+        try:
+            await asyncio.sleep(SWEEP_INTERVAL_SECONDS)
+            swept = await container.task_queue.sweep()
+            if swept:
+                logger.info("sweep 把 %s 个过期任务置为 stale", swept)
+        except asyncio.CancelledError:
+            raise
+        except Exception:  # noqa: BLE001
+            # 后台任务不能因为偶发错误退出，否则过期任务再也无人清理
+            logger.exception("sweep 后台任务出错，将继续重试")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """应用生命周期：启动 DB、起 sweep 后台任务、关闭时反序释放"""
+    container = build_container()
+    app.state.container = container
+
+    configure_logging(container.settings)
+    logger.info(
+        "网关启动：%s:%s", container.settings.gateway_host, container.settings.gateway_port
+    )
+    logger.info("当前环境：%s", container.settings.app_env)
+    logger.info("DB 路径：%s", container.settings.gateway_db_path_resolved)
+
+    await container.db.start()
+    # 启动时先扫一次：上次进程退出时可能留有 leased/running 的过期任务
+    startup_swept = await container.task_queue.sweep()
+    if startup_swept:
+        logger.warning("启动时把 %s 个遗留过期任务置为 stale", startup_swept)
+
+    container.sweep_task = asyncio.create_task(
+        _sweep_loop(container), name="gateway-sweep"
+    )
+
+    try:
+        yield
+    finally:
+        if container.sweep_task is not None:
+            container.sweep_task.cancel()
+            try:
+                await container.sweep_task
+            except asyncio.CancelledError:
+                pass
+            container.sweep_task = None
+        await container.db.close()
+
+
+def create_app() -> FastAPI:
+    """创建 FastAPI 应用实例，注册路由和异常处理器"""
+    app = FastAPI(title="Rakuten Order Gateway", lifespan=lifespan)
+    app.include_router(health_router)
+    app.include_router(orders_router)
+    register_exception_handlers(app)
+    return app
+
+
+app = create_app()
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    settings = get_settings()
+    configure_logging(settings)
+    uvicorn.run(
+        "app.gateway.main:app",
+        host=settings.gateway_host,
+        port=settings.gateway_port,
+        log_config=None,
+        timeout_keep_alive=120,
+        # 单进程：SQLite 单连接 + 全局并发度 1，多进程会抢同一个 DB
+        workers=1,
+    )

app/gateway/models.py

@@ -0,0 +1,194 @@
+"""网关 API 数据模型：请求体与响应体
+
+intent 字段刻意保留成 `dict[str, Any]`——网关不解释下单意图，结构由 trading 侧
+定义。网关只负责把它存下来、原样吐给 worker，避免业务规则悄悄渗进任务队列。
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from app.shared.task_state import OrderState, TaskStatus
+
+
+# ---- POST /api/orders ----
+
+
+class SubmitOrderRequest(BaseModel):
+    """上游提交下单意图
+
+    task_id 可选：上游自带的幂等键。不传则服务端生成。同一个 task_id 重复提交
+    不新建任务，返回既有任务且 created=false。
+    """
+
+    task_id: str | None = None
+    site: str
+    intent: dict[str, Any]
+
+
+class SubmitOrderData(BaseModel):
+    """提交响应"""
+
+    task_id: str
+    status: TaskStatus
+    created: bool  # True=本次新建，False=命中既有任务（幂等）
+
+
+# ---- GET /api/orders/lease ----
+
+
+class LeaseData(BaseModel):
+    """lease 响应
+
+    无任务可领时整个 data 为 null（HTTP 仍 200）。lease_count > 1 表示这是恢复
+    领取（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
+
+
+# ---- POST /api/orders/{id}/renew ----
+
+
+class RenewRequest(BaseModel):
+    """续租请求"""
+
+    worker_id: str
+
+
+class RenewData(BaseModel):
+    """续租响应"""
+
+    task_id: str
+    lease_expires_at: str
+    lease_count: int
+
+
+# ---- POST /api/orders/{id}/report ----
+
+
+class ReportRequest(BaseModel):
+    """本地回报订单状态
+
+    同一 (task_id, state) 重复上报是幂等的——网络抖动导致 worker 重发时覆盖同一行，
+    不产生第二条记录。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 推断
+
+
+class ReportData(BaseModel):
+    """回报响应"""
+
+    task_id: str
+    status: TaskStatus
+    recorded: bool  # False=同 (task_id, state) 已存在，本次为幂等覆盖；True=新写入
+
+
+# ---- POST /api/orders/{id}/reclaim ----
+
+
+class ReclaimRequest(BaseModel):
+    """把 stale 任务重新租给 worker"""
+
+    worker_id: str
+
+
+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
+
+
+# ---- GET /api/orders/{id} 与 GET /api/orders ----
+
+
+class ReportEntry(BaseModel):
+    """task_reports 单行"""
+
+    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
+
+
+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)
+
+
+class TaskListData(BaseModel):
+    """任务列表"""
+
+    items: list[TaskDetail]
+    total: int
+    limit: int
+    offset: int
+
+
+# ---- GET /health ----
+
+
+class WorkerHealthEntry(BaseModel):
+    """单个 worker 的健康指标"""
+
+    worker_id: str
+    last_seen_at: str
+    last_seen_seconds: int
+
+
+class QueuedAlertEntry(BaseModel):
+    """长时间无人领的任务告警项"""
+
+    task_id: str
+    site: str
+    created_at: str
+    age_seconds: int
+
+
+class GatewayHealthData(BaseModel):
+    """网关健康状态
+
+    只做规格 §4.7 的两条兜底告警：worker 失联、任务长时间无人领。付款期限监控
+    不在网关——本地机 7×24 在线，那套逻辑放本地。
+    """
+
+    status: str  # "ok" 或 "degraded"
+    queued_count: int
+    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)

app/gateway/task_queue.py

@@ -0,0 +1,505 @@
+"""任务队列业务逻辑：状态机、租约、并发度、幂等
+
+所有写操作通过 `self._lock` 串行化。该锁同时保护「检查 + 写入」的原子序列
+（如 lease 时「检查是否已有 active 任务 → 取 queued → 改为 leased」），避免两个
+lease 请求并发取到同一个任务。
+
+长轮询通过 `self._cond`（基于同一把锁的 Condition）唤醒：submit / report（terminal）
+/ reclaim 失败等任何可能让「队列前进」的事件都 notify_all。lease 在无可领任务时
+wait_for，超时返回 None。
+
+绝不自动重投（docs/order-gateway.md §5）：sweep 把过期任务置 stale 后**不**回到
+queued，普通 lease 取不到它；恢复只能走 reclaim。
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import secrets
+from datetime import datetime, timedelta, timezone
+
+from app.shared.task_state import (
+    ACTIVE_STATUSES,
+    LEASABLE_STATUSES,
+    RECLAIMABLE_STATUSES,
+    TERMINAL_STATUSES,
+    TaskStatus,
+)
+from app.gateway.db import GatewayDB, ReportRow, TaskRow
+from app.gateway.models import (
+    GatewayHealthData,
+    LeaseData,
+    QueuedAlertEntry,
+    ReportEntry,
+    RenewData,
+    ReclaimData,
+    ReportData,
+    SubmitOrderData,
+    TaskDetail,
+    TaskListData,
+    WorkerHealthEntry,
+)
+from app.shared.errors import (
+    InvalidTaskStateError,
+    LeaseInvalidError,
+    TaskNotFoundError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def to_iso(dt: datetime) -> str:
+    """统一时间戳格式：ISO8601 UTC，秒精度，Z 结尾"""
+    return dt.astimezone(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def parse_iso(s: str) -> datetime:
+    """解析 to_iso 产出的字符串（也兼容带 +00:00 的变体）"""
+    if s.endswith("Z"):
+        s = s[:-1] + "+00:00"
+    return datetime.fromisoformat(s)
+
+
+def _generate_task_id() -> str:
+    """服务端生成的 task_id：日期 + 8 字节随机 hex，避免与上游自带的冲突"""
+    return f"po-{to_iso(utcnow())[:10].replace('-', '')}-{secrets.token_hex(4)}"
+
+
+def _task_to_detail(task: TaskRow, latest_state: str | None, reports: list[ReportEntry]) -> TaskDetail:
+    return TaskDetail(
+        task_id=task.task_id,
+        site=task.site,
+        intent=task.intent,
+        status=TaskStatus(task.status),
+        lease_owner=task.lease_owner,
+        lease_expires_at=task.lease_expires_at,
+        lease_count=task.lease_count,
+        created_at=task.created_at,
+        updated_at=task.updated_at,
+        latest_state=latest_state,
+        reports=reports,
+    )
+
+
+class TaskQueue:
+    """任务队列业务逻辑
+
+    持有一个 GatewayDB 实例。所有写操作与「检查 + 写入」原子序列都在 `self._lock`
+    保护下；长轮询等待通过 `self._cond` 唤醒。
+    """
+
+    def __init__(self, db: GatewayDB, *, lease_ttl_seconds: int, worker_offline_alert_seconds: int):
+        self._db = db
+        self._lease_ttl = lease_ttl_seconds
+        self._worker_offline_alert_seconds = worker_offline_alert_seconds
+        self._lock = asyncio.Lock()
+        self._cond = asyncio.Condition(self._lock)
+
+    # ---- 提交 ----
+
+    async def submit(self, *, task_id: str | None, site: str, intent: dict) -> SubmitOrderData:
+        """上游提交下单意图。task_id 缺省时服务端生成；重复提交幂等"""
+        import json
+
+        tid = task_id or _generate_task_id()
+        now = to_iso(utcnow())
+        row = TaskRow(
+            task_id=tid,
+            site=site,
+            intent_json=json.dumps(intent, ensure_ascii=False),
+            status=TaskStatus.QUEUED.value,
+            lease_owner=None,
+            lease_expires_at=None,
+            lease_count=0,
+            created_at=now,
+            updated_at=now,
+        )
+        async with self._lock:
+            created = await self._db.insert_task(row)
+            if created:
+                self._cond.notify_all()
+            else:
+                existing = await self._db.get_task(tid)
+                # 既不可能创建失败又拿不到既有行：除非被并发删除，按罕见错误处理
+                if existing is None:
+                    raise RuntimeError(f"任务 {tid} 既未新建也无法读取，状态异常")
+                row = existing
+        return SubmitOrderData(task_id=row.task_id, status=TaskStatus(row.status), created=created)
+
+    # ---- 领取 ----
+
+    async def lease(
+        self,
+        *,
+        worker_id: str,
+        wait: int,
+        site: str | None,
+        max_wait: int,
+    ) -> LeaseData | None:
+        """本地长轮询领取
+
+        - 全局并发度 1：已有 leased/running 任务时立即返回 None
+        - 无可领任务时挂起最多 `min(wait, max_wait)` 秒，超时返回 None
+        - 拿到任务时 queued → leased，写入 lease_owner / lease_expires_at / lease_count
+        - 顺带刷新 worker 心跳（last_seen_at），这就是 lease 兼任心跳的设计
+        """
+        effective_wait = max(0, min(wait, max_wait))
+        deadline = utcnow() + timedelta(seconds=effective_wait)
+
+        async with self._lock:
+            # 先把过期租约扫到 stale，避免「卡死的任务」堵住新任务
+            await self._sweep_locked()
+
+            await self._db.upsert_worker(worker_id, to_iso(utcnow()))
+
+            while True:
+                result = await self._try_pick_locked(worker_id, site)
+                if result is not None:
+                    return result
+
+                remaining = (deadline - utcnow()).total_seconds()
+                if remaining <= 0:
+                    return None
+                try:
+                    await asyncio.wait_for(self._cond.wait(), timeout=remaining)
+                except asyncio.TimeoutError:
+                    return None
+
+    async def _try_pick_locked(self, worker_id: str, site: str | None) -> LeaseData | None:
+        """锁内尝试领取一次。返回 None 表示此刻无可领任务"""
+        # 全局并发度 1：已有 leased/running 立即返回空
+        active = await self._db.list_tasks_in_statuses(tuple(s.value for s in ACTIVE_STATUSES))
+        if active:
+            return None
+
+        task = await self._db.pick_queued_task(site)
+        if task is None:
+            return None
+
+        return await self._lease_to_locked(task, worker_id, known_state=None)
+
+    async def _lease_to_locked(
+        self,
+        task: TaskRow,
+        worker_id: str,
+        *,
+        known_state: str | None,
+    ) -> LeaseData:
+        """把一个 queued 或 stale 任务租给 worker。调用方必须持有 self._lock"""
+        expires = to_iso(utcnow() + timedelta(seconds=self._lease_ttl))
+        new_count = task.lease_count + 1
+        await self._db.update_task(
+            task.task_id,
+            status=TaskStatus.LEASED.value,
+            lease_owner=worker_id,
+            lease_expires_at=expires,
+            lease_count=new_count,
+            updated_at=to_iso(utcnow()),
+        )
+        # 已知状态：取最近一次 report 的 state（首次领取为 None）
+        if known_state is None:
+            known_state = await self._db.get_latest_state(task.task_id)
+        return LeaseData(
+            task_id=task.task_id,
+            site=task.site,
+            intent=task.intent,
+            lease_expires_at=expires,
+            lease_count=new_count,
+            known_state=known_state,  # type: ignore[arg-type]
+        )
+
+    # ---- 续租 ----
+
+    async def renew(self, task_id: str, worker_id: str) -> RenewData:
+        async with self._lock:
+            task = await self._db.get_task(task_id)
+            if task is None:
+                raise TaskNotFoundError(task_id)
+            if task.lease_owner != worker_id:
+                raise LeaseInvalidError(f"worker {worker_id} 不是任务 {task_id} 的租约持有者")
+            if TaskStatus(task.status) in TERMINAL_STATUSES:
+                raise LeaseInvalidError(f"任务 {task_id} 已终结，无法续租")
+            if TaskStatus(task.status) not in ACTIVE_STATUSES:
+                raise LeaseInvalidError(f"任务 {task_id} 状态 {task.status}，无可续租约")
+
+            expires = to_iso(utcnow() + timedelta(seconds=self._lease_ttl))
+            await self._db.update_task(
+                task_id,
+                lease_expires_at=expires,
+                updated_at=to_iso(utcnow()),
+            )
+            return RenewData(task_id=task_id, lease_expires_at=expires, lease_count=task.lease_count)
+
+    # ---- 回报 ----
+
+    async def report(
+        self,
+        task_id: str,
+        *,
+        worker_id: str,
+        state: str,
+        payable_yen: int | None,
+        pay_deadline: str | None,
+        site_order_id: str | None,
+        evidence_ref: str | None,
+        detail: str,
+        terminal: bool,
+        terminal_status: str | None,
+    ) -> ReportData:
+        async with self._lock:
+            task = await self._db.get_task(task_id)
+            if task is None:
+                raise TaskNotFoundError(task_id)
+            if task.lease_owner != worker_id:
+                raise LeaseInvalidError(f"worker {worker_id} 不是任务 {task_id} 的租约持有者")
+            status = TaskStatus(task.status)
+
+            if status in TERMINAL_STATUSES:
+                # 任务已终结：仍然追加 report（规格 §6 末尾「任务已 terminal 的仍可上报，
+                # gateway 追加到 task_reports」），但不允许改任务状态
+                if terminal and terminal_status is not None and terminal_status != status.value:
+                    raise InvalidTaskStateError(
+                        f"任务 {task_id} 已是终态 {status.value}，不能改为 {terminal_status}"
+                    )
+            elif status == TaskStatus.LEASED:
+                # 首次 report：leased → running
+                await self._db.update_task(
+                    task_id, status=TaskStatus.RUNNING.value, updated_at=to_iso(utcnow())
+                )
+
+            now = to_iso(utcnow())
+            inserted = await self._db.upsert_report(
+                ReportRow(
+                    task_id=task_id,
+                    state=state,
+                    payable_yen=payable_yen,
+                    pay_deadline=pay_deadline,
+                    site_order_id=site_order_id,
+                    evidence_ref=evidence_ref,
+                    detail=detail,
+                    reported_at=now,
+                )
+            )
+
+            final_status = status.value
+            if terminal:
+                final_status = self._resolve_terminal_status(
+                    current=status, explicit=terminal_status, state=state
+                )
+                await self._db.update_task(
+                    task_id,
+                    status=final_status,
+                    clear_lease=True,
+                    updated_at=now,
+                )
+                # 任务终结可能让并发度 1 的闸门放开，唤醒等着的 lease
+                self._cond.notify_all()
+
+            return ReportData(task_id=task_id, status=TaskStatus(final_status), recorded=inserted)
+
+    @staticmethod
+    def _resolve_terminal_status(
+        *, current: TaskStatus, explicit: str | None, state: str
+    ) -> str:
+        """terminal=true 时决定任务的终态。
+
+        显式指定优先；否则按订单 state 推断：paid → succeeded，cancelled → failed，
+        其余（如 awaiting_payment 永久搁置）→ needs_human。
+
+        注意 cancelled 既可能来自明确失败，也可能是站点侧自动取消（如付款期限过期），
+        统一记 failed 让上游看到需要处理。
+        """
+        if explicit is not None:
+            if explicit not in {s.value for s in TERMINAL_STATUSES}:
+                raise InvalidTaskStateError(f"terminal_status={explicit} 不是终态")
+            return explicit
+        if state == "paid":
+            return TaskStatus.SUCCEEDED.value
+        if state == "cancelled":
+            return TaskStatus.FAILED.value
+        # awaiting_payment 等无明确结局的状态被标 terminal 时，多半是 worker 检测到
+        # 3DS 之类人工环节，按 needs_human 处理
+        return TaskStatus.NEEDS_HUMAN.value
+
+    # ---- 恢复（绝不自动重投，见规格 §5）----
+
+    async def reclaim(self, task_id: str, worker_id: str) -> ReclaimData:
+        """把 stale 任务重新租给 worker。lease_count 必然 > 1"""
+        async with self._lock:
+            task = await self._db.get_task(task_id)
+            if task is None:
+                raise TaskNotFoundError(task_id)
+            if TaskStatus(task.status) not in RECLAIMABLE_STATUSES:
+                raise InvalidTaskStateError(
+                    f"任务 {task_id} 状态 {task.status}，不能 reclaim（只能 reclaim stale 任务）"
+                )
+
+            known_state = await self._db.get_latest_state(task_id)
+            lease = await self._lease_to_locked(task, worker_id, known_state=known_state)
+            # 复用 LeaseData 的字段构造 ReclaimData（结构一致）
+            return ReclaimData(
+                task_id=lease.task_id,
+                site=lease.site,
+                intent=lease.intent,
+                lease_expires_at=lease.lease_expires_at,
+                lease_count=lease.lease_count,
+                known_state=lease.known_state,
+            )
+
+    # ---- 过期清扫 ----
+
+    async def sweep(self) -> int:
+        """把过期的 leased/running 任务置 stale。返回清扫条数"""
+        async with self._lock:
+            return await self._sweep_locked()
+
+    async def _sweep_locked(self) -> int:
+        """锁内执行 sweep。调用方必须持有 self._lock"""
+        active = await self._db.list_tasks_in_statuses(tuple(s.value for s in ACTIVE_STATUSES))
+        now = utcnow()
+        swept = 0
+        for task in active:
+            if task.lease_expires_at and parse_iso(task.lease_expires_at) < now:
+                await self._db.update_task(
+                    task.task_id,
+                    status=TaskStatus.STALE.value,
+                    clear_lease=True,
+                    updated_at=to_iso(now),
+                )
+                swept += 1
+                logger.warning(
+                    "租约过期，任务置 stale（不自动重投）：task_id=%s site=%s",
+                    task.task_id,
+                    task.site,
+                )
+        if swept:
+            # stale 后腾出了「全局并发度 1」的槽位，唤醒等待者
+            # （虽然 stale 任务不会被普通 lease 取到，但队列里可能还有 queued）
+            self._cond.notify_all()
+        return swept
+
+    # ---- 查询 ----
+
+    async def get_task_detail(self, task_id: str) -> TaskDetail:
+        task = await self._db.get_task(task_id)
+        if task is None:
+            raise TaskNotFoundError(task_id)
+        reports = await self._db.get_reports(task_id)
+        latest = reports[-1].state if reports else None
+        return _task_to_detail(
+            task,
+            latest_state=latest,
+            reports=[
+                ReportEntry(
+                    state=r.state,
+                    payable_yen=r.payable_yen,
+                    pay_deadline=r.pay_deadline,
+                    site_order_id=r.site_order_id,
+                    evidence_ref=r.evidence_ref,
+                    detail=r.detail,
+                    reported_at=r.reported_at,
+                )
+                for r in reports
+            ],
+        )
+
+    async def list_tasks(
+        self,
+        *,
+        status: str | None,
+        site: str | None,
+        limit: int,
+        offset: int,
+    ) -> TaskListData:
+        rows, total = await self._db.list_tasks(
+            status=status, site=site, limit=limit, offset=offset
+        )
+        items: list[TaskDetail] = []
+        for row in rows:
+            reports = await self._db.get_reports(row.task_id)
+            latest = reports[-1].state if reports else None
+            items.append(
+                _task_to_detail(
+                    row,
+                    latest_state=latest,
+                    reports=[
+                        ReportEntry(
+                            state=r.state,
+                            payable_yen=r.payable_yen,
+                            pay_deadline=r.pay_deadline,
+                            site_order_id=r.site_order_id,
+                            evidence_ref=r.evidence_ref,
+                            detail=r.detail,
+                            reported_at=r.reported_at,
+                        )
+                        for r in reports
+                    ],
+                )
+            )
+        return TaskListData(items=items, total=total, limit=limit, offset=offset)
+
+    # ---- 健康检查 ----
+
+    async def health_snapshot(self) -> GatewayHealthData:
+        """规格 §4.7：只做 worker 失联 + 任务长时间无人领两条兜底告警"""
+        async with self._lock:
+            queued_count = await self._db.count_by_status(TaskStatus.QUEUED.value)
+            active_rows = await self._db.list_tasks_in_statuses(
+                tuple(s.value for s in ACTIVE_STATUSES)
+            )
+            queued_rows = await self._db.list_tasks_in_statuses(
+                (TaskStatus.QUEUED.value,)
+            )
+            workers = await self._db.list_workers()
+
+        now = utcnow()
+        offline_workers: list[WorkerHealthEntry] = []
+        worker_entries: list[WorkerHealthEntry] = []
+        for w in workers:
+            last_seen = parse_iso(w.last_seen_at)
+            age = int((now - last_seen).total_seconds())
+            entry = WorkerHealthEntry(
+                worker_id=w.worker_id,
+                last_seen_at=w.last_seen_at,
+                last_seen_seconds=age,
+            )
+            worker_entries.append(entry)
+            if age > self._worker_offline_alert_seconds:
+                offline_workers.append(entry)
+
+        stale_queued_threshold = utcnow() - timedelta(seconds=self._worker_offline_alert_seconds)
+        stale_queued: list[QueuedAlertEntry] = []
+        for t in queued_rows:
+            created = parse_iso(t.created_at)
+            if created < stale_queued_threshold:
+                stale_queued.append(
+                    QueuedAlertEntry(
+                        task_id=t.task_id,
+                        site=t.site,
+                        created_at=t.created_at,
+                        age_seconds=int((now - created).total_seconds()),
+                    )
+                )
+
+        active_details = [
+            _task_to_detail(
+                t,
+                latest_state=await self._db.get_latest_state(t.task_id),
+                reports=[],
+            )
+            for t in active_rows
+        ]
+
+        degraded = bool(offline_workers or stale_queued)
+        return GatewayHealthData(
+            status="degraded" if degraded else "ok",
+            queued_count=queued_count,
+            active_tasks=active_details,
+            workers=worker_entries,
+            offline_workers=offline_workers,
+            stale_queued_tasks=stale_queued,
+        )

app/shared/config.py

@@ -3,14 +3,16 @@
 配置项统一使用 RAKUTEN_ 前缀，例如 RAKUTEN_APP_PORT=31107。
 支持 .env 文件自动加载。
 
-抓取服务与交易服务是两个进程，但共用这一个 Settings 类：两边都要日志、代理、
-超时与同一个 Bearer token，拆成两份配置只会让部署时多维护一套。下面按
-「通用 / 仅抓取 / 仅交易」分区标注，各进程只读自己那部分。
+抓取、交易与下单任务网关是三个进程，但共用这一个 Settings 类：三方都要日志、
+代理、超时与同一个 Bearer token，拆成三份配置只会让部署时多维护一套。下面按
+「通用 / 仅抓取 / 仅交易 / 仅网关 / 仅交易 worker」分区标注，各进程只读自己那部分。
 """
+import socket
 from functools import lru_cache
 from pathlib import Path
 from typing import Literal
 
+from pydantic import Field
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 BASE_DIR = Path(__file__).resolve().parent.parent.parent
@@ -47,6 +49,11 @@ class Settings(BaseSettings):
     trading_host: str = "0.0.0.0"
     trading_port: int = 31108
 
+    # 下单任务网关监听地址（第三个部署单元）。网关部署在服务器侧，本地 worker
+    # 通过出站长轮询从这里领任务。详见 docs/order-gateway.md。
+    gateway_host: str = "0.0.0.0"
+    gateway_port: int = 31109
+
     # ---- 日志配置 ----
     log_level: str = "INFO"
     log_to_file: bool | None = None  # None 表示根据环境自动决定
@@ -102,6 +109,36 @@ class Settings(BaseSettings):
     # 页面改版导致买到远超预期的订单。设为 0 表示不设上限（不建议）。
     order_max_total_yen: int = 30000
 
+    # ---- 下单任务网关（仅网关进程 app.gateway.main 使用）----
+    # 网关的 SQLite 文件路径（相对项目根目录）。任务队列与状态镜像都在这里，
+    # 部署时务必放在持久化卷上，丢了等于丢了一批下单任务。
+    gateway_db_path: str = "data/gateway.db"
+    # 任务租约 TTL（秒）。worker 领取后必须在此时间内首次 report 或 renew，
+    # 否则网关把任务标记为 stale。**绝不自动重投**（见 docs/order-gateway.md §5）。
+    lease_ttl_seconds: int = 300
+    # 长轮询单次最长挂起秒数。worker 端的 wait 参数会被夹到这个上限。
+    lease_max_wait_seconds: int = Field(default=60, ge=1, le=300)
+    # worker 心跳超时阈值（秒）。网关 /health 据此判断 worker 是否失联：
+    # 正常 worker 每 30 秒来一次 lease，超过该阈值未来 lease 即视为异常。
+    worker_offline_alert_seconds: int = 300
+
+    # ---- 本地下单 worker（仅交易服务内的 worker 子模块使用）----
+    # 网关 URL。**留空则不启动 worker**，交易服务只跑登录态接口。
+    # 部署形态：本地机（NAT 后无公网入口）通过出站长轮询领任务，详见
+    # docs/order-gateway.md。
+    order_gateway_url: str = ""
+    # worker 标识。同一时间只能有一个 worker 持有 lease，这个值用来区分不同
+    # 本地机；留空时取主机名。
+    worker_id: str | None = None
+    # 本地订单 SQLite 文件路径。订单主表 + 状态事件 + 证据索引都在这里，
+    # 是执行事实的权威记录；网关上只是镜像。
+    trading_db_path: str = "data/trading.db"
+    # 页面证据落盘目录（HTML 快照 + 截图 + meta.json），按 task_id 分子目录。
+    evidence_dir: str = "data/evidence"
+    # 抓取服务基地址。worker 需要商品数据（加购要用 purchase 块）时出站请求这里，
+    # 不直接 import 解析器——抓取与交易是两个进程，详见 README「两个部署单元」。
+    scraper_base_url: str = ""
+
     # ---- 目标站点 ----
     home_url: str = DEFAULT_HOME_URL
 
@@ -155,6 +192,38 @@ class Settings(BaseSettings):
         path.mkdir(parents=True, exist_ok=True)
         return path
 
+    @property
+    def gateway_db_path_resolved(self) -> Path:
+        """网关 SQLite 文件的绝对路径，父目录不存在时创建"""
+        path = Path(self.gateway_db_path)
+        if not path.is_absolute():
+            path = BASE_DIR / path
+        path.parent.mkdir(parents=True, exist_ok=True)
+        return path
+
+    @property
+    def trading_db_path_resolved(self) -> Path:
+        """本地订单 SQLite 文件的绝对路径，父目录不存在时创建"""
+        path = Path(self.trading_db_path)
+        if not path.is_absolute():
+            path = BASE_DIR / path
+        path.parent.mkdir(parents=True, exist_ok=True)
+        return path
+
+    @property
+    def evidence_path(self) -> Path:
+        """证据目录的绝对路径，不存在时创建"""
+        path = Path(self.evidence_dir)
+        if not path.is_absolute():
+            path = BASE_DIR / path
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    @property
+    def worker_id_effective(self) -> str:
+        """worker 标识：显式配置优先，否则取主机名"""
+        return self.worker_id or socket.gethostname()
+
 
 @lru_cache(maxsize=1)
 def get_settings() -> Settings:

app/shared/errors.py

@@ -6,6 +6,7 @@
 - 3xxx: 反爬/上游阻断相关错误
 - 4xxx: 页面解析错误
 - 5xxx: 加购/下单错误（需要账号登录态的写操作）
+- 6xxx: 下单任务编排错误（网关侧的租约与状态机）
 """
 
 
@@ -169,3 +170,57 @@ class OrderGuardError(AppError):
 
     def __init__(self, message: str):
         super().__init__(message=message, code="ORDER_GUARD", err_code=5004, retryable=False)
+
+
+# ---- 下单任务编排（仅网关进程 app.gateway.main 使用）----
+# 下单不可逆，因此任务队列侧的错误一律标记 retryable=False——重复入队/重投
+# 都可能变成重复下单。详见 docs/order-gateway.md §8。
+
+
+class TaskNotFoundError(AppError):
+    """任务不存在"""
+
+    def __init__(self, task_id: str):
+        super().__init__(
+            message=f"任务不存在：{task_id}",
+            code="TASK_NOT_FOUND",
+            err_code=6001,
+            retryable=False,
+            status_code=404,
+        )
+        self.task_id = task_id
+
+
+class LeaseInvalidError(AppError):
+    """租约无效：不是持有者、已过期或任务已终结
+
+    worker 在 renew / report / reclaim 时必须校验自己是当前租约的持有者，且任务
+    尚未终结。任意一条不满足都报 6002，让 worker 停下来而不是猜测当前状态。
+    """
+
+    def __init__(self, message: str = "租约无效"):
+        super().__init__(
+            message=message,
+            code="LEASE_INVALID",
+            err_code=6002,
+            retryable=False,
+            status_code=409,
+        )
+
+
+class InvalidTaskStateError(AppError):
+    """任务状态不允许该操作
+
+    例如对已终结（succeeded/failed/needs_human）的任务再 reclaim。与 6002 的区别：
+    6002 是租约本身的问题（不是持有者 / 已过期），6003 是状态机层面的问题
+    （当前状态不接受这个动作）。
+    """
+
+    def __init__(self, message: str = "任务状态不允许该操作"):
+        super().__init__(
+            message=message,
+            code="INVALID_TASK_STATE",
+            err_code=6003,
+            retryable=False,
+            status_code=409,
+        )

app/shared/task_state.py

@@ -0,0 +1,65 @@
+"""任务与订单状态枚举：网关与本地 worker 共享的词汇表
+
+放在 shared 层是因为这是网关与 worker 之间的 HTTP 契约——两侧都需要知道合法
+取值，不能由任何一方私有持有。shared 本身不引入对 scraping/trading 的依赖，
+这个模块也一样：纯枚举与状态集合，不引用任何业务模块。
+
+两层状态不要混：task.status 描述「这个任务被谁领了、做完没有」，order state
+描述「这笔订单在站点上走到哪一步」。前者权威方是网关，后者权威方是本地 trading，
+网关只存镜像。详见 docs/order-gateway.md §3。
+
+迁移图（task.status）：
+
+    queued ──lease──> leased ──首次 report──> running ──terminal report──> succeeded
+       ▲                 │                        │                    └─> failed
+       │                 └──── 租约过期 ──────────┴──> stale            └─> needs_human
+       └── 只有人工介入才能从 stale 回到 leased（reclaim）
+
+注意 stale **不**自动回 queued——下单不可逆，自动重投等于再买一次。
+"""
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class TaskStatus(StrEnum):
+    """任务状态（网关权威）"""
+
+    QUEUED = "queued"  # 已入队，等待 worker 领取
+    LEASED = "leased"  # 已被 worker 领走，尚未首次 report
+    RUNNING = "running"  # worker 已首次 report，正在进行
+    SUCCEEDED = "succeeded"  # 终态：成功
+    FAILED = "failed"  # 终态：worker 明确失败
+    NEEDS_HUMAN = "needs_human"  # 终态：需要人介入（如 3DS、核对不出结论）
+    STALE = "stale"  # 租约过期，等人工 reclaim，不自动重投
+
+
+# 终态集合：到达后任何 renew / report / reclaim 都报 6003
+TERMINAL_STATUSES: frozenset[TaskStatus] = frozenset(
+    {TaskStatus.SUCCEEDED, TaskStatus.FAILED, TaskStatus.NEEDS_HUMAN}
+)
+
+# 处于「执行中」的状态：这些状态存在时，lease 一律返回空（全局并发度 1）
+ACTIVE_STATUSES: frozenset[TaskStatus] = frozenset({TaskStatus.LEASED, TaskStatus.RUNNING})
+
+# 可以被普通 lease 领走的状态：只有 queued
+LEASABLE_STATUSES: frozenset[TaskStatus] = frozenset({TaskStatus.QUEUED})
+
+# 可以被 reclaim 领走的状态：只有 stale
+RECLAIMABLE_STATUSES: frozenset[TaskStatus] = frozenset({TaskStatus.STALE})
+
+
+class OrderState(StrEnum):
+    """订单状态（本地权威，网关只存镜像）
+
+    沿用 docs/order-gateway.md §3 给的取值。网关本身不解释这些值，只是字符串透传。
+    """
+
+    CREATED = "created"
+    IN_CART = "in_cart"
+    ORDERED = "ordered"
+    AWAITING_PAYMENT = "awaiting_payment"
+    PAID = "paid"
+    SHIPPED = "shipped"
+    DELIVERED = "delivered"
+    CANCELLED = "cancelled"

app/trading/container.py

@@ -1,9 +1,15 @@
 """交易服务容器：集中管理交易侧服务实例，用于依赖注入
 
-目前只有登录态会话。加购、下单、付款、订单监控与页面证据留痕的服务实例
-后续挂在这里，它们共享同一份 auth_session——同一个账号的写操作必须走同一条
-cookie 通道，且必须串行，不能各建各的客户端。
+持有两类东西：
+- 登录态会话（auth_session）——加购与下单必须用同一份 cookie，全程共享
+- 本地下单 worker（可选）——RAKUTEN_ORDER_GATEWAY_URL 留空时整套不构造
+
+worker 的子组件（gateway_client / local_db / evidence_store / runner）都在
+app.trading.worker 包内，与抓取/网关互不 import；worker 需要商品数据时走抓取
+服务的 HTTP 接口，需要任务调度时走网关的 HTTP 接口。
 """
+from __future__ import annotations
+
 from dataclasses import dataclass
 
 from app.shared.config import Settings
@@ -17,7 +23,15 @@ class TradingContainer:
     与抓取容器最本质的差别不是字段多少，而是**这个进程有状态**：登录态、
     订单、页面证据都属于某个具体账号，因此交易服务只能单实例运行
     （或按账号分片），不能像抓取服务那样随意横向扩容。
+
+    worker_* 字段在 RAKUTEN_ORDER_GATEWAY_URL 留空时为 None——此时交易服务
+    只跑登录态接口，不起后台 worker。
     """
 
     settings: Settings
     auth_session: AuthSession
+    # 以下四项仅在 order_gateway_url 配置时构造；否则为 None，worker 不启动
+    worker_client: object | None = None  # app.trading.worker.client.GatewayClient
+    worker_local_db: object | None = None  # app.trading.worker.local_db.LocalDB
+    worker_evidence: object | None = None  # app.trading.worker.evidence.EvidenceStore
+    worker_runner: object | None = None  # app.trading.worker.runner.WorkerRunner

app/trading/main.py

@@ -10,10 +10,12 @@
 
 因此本服务只能单实例运行（或按账号分片），扩容靠抓取服务那一侧。
 
-当前只提供登录态的查询与重载；加购、下单、付款与订单监控在此基础上叠加。
+worker 启动条件：RAKUTEN_ORDER_GATEWAY_URL 非空。留空时本服务只跑登录态接口，
+不构造任何 worker 子组件（本地 DB / 证据目录 / 出站客户端都不创建）。
 """
 from __future__ import annotations
 
+import asyncio
 import logging
 from contextlib import asynccontextmanager
 
@@ -32,14 +34,41 @@ logger = logging.getLogger(__name__)
 
 
 def build_container() -> TradingContainer:
-    """构建交易服务容器，组装所有依赖"""
+    """构建交易服务容器：登录态会话始终构造，worker 仅在配置了网关 URL 时构造"""
     settings = get_settings()
-    return TradingContainer(settings=settings, auth_session=AuthSession(settings))
+    container = TradingContainer(settings=settings, auth_session=AuthSession(settings))
+
+    if settings.order_gateway_url:
+        # 延迟 import：未配置网关 URL 时不加载 worker 模块（也就不会拉起 aiosqlite 等）
+        from app.trading.worker.client import GatewayClient
+        from app.trading.worker.evidence import EvidenceStore
+        from app.trading.worker.local_db import LocalDB
+        from app.trading.worker.runner import WorkerRunner
+
+        client = GatewayClient(
+            settings.order_gateway_url,
+            settings.bearer_token,
+            timeout=max(60.0, settings.lease_max_wait_seconds + 10),
+        )
+        local_db = LocalDB(settings.trading_db_path_resolved)
+        evidence = EvidenceStore(settings.evidence_path)
+        runner = WorkerRunner(
+            settings=settings,
+            gateway_client=client,
+            local_db=local_db,
+            evidence=evidence,
+        )
+        container.worker_client = client
+        container.worker_local_db = local_db
+        container.worker_evidence = evidence
+        container.worker_runner = runner
+
+    return container
 
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-    """应用生命周期管理：启动时加载登录态，关闭时释放 HTTP 客户端"""
+    """应用生命周期管理：登录态会话 + 可选 worker"""
     container = build_container()
     app.state.container = container
 
@@ -52,10 +81,42 @@ async def lifespan(app: FastAPI):
         container.settings.trading_port,
     )
     logger.info("当前环境：%s", container.settings.app_env)
+
     await container.auth_session.start()
+
+    worker_task: asyncio.Task | None = None
+    if container.worker_runner is not None:
+        # 顺序：先开本地 DB（worker 写证据前要先能写库），再起后台任务
+        assert container.worker_local_db is not None
+        assert container.worker_client is not None
+        await container.worker_local_db.start()
+        worker_task = asyncio.create_task(
+            container.worker_runner.run(), name="trading-worker"
+        )
+        logger.info(
+            "下单 worker 已启动：worker_id=%s gateway=%s",
+            container.settings.worker_id_effective,
+            container.settings.order_gateway_url,
+        )
+    else:
+        logger.info(
+            "未配置 RAKUTEN_ORDER_GATEWAY_URL，下单 worker 不启动（仅登录态接口）"
+        )
+
     try:
         yield
     finally:
+        if worker_task is not None:
+            container.worker_runner.stop()  # type: ignore[union-attr]
+            worker_task.cancel()
+            try:
+                await worker_task
+            except asyncio.CancelledError:
+                pass
+        if container.worker_local_db is not None:
+            await container.worker_local_db.close()
+        if container.worker_client is not None:
+            await container.worker_client.aclose()
         await container.auth_session.close()
         shutdown_telemetry()
 

app/trading/worker/__init__.py

@@ -0,0 +1,9 @@
+"""本地下单 worker：从网关长轮询领任务，本地执行下单与付款
+
+部署在本地交易服务进程内（NAT 后无公网入口），通过出站长轮询从服务器侧的
+order-gateway 取任务。**零入站端口**：所有跨机通信都由本地发起。
+
+主循环见 runner.WorkerRunner.run：lease → 本地幂等闸门 → 恢复核对 → 执行 → 监控。
+站点交互（加购 / 下单 / 付款）当前未实测（docs/order-gateway.md §10），留作
+NotImplementedError 缺口，runner 捕获后上报 needs_human。
+"""

app/trading/worker/client.py

@@ -0,0 +1,145 @@
+"""网关 HTTP 客户端：出站长轮询领任务、回报状态、续租、恢复领取
+
+worker 与网关之间是出站单向通信。所有方法都包装成「成功 → data，失败 → 抛
+AppError」的形式，runner 拿到 AppError 直接打日志或转报 needs_human。
+
+请求与响应严格使用 shared.api 的 ApiResponse 信封；网关侧错误码（6xxx）原样上抛，
+不在这里翻译。鉴权头从 settings.bearer_token 取，与抓取/交易服务共用同一份。
+
+**不 import app.gateway**：worker 只看 HTTP 响应 JSON，本地用 LeaseTask 表达领到的
+任务，与网关侧的 Pydantic 模型解耦。
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+
+from app.shared.errors import AppError
+from app.shared.task_state import OrderState, TaskStatus
+from app.trading.worker.models import LeaseTask
+
+logger = logging.getLogger(__name__)
+
+
+class GatewayClient:
+    """网关 HTTP 客户端
+
+    一份 AsyncClient 实例贯穿 worker 整个生命周期，连接池由 httpx 管理。
+    """
+
+    def __init__(self, base_url: str, bearer_token: str, *, timeout: float = 60.0):
+        # 末尾去斜杠，避免 base + "/api/..." 拼出双斜杠
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers={"Authorization": f"Bearer {bearer_token}"},
+            timeout=timeout,
+        )
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    # ---- 基础封装 ----
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        """发起请求并解信封。失败（success=False）抛 AppError"""
+        response = await self._client.request(method, path, **kwargs)
+        try:
+            body = response.json()
+        except ValueError as exc:
+            raise AppError(
+                message=f"网关响应不是合法 JSON：HTTP {response.status_code}",
+                code="GATEWAY_BAD_BODY",
+                err_code=3001,
+                retryable=True,
+            ) from exc
+
+        if not body.get("success"):
+            raise AppError(
+                message=body.get("msg", "网关返回失败"),
+                code="GATEWAY_ERROR",
+                err_code=int(body.get("code", 1500)),
+                retryable=False,
+                status_code=response.status_code,
+            )
+        return body
+
+    # ---- 接口 ----
+
+    async def lease(
+        self, worker_id: str, *, wait: int = 30, site: str | None = None
+    ) -> LeaseTask | None:
+        """长轮询领取。无可领任务时返回 None"""
+        params: dict[str, Any] = {"worker_id": worker_id, "wait": wait}
+        if site:
+            params["site"] = site
+        body = await self._request("GET", "/api/orders/lease", params=params)
+        data = body.get("data")
+        if not data:
+            return None
+        return LeaseTask(
+            task_id=data["task_id"],
+            site=data["site"],
+            intent=data.get("intent") or {},
+            lease_expires_at=data.get("lease_expires_at", ""),
+            lease_count=data.get("lease_count", 1),
+            known_state=data.get("known_state"),
+        )
+
+    async def renew(self, task_id: str, worker_id: str) -> dict[str, Any]:
+        """续租，返回网关响应里的 data 字段"""
+        body = await self._request(
+            "POST",
+            f"/api/orders/{task_id}/renew",
+            json={"worker_id": worker_id},
+        )
+        return body["data"]
+
+    async def report(
+        self,
+        task_id: str,
+        worker_id: str,
+        *,
+        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 = "",
+        terminal: bool = False,
+        terminal_status: TaskStatus | None = None,
+    ) -> dict[str, Any]:
+        """回报状态，返回网关响应里的 data 字段"""
+        payload: dict[str, Any] = {
+            "worker_id": worker_id,
+            "state": state.value,
+            "payable_yen": payable_yen,
+            "pay_deadline": pay_deadline,
+            "site_order_id": site_order_id,
+            "evidence_ref": evidence_ref,
+            "detail": detail,
+            "terminal": terminal,
+        }
+        if terminal_status is not None:
+            payload["terminal_status"] = terminal_status.value
+        body = await self._request("POST", f"/api/orders/{task_id}/report", json=payload)
+        return body["data"]
+
+    async def reclaim(self, task_id: str, worker_id: str) -> LeaseTask:
+        """恢复领取。返回的 LeaseTask 必然 lease_count > 1"""
+        body = await self._request(
+            "POST",
+            f"/api/orders/{task_id}/reclaim",
+            json={"worker_id": worker_id},
+        )
+        data = body["data"]
+        return LeaseTask(
+            task_id=data["task_id"],
+            site=data["site"],
+            intent=data.get("intent") or {},
+            lease_expires_at=data.get("lease_expires_at", ""),
+            lease_count=data.get("lease_count", 1),
+            known_state=data.get("known_state"),
+        )

app/trading/worker/evidence.py

@@ -0,0 +1,56 @@
+"""证据落盘：HTML 快照、截图与 meta.json
+
+规格 §6.1：每个任务一个子目录，按步骤序号命名文件。report 里的 evidence_ref
+填 `{task_id}/{序号}-{步骤名}`，不含扩展名。
+
+证据**只留本地**（约束 4），网关只存 evidence_ref 这个相对路径字符串。
+"""
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class EvidenceStore:
+    """把每一步的页面快照、截图与 meta 落到 {evidence_dir}/{task_id}/ 下"""
+
+    def __init__(self, evidence_dir: Path):
+        self._root = evidence_dir
+
+    def step_dir(self, task_id: str) -> Path:
+        path = self._root / task_id
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def write_step(
+        self,
+        task_id: str,
+        step_no: int,
+        step_name: str,
+        *,
+        html: str | None = None,
+        png: bytes | None = None,
+        meta: dict[str, Any] | None = None,
+    ) -> str:
+        """写入一步的证据文件
+
+        返回相对 evidence_dir 的引用路径（不含扩展名），用于 report 的 evidence_ref
+        字段。文件命名：`{序号:02d}-{步骤名}.{html|png|meta.json}`。
+        """
+        step_dir = self.step_dir(task_id)
+        stem = f"{step_no:02d}-{step_name}"
+        rel_stem = f"{task_id}/{stem}"
+
+        if html is not None:
+            (step_dir / f"{stem}.html").write_text(html, encoding="utf-8")
+        if png is not None:
+            (step_dir / f"{stem}.png").write_bytes(png)
+        if meta is not None:
+            (step_dir / f"{stem}.meta.json").write_text(
+                json.dumps(meta, ensure_ascii=False, indent=2), encoding="utf-8"
+            )
+        return rel_stem

app/trading/worker/local_db.py

@@ -0,0 +1,181 @@
+"""本地订单 SQLite：执行事实的权威记录
+
+与网关的 tasks/task_reports 表对偶，但本地这张表才是「这单到底下没下、付没付」
+的权威。网关失联或数据丢失时，本地这张表用于补报与对账。
+
+三张表：
+- orders：每笔任务一行，记录开始/结束时间与最终状态
+- order_events：append-only 的状态迁移事件（与网关 task_reports 对账）
+- evidence_index：每步证据文件的相对路径索引，便于事后翻查
+"""
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import aiosqlite
+
+logger = logging.getLogger(__name__)
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS orders (
+    task_id      TEXT PRIMARY KEY,
+    site         TEXT NOT NULL,
+    intent_json  TEXT NOT NULL,
+    final_state  TEXT,
+    started_at   TEXT NOT NULL,
+    finished_at  TEXT
+);
+
+CREATE TABLE IF NOT EXISTS order_events (
+    task_id      TEXT NOT NULL,
+    state        TEXT NOT NULL,
+    detail       TEXT,
+    evidence_ref TEXT,
+    recorded_at  TEXT NOT NULL,
+    PRIMARY KEY (task_id, state)
+);
+
+CREATE TABLE IF NOT EXISTS evidence_index (
+    task_id      TEXT NOT NULL,
+    step_no      INTEGER NOT NULL,
+    step_name    TEXT NOT NULL,
+    rel_path     TEXT NOT NULL,
+    saved_at     TEXT NOT NULL,
+    PRIMARY KEY (task_id, step_no)
+);
+"""
+
+
+def _utcnow_iso() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+@dataclass(slots=True)
+class OrderRow:
+    task_id: str
+    site: str
+    intent_json: str
+    final_state: str | None
+    started_at: str
+    finished_at: str | None
+
+    @property
+    def intent(self) -> dict[str, Any]:
+        return json.loads(self.intent_json)
+
+
+class LocalDB:
+    """本地订单 SQLite 访问对象"""
+
+    def __init__(self, db_path: Path):
+        self._db_path = db_path
+        self._conn: aiosqlite.Connection | None = None
+
+    async def start(self) -> None:
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn = await aiosqlite.connect(str(self._db_path))
+        self._conn.row_factory = aiosqlite.Row
+        await self._conn.executescript(SCHEMA)
+        await self._conn.commit()
+        logger.info("本地订单 DB 已就绪：%s", self._db_path)
+
+    async def close(self) -> None:
+        if self._conn is not None:
+            await self._conn.close()
+            self._conn = None
+
+    @property
+    def conn(self) -> aiosqlite.Connection:
+        if self._conn is None:
+            raise RuntimeError("LocalDB 未启动：先调用 start()")
+        return self._conn
+
+    # ---- orders ----
+
+    async def ensure_started(self, task_id: str, site: str, intent: dict[str, Any]) -> None:
+        """记录任务开始执行。已存在则忽略（同任务被重新领回时）"""
+        await self.conn.execute(
+            "INSERT OR IGNORE INTO orders (task_id, site, intent_json, started_at) "
+            "VALUES (?, ?, ?, ?)",
+            (task_id, site, json.dumps(intent, ensure_ascii=False), _utcnow_iso()),
+        )
+        await self.conn.commit()
+
+    async def get_order(self, task_id: str) -> OrderRow | None:
+        async with self.conn.execute(
+            "SELECT * FROM orders WHERE task_id = ?",
+            (task_id,),
+        ) as cur:
+            row = await cur.fetchone()
+            if row is None:
+                return None
+            return OrderRow(
+                task_id=row["task_id"],
+                site=row["site"],
+                intent_json=row["intent_json"],
+                final_state=row["final_state"],
+                started_at=row["started_at"],
+                finished_at=row["finished_at"],
+            )
+
+    async def has_finished(self, task_id: str) -> bool:
+        """是否已有终态记录。用于主循环里的本地幂等闸门"""
+        async with self.conn.execute(
+            "SELECT 1 FROM orders WHERE task_id = ? AND finished_at IS NOT NULL",
+            (task_id,),
+        ) as cur:
+            return await cur.fetchone() is not None
+
+    async def mark_finished(self, task_id: str, final_state: str) -> None:
+        await self.conn.execute(
+            "UPDATE orders SET final_state = ?, finished_at = ? WHERE task_id = ?",
+            (final_state, _utcnow_iso(), task_id),
+        )
+        await self.conn.commit()
+
+    async def final_state(self, task_id: str) -> str | None:
+        async with self.conn.execute(
+            "SELECT final_state FROM orders WHERE task_id = ?",
+            (task_id,),
+        ) as cur:
+            row = await cur.fetchone()
+            return row["final_state"] if row else None
+
+    # ---- events ----
+
+    async def record_event(
+        self,
+        task_id: str,
+        state: str,
+        *,
+        detail: str = "",
+        evidence_ref: str | None = None,
+    ) -> None:
+        """记录一次状态迁移事件（与网关 task_reports 对账）
+
+        同一 (task_id, state) 重复记录视为同一次——INSERT OR IGNORE，与网关侧的
+        INSERT OR REPLACE 不同：本地这张表是事件日志，不覆盖既有记录。
+        """
+        await self.conn.execute(
+            "INSERT OR IGNORE INTO order_events "
+            "(task_id, state, detail, evidence_ref, recorded_at) VALUES (?, ?, ?, ?, ?)",
+            (task_id, state, detail, evidence_ref, _utcnow_iso()),
+        )
+        await self.conn.commit()
+
+    # ---- evidence index ----
+
+    async def index_evidence(
+        self, task_id: str, step_no: int, step_name: str, rel_path: str
+    ) -> None:
+        await self.conn.execute(
+            "INSERT OR REPLACE INTO evidence_index "
+            "(task_id, step_no, step_name, rel_path, saved_at) VALUES (?, ?, ?, ?, ?)",
+            (task_id, step_no, step_name, rel_path, _utcnow_iso()),
+        )
+        await self.conn.commit()

app/trading/worker/models.py

@@ -0,0 +1,28 @@
+"""worker 侧数据模型：不引用网关的 Pydantic 模型
+
+worker 通过 HTTP 与网关交互，看到的只有 JSON。这里定义 worker 自己用来表达
+「领到的任务」「核对结论」的数据类——结构上对应网关响应，但**不 import**
+app.gateway 的任何东西，保证架构边界（worker → shared，禁止 worker → gateway）。
+
+OrderState / TaskStatus 枚举在 app.shared.task_state，两侧共用同一份取值表。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class LeaseTask:
+    """worker 从网关领到的任务
+
+    对应网关 GET /api/orders/lease 的 LeaseData，但用 dataclass 表达——worker
+    内部不依赖网关侧的 Pydantic 模型。
+    """
+
+    task_id: str
+    site: str
+    intent: dict[str, Any] = field(default_factory=dict)
+    lease_expires_at: str = ""
+    lease_count: int = 1
+    known_state: str | None = None

app/trading/worker/runner.py

@@ -0,0 +1,420 @@
+"""worker 主循环与每任务执行流
+
+主循环（规格 §6）：
+
+    while running:
+        task = await gateway.lease(worker_id, wait=30)
+        if task is None:
+            continue
+
+        if local_db.has_finished(task.task_id):              # 本地幂等闸门
+            await gateway.report(...); continue
+
+        if task.lease_count > 1:                             # 恢复领取
+            verdict = await verify_on_site(task)
+            if verdict.already_ordered: await report(...); continue
+            if verdict.unknown: await report(needs_human); continue
+
+        async with renew_lease_every(60):
+            await execute(task)
+
+每个动作的顺序固定为：动作 → 落证据 → 写本地 SQLite → 回报 gateway。
+顺序不能颠倒——先落证据再回报，保证服务器上看到的状态一定有本地证据可查。
+"""
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from typing import TYPE_CHECKING
+
+from app.shared.errors import AppError, OrderGuardError
+from app.shared.task_state import OrderState, TaskStatus
+from app.trading.worker import site_interact, verify
+from app.trading.worker.client import GatewayClient
+from app.trading.worker.evidence import EvidenceStore
+from app.trading.worker.local_db import LocalDB
+from app.trading.worker.models import LeaseTask
+
+if TYPE_CHECKING:
+    from app.shared.config import Settings
+
+logger = logging.getLogger(__name__)
+
+
+def _coerce_state(value: str | None) -> OrderState:
+    """把网关返回的 state 字符串安全地包成 OrderState；None 或非法值回落到 CREATED"""
+    if not value:
+        return OrderState.CREATED
+    try:
+        return OrderState(value)
+    except ValueError:
+        logger.warning("未知的 order state 字符串，回落到 CREATED：%s", value)
+        return OrderState.CREATED
+
+
+class WorkerRunner:
+    """worker 主循环与执行流
+
+    持有 gateway 客户端、本地 DB、证据存储。`run()` 是常驻 asyncio 任务，
+    `handle()` 处理单个任务，`execute()` 是站点交互的实际调度（当前多数步骤未实现）。
+    """
+
+    def __init__(
+        self,
+        *,
+        settings: "Settings",
+        gateway_client: GatewayClient,
+        local_db: LocalDB,
+        evidence: EvidenceStore,
+    ):
+        self._settings = settings
+        self._gateway = gateway_client
+        self._db = local_db
+        self._evidence = evidence
+        self._running = False
+
+    def stop(self) -> None:
+        self._running = False
+
+    @property
+    def worker_id(self) -> str:
+        return self._settings.worker_id_effective
+
+    # ---- 主循环 ----
+
+    async def run(self) -> None:
+        """常驻循环：长轮询领任务，按 §6 调度"""
+        self._running = True
+        logger.info("worker 启动：worker_id=%s", self.worker_id)
+        while self._running:
+            try:
+                task = await self._gateway.lease(self.worker_id, wait=30)
+            except AppError as exc:
+                logger.warning("lease 失败：%s (err=%s)", exc.message, exc.err_code)
+                await asyncio.sleep(5)
+                continue
+            except Exception:  # noqa: BLE001
+                logger.exception("lease 异常")
+                await asyncio.sleep(5)
+                continue
+
+            if task is None:
+                continue
+
+            try:
+                await self.handle(task)
+            except Exception:  # noqa: BLE001
+                # 任何未预期的异常都不应让 worker 退出
+                logger.exception("handle 任务异常：task_id=%s", task.task_id)
+
+    # ---- 单任务调度 ----
+
+    async def handle(self, task: LeaseTask) -> None:
+        """单任务调度入口：本地幂等闸门 → 恢复核对 → 执行"""
+        # 本地幂等闸门：之前已完成过的任务不再执行
+        if await self._db.has_finished(task.task_id):
+            final_state = await self._db.final_state(task.task_id)
+            logger.info(
+                "本地已完成，补报终态：task_id=%s state=%s", task.task_id, final_state
+            )
+            await self._report_safe(
+                task,
+                state=_coerce_state(final_state),
+                detail="本地已完成，补报避免重复执行",
+                terminal=True,
+            )
+            return
+
+        # 恢复领取：lease_count > 1 表示 stale → reclaim，必须先核对站点订单
+        if task.lease_count > 1:
+            await self._handle_recovery(task)
+            return
+
+        # 常规执行
+        await self._execute_with_renewal(task)
+
+    async def _handle_recovery(self, task: LeaseTask) -> None:
+        """lease_count > 1 的恢复路径：先核对，不直接执行"""
+        logger.warning(
+            "恢复领取（lease_count=%s），先核对站点订单：task_id=%s",
+            task.lease_count,
+            task.task_id,
+        )
+        verdict = await verify.verify_on_site(task)
+        if verdict.verdict == verify.VerifyVerdict.ALREADY_ORDERED:
+            await self._report_safe(
+                task,
+                state=OrderState.ORDERED,
+                site_order_id=verdict.site_order_id,
+                detail=f"核对结论：已下单（{verdict.detail}）",
+                terminal=True,
+                terminal_status=TaskStatus.SUCCEEDED,
+            )
+            await self._db.ensure_started(task.task_id, task.site, task.intent)
+            await self._db.mark_finished(task.task_id, OrderState.ORDERED.value)
+            return
+
+        # NOT_ORDERED 也走 needs_human：当前 verify 桩不会返回这个值，但留接口给
+        # 未来真正能可靠核对时——那时再决定 NOT_ORDERED 是否直接重新执行
+        await self._report_safe(
+            task,
+            state=_coerce_state(task.known_state),
+            detail=f"恢复核对无法定论：{verdict.detail}",
+            terminal=True,
+            terminal_status=TaskStatus.NEEDS_HUMAN,
+        )
+
+    # ---- 常规执行 ----
+
+    async def _execute_with_renewal(self, task: LeaseTask) -> None:
+        """在租约自动续期的上下文里执行任务"""
+        async with self._renew_lease_every(task, interval=60):
+            try:
+                await self.execute(task)
+            except NotImplementedError as exc:
+                # 站点交互未实现（规格 §10）：上报 needs_human，不视为 worker 失败
+                logger.warning(
+                    "站点交互未实现，转 needs_human：task_id=%s what=%s",
+                    task.task_id,
+                    exc,
+                )
+                await self._report_safe(
+                    task,
+                    state=_coerce_state(task.known_state),
+                    detail=f"站点交互未实现：{exc}",
+                    terminal=True,
+                    terminal_status=TaskStatus.NEEDS_HUMAN,
+                )
+            except OrderGuardError as exc:
+                # 金额守卫等闸门拦截：上报 needs_human，站点侧无提交动作
+                logger.warning(
+                    "下单闸门拦截，转 needs_human：task_id=%s msg=%s",
+                    task.task_id,
+                    exc.message,
+                )
+                await self._report_safe(
+                    task,
+                    state=_coerce_state(task.known_state),
+                    detail=exc.message,
+                    terminal=True,
+                    terminal_status=TaskStatus.NEEDS_HUMAN,
+                )
+            except AppError as exc:
+                logger.warning(
+                    "执行失败：task_id=%s code=%s msg=%s",
+                    task.task_id,
+                    exc.err_code,
+                    exc.message,
+                )
+                await self._report_safe(
+                    task,
+                    state=_coerce_state(task.known_state),
+                    detail=exc.message,
+                    terminal=True,
+                    terminal_status=TaskStatus.FAILED,
+                )
+
+    async def execute(self, task: LeaseTask) -> None:
+        """站点交互的实际调度：加购 → 校验 → 确认页 → 金额守卫 → 提交 → 付款
+
+        每一步的顺序：动作 → 落证据 → 写本地 SQLite → 回报 gateway。
+        站点交互当前未实现（site_interact 抛 NotImplementedError），第一步就会
+        转到 _execute_with_renewal 的 except 分支上报 needs_human。
+        """
+        await self._db.ensure_started(task.task_id, task.site, task.intent)
+
+        # ラクマ 加购契约未实现，首版只对乐天。其他站点直接转人工
+        if task.site != "rakuten":
+            raise NotImplementedError(f"site={task.site} 暂未实现下单（首版仅 rakuten）")
+
+        # 步骤 1：加购
+        await self._run_step(
+            task, step_no=1, step_name="cart-add",
+            action=lambda: site_interact.add_to_cart(task),
+            state=OrderState.IN_CART,
+            detail="已加入购物车",
+        )
+
+        # 步骤 2：校验购物车
+        await self._run_step(
+            task, step_no=2, step_name="cart-check",
+            action=lambda: site_interact.verify_cart(task),
+            state=OrderState.IN_CART,
+            detail="购物车已校验",
+        )
+
+        # 步骤 3：进入下单确认页 + 金额守卫
+        checkout_html = await site_interact.enter_checkout(task)
+        summary = await site_interact.parse_checkout(checkout_html)
+        self._enforce_amount_guard(task, summary.payable_yen)
+        await self._run_step(
+            task, step_no=3, step_name="order-confirm",
+            action=self._noop(),
+            state=OrderState.CREATED,
+            detail=f"下单确认页已解析：应付 {summary.payable_yen} 円",
+            evidence_meta={
+                "payable_yen": summary.payable_yen,
+                "site_order_id": summary.site_order_id,
+                "pay_deadline": summary.pay_deadline,
+            },
+        )
+
+        # 步骤 4：提交下单
+        site_order_id = await site_interact.submit_order(task)
+        await self._run_step(
+            task, step_no=4, step_name="order-submit",
+            action=self._noop(),
+            state=OrderState.ORDERED,
+            site_order_id=site_order_id,
+            detail=f"已提交下单，站点订单号 {site_order_id}",
+        )
+
+        # 步骤 5：付款
+        await self._run_step(
+            task, step_no=5, step_name="payment",
+            action=lambda: site_interact.pay(task, site_order_id),
+            state=OrderState.AWAITING_PAYMENT,
+            site_order_id=site_order_id,
+            payable_yen=summary.payable_yen,
+            pay_deadline=summary.pay_deadline,
+            detail="已进入付款流程",
+        )
+        await self._report_safe(
+            task,
+            state=OrderState.PAID,
+            site_order_id=site_order_id,
+            payable_yen=summary.payable_yen,
+            pay_deadline=summary.pay_deadline,
+            detail="付款完成",
+            terminal=True,
+            terminal_status=TaskStatus.SUCCEEDED,
+        )
+        await self._db.mark_finished(task.task_id, OrderState.PAID.value)
+
+        # 步骤 6：付款后监控（非阻塞，常驻轮询；当前未实现）
+        try:
+            await site_interact.monitor(task, site_order_id)
+        except NotImplementedError:
+            logger.info("付款后监控未实现，跳过：task_id=%s", task.task_id)
+
+    def _enforce_amount_guard(self, task: LeaseTask, payable_yen: int) -> None:
+        """金额守卫：实际应付超过 intent.max_total_yen 或 RAKUTEN_ORDER_MAX_TOTAL_YEN 时拦截"""
+        intent = task.intent or {}
+        limit = intent.get("max_total_yen")
+        if limit is None or limit <= 0:
+            limit = self._settings.order_max_total_yen
+        if limit > 0 and payable_yen > limit:
+            raise OrderGuardError(
+                f"实际应付 {payable_yen} 円超过上限 {limit} 円"
+                f"（task_id={task.task_id}）"
+            )
+
+    @staticmethod
+    def _noop() -> "callable":
+        async def _f() -> None:
+            return None
+
+        return _f
+
+    async def _run_step(
+        self,
+        task: LeaseTask,
+        *,
+        step_no: int,
+        step_name: str,
+        action: "callable",
+        state: OrderState,
+        detail: str,
+        site_order_id: str | None = None,
+        payable_yen: int | None = None,
+        pay_deadline: str | None = None,
+        evidence_meta: dict | None = None,
+    ) -> None:
+        """单步执行：动作 → 落证据 → 写本地 → 回报 gateway"""
+        await action()
+        meta = {
+            "step": step_name,
+            "state": state.value,
+            **(evidence_meta or {}),
+        }
+        evidence_ref = self._evidence.write_step(
+            task.task_id, step_no, step_name, meta=meta
+        )
+        await self._db.index_evidence(task.task_id, step_no, step_name, evidence_ref)
+        await self._db.record_event(
+            task.task_id, state.value, detail=detail, evidence_ref=evidence_ref
+        )
+        await self._gateway.report(
+            task.task_id,
+            self.worker_id,
+            state=state,
+            payable_yen=payable_yen,
+            pay_deadline=pay_deadline,
+            site_order_id=site_order_id,
+            evidence_ref=evidence_ref,
+            detail=detail,
+        )
+
+    async def _report_safe(
+        self,
+        task: LeaseTask,
+        *,
+        state: OrderState,
+        detail: str,
+        terminal: bool = False,
+        terminal_status: TaskStatus | None = None,
+        site_order_id: str | None = None,
+        payable_yen: int | None = None,
+        pay_deadline: str | None = None,
+    ) -> None:
+        """回报 gateway，失败只记日志不抛——主循环不能因为回报失败退出"""
+        try:
+            await self._gateway.report(
+                task.task_id,
+                self.worker_id,
+                state=state,
+                detail=detail,
+                terminal=terminal,
+                terminal_status=terminal_status,
+                site_order_id=site_order_id,
+                payable_yen=payable_yen,
+                pay_deadline=pay_deadline,
+            )
+        except Exception:  # noqa: BLE001
+            logger.exception("回报 gateway 失败：task_id=%s state=%s", task.task_id, state)
+
+    @contextlib.asynccontextmanager
+    async def _renew_lease_every(self, task: LeaseTask, *, interval: int):
+        """后台任务：每隔 interval 秒续租一次。退出时停掉"""
+        stop_event = asyncio.Event()
+
+        async def _loop() -> None:
+            while not stop_event.is_set():
+                try:
+                    await asyncio.wait_for(stop_event.wait(), timeout=interval)
+                except asyncio.TimeoutError:
+                    pass
+                if stop_event.is_set():
+                    return
+                try:
+                    await self._gateway.renew(task.task_id, self.worker_id)
+                except AppError as exc:
+                    logger.warning(
+                        "续租失败：task_id=%s code=%s msg=%s",
+                        task.task_id,
+                        exc.err_code,
+                        exc.message,
+                    )
+                    return
+                except Exception:  # noqa: BLE001
+                    logger.exception("续租异常：task_id=%s", task.task_id)
+                    return
+
+        renewal = asyncio.create_task(_loop(), name=f"renew-{task.task_id}")
+        try:
+            yield
+        finally:
+            stop_event.set()
+            with contextlib.suppress(asyncio.CancelledError):
+                await renewal

app/trading/worker/site_interact.py

@@ -0,0 +1,73 @@
+"""站点交互：加购 / 校验购物车 / 进入下单确认页 / 金额守卫 / 提交 / 付款 / 监控
+
+**全部未实现**。规格 docs/order-gateway.md §10 明确说明：加购 → 下单 → 付款的
+实际站点交互没有实测过，未实测前调用直接抛「未实现」，不要写猜测的提交逻辑。
+
+签名刻意保留：runner 把这一层当接口缝用，等真实账号 + 真实站点把每个动作
+实现填进来后，主循环逻辑不需要改动。
+
+实现方需要补齐的实测点（规格 §10）：
+1. 自动付款是否触发 3D Secure / 短信验证。触发则这条路走不通，付款环节改为
+   「下单到 awaiting_payment + 上报 needs_human 交人工」。
+2. 下单确认页的实际应付金额、付款方式、付款期限、站点订单号各自在哪个字段。
+3. 订单列表页能否按商品 + 时间窗口可靠地反查「这单下没下」。
+4. ラクマ 侧尚无加购契约（README 已注明未实现）。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from app.trading.worker.models import LeaseTask
+
+
+_NOT_IMPLEMENTED_MSG = (
+    "站点交互未实现：见 docs/order-gateway.md §10。"
+    "未实测前不写猜测的提交逻辑——需要真实账号 + 真实站点把这一步实现填进来。"
+)
+
+
+@dataclass(slots=True)
+class CheckoutSummary:
+    """下单确认页解析结果（待实测确认字段位置）
+
+    payable_yen 用于金额守卫；其他字段在实测确认后补全。
+    """
+
+    payable_yen: int
+    site_order_id: str | None = None
+    pay_deadline: str | None = None
+
+
+async def add_to_cart(task: LeaseTask) -> None:
+    """加购。需要 auth_session 的登录 cookie + intent 里的 purchase 标识"""
+    raise NotImplementedError(_NOT_IMPLEMENTED_MSG)
+
+
+async def verify_cart(task: LeaseTask) -> None:
+    """校验购物车：加购后购物车里有没有这件商品"""
+    raise NotImplementedError(_NOT_IMPLEMENTED_MSG)
+
+
+async def enter_checkout(task: LeaseTask) -> str:
+    """进入下单确认页，返回页面 HTML（供解析金额守卫所需字段）"""
+    raise NotImplementedError(_NOT_IMPLEMENTED_MSG)
+
+
+async def parse_checkout(html: str) -> CheckoutSummary:
+    """从下单确认页解析实际应付金额、付款期限、站点订单号"""
+    raise NotImplementedError(_NOT_IMPLEMENTED_MSG)
+
+
+async def submit_order(task: LeaseTask) -> str:
+    """提交下单。返回站点订单号（site_order_id）"""
+    raise NotImplementedError(_NOT_IMPLEMENTED_MSG)
+
+
+async def pay(task: LeaseTask, site_order_id: str) -> None:
+    """付款。检测到 3DS / 短信验证等人工环节时抛 OrderGuardError"""
+    raise NotImplementedError(_NOT_IMPLEMENTED_MSG)
+
+
+async def monitor(task: LeaseTask, site_order_id: str) -> None:
+    """付款后监控：常驻轮询订单状态与付款期限，状态变化时继续 report"""
+    raise NotImplementedError(_NOT_IMPLEMENTED_MSG)

app/trading/worker/verify.py

@@ -0,0 +1,46 @@
+"""恢复核对：lease_count > 1 时，worker 必须先查站点订单列表确认是否已下单
+
+规格 §5：租约过期 → stale → reclaim 后 worker 领回的任务 lease_count 必然 > 1。
+此时 worker 不能盲目重新提交（可能上次已经下单成功，只是回报断网），必须先查
+站点订单列表比对。
+
+订单列表反查的实现需要实测（规格 §10 第 3 条：订单列表页能否按商品 + 时间窗口
+可靠地反查出「这单下没下」）。当前为桩：恒返回 `unknown`，让 runner 走
+needs_human 分支。**绝不**默认按「没下单」处理——那是猜，可能变成重复下单。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from app.trading.worker.models import LeaseTask
+
+
+class VerifyVerdict(StrEnum):
+    """核对结论"""
+
+    ALREADY_ORDERED = "already_ordered"  # 确认已下单，补报状态即可
+    NOT_ORDERED = "not_ordered"  # 确认未下单，可重新执行
+    UNKNOWN = "unknown"  # 核对不出结论，交人工
+
+
+@dataclass(slots=True)
+class VerifyResult:
+    verdict: VerifyVerdict
+    site_order_id: str | None = None
+    detail: str = ""
+
+
+async def verify_on_site(task: LeaseTask) -> VerifyResult:
+    """核对一笔任务是否已在站点上下过单
+
+    桩实现：永远返回 UNKNOWN。**绝不返回 NOT_ORDERED**——除非真实订单列表反查
+    能可靠证明这一点，否则视为「无法判断」交人工，宁可卡住等人看一眼。
+
+    实现方需要补的实测：用 intent 里的商品 + 时间窗口（created_at 到 stale 之间）
+    比对订单列表，能拿到 site_order_id 最好。
+    """
+    return VerifyResult(
+        verdict=VerifyVerdict.UNKNOWN,
+        detail="订单列表反查未实现：见 docs/order-gateway.md §10 第 3 条",
+    )