shopping-cli 3.1.0__tar.gz → 3.2.0__tar.gz

{shopping_cli-3.1.0/shopping_cli.egg-info → shopping_cli-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shopping-cli
-Version: 3.1.0
+Version: 3.2.0
 Summary: Standalone local-commerce AI consultation marketplace runtime
 License:                                  Apache License
                                    Version 2.0, January 2004

{shopping_cli-3.1.0 → shopping_cli-3.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "shopping-cli"
-version = "3.1.0"
+version = "3.2.0"
 description = "Standalone local-commerce AI consultation marketplace runtime"
 readme = "README.md"
 requires-python = ">=3.11"

{shopping_cli-3.1.0 → shopping_cli-3.2.0}/shopping_cli/__init__.py

@@ -1,3 +1,3 @@
 """Standalone shopping-cli consultation runtime."""
 
-VERSION = "3.1.0"
+VERSION = "3.2.0"

{shopping_cli-3.1.0 → shopping_cli-3.2.0}/shopping_cli/api/handlers/conversations.py

@@ -74,7 +74,9 @@ def append_conversation_message(db_path: str | Path, conversation_id: str, paylo
 def close_conversation(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)
-        sender = str(payload.get("sender") or "operator")
+        # 审查 S-H1：sender 缺省不得是 "operator"——商家用自己 token 不带
+        # sender 关会话会被误记为 operator。缺省回落到最诚实的 "merchant"。
+        sender = str(payload.get("sender") or "merchant")
         if sender in {"buyer", "buyer_cli"}:
             token_service.require_buyer_conversation_token(conn, conversation, _payload_token(payload))
         elif sender == "merchant":

{shopping_cli-3.1.0 → shopping_cli-3.2.0}/shopping_cli/api/handlers/listings_projection.py

@@ -40,10 +40,12 @@ def list_listing_projections(
         raise ValidationError("merchant_id is required")
     with db_session(db_path) as conn:
         owner = _owner_merchant_from_payload(conn, payload)
-        projections = list_publishable_listings(conn, merchant_id=merchant_id)
-        if not (owner and owner == merchant_id):
-            for projection in projections:
-                projection.pop("handoff_destination", None)
+        is_owner = bool(owner and owner == merchant_id)
+        # 审查 S-M3：私有剥离收进投影层（include_private）——此前调用方手动
+        # pop，CLI --format json 路径漏剥。
+        projections = list_publishable_listings(
+            conn, merchant_id=merchant_id, include_private=is_owner
+        )
         return {"ok": True, "results": projections, "count": len(projections)}
 
 
@@ -53,12 +55,14 @@ def get_listing_projection(db_path: str | Path, sku: str, payload: dict[str, Any
     if not sku:
         raise ValidationError("sku is required")
     with db_session(db_path) as conn:
+        row = conn.execute("select merchant_id from products where sku = ?", (sku,)).fetchone()
+        owner = _owner_merchant_from_payload(conn, payload)
+        is_owner = bool(
+            owner and row is not None and owner == str(row["merchant_id"] or "")
+        )
         try:
-            projection = project_product_listing(conn, sku)
+            # 审查 S-M3：私有剥离收进投影层（include_private）。
+            projection = project_product_listing(conn, sku, include_private=is_owner)
         except ProjectionError as exc:
             raise NotFoundError(str(exc)) from exc
-        owner = _owner_merchant_from_payload(conn, payload)
-        row = conn.execute("select merchant_id from products where sku = ?", (sku,)).fetchone()
-        if not (owner and row is not None and owner == str(row["merchant_id"] or "")):
-            projection.pop("handoff_destination", None)
         return {"ok": True, "projection": projection}

{shopping_cli-3.1.0 → shopping_cli-3.2.0}/shopping_cli/api/handlers/negotiation.py

@@ -6,15 +6,51 @@ fallback ASGI router dispatch here, so no business logic is duplicated.
 
 from __future__ import annotations
 
+import os
+import threading
+import time
 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.core.errors import RateLimitError
 from shopping_cli.db.session import db_session
 from shopping_cli.services import negotiation as negotiation_service
 
+# 审查 S-M2：merchant/agent/negotiation/human-review 端点此前均无限流——已泄露/
+# 低熵 token 的滥用无节流。对磋商决策提交（写路径，追加磋商消息）加 per-owner
+# 固定窗口限流：进程内（单进程部署前提，与 ERP sync 限流同款）。env 可覆盖
+# （调用时读取，便于测试注入）。
+_NEGOTIATION_DECISION_WINDOW_SECONDS = 60
+_DECISION_RATE_LIMIT_DEFAULT_PER_MINUTE = 600
+_decision_buckets: dict[str, tuple[float, int]] = {}
+_decision_buckets_lock = threading.Lock()
+
+
+def _decision_rate_limit_per_minute() -> int:
+    raw = os.environ.get("SHOPPING_NEGOTIATION_DECISION_RATE_LIMIT_PER_MINUTE", "")
+    try:
+        value = int(raw)
+    except ValueError:
+        return _DECISION_RATE_LIMIT_DEFAULT_PER_MINUTE
+    return value if value > 0 else _DECISION_RATE_LIMIT_DEFAULT_PER_MINUTE
+
+
+def _enforce_decision_rate_limit(owner_id: str) -> None:
+    limit = _decision_rate_limit_per_minute()
+    now = time.monotonic()
+    with _decision_buckets_lock:
+        window_start, count = _decision_buckets.get(owner_id, (0.0, 0))
+        if now - window_start >= _NEGOTIATION_DECISION_WINDOW_SECONDS:
+            window_start, count = now, 0
+        if count >= limit:
+            raise RateLimitError(
+                f"negotiation decision rate limit exceeded ({limit}/minute)"
+            )
+        _decision_buckets[owner_id] = (window_start, count + 1)
+
 
 def _actor(conn: Any, payload: dict[str, Any]) -> negotiation_service.NegotiationActor:
     return negotiation_service.require_negotiation_actor(conn, api_auth.payload_token(payload))
@@ -60,6 +96,8 @@ def get_snapshot(db_path: str | Path, payload: dict[str, Any], query: dict[str,
 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)
+        # 审查 S-M2：per-owner 固定窗口限流（决策提交=磋商消息追加，滥用最直接）。
+        _enforce_decision_rate_limit(actor.owner_id)
         policy_result = negotiation_service.submit_decision(
             conn,
             actor,

{shopping_cli-3.1.0 → shopping_cli-3.2.0}/shopping_cli/api/idempotency.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import hashlib
 import hmac
 import json
+import os
 import sqlite3
 from datetime import datetime
 from typing import Any
@@ -15,6 +16,11 @@ from shopping_cli.db.session import decode_json, encode_json, now_iso
 
 DEFAULT_BUYER_BOOTSTRAP_RATE_LIMIT_PER_MINUTE = 60
 BUYER_BOOTSTRAP_RATE_LIMIT_WINDOW_SECONDS = 60
+# 审查 S-M1：保留桶（sentinel buyer_id）承载共享 token 的全局硬上限——
+# buyer_id 完全客户端声明，轮换即可绕过单买家限流；全局桶任何请求都计数。
+BUYER_BOOTSTRAP_GLOBAL_BUCKET = "__global__"
+# 全局硬上限 = 单买家上限 × 该倍数（轮换 buyer_id 无法越过的兜底）。
+DEFAULT_BUYER_BOOTSTRAP_GLOBAL_LIMIT_MULTIPLIER = 100
 MAX_IDEMPOTENCY_KEY_LENGTH = 160
 MAX_SQLITE_INTEGER = 2**63 - 1
 
@@ -87,6 +93,41 @@ def rate_limit_window_start(current: datetime) -> str:
     return datetime.fromtimestamp(window_epoch).replace(microsecond=0).isoformat()
 
 
+def _buyer_bootstrap_global_limit_multiplier() -> int:
+    """全局硬上限倍数（env 可覆盖，测试注入用；非法/非正回退缺省）。"""
+    raw = os.environ.get("SHOPPING_BUYER_BOOTSTRAP_GLOBAL_LIMIT_MULTIPLIER", "")
+    try:
+        value = int(raw)
+    except ValueError:
+        return DEFAULT_BUYER_BOOTSTRAP_GLOBAL_LIMIT_MULTIPLIER
+    return value if value > 0 else DEFAULT_BUYER_BOOTSTRAP_GLOBAL_LIMIT_MULTIPLIER
+
+
+def _bump_window(
+    conn: Any,
+    token_hash: str,
+    bucket: str,
+    window_start: str,
+    limit: int,
+    current: datetime,
+    label: str,
+) -> None:
+    """给 (token_hash, bucket, window) 计数 +1；超过 limit 抛 RateLimitError。"""
+    cursor = conn.execute(
+        """
+        insert into buyer_bootstrap_rate_limits(token_hash, buyer_id, window_start, request_count, updated_at)
+        values (?, ?, ?, 1, ?)
+        on conflict(token_hash, buyer_id, window_start) do update set
+            request_count = buyer_bootstrap_rate_limits.request_count + 1,
+            updated_at = excluded.updated_at
+        where buyer_bootstrap_rate_limits.request_count < ?
+        """,
+        (token_hash, bucket, window_start, current.isoformat(), limit),
+    )
+    if cursor.rowcount != 1:
+        raise RateLimitError(f"{label} rate limit exceeded ({limit}/minute)")
+
+
 def enforce_buyer_bootstrap_rate_limit(
     conn: Any,
     bootstrap_token_hash: str,
@@ -124,19 +165,24 @@ def enforce_buyer_bootstrap_rate_limit(
     except sqlite3.OperationalError:
         # 清理失败不影响限流本身（fail-safe 方向；下次再试）
         pass
-    cursor = conn.execute(
-        """
-        insert into buyer_bootstrap_rate_limits(token_hash, buyer_id, window_start, request_count, updated_at)
-        values (?, ?, ?, 1, ?)
-        on conflict(token_hash, buyer_id, window_start) do update set
-            request_count = buyer_bootstrap_rate_limits.request_count + 1,
-            updated_at = excluded.updated_at
-        where buyer_bootstrap_rate_limits.request_count < ?
-        """,
-        (bootstrap_token_hash, buyer_id, rate_limit_window_start(current), current.isoformat(), limit),
+    window_start = rate_limit_window_start(current)
+    # 单买家窗口（买家维度预算隔离）
+    _bump_window(
+        conn, bootstrap_token_hash, buyer_id, window_start, limit, current, "buyer bootstrap"
+    )
+    # 全局硬上限（审查 S-M1）：同一 token 的全部请求（无论 buyer_id）都计入
+    # 保留桶——buyer_id 完全客户端声明、轮换即可绕过单买家限流，全局桶轮换
+    # 无法绕过。
+    global_limit = limit * _buyer_bootstrap_global_limit_multiplier()
+    _bump_window(
+        conn,
+        bootstrap_token_hash,
+        BUYER_BOOTSTRAP_GLOBAL_BUCKET,
+        window_start,
+        global_limit,
+        current,
+        "buyer bootstrap global",
     )
-    if cursor.rowcount != 1:
-        raise RateLimitError(f"buyer bootstrap rate limit exceeded ({limit}/minute)")
 
 
 def idempotency_row(

{shopping_cli-3.1.0 → shopping_cli-3.2.0}/shopping_cli/cli.py

@@ -65,6 +65,7 @@ from shopping_cli.cli_conversation_commands import (
 )
 from shopping_cli.cli_erp_commands import cmd_erp_sync
 from shopping_cli.cli_listing_commands import cmd_listing_projections_list
+from shopping_cli.cli_adapter_commands import cmd_adapters_list, cmd_import_csv_excel
 from shopping_cli.config import ConfigError, DEFAULT_DB_PATH, validate_production_config
 from shopping_cli.core.catalog import require_merchant
 from shopping_cli.core.conversations import merchant_conversations
@@ -854,6 +855,23 @@ def build_parser() -> argparse.ArgumentParser:
     erp_sync.add_argument("--format", choices=["text", "json"], default="text")
     erp_sync.set_defaults(func=cmd_erp_sync)
 
+    # ── adapters（Issue 14 / §6.3：Adapter SDK 注册表）────────────────────
+    adapters = subparsers.add_parser("adapters", help="Registered data source adapters (Adapter SDK)")
+    adapters_sub = adapters.add_subparsers(dest="adapters_command", required=True)
+    adapters_list = adapters_sub.add_parser("list", help="List registered adapters")
+    adapters_list.add_argument("--format", choices=["text", "json"], default="text")
+    adapters_list.set_defaults(func=cmd_adapters_list)
+
+    # ── import-csv-excel（Issue 14 / §6.3：首条接入路径）─────────────────
+    import_csv = subparsers.add_parser(
+        "import-csv-excel", help="Import product facts from CSV / Excel (.xlsx) into the local store"
+    )
+    import_csv.add_argument("--file", required=True, help="Path to .csv / .tsv / .xlsx file")
+    import_csv.add_argument("--merchant", default="", dest="merchant", help="Owning merchant id (required, FK guard)")
+    import_csv.add_argument("--allowed-merchant", default="", dest="allowed_merchant", help="Tenant boundary: only rows of this merchant are written")
+    import_csv.add_argument("--format", choices=["text", "json"], default="text")
+    import_csv.set_defaults(func=cmd_import_csv_excel)
+
     # ── listings（shopping-cli v0.3 §14：PublicListingProjection 只读预览）───
     listings = subparsers.add_parser("listings", help="Product-first listing projections (read-only preview)")
     listings_sub = listings.add_subparsers(dest="listings_command", required=True)

shopping_cli-3.2.0/shopping_cli/cli_adapter_commands.py

@@ -0,0 +1,49 @@
+"""Adapter SDK CLI（Issue 14 / §6.3）。
+
+``shopping adapters list``            —— 列出已注册数据源适配器
+``shopping import-csv-excel ...``     —— 运行 CSV/Excel 适配器（首条接入路径）
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from shopping_cli.cli_common import db_path_from_args, emit
+from shopping_cli.data_sources import csv_excel_source  # noqa: F401  # 导入即注册适配器
+from shopping_cli.data_sources.adapter import (
+    AdapterError,
+    SyncContext,
+    registered_adapters,
+    run,
+)
+from shopping_cli.db.session import db_session
+
+
+def cmd_adapters_list(args: argparse.Namespace) -> None:
+    """列出已注册适配器（Adapter SDK 注册表）。"""
+    emit(
+        [{"name": a.name, "description": a.description} for a in registered_adapters().values()],
+        args.format,
+    )
+
+
+def cmd_import_csv_excel(args: argparse.Namespace) -> None:
+    """运行 CSV/Excel 适配器导入本地 products 表。"""
+    db_path = db_path_from_args(args)
+    merchant_id = str(args.merchant or "").strip() or str(args.default_merchant or "").strip()
+    if not merchant_id:
+        raise SystemExit("--merchant is required (FK 归属防护)")
+    with db_session(db_path) as conn:
+        ctx = SyncContext(
+            conn=conn,
+            default_merchant_id=merchant_id,
+            allowed_merchant_id=str(args.allowed_merchant or "").strip(),
+            config={"path": args.file},
+        )
+        report = run("csv_excel", ctx)
+    emit(report.as_dict(), args.format)
+    if report.errors or report.conflicts:
+        raise SystemExit(
+            f"csv_excel import completed with {len(report.errors)} errors and "
+            f"{len(report.conflicts)} conflicts (see report above)"
+        )

shopping_cli-3.2.0/shopping_cli/data_sources/adapter.py

@@ -0,0 +1,175 @@
+"""Adapter SDK（Issue 14 / §6.3）：稳定 REST/ERP adapter 接口 + 注册表。
+
+shopping-cli 是 Merchant Commerce Data & Operations Hub——外部商品事实（ERP、
+CSV/Excel、未来 REST 连接器）经**数据源适配器**接入本地 ``products`` 表，Kiwi
+merchant 只消费 shopping-cli 的开放层。
+
+本模块定义稳定的适配器契约（不按品牌堆连接器代码）：
+
+* ``DataSourceAdapter`` Protocol——任何适配器实现 ``sync(ctx) -> SyncReport``；
+* ``SyncContext``——连接、授权边界（跨租户）、时钟、适配器配置；
+* ``SyncReport``——可审计结果（fetched/upserted/skipped/conflicts/errors）；
+* 注册表 + ``run(name, ctx)``——CLI / API 统一按名字执行适配器。
+
+权威语义（data hub v0.2.1 §5）：source='local' 本地录入 = LOCAL_AUTHORITATIVE；
+外部源（erp / csv_excel）= UPSTREAM_PROXY（本地是缓存）。同 SKU 冲突绝不静默
+合并冲突权威源。
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Callable, Protocol
+
+SOURCE_LOCAL = "local"
+AUTHORITY_LOCAL = "LOCAL_AUTHORITATIVE"
+AUTHORITY_UPSTREAM = "UPSTREAM_PROXY"
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+@dataclass(frozen=True)
+class SyncContext:
+    """适配器执行上下文。"""
+
+    conn: sqlite3.Connection
+    default_merchant_id: str = ""
+    allowed_merchant_id: str = ""
+    now: Callable[[], str] = _now_iso
+    config: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SyncReport:
+    """一次适配器同步的可审计结果。"""
+
+    source: str
+    authority: str = AUTHORITY_UPSTREAM
+    fetched: int = 0
+    upserted: int = 0
+    skipped: int = 0
+    conflicts: list[dict[str, Any]] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "fetched": self.fetched,
+            "upserted": self.upserted,
+            "skipped": self.skipped,
+            "conflicts": self.conflicts,
+            "errors": self.errors,
+            "source": self.source,
+            "authority": self.authority,
+        }
+
+
+class AdapterError(Exception):
+    """适配器执行失败（fail-closed：任何校验/结构/IO 错误抛本异常）。"""
+
+
+class DataSourceAdapter(Protocol):
+    """适配器契约：``name`` + ``sync(ctx)``。"""
+
+    name: str
+    description: str
+
+    def sync(self, ctx: SyncContext) -> SyncReport: ...
+
+
+# ---------------------------------------------------------------------------
+# 注册表
+# ---------------------------------------------------------------------------
+
+_ADAPTERS: dict[str, DataSourceAdapter] = {}
+
+
+def register(adapter: DataSourceAdapter) -> DataSourceAdapter:
+    """注册适配器（同名字符串参数不覆盖——重复注册即显式错误）。"""
+    if adapter.name in _ADAPTERS:
+        raise AdapterError(f"adapter {adapter.name!r} already registered")
+    _ADAPTERS[adapter.name] = adapter
+    return adapter
+
+
+def registered_adapters() -> dict[str, DataSourceAdapter]:
+    """按名字返回已注册适配器（拷贝，避免外部篡改）。"""
+    return dict(_ADAPTERS)
+
+
+def run(name: str, ctx: SyncContext) -> SyncReport:
+    """按名字执行适配器。未知名字 → AdapterError（fail-closed）。"""
+    adapter = _ADAPTERS.get(name)
+    if adapter is None:
+        raise AdapterError(
+            f"unknown adapter {name!r} (registered: {', '.join(sorted(_ADAPTERS)) or 'none'})"
+        )
+    return adapter.sync(ctx)
+
+
+def resolve_merchant_or_raise(conn: sqlite3.Connection, merchant_id: str) -> None:
+    """FK 防护：归属 merchant 必须真实存在（否则裸 IntegrityError 中止同步）。"""
+    exists = conn.execute("select 1 from merchants where id = ?", (merchant_id,)).fetchone()
+    if exists is None:
+        raise AdapterError(f"unknown merchant {merchant_id!r}")
+
+
+def upsert_product_row(
+    conn: sqlite3.Connection,
+    *,
+    sku: str,
+    merchant_id: str,
+    title: str,
+    description: str,
+    category: str,
+    price: float,
+    currency: str,
+    stock: int,
+    source: str,
+    revision: str,
+    now_ts: str,
+    fresh_until: str,
+) -> None:
+    """共享 upsert（ERP / CSV-Excel 同款语义：source 标注 + provenance 回填）。"""
+    conn.execute(
+        """
+        insert into products(
+            sku, merchant_id, title, description, category, tags_json,
+            price, currency, stock, delivery_attributes_json, active,
+            source, source_revision, observed_at, fresh_until,
+            created_at, updated_at
+        ) values (?, ?, ?, ?, ?, '[]', ?, ?, ?, '[]', 1, ?, ?, ?, ?, ?, ?)
+        on conflict(sku) do update set
+            merchant_id=excluded.merchant_id,
+            title=excluded.title,
+            description=excluded.description,
+            category=excluded.category,
+            price=excluded.price,
+            currency=excluded.currency,
+            stock=excluded.stock,
+            source=excluded.source,
+            source_revision=excluded.source_revision,
+            observed_at=excluded.observed_at,
+            fresh_until=excluded.fresh_until,
+            updated_at=excluded.updated_at
+        """,
+        (
+            sku,
+            merchant_id,
+            title,
+            description,
+            category,
+            price,
+            currency,
+            stock,
+            source,
+            revision,
+            now_ts,
+            fresh_until,
+            now_ts,
+            now_ts,
+        ),
+    )