"""任务与订单状态枚举：网关与本地 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"