99 lines
3.2 KiB
Python
99 lines
3.2 KiB
Python
|
"""订单状态机 (T4.1)
|
|||
|
|
|
|||
|
|
6 态状态机：pending → paid → serving → delivered → completed；
|
|||
|
|
任何阶段可转入 refunded。completed / refunded 为终态。
|
|||
|
|
|
|||
|
|
非法转换抛 InvalidStateTransition；DAO 层捕获后回滚事务。
|
|||
|
|
"""
|
|||
|
|
|
|||
|
|
from __future__ import annotations
|
|||
|
|
|
|||
|
|
from enum import Enum
|
|||
|
|
|
|||
|
|
|
|||
|
|
class OrderStatus(str, Enum):
|
|||
|
|
"""订单 6 态枚举（继承 str 以便直接写入 SQLite / JSON）。"""
|
|||
|
|
|
|||
|
|
PENDING = "pending"
|
|||
|
|
PAID = "paid"
|
|||
|
|
SERVING = "serving"
|
|||
|
|
DELIVERED = "delivered"
|
|||
|
|
COMPLETED = "completed"
|
|||
|
|
REFUNDED = "refunded"
|
|||
|
|
|
|||
|
|
|
|||
|
|
TERMINAL_STATUSES: frozenset[str] = frozenset(
|
|||
|
|
{OrderStatus.COMPLETED.value, OrderStatus.REFUNDED.value}
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
|
|||
|
|
# 合法状态转换：单向推进 + 任意阶段可退款
|
|||
|
|
ALLOWED_TRANSITIONS: dict[str, frozenset[str]] = {
|
|||
|
|
OrderStatus.PENDING.value: frozenset(
|
|||
|
|
{OrderStatus.PAID.value, OrderStatus.REFUNDED.value}
|
|||
|
|
),
|
|||
|
|
OrderStatus.PAID.value: frozenset(
|
|||
|
|
{OrderStatus.SERVING.value, OrderStatus.REFUNDED.value}
|
|||
|
|
),
|
|||
|
|
OrderStatus.SERVING.value: frozenset(
|
|||
|
|
{OrderStatus.DELIVERED.value, OrderStatus.REFUNDED.value}
|
|||
|
|
),
|
|||
|
|
OrderStatus.DELIVERED.value: frozenset(
|
|||
|
|
{OrderStatus.COMPLETED.value, OrderStatus.REFUNDED.value}
|
|||
|
|
),
|
|||
|
|
OrderStatus.COMPLETED.value: frozenset(),
|
|||
|
|
OrderStatus.REFUNDED.value: frozenset(),
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
|
|||
|
|
class InvalidStateTransition(ValueError):
|
|||
|
|
"""非法状态转换时抛出。"""
|
|||
|
|
|
|||
|
|
|
|||
|
|
def is_known_status(status: str) -> bool:
|
|||
|
|
"""判断字符串是否为已定义的 6 态之一。"""
|
|||
|
|
return status in {s.value for s in OrderStatus}
|
|||
|
|
|
|||
|
|
|
|||
|
|
def is_terminal(status: str) -> bool:
|
|||
|
|
"""判断状态是否为终态（completed / refunded）。"""
|
|||
|
|
return status in TERMINAL_STATUSES
|
|||
|
|
|
|||
|
|
|
|||
|
|
def is_valid_transition(from_status: str, to_status: str) -> bool:
|
|||
|
|
"""判断 from → to 是否为合法转换。
|
|||
|
|
|
|||
|
|
- 已知状态但非法转换 → False
|
|||
|
|
- 未知状态 → False（不抛异常，DAO 层需先校验状态合法性）
|
|||
|
|
"""
|
|||
|
|
if not (is_known_status(from_status) and is_known_status(to_status)):
|
|||
|
|
return False
|
|||
|
|
if from_status == to_status:
|
|||
|
|
# 相同状态视为非法（避免无意义的状态写入历史表）
|
|||
|
|
return False
|
|||
|
|
return to_status in ALLOWED_TRANSITIONS[from_status]
|
|||
|
|
|
|||
|
|
|
|||
|
|
def assert_valid_transition(from_status: str, to_status: str) -> None:
|
|||
|
|
"""校验状态转换合法性，非法时抛 InvalidStateTransition。"""
|
|||
|
|
if not is_known_status(from_status):
|
|||
|
|
raise InvalidStateTransition(f"未知起始状态: {from_status!r}")
|
|||
|
|
if not is_known_status(to_status):
|
|||
|
|
raise InvalidStateTransition(f"未知目标状态: {to_status!r}")
|
|||
|
|
if from_status == to_status:
|
|||
|
|
raise InvalidStateTransition(
|
|||
|
|
f"状态相同无需转换: {from_status!r} → {to_status!r}"
|
|||
|
|
)
|
|||
|
|
if to_status not in ALLOWED_TRANSITIONS[from_status]:
|
|||
|
|
allowed = sorted(ALLOWED_TRANSITIONS[from_status])
|
|||
|
|
raise InvalidStateTransition(
|
|||
|
|
f"非法状态转换: {from_status!r} → {to_status!r}（允许: {allowed}）"
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
|
|||
|
|
def next_states(from_status: str) -> frozenset[str]:
|
|||
|
|
"""返回 from_status 的所有合法下一状态（用于前端展示）。"""
|
|||
|
|
if not is_known_status(from_status):
|
|||
|
|
return frozenset()
|
|||
|
|
return ALLOWED_TRANSITIONS[from_status]
|