shopping-cli 3.0.0__py3-none-any.whl

shopping_cli/api/handlers/erp.py

@@ -0,0 +1,127 @@
+"""ERP 同步 API handler（shopping-cli v0.3 §3/#3；MVP #3 接线）。
+
+POST /v1/merchant/erp/sync —— admin 或 merchant token 触发的 ERP 商品同步
+（写面鉴权与 /products 一致；结果 = ErpSyncReport，含 fetched/upserted/
+conflicts/errors；网络/结构错误 fail-closed 返回 200+ok:false 信封）。
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+from shopping_cli.api import auth as api_auth
+from shopping_cli.core.catalog import require_merchant
+from shopping_cli.core.errors import PermissionDenied, RateLimitError, ValidationError
+from shopping_cli.data_sources.erp_source import (
+    ErpSourceError,
+    ErpSyncConfig,
+    sync_erp_products,
+)
+from shopping_cli.db.session import db_session
+from shopping_cli.services import tokens as token_service
+
+# per-merchant 同步限流：每次同步含无界网络拉取（有分页上限兜底），并发
+# 同步还会竞争同一批行（last-write-wins）。进程内固定窗口即可——单进程
+# 部署（FastAPI threadpool + fallback ASGI 同一进程）。
+_ERP_SYNC_RATE_LIMIT_PER_MINUTE = 3
+_ERP_SYNC_WINDOW_SECONDS = 60
+_erp_sync_lock = threading.Lock()
+_erp_sync_buckets: dict[str, tuple[float, int]] = {}
+
+
+def _enforce_erp_sync_rate_limit(actor_key: str) -> None:
+    now = time.monotonic()
+    with _erp_sync_lock:
+        window_start, count = _erp_sync_buckets.get(actor_key, (0.0, 0))
+        if now - window_start >= _ERP_SYNC_WINDOW_SECONDS:
+            window_start, count = now, 0
+        if count >= _ERP_SYNC_RATE_LIMIT_PER_MINUTE:
+            raise RateLimitError(
+                f"erp sync rate limit exceeded ({_ERP_SYNC_RATE_LIMIT_PER_MINUTE}/minute)"
+            )
+        _erp_sync_buckets[actor_key] = (window_start, count + 1)
+
+
+def _bounded_int(payload: dict[str, Any], key: str, default: int, lo: int, hi: int) -> int:
+    """读整数参数；非数字输入 fail-closed 抛 ValidationError（不落到 500）。"""
+    raw = payload.get(key)
+    if raw is None or raw == "":
+        return default
+    try:
+        value = int(raw)
+    except (TypeError, ValueError) as exc:
+        raise ValidationError(f"{key} must be an integer") from exc
+    return max(lo, min(value, hi))
+
+
+def sync_erp(db_path: str | Path, payload: dict[str, Any]) -> dict[str, Any]:
+    """POST /v1/merchant/erp/sync —— 手动触发 ERP 同步（同步本身可重复执行）。"""
+    base_url = str(payload.get("base_url") or "").strip()
+    if not base_url:
+        raise ValidationError("base_url is required")
+
+    with db_session(db_path) as conn:
+        # 鉴权：admin token 或 merchant token（写面，与 /products 一致）。
+        # admin 判定先行（仅探测 token 有效性，无副作用），再进入各自分支，
+        # 避免 admin 分支的校验错误被误吞进 merchant 分支。
+        try:
+            api_auth.require_admin_token(payload)
+            is_admin = True
+        except Exception:
+            is_admin = False
+
+        actor: str
+        allowed_merchant_id = ""
+        default_merchant_id = str(payload.get("default_merchant_id") or "").strip()
+        if is_admin:
+            actor = "admin"
+            # admin 可任意指定默认归属，但必须真实存在（FK 防护，避免裸
+            # IntegrityError 落到 500）。
+            if default_merchant_id:
+                require_merchant(conn, default_merchant_id)
+        else:
+            merchant_id = str(payload.get("merchant_id") or "").strip()
+            if not merchant_id:
+                raise PermissionDenied("merchant_id (or admin_token) is required for ERP sync")
+            token_service.require_merchant_token(
+                conn, merchant_id, api_auth.payload_token(payload)
+            )
+            require_merchant(conn, merchant_id)
+            actor = f"merchant:{merchant_id}"
+            # 跨租户防护：merchant-token 调用者只能写入自己名下的行；调用方
+            # 传入其他 default_merchant_id 直接拒绝（fail-closed，不静默覆盖）。
+            if default_merchant_id and default_merchant_id != merchant_id:
+                raise ValidationError(
+                    f"merchant token callers may only sync into their own merchant "
+                    f"({merchant_id}); got default_merchant_id={default_merchant_id!r}"
+                )
+            default_merchant_id = merchant_id
+            allowed_merchant_id = merchant_id
+
+        # per-actor 限流：每个 merchant/admin 每分钟最多 3 次同步。
+        _enforce_erp_sync_rate_limit(actor)
+
+        config = ErpSyncConfig(
+            base_url=base_url,
+            auth_token=str(payload.get("auth_token") or "").strip(),
+            timeout_seconds=_bounded_int(payload, "timeout_seconds", 15, 1, 60),
+            page_size=_bounded_int(payload, "page_size", 100, 1, 500),
+            default_merchant_id=default_merchant_id,
+            allowed_merchant_id=allowed_merchant_id,
+        )
+        try:
+            report = sync_erp_products(conn, config)
+        except (ErpSourceError, OSError) as exc:
+            # ERP 网络/结构失败统一 fail-closed 信封（200 + ok:false）
+            return {"ok": False, "error": str(exc), "actor": actor}
+        except sqlite3.IntegrityError as exc:
+            # 数据完整性失败兜底：不落到 500，转为 4xx。
+            raise ValidationError(f"ERP sync failed integrity check: {exc}") from exc
+    result = report.as_dict()
+    result["ok"] = not result["errors"] and not result["conflicts"]
+    result["actor"] = actor
+    return result

shopping_cli/api/handlers/human_review.py

@@ -0,0 +1,293 @@
+"""Human review API handlers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from shopping_cli.api import auth as api_auth
+from shopping_cli.api.handlers.common import DEFAULT_RESULT_LIMIT, positive_whole_int, result_limit, result_offset
+from shopping_cli.core.conversations import add_flag, append_message, conversation_summary
+from shopping_cli.core.errors import AuthError, ConflictError, NotFoundError
+from shopping_cli.core.harness import append_audit_event, next_actor_for_review_reason, next_actor_for_status
+from shopping_cli.db.session import db_session, now_iso
+from shopping_cli.services import conversations as conversation_service
+from shopping_cli.services import human_review as human_review_service
+from shopping_cli.services import tokens as token_service
+
+
+def _payload_token(payload: dict[str, Any]) -> str:
+    return api_auth.payload_token(payload)
+
+
+def human_review_sender(payload: dict[str, Any]) -> str:
+    return human_review_service.human_review_sender(payload)
+
+
+def review_summary(conn: Any, flag_row: Any) -> dict[str, Any]:
+    row_keys = set(flag_row.keys()) if hasattr(flag_row, "keys") else set()
+    if {"merchant_id", "buyer_id"}.issubset(row_keys):
+        merchant_id = flag_row["merchant_id"]
+        buyer_id = flag_row["buyer_id"]
+    else:
+        conversation = conversation_summary(conn, flag_row["conversation_id"])
+        merchant_id = conversation["merchant_id"]
+        buyer_id = conversation["buyer_id"]
+    return {
+        "id": flag_row["id"],
+        "conversation_id": flag_row["conversation_id"],
+        "merchant_id": merchant_id,
+        "buyer_id": buyer_id,
+        "sku": flag_row["sku"],
+        "reason": flag_row["reason"],
+        "severity": flag_row["severity"],
+        "created_at": flag_row["created_at"],
+        "resolved_at": flag_row["resolved_at"] or None,
+        "resolution": flag_row["resolution"],
+        "resolved_by": flag_row["resolved_by"],
+    }
+
+
+def human_review_queue(
+    db_path: str | Path,
+    payload: dict[str, Any],
+    merchant_id: str = "",
+    limit: Any = DEFAULT_RESULT_LIMIT,
+    offset: Any = 0,
+) -> dict[str, Any]:
+    if not merchant_id:
+        raise AuthError("merchant_id is required for human-review queue")
+    with db_session(db_path) as conn:
+        token_service.require_merchant_read_token(conn, merchant_id, _payload_token(payload))
+        rows = human_review_service.list_unresolved_reviews(
+            conn,
+            merchant_id,
+            limit=result_limit(limit),
+            offset=result_offset(offset),
+        )
+        return {"ok": True, "reviews": [review_summary(conn, row) for row in rows]}
+
+
+def human_review_row(conn: Any, review_id: str | int) -> Any:
+    return human_review_service.human_review_row(conn, review_id, positive_whole_int)
+
+
+def get_human_review(db_path: str | Path, review_id: str | int, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        row = human_review_row(conn, review_id)
+        review = review_summary(conn, row)
+        token_service.require_merchant_read_token(conn, review["merchant_id"], _payload_token(payload))
+        return {"ok": True, "review": review, "conversation": conversation_summary(conn, review["conversation_id"])}
+
+
+def create_human_review(db_path: str | Path, conversation_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        conversation = conversation_summary(conn, conversation_id)
+        token_row = token_service.require_api_token(conn, _payload_token(payload), "merchant or agent token required")
+        if token_row["merchant_id"] != conversation["merchant_id"] or token_row["role"] not in {"merchant", "agent"}:
+            raise AuthError("invalid merchant or agent token")
+        actor = str(token_row["agent_id"] or token_row["merchant_id"])
+        review = add_flag(
+            conn,
+            conversation_id,
+            reason=str(payload.get("reason") or "human_required"),
+            severity=str(payload.get("severity") or "review"),
+            sku=conversation.get("sku") or "",
+        )
+        # add_flag already transitions the conversation to human_required with
+        # a rowcount-guarded UPDATE — no need for a separate status update here.
+        append_audit_event(
+            conn,
+            conversation_id,
+            actor,
+            "conversation_routed",
+            {"status": "human_required", "next_actor": next_actor_for_status("human_required", review["reason"]), "reason": review["reason"]},
+        )
+        row = human_review_service.human_review_row(conn, review["id"], positive_whole_int)
+        return {
+            "ok": True,
+            "review": review_summary(conn, row),
+            "conversation": conversation_summary(conn, conversation_id),
+        }
+
+
+def _require_resolver_identity(
+    conn: Any,
+    conversation: dict[str, Any],
+    reasons: list[str],
+    payload: dict[str, Any],
+) -> str:
+    """H7: operator 路由的 flag（suspicious_content）只能由 admin 身份销案。
+
+    merchant 是"被审查方"——用自家 merchant token 自销 operator 仲裁的
+    flag 会完全绕过人工审查控制。普通 flag 仍走 merchant token。
+    返回解析者 actor 标识。
+    """
+    if any(
+        next_actor_for_review_reason(str(reason or "")) == "operator" for reason in reasons
+    ):
+        api_auth.require_admin_token(payload)
+        return "admin"
+    token_row = token_service.require_merchant_token(conn, conversation["merchant_id"], _payload_token(payload))
+    return str(token_row["agent_id"] or token_row["merchant_id"]) if token_row is not None else conversation["merchant_id"]
+
+
+def resolve_human_review_item(db_path: str | Path, review_id: str | int, payload: dict[str, Any]) -> dict[str, Any]:
+    action = human_review_service.validate_action(str(payload.get("action") or "reply"))
+    sender = human_review_sender(payload)
+    with db_session(db_path) as conn:
+        row = human_review_row(conn, review_id)
+        if row["resolved_at"]:
+            raise ConflictError(f"Human review already resolved: {review_id}")
+        conversation_id = row["conversation_id"]
+        conversation = conversation_summary(conn, conversation_id)
+        actor = _require_resolver_identity(conn, conversation, [str(row["reason"] or "")], payload)
+        if conversation["status"] == "closed":
+            raise ConflictError(f"Conversation {conversation_id} is closed")
+        now = now_iso()
+        rowcount = human_review_service.resolve_review(
+            conn,
+            int(review_id),
+            action=action,
+            sender=actor,
+            now=now,
+        )
+        if rowcount != 1:
+            raise ConflictError(f"Human review already resolved: {review_id}")
+        remaining_reasons = human_review_service.remaining_unresolved_reviews(conn, conversation_id)
+        remaining = len(remaining_reasons)
+        remaining_reason = remaining_reasons[0] if remaining_reasons else ""
+        status = "human_required" if remaining else ("closed" if action == "close" else "waiting_buyer")
+        status_reason = remaining_reason if status == "human_required" else str(row["reason"] or "")
+        next_actor = next_actor_for_status(status, status_reason if status == "human_required" else "")
+        if payload.get("text"):
+            append_message(
+                conn,
+                conversation_id,
+                sender=sender,
+                intent=str(payload.get("intent") or "support"),
+                text=str(payload["text"]),
+                structured_payload={
+                    "resolution": action,
+                    "source_id": actor,
+                    "review_id": int(review_id),
+                    "reason": status_reason,
+                    "resolved_reason": row["reason"],
+                },
+                status=status,
+            )
+        else:
+            human_review_service.update_conversation_status(
+                conn,
+                conversation_id,
+                status=status,
+                next_actor=next_actor,
+                sender=actor,
+                expected_status="human_required",
+                # 非 human_required 目标态必须无未决 flag（防并发 add_flag
+                # 竞态把会话带 flag 推进到 waiting_buyer/closed）；human_required
+                # 时剩余未决 flag 是正常状态，不能 reject。
+                reject_if_unresolved=(status != "human_required"),
+                now=now,
+            )
+        append_audit_event(
+            conn,
+            conversation_id,
+            actor,
+            "human_review_resolved",
+            {
+                "review_id": int(review_id),
+                "resolution": action,
+                "status": status,
+                "next_actor": next_actor,
+                "remaining_unresolved_reviews": int(remaining or 0),
+            },
+        )
+        if status == "closed":
+            conversation_service.append_conversation_closed_audit(
+                conn,
+                conversation_id,
+                actor,
+                next_actor,
+                {"resolution": action, "review_id": int(review_id), "source": "human_review"},
+            )
+        review = review_summary(conn, human_review_row(conn, review_id))
+        rows = human_review_service.list_conversation_reviews(conn, conversation_id)
+        return {
+            "ok": True,
+            "review": review,
+            "reviews": [review_summary(conn, row) for row in rows],
+            "conversation": conversation_summary(conn, conversation_id),
+        }
+
+
+def resolve_human_review(db_path: str | Path, conversation_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+    action = human_review_service.validate_action(str(payload.get("action") or "reply"))
+    sender = human_review_sender(payload)
+    status = "closed" if action == "close" else "waiting_buyer"
+    with db_session(db_path) as conn:
+        conversation = conversation_summary(conn, conversation_id)
+        unresolved_reasons = [
+            str(r["reason"] or "")
+            for r in human_review_service.list_conversation_reviews(conn, conversation_id)
+            if not str(r["resolved_at"] or "")
+        ]
+        actor = _require_resolver_identity(conn, conversation, unresolved_reasons, payload)
+        if conversation["status"] == "closed":
+            raise ConflictError(f"Conversation {conversation_id} is closed")
+        now = now_iso()
+        rowcount = human_review_service.resolve_all_conversation_reviews(
+            conn,
+            conversation_id,
+            action=action,
+            sender=actor,
+            now=now,
+        )
+        if rowcount == 0:
+            raise NotFoundError(f"No unresolved human reviews for conversation: {conversation_id}")
+        next_actor = next_actor_for_status(status)
+        if payload.get("text"):
+            append_message(
+                conn,
+                conversation_id,
+                sender=sender,
+                intent=str(payload.get("intent") or "support"),
+                text=str(payload["text"]),
+                structured_payload={"resolution": action, "source_id": actor},
+                status=status,
+            )
+        else:
+            human_review_service.update_conversation_status(
+                conn,
+                conversation_id,
+                status=status,
+                next_actor=next_actor,
+                sender=actor,
+                expected_status="human_required",
+                # 非 human_required 目标态必须无未决 flag（防并发 add_flag
+                # 竞态把会话带 flag 推进到 waiting_buyer/closed）；human_required
+                # 时剩余未决 flag 是正常状态，不能 reject。
+                reject_if_unresolved=(status != "human_required"),
+                now=now,
+            )
+        append_audit_event(
+            conn,
+            conversation_id,
+            actor,
+            "human_review_resolved",
+            {"resolution": action, "status": status, "next_actor": next_actor},
+        )
+        if status == "closed":
+            conversation_service.append_conversation_closed_audit(
+                conn,
+                conversation_id,
+                actor,
+                next_actor,
+                {"resolution": action, "source": "human_review"},
+            )
+        rows = human_review_service.list_conversation_reviews(conn, conversation_id)
+        return {
+            "ok": True,
+            "reviews": [review_summary(conn, row) for row in rows],
+            "conversation": conversation_summary(conn, conversation_id),
+        }

shopping_cli/api/handlers/listings_projection.py

@@ -0,0 +1,42 @@
+"""Listing 投影只读 API（shopping-cli v0.3 §14；Merchant Kiwi-compatible）。
+
+- GET /v1/merchant/listings/projections —— 可发布投影列表（public-only）；
+- GET /v1/merchant/listings/{sku}/projection —— 单条投影。
+
+公开读免鉴权（沿用 products 现状）；发布动作只经 CLI 不进 API（评审：
+写面保持 push-first 单向，API 不暴露发布副作用）。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from shopping_cli.core.errors import NotFoundError, ValidationError
+from shopping_cli.db.session import db_session
+from shopping_cli.listings.projection import (
+    ProjectionError,
+    list_publishable_listings,
+    project_product_listing,
+)
+
+
+def list_listing_projections(db_path: str | Path, query: dict[str, Any]) -> dict[str, Any]:
+    """GET /v1/merchant/listings/projections —— 可发布投影（public-only）。"""
+    merchant_id = str(query.get("merchant_id") or "").strip()
+    with db_session(db_path) as conn:
+        projections = list_publishable_listings(conn, merchant_id=merchant_id)
+        return {"ok": True, "results": projections, "count": len(projections)}
+
+
+def get_listing_projection(db_path: str | Path, sku: str) -> dict[str, Any]:
+    """GET /v1/merchant/listings/{sku}/projection —— 单条投影。"""
+    sku = str(sku).strip()
+    if not sku:
+        raise ValidationError("sku is required")
+    with db_session(db_path) as conn:
+        try:
+            projection = project_product_listing(conn, sku)
+        except ProjectionError as exc:
+            raise NotFoundError(str(exc)) from exc
+        return {"ok": True, "projection": projection}

shopping_cli/api/handlers/negotiation.py

@@ -0,0 +1,121 @@
+"""shopping.negotiation/0.1 API handlers.
+
+Thin adapters over services.negotiation; both the FastAPI app and the
+fallback ASGI router dispatch here, so no business logic is duplicated.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from shopping_cli.api import auth as api_auth
+from shopping_cli.api.handlers.common import positive_whole_int, require_field
+from shopping_cli.core import negotiation as protocol
+from shopping_cli.db.session import db_session
+from shopping_cli.services import negotiation as negotiation_service
+
+
+def _actor(conn: Any, payload: dict[str, Any]) -> negotiation_service.NegotiationActor:
+    return negotiation_service.require_negotiation_actor(conn, api_auth.payload_token(payload))
+
+
+def capabilities(db_path: str | Path) -> dict[str, Any]:
+    return {"ok": True, "capabilities": protocol.capabilities_report()}
+
+
+def pending_messages(db_path: str | Path, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        actor = _actor(conn, payload)
+        pending = negotiation_service.list_pending_messages(conn, actor)
+        return {"ok": True, "role": actor.role, "owner_id": actor.owner_id, "pending": pending}
+
+
+def claim_message(db_path: str | Path, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        actor = _actor(conn, payload)
+        claim = negotiation_service.claim_message(
+            conn,
+            actor,
+            str(require_field(payload, "conversation_id")),
+            positive_whole_int(require_field(payload, "message_id"), "message_id"),
+            str(require_field(payload, "idempotency_key")),
+        )
+        return {"ok": True, "claim": claim}
+
+
+def get_snapshot(db_path: str | Path, payload: dict[str, Any], query: dict[str, Any] | None = None) -> dict[str, Any]:
+    query = query or {}
+    with db_session(db_path) as conn:
+        actor = _actor(conn, payload)
+        snapshot = negotiation_service.build_snapshot(
+            conn,
+            actor,
+            str(query.get("conversation_id") or require_field(payload, "conversation_id")),
+            positive_whole_int(query.get("message_id") or require_field(payload, "message_id"), "message_id"),
+        )
+        return {"ok": True, "snapshot": snapshot}
+
+
+def submit_decision(db_path: str | Path, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        actor = _actor(conn, payload)
+        policy_result = negotiation_service.submit_decision(
+            conn,
+            actor,
+            require_field(payload, "decision"),
+            str(require_field(payload, "idempotency_key")),
+        )
+        return {"ok": True, "policy_result": policy_result}
+
+
+def complete_claim(db_path: str | Path, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        actor = _actor(conn, payload)
+        process = negotiation_service.complete_claim(
+            conn, actor, positive_whole_int(require_field(payload, "message_id"), "message_id")
+        )
+        return {"ok": True, "process": process}
+
+
+def fail_claim(db_path: str | Path, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        actor = _actor(conn, payload)
+        process = negotiation_service.fail_claim(
+            conn,
+            actor,
+            positive_whole_int(require_field(payload, "message_id"), "message_id"),
+            str(payload.get("error") or "agent failure"),
+        )
+        return {"ok": True, "process": process}
+
+
+def abandon_claim(db_path: str | Path, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        actor = _actor(conn, payload)
+        process = negotiation_service.abandon_claim(
+            conn,
+            actor,
+            positive_whole_int(require_field(payload, "message_id"), "message_id"),
+            str(payload.get("error") or "agent abandoned claim"),
+        )
+        return {"ok": True, "process": process}
+
+
+def heartbeat_claims(db_path: str | Path, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        actor = _actor(conn, payload)
+        message_id = payload.get("message_id")
+        heartbeat = negotiation_service.heartbeat_claims(
+            conn,
+            actor,
+            None if message_id is None else positive_whole_int(message_id, "message_id"),
+        )
+        return {"ok": True, "heartbeat": heartbeat}
+
+
+def abandon_stale_claims(db_path: str | Path, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        actor = _actor(conn, payload)
+        stale = negotiation_service.abandon_stale_claims(conn, actor, payload.get("ttl_seconds"))
+        return {"ok": True, "stale": stale}