476 lines
18 KiB
Python
476 lines
18 KiB
Python
"""order_site 订单读取适配层(P0)。
|
||
|
||
**全项目唯一允许出现跨库 SQL 的地方。** order_site 是别人的生产库,表结构
|
||
随时可能变;把所有 PG 查询收在这一个文件,将来换数据源只改这里。
|
||
|
||
设计约束(规划 §6.5 / §6.5.1):
|
||
|
||
- **只读**:账号 `livehub_ro` 本身是 SELECT-only + `default_transaction_read_only`,
|
||
这里再叠一层 `statement_timeout`,避免慢查询拖住对方库;
|
||
- **极小连接池**:独立引擎、2 条连接,绝不影响本系统主库连接池;
|
||
- **可降级**:`ORDER_SITE_LOOKUP_ENABLED=false` 或未配 URL 时整体不查外部,
|
||
主流程退化成客服手工填写;
|
||
- **route 按订单号维度聚合**:同一个 `platform_order_id` 在 order_site 里有
|
||
541 组重复(发货方内部行 + 真实店铺行),任一行已发货即算 `auto_fulfilled`,
|
||
否则这 540 个已发货订单会被误判成「没人管」而重复履约。
|
||
|
||
对外只暴露 :func:`lookup_order`,业务代码只认语义化的 `route`,不认 SQL。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
import json
|
||
import os
|
||
from datetime import UTC, datetime, timedelta
|
||
from typing import Any
|
||
|
||
from loguru import logger
|
||
from sqlalchemy import Engine, create_engine, text
|
||
|
||
CACHE_TTL = timedelta(hours=24)
|
||
|
||
ROUTE_UNHANDLED = "unhandled"
|
||
ROUTE_AUTO_FULFILLED = "auto_fulfilled"
|
||
ROUTE_WORKER_PLATFORM = "worker_platform"
|
||
PLATFORM_FULFILLMENT_SOURCE = "order_site"
|
||
|
||
# 发货方内部行:同一订单号下与真实店铺行成对出现,其 sku_code 是内部编码
|
||
# (如 suit_shadow_gothic),不能用来回显给买家。
|
||
INTERNAL_SHOP_ID = "91kaquan"
|
||
|
||
_ENGINE: Engine | None = None
|
||
_INITIALIZED = False
|
||
|
||
|
||
class OrderLookupUnavailable(Exception):
|
||
"""外部订单库不可用(未配置 / 关闭 / 连不上 / 查询失败)。
|
||
|
||
调用方应据此走降级:允许提交但标记 `order_unverified`,交人工确认。
|
||
"""
|
||
|
||
|
||
def _env_flag(name: str, default: bool = False) -> bool:
|
||
return os.getenv(name, "").strip().lower() in {"1", "true", "yes", "on"}
|
||
|
||
|
||
def _enabled() -> bool:
|
||
"""是否启用外部查询。未配置连接串时一律关闭。"""
|
||
if not os.getenv("ORDER_SITE_DATABASE_URL", "").strip():
|
||
return False
|
||
return _env_flag("ORDER_SITE_LOOKUP_ENABLED", False)
|
||
|
||
|
||
def _normalize_url(url: str) -> str:
|
||
"""把 `postgresql://` 归一成带驱动的 `postgresql+psycopg://`。
|
||
|
||
`.env` 里写的是不带驱动的裸 URL,SQLAlchemy 2 会去猜默认驱动;显式指定
|
||
能避免容器里驱动缺失时报出含糊的错误。
|
||
"""
|
||
if url.startswith("postgresql://"):
|
||
return "postgresql+psycopg://" + url[len("postgresql://") :]
|
||
return url
|
||
|
||
|
||
def _get_engine() -> Engine:
|
||
"""惰性创建(且只创建一次)外部只读引擎。
|
||
|
||
``_INITIALIZED`` 只在引擎真正建出来之后才置位 —— 否则一次「未配置」就会
|
||
把这个模块永久毒化成不可用,之后补上连接串也救不回来。
|
||
"""
|
||
global _ENGINE, _INITIALIZED
|
||
if _ENGINE is not None:
|
||
return _ENGINE
|
||
|
||
raw = os.getenv("ORDER_SITE_DATABASE_URL", "").strip()
|
||
if not raw:
|
||
raise OrderLookupUnavailable("ORDER_SITE_DATABASE_URL 未配置")
|
||
|
||
timeout_ms = int(float(os.getenv("ORDER_SITE_LOOKUP_TIMEOUT_SECONDS", "3")) * 1000)
|
||
engine = create_engine(
|
||
_normalize_url(raw),
|
||
pool_size=2,
|
||
max_overflow=0,
|
||
pool_timeout=timeout_ms / 1000,
|
||
pool_recycle=1800,
|
||
pool_pre_ping=True,
|
||
connect_args={
|
||
# 双保险:账号级已设 statement_timeout,这里再按连接设一次。
|
||
"options": f"-c statement_timeout={timeout_ms}",
|
||
},
|
||
)
|
||
_ENGINE = engine
|
||
_INITIALIZED = True
|
||
return _ENGINE
|
||
|
||
|
||
def reset_engine() -> None:
|
||
"""丢弃已缓存的引擎(测试或配置变更后用)。"""
|
||
global _ENGINE, _INITIALIZED
|
||
if _ENGINE is not None:
|
||
_ENGINE.dispose()
|
||
_ENGINE = None
|
||
_INITIALIZED = False
|
||
|
||
|
||
def _fetch_rows(order_no: str) -> list[dict[str, Any]]:
|
||
"""按订单号取全部行(通常 1 行,重复订单号 2 行)。
|
||
|
||
只走 `idx_orders_platform_order_id` 单行索引查询,禁止全表扫描与聚合。
|
||
"""
|
||
engine = _get_engine()
|
||
# 一个订单号最多几行,限 10 防止异常数据把结果撑爆。
|
||
sql = text(
|
||
"""
|
||
SELECT o.id AS source_order_id,
|
||
o.platform AS platform,
|
||
o.provider AS provider,
|
||
o.shop_id AS shop_id,
|
||
o.order_status AS order_status,
|
||
oi.sku_code AS sku_code,
|
||
oi.sku_name AS sku_name,
|
||
oi.quantity AS quantity,
|
||
oi.spec_json AS spec_json,
|
||
EXISTS (SELECT 1 FROM fulfillment_tasks ft WHERE ft.order_id = o.id)
|
||
AS has_fulfillment,
|
||
EXISTS (SELECT 1 FROM work_orders wo WHERE wo.order_id = o.id)
|
||
AS has_work_order
|
||
FROM orders o
|
||
LEFT JOIN order_items oi ON oi.order_id = o.id
|
||
WHERE o.platform_order_id = :order_no
|
||
ORDER BY o.id DESC
|
||
LIMIT 10
|
||
"""
|
||
)
|
||
try:
|
||
with engine.connect() as conn:
|
||
return [
|
||
dict(row)
|
||
for row in conn.execute(sql, {"order_no": order_no}).mappings()
|
||
]
|
||
except Exception as exc:
|
||
logger.warning(f"查询 order_site 失败(订单号 {order_no}):{exc}")
|
||
raise
|
||
|
||
|
||
def _fetch_pending_manual_fulfillments(limit: int = 100) -> list[dict[str, Any]]:
|
||
"""读取最近的人工渠道待履约订单项。
|
||
|
||
是否由直播账号履约由 live-hub 本地商品映射决定,不修改 order_site 配置。
|
||
"""
|
||
engine = _get_engine()
|
||
sql = text(
|
||
"""
|
||
SELECT o.id AS source_order_id,
|
||
o.platform_order_id,
|
||
o.provider,
|
||
o.platform,
|
||
o.shop_id,
|
||
o.shop_name,
|
||
o.order_status,
|
||
o.pay_status,
|
||
o.total_amount,
|
||
o.paid_at,
|
||
o.updated_at AS order_updated_at,
|
||
oi.id AS source_order_item_id,
|
||
oi.sku_code,
|
||
oi.sku_name,
|
||
oi.quantity,
|
||
oi.revenue_amount_fen,
|
||
oi.manual_sku_key,
|
||
oi.spec_json,
|
||
oi.updated_at AS item_updated_at,
|
||
f.id AS source_fulfillment_id,
|
||
f.channel AS fulfillment_channel,
|
||
f.status AS fulfillment_status,
|
||
f.issue_code AS fulfillment_issue_code
|
||
FROM orders o
|
||
JOIN order_items oi ON oi.order_id = o.id
|
||
JOIN fulfillments f ON f.order_item_id = oi.id
|
||
WHERE f.channel = 'manual'
|
||
AND f.status = 'assigned'
|
||
AND o.pay_status = 'paid'
|
||
AND o.order_status NOT IN ('refunded', 'cancelled', 'closed')
|
||
AND oi.quantity = 1
|
||
AND COALESCE(f.issue_code, '') NOT IN ('user_refund', 'platform_cancelled')
|
||
ORDER BY oi.updated_at DESC NULLS LAST, oi.id DESC
|
||
LIMIT :limit
|
||
"""
|
||
)
|
||
try:
|
||
with engine.connect() as conn:
|
||
return [
|
||
dict(row)
|
||
for row in conn.execute(
|
||
sql, {"limit": max(1, min(limit, 500))}
|
||
).mappings()
|
||
]
|
||
except Exception as exc:
|
||
logger.warning(f"查询 order_site 人工待履约订单失败:{exc}")
|
||
raise
|
||
|
||
|
||
def list_pending_manual_fulfillments(limit: int = 100) -> list[dict[str, Any]]:
|
||
"""返回最近的人工渠道待履约订单项快照。"""
|
||
if not _enabled():
|
||
raise OrderLookupUnavailable("外部订单查询未启用")
|
||
result: list[dict[str, Any]] = []
|
||
for row in _fetch_pending_manual_fulfillments(limit=limit):
|
||
internal_sku_key = str(
|
||
row.get("manual_sku_key")
|
||
or row.get("sku_name")
|
||
or row.get("sku_code")
|
||
or ""
|
||
).strip()
|
||
result.append(
|
||
{
|
||
"source_system": PLATFORM_FULFILLMENT_SOURCE,
|
||
"source_order_id": str(row.get("source_order_id") or ""),
|
||
"source_order_item_id": str(row.get("source_order_item_id") or ""),
|
||
"source_fulfillment_id": str(row.get("source_fulfillment_id") or ""),
|
||
"platform_order_id": str(row.get("platform_order_id") or ""),
|
||
"provider": str(row.get("provider") or ""),
|
||
"platform": str(row.get("platform") or ""),
|
||
"shop_id": str(row.get("shop_id") or ""),
|
||
"shop_name": str(row.get("shop_name") or ""),
|
||
"order_status": str(row.get("order_status") or ""),
|
||
"pay_status": str(row.get("pay_status") or ""),
|
||
"total_amount": int(row.get("total_amount") or 0),
|
||
"revenue_amount_fen": int(row.get("revenue_amount_fen") or 0),
|
||
"paid_at": row.get("paid_at"),
|
||
"sku_code": str(row.get("sku_code") or ""),
|
||
"sku_name": str(row.get("sku_name") or ""),
|
||
"internal_sku_key": internal_sku_key,
|
||
"quantity": int(row.get("quantity") or 1),
|
||
"spec_json": row.get("spec_json"),
|
||
"item_updated_at": row.get("item_updated_at"),
|
||
}
|
||
)
|
||
return result
|
||
|
||
|
||
def _route_of(rows: list[dict[str, Any]]) -> str:
|
||
"""订单号维度的聚合判定:任一行已处理即算已处理。"""
|
||
if any(row["has_fulfillment"] for row in rows):
|
||
return ROUTE_AUTO_FULFILLED
|
||
if any(row["has_work_order"] for row in rows):
|
||
return ROUTE_WORKER_PLATFORM
|
||
return ROUTE_UNHANDLED
|
||
|
||
|
||
def _spec_of(spec_json: Any) -> dict[str, Any]:
|
||
"""spec_json 可能是 dict(jsonb 已解析)或字符串,统一成 dict。"""
|
||
if isinstance(spec_json, dict):
|
||
return spec_json
|
||
if isinstance(spec_json, str) and spec_json.strip():
|
||
import json
|
||
|
||
try:
|
||
loaded = json.loads(spec_json)
|
||
except ValueError:
|
||
return {}
|
||
return loaded if isinstance(loaded, dict) else {}
|
||
return {}
|
||
|
||
|
||
def _pick_display_row(rows: list[dict[str, Any]]) -> dict[str, Any]:
|
||
"""回显优先取真实店铺行,跳过发货方内部行。"""
|
||
for row in rows:
|
||
if row.get("shop_id") != INTERNAL_SHOP_ID:
|
||
return row
|
||
return rows[0]
|
||
|
||
|
||
def _build_result(order_no: str, rows: list[dict[str, Any]]) -> dict[str, Any]:
|
||
row = _pick_display_row(rows)
|
||
spec = _spec_of(row.get("spec_json"))
|
||
return {
|
||
"order_no": order_no,
|
||
"source_order_id": str(row.get("source_order_id") or ""),
|
||
"platform": row.get("platform") or "",
|
||
"provider": row.get("provider") or "",
|
||
"shop_id": row.get("shop_id") or "",
|
||
"order_status": row.get("order_status") or "",
|
||
"sku_code": row.get("sku_code") or "",
|
||
"sku_name": row.get("sku_name") or "",
|
||
"quantity": row.get("quantity"),
|
||
"route": _route_of(rows),
|
||
# SKU 定位键(规划 §3.6):优先 spec_json,sku_code 兜底。
|
||
"seller_id": str(spec.get("sellerId") or ""),
|
||
"rel_item_id": str(spec.get("relItemId") or ""),
|
||
"rel_sku_id": str(spec.get("relSkuId") or spec.get("skuId") or ""),
|
||
"sku_nick": str(spec.get("skuNick") or ""),
|
||
"item_title": str(spec.get("itemTitle") or ""),
|
||
"cached": False,
|
||
"error": None,
|
||
}
|
||
|
||
|
||
def lookup_order(order_no: str, use_cache: bool = True) -> dict[str, Any]:
|
||
"""按订单号查订单,返回语义化结果。
|
||
|
||
- 命中缓存且未过期 → 直接返回(`cached=True`);
|
||
- 未命中 → 查 PG → 回写缓存;
|
||
- 外部不可用 → 抛 :class:`OrderLookupUnavailable`(调用方走降级)。
|
||
|
||
订单号不存在时返回 `route=unhandled` 且各字段为空,由调用方按
|
||
「订单号不存在」提示(见 §6.4)。
|
||
"""
|
||
order_no = (order_no or "").strip()
|
||
if not order_no:
|
||
raise OrderLookupUnavailable("订单号为空")
|
||
|
||
if not _enabled():
|
||
raise OrderLookupUnavailable("外部订单查询未启用")
|
||
|
||
if use_cache:
|
||
cached = _read_cache(order_no)
|
||
if cached is not None:
|
||
return cached
|
||
|
||
try:
|
||
rows = _fetch_rows(order_no)
|
||
except Exception as exc:
|
||
# 降级保证落在公开入口这一层:外部库任何异常(连不上、超时、权限、
|
||
# 表结构变了)都统一成「不可用」,调用方据此走人工确认,而不是把
|
||
# 原始异常抛给用户。
|
||
logger.warning(f"订单查询不可用({order_no}):{exc}")
|
||
raise OrderLookupUnavailable(str(exc)) from exc
|
||
|
||
if not rows:
|
||
raise OrderLookupUnavailable("订单号不存在")
|
||
|
||
result = _build_result(order_no, rows)
|
||
_write_cache(result)
|
||
return result
|
||
|
||
|
||
def _read_cache(order_no: str) -> dict[str, Any] | None:
|
||
"""读本地快照,未过期才用。缓存读写失败不影响主流程。"""
|
||
from web.backend.database import SessionLocal
|
||
|
||
try:
|
||
with SessionLocal() as session:
|
||
row = (
|
||
session.execute(
|
||
text(
|
||
"""
|
||
SELECT source_order_id, platform, provider, shop_id,
|
||
order_status, sku_code, sku_name, quantity, route,
|
||
seller_id, rel_item_id, rel_sku_id, sku_nick,
|
||
item_title, fetched_at
|
||
FROM external_order_cache
|
||
WHERE platform_order_id = :order_no
|
||
ORDER BY fetched_at DESC
|
||
LIMIT 1
|
||
"""
|
||
),
|
||
{"order_no": order_no},
|
||
)
|
||
.mappings()
|
||
.first()
|
||
)
|
||
except Exception as exc: # noqa: BLE001 - 缓存不可用就当没命中
|
||
logger.warning(f"读取订单快照失败:{exc}")
|
||
return None
|
||
|
||
if row is None:
|
||
return None
|
||
|
||
fetched_at = row["fetched_at"]
|
||
if fetched_at is not None:
|
||
if fetched_at.tzinfo is None:
|
||
fetched_at = fetched_at.replace(tzinfo=UTC)
|
||
if datetime.now(UTC) - fetched_at > CACHE_TTL:
|
||
return None
|
||
|
||
return {
|
||
"order_no": order_no,
|
||
"source_order_id": str(row["source_order_id"] or ""),
|
||
"platform": row["platform"] or "",
|
||
"provider": row["provider"] or "",
|
||
"shop_id": row["shop_id"] or "",
|
||
"order_status": row["order_status"] or "",
|
||
"sku_code": row["sku_code"] or "",
|
||
"sku_name": row["sku_name"] or "",
|
||
"quantity": row["quantity"],
|
||
"route": row["route"] or "",
|
||
"seller_id": row["seller_id"] or "",
|
||
"rel_item_id": row["rel_item_id"] or "",
|
||
"rel_sku_id": row["rel_sku_id"] or "",
|
||
"sku_nick": row["sku_nick"] or "",
|
||
"item_title": row["item_title"] or "",
|
||
"cached": True,
|
||
"error": None,
|
||
}
|
||
|
||
|
||
def _write_cache(result: dict[str, Any]) -> None:
|
||
"""回写快照。写失败只记日志 —— 缓存不是业务数据。"""
|
||
from web.backend.database import SessionLocal
|
||
|
||
sql = text(
|
||
"""
|
||
INSERT INTO external_order_cache (
|
||
platform_order_id, source_order_id, platform, provider, shop_id,
|
||
order_status, sku_code, sku_name, quantity, route,
|
||
seller_id, rel_item_id, rel_sku_id, sku_nick, item_title,
|
||
payload, fetched_at
|
||
) VALUES (
|
||
:platform_order_id, :source_order_id, :platform, :provider, :shop_id,
|
||
:order_status, :sku_code, :sku_name, :quantity, :route,
|
||
:seller_id, :rel_item_id, :rel_sku_id, :sku_nick, :item_title,
|
||
:payload, :fetched_at
|
||
)
|
||
ON DUPLICATE KEY UPDATE
|
||
platform = VALUES(platform),
|
||
provider = VALUES(provider),
|
||
shop_id = VALUES(shop_id),
|
||
order_status = VALUES(order_status),
|
||
sku_code = VALUES(sku_code),
|
||
sku_name = VALUES(sku_name),
|
||
quantity = VALUES(quantity),
|
||
route = VALUES(route),
|
||
seller_id = VALUES(seller_id),
|
||
rel_item_id = VALUES(rel_item_id),
|
||
rel_sku_id = VALUES(rel_sku_id),
|
||
sku_nick = VALUES(sku_nick),
|
||
item_title = VALUES(item_title),
|
||
payload = VALUES(payload),
|
||
fetched_at = VALUES(fetched_at)
|
||
"""
|
||
)
|
||
payload = json.dumps(
|
||
{
|
||
"platform": result["platform"],
|
||
"provider": result["provider"],
|
||
"shop_id": result["shop_id"],
|
||
"order_status": result["order_status"],
|
||
},
|
||
ensure_ascii=False,
|
||
)
|
||
params = {
|
||
"platform_order_id": result["order_no"],
|
||
"source_order_id": result["source_order_id"],
|
||
"platform": result["platform"],
|
||
"provider": result["provider"],
|
||
"shop_id": result["shop_id"],
|
||
"order_status": result["order_status"],
|
||
"sku_code": result["sku_code"],
|
||
"sku_name": result["sku_name"],
|
||
"quantity": result["quantity"],
|
||
"route": result["route"],
|
||
"seller_id": result["seller_id"],
|
||
"rel_item_id": result["rel_item_id"],
|
||
"rel_sku_id": result["rel_sku_id"],
|
||
"sku_nick": result["sku_nick"],
|
||
"item_title": result["item_title"],
|
||
"payload": payload,
|
||
"fetched_at": datetime.now(UTC).replace(tzinfo=None),
|
||
}
|
||
try:
|
||
with SessionLocal() as session:
|
||
session.execute(sql, params)
|
||
session.commit()
|
||
except Exception as exc: # noqa: BLE001
|
||
logger.warning(f"写入订单快照失败:{exc}")
|