rakuten-api/app/gateway/api/routes/orders.py

"""下单任务网关路由

承担规格 §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

    网关只做任务队列与状态镜像：intent 原文存库，由本地 worker 出站长轮询领走
    （GET /api/orders/lease），真正的加购、下单、付款都在本地机完成。

    幂等：同一个 task_id 重复提交不新建任务，返回既有任务且 created=false——
    上游重发不会变成两单。下单不可逆，这是防重复下单的第一道闸。

    可带 callback_url：任务到达终态（succeeded / failed / needs_human）或被置
    stale 时，网关向该地址 POST 一条 JSON 通知（best-effort 单次投递，§4.8）。
    幂等重发不会更新既有任务的回调地址。

    提交后任务为 queued。进度跟踪用 GET /api/orders/{task_id}（任务状态 +
    完整状态历史）；任务状态词汇表：queued / leased / running / succeeded /
    failed / needs_human / stale。
    """
    data = await container.task_queue.submit(
        task_id=payload.task_id,
        site=payload.site,
        intent=payload.intent,
        callback_url=payload.callback_url,
    )
    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(..., description="worker 标识，每次调用刷新心跳"),
    wait: int = Query(
        default=30, ge=0, le=300,
        description="无任务时的挂起秒数。服务端上限 RAKUTEN_LEASE_MAX_WAIT_SECONDS（默认 60）",
    ),
    site: str | None = Query(default=None, description="限定站点（rakuten）；不传不限"),
    container: GatewayContainer = Depends(get_container),
) -> ApiResponse[LeaseData | None]:
    """本地长轮询领取下单任务（worker 专用）

    - 每次调用刷新 worker 心跳（workers.last_seen_at），不另建心跳接口。
    - **全局并发度 1**：已存在 leased / running 任务时立即返回空，绝不发第二个任务。
    - 有可领任务时原子置 queued → leased，写入 lease_owner 与过期时间
      （TTL 由 RAKUTEN_LEASE_TTL_SECONDS 控制，默认 300 秒），lease_count += 1。
    - 无任务时挂起至多 wait 秒再返回，HTTP 仍 200、data 为 null。
    - 响应 lease_count > 1 只可能来自 reclaim（正常 lease 拿不到 stale 任务）。
    """
    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)],
    responses={
        404: {"description": "任务不存在（错误码 6001）"},
        409: {"description": "租约无效：不是持有者或任务已终结（错误码 6002）"},
    },
)
async def renew_order(
    task_id: str,
    payload: RenewRequest,
    container: GatewayContainer = Depends(get_container),
) -> ApiResponse[RenewData]:
    """续租（worker 专用）

    执行时间可能超过租约 TTL（下单页面慢、付款要等），worker 在长任务中每 60 秒
    调一次，避免租约过期被误判成 stale。
    """
    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)],
    responses={
        404: {"description": "任务不存在（错误码 6001）"},
        409: {"description": "租约无效或终态冲突（错误码 6002 / 6003）"},
    },
)
async def report_order(
    task_id: str,
    payload: ReportRequest,
    container: GatewayContainer = Depends(get_container),
) -> ApiResponse[ReportData]:
    """本地回报订单状态（worker 专用）

    worker 每一步遵循「动作 → 落证据 → 写本地库 → 回报」，先落证据再回报，
    保证服务器上看到的状态一定有本地证据可查。

    - worker_id 必须是当前租约持有者，否则 6002。
    - 首次 report 把任务从 leased 推到 running。
    - 同一 (task_id, state) 重复上报幂等（覆盖同一行，recorded=false），
      网络抖动重发安全。
    - terminal=true 时释放租约并推到终态：terminal_status 显式指定优先，否则按
      state 推断（paid→succeeded，cancelled→failed，其余→needs_human）。
    """
    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)],
    responses={
        404: {"description": "任务不存在（错误码 6001）"},
        409: {"description": "任务不是 stale 状态（错误码 6003）"},
    },
)
async def reclaim_order(
    task_id: str,
    payload: ReclaimRequest,
    container: GatewayContainer = Depends(get_container),
) -> ApiResponse[ReclaimData]:
    """把 stale 任务重新租给 worker（恢复领取，绝不自动重投）

    租约过期后任务置 stale 并告警，**不回 queued、不会被正常 lease 取到**——本地
    可能已经下单成功、只是回报那一步断网，自动重投等于再买一次。恢复只能显式
    调本接口。

    返回体的 lease_count 必然 > 1 且带 known_state（租约丢失前的最新订单状态）。
    worker 执行前**必须先核对站点订单列表**（用 intent 里的商品 + 时间窗口比对）：
    确认已下单则直接补报状态，核对不出结论报 needs_human，绝不重新提交。

    仅 stale 状态可 reclaim；其他状态报 6003。
    """
    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)],
    responses={404: {"description": "任务不存在（错误码 6001）"}},
)
async def get_order(
    task_id: str,
    container: GatewayContainer = Depends(get_container),
) -> ApiResponse[TaskDetail]:
    """任务详情 + 完整状态历史

    返回任务本体（status / 租约信息 / intent 原文）、latest_state（最新一次上报的
    订单状态）与 reports（append-only 状态历史，含金额、付款期限、站点订单号、
    证据路径）。任务不存在报 6001。
    """
    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,
        description="按任务状态筛选：queued / leased / running / succeeded / failed / needs_human / stale",
    ),
    site: str | None = Query(default=None, description="按站点筛选（rakuten）"),
    limit: int = Query(default=50, ge=1, le=500, description="分页大小"),
    offset: int = Query(default=0, ge=0, description="分页偏移"),
    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)