tb-order-sync 0.3.0

package/config/__init__.py

@@ -0,0 +1,4 @@
+from config.settings import get_settings
+from config.mappings import ColumnMapping, get_column_mapping
+
+__all__ = ["get_settings", "ColumnMapping", "get_column_mapping"]

package/config/mappings.py

@@ -0,0 +1,63 @@
+"""Column mapping utilities.
+
+Converts between column letters (A, B, ...) and 0-based indices,
+and provides a typed mapping object built from Settings.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import lru_cache
+
+from config.settings import get_settings
+
+
+def col_letter_to_index(letter: str) -> int:
+    """Convert column letter(s) to 0-based index. A->0, B->1, ..., Z->25, AA->26."""
+    letter = letter.upper().strip()
+    result = 0
+    for ch in letter:
+        result = result * 26 + (ord(ch) - ord("A") + 1)
+    return result - 1
+
+
+def col_index_to_letter(index: int) -> str:
+    """Convert 0-based index to column letter(s). 0->A, 1->B, ..., 25->Z, 26->AA."""
+    result = ""
+    idx = index + 1
+    while idx > 0:
+        idx, remainder = divmod(idx - 1, 26)
+        result = chr(65 + remainder) + result
+    return result
+
+
+@dataclass(frozen=True)
+class ColumnMapping:
+    """Resolved column indices for A / B tables."""
+
+    # A 表
+    a_product_price: int
+    a_packaging_price: int
+    a_freight: int
+    a_customer_quote: int
+    a_gross_profit: int
+    a_order_no: int
+    a_refund_status: int
+
+    # B 表
+    b_order_no: int
+
+
+@lru_cache(maxsize=1)
+def get_column_mapping() -> ColumnMapping:
+    s = get_settings()
+    return ColumnMapping(
+        a_product_price=col_letter_to_index(s.a_col_product_price),
+        a_packaging_price=col_letter_to_index(s.a_col_packaging_price),
+        a_freight=col_letter_to_index(s.a_col_freight),
+        a_customer_quote=col_letter_to_index(s.a_col_customer_quote),
+        a_gross_profit=col_letter_to_index(s.a_col_gross_profit),
+        a_order_no=col_letter_to_index(s.a_col_order_no),
+        a_refund_status=col_letter_to_index(s.a_col_refund_status),
+        b_order_no=col_letter_to_index(s.b_col_order_no),
+    )

package/config/settings.py

@@ -0,0 +1,95 @@
+"""Application settings via pydantic-settings + .env file."""
+
+from __future__ import annotations
+
+import os
+import sys
+from enum import Enum
+from functools import lru_cache
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+def _get_project_root() -> Path:
+    """Resolve project root, compatible with PyInstaller frozen exe."""
+    if getattr(sys, "frozen", False):
+        # Running as packaged exe — use exe's directory as root
+        return Path(sys.executable).resolve().parent
+    return Path(__file__).resolve().parent.parent
+
+
+PROJECT_ROOT = _get_project_root()
+
+
+class AppEnv(str, Enum):
+    DEV = "dev"
+    STAGING = "staging"
+    PROD = "prod"
+
+
+class SyncMode(str, Enum):
+    INCREMENTAL = "incremental"
+    FULL = "full"
+
+
+class Settings(BaseSettings):
+    """All configuration knobs, sourced from .env / environment variables."""
+
+    model_config = SettingsConfigDict(
+        env_file=os.environ.get("DOTENV_PATH", str(PROJECT_ROOT / ".env")),
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # ── 基础 ──────────────────────────────────────────────
+    app_env: AppEnv = AppEnv.DEV
+    log_level: str = "INFO"
+    state_dir: str = str(PROJECT_ROOT / "state")
+
+    # ── 腾讯文档 ──────────────────────────────────────────
+    tencent_client_id: str = ""
+    tencent_client_secret: str = ""
+    tencent_open_id: str = ""
+    tencent_access_token: str = ""
+    tencent_a_file_id: str = ""
+    tencent_a_sheet_id: str = ""
+    tencent_b_file_id: str = ""
+    tencent_b_sheet_id: str = ""
+
+    # ── 飞书（预留） ─────────────────────────────────────
+    feishu_app_id: str = ""
+    feishu_app_secret: str = ""
+    feishu_c_file_token: str = ""
+    feishu_c_sheet_id: str = ""
+
+    # ── 运行 ──────────────────────────────────────────────
+    gross_profit_mode: SyncMode = SyncMode.INCREMENTAL
+    refund_match_mode: SyncMode = SyncMode.INCREMENTAL
+    c_sync_mode: SyncMode = SyncMode.INCREMENTAL
+    task_interval_minutes: int = 10
+    startup_jitter_seconds: int = 15
+    write_batch_size: int = 100
+    retry_times: int = 3
+    dry_run: bool = False
+    enable_style_update: bool = False
+
+    # ── 列映射（可覆盖） ─────────────────────────────────
+    a_col_product_price: str = "C"
+    a_col_packaging_price: str = "D"
+    a_col_freight: str = "E"
+    a_col_customer_quote: str = "F"
+    a_col_gross_profit: str = "G"
+    a_col_order_no: str = "H"
+    a_col_refund_status: str = "I"
+    b_col_order_no: str = "A"
+
+    # ── 业务文案 ──────────────────────────────────────────
+    refund_status_text: str = "进入退款流程"
+    data_error_text: str = "数据异常"
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    return Settings()

package/connectors/base.py

@@ -0,0 +1,98 @@
+"""Abstract base class for all sheet connectors."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Optional, Sequence
+
+
+class BaseSheetConnector(ABC):
+    """Unified interface for reading/writing cloud spreadsheets.
+
+    All platform-specific connectors (Tencent Docs, Feishu, etc.)
+    must implement this interface so that services remain platform-agnostic.
+    """
+
+    @abstractmethod
+    def read_rows(
+        self,
+        file_id: str,
+        sheet_id: str,
+        *,
+        start_row: int = 0,
+        end_row: Optional[int] = None,
+    ) -> list[list[Any]]:
+        """Read rows from a sheet. Returns list of rows, each row is a list of cell values.
+
+        Row indices are 0-based (row 0 = first row in sheet, typically the header).
+        """
+        ...
+
+    @abstractmethod
+    def write_cells(
+        self,
+        file_id: str,
+        sheet_id: str,
+        updates: list[CellUpdate],
+    ) -> None:
+        """Write individual cell values."""
+        ...
+
+    @abstractmethod
+    def batch_update(
+        self,
+        file_id: str,
+        sheet_id: str,
+        updates: list[CellUpdate],
+        batch_size: int = 100,
+    ) -> None:
+        """Write cells in batches to respect API rate limits."""
+        ...
+
+    @abstractmethod
+    def ensure_column(
+        self,
+        file_id: str,
+        sheet_id: str,
+        col_letter: str,
+        header_name: str,
+    ) -> None:
+        """Ensure a column exists with the given header. Create if missing."""
+        ...
+
+    @abstractmethod
+    def get_header(
+        self,
+        file_id: str,
+        sheet_id: str,
+    ) -> list[str]:
+        """Return the header row (first row) as a list of strings."""
+        ...
+
+    def update_row_style(
+        self,
+        file_id: str,
+        sheet_id: str,
+        row_index: int,
+        bg_color: Optional[str] = None,
+    ) -> None:
+        """Optional: set background color for an entire row.
+
+        Default implementation is a no-op. Connectors may override
+        if the platform API supports style manipulation.
+        """
+        pass
+
+
+class CellUpdate:
+    """A single cell write instruction."""
+
+    __slots__ = ("row", "col", "value")
+
+    def __init__(self, row: int, col: int, value: Any) -> None:
+        self.row = row
+        self.col = col
+        self.value = value
+
+    def __repr__(self) -> str:
+        return f"CellUpdate(row={self.row}, col={self.col}, value={self.value!r})"

package/connectors/feishu_sheets.py

@@ -0,0 +1,96 @@
+"""Feishu (飞书) sheet connector — structural skeleton.
+
+This connector implements the BaseSheetConnector interface for Feishu/Lark spreadsheets.
+Currently a placeholder — all methods raise NotImplementedError with guidance.
+
+API Reference (TODO / NEED_VERIFY):
+  飞书开放平台电子表格: https://open.feishu.cn/document/server-docs/docs/sheets-v3/overview
+
+Implementation priority for Phase 2:
+  1. Authentication (app_id + app_secret → tenant_access_token)
+  2. read_rows  — GET /open-apis/sheets/v2/spreadsheets/{spreadsheetToken}/values/{range}
+  3. write_cells — PUT /open-apis/sheets/v2/spreadsheets/{spreadsheetToken}/values
+  4. batch_update — same as write_cells with batch splitting
+  5. get_header / ensure_column
+  6. update_row_style (if needed)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from connectors.base import BaseSheetConnector, CellUpdate
+from utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class FeishuSheetsConnector(BaseSheetConnector):
+    """Connector for 飞书电子表格.
+
+    TODO: Implement when Feishu integration is needed.
+    """
+
+    def __init__(
+        self,
+        app_id: str,
+        app_secret: str,
+    ) -> None:
+        self._app_id = app_id
+        self._app_secret = app_secret
+        self._tenant_token: Optional[str] = None
+        # TODO: Initialize httpx client with base_url = "https://open.feishu.cn"
+
+    def _ensure_token(self) -> None:
+        """Obtain or refresh tenant_access_token.
+
+        TODO / NEED_VERIFY:
+          POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal
+          body: { "app_id": ..., "app_secret": ... }
+        """
+        raise NotImplementedError("Feishu token acquisition not yet implemented")
+
+    def read_rows(
+        self,
+        file_id: str,
+        sheet_id: str,
+        *,
+        start_row: int = 0,
+        end_row: Optional[int] = None,
+    ) -> list[list[Any]]:
+        """TODO: GET /open-apis/sheets/v2/spreadsheets/{file_id}/values/{sheet_id}!A:ZZ"""
+        raise NotImplementedError("FeishuSheetsConnector.read_rows not yet implemented")
+
+    def write_cells(
+        self,
+        file_id: str,
+        sheet_id: str,
+        updates: list[CellUpdate],
+    ) -> None:
+        """TODO: PUT /open-apis/sheets/v2/spreadsheets/{file_id}/values"""
+        raise NotImplementedError("FeishuSheetsConnector.write_cells not yet implemented")
+
+    def batch_update(
+        self,
+        file_id: str,
+        sheet_id: str,
+        updates: list[CellUpdate],
+        batch_size: int = 100,
+    ) -> None:
+        raise NotImplementedError("FeishuSheetsConnector.batch_update not yet implemented")
+
+    def ensure_column(
+        self,
+        file_id: str,
+        sheet_id: str,
+        col_letter: str,
+        header_name: str,
+    ) -> None:
+        raise NotImplementedError("FeishuSheetsConnector.ensure_column not yet implemented")
+
+    def get_header(
+        self,
+        file_id: str,
+        sheet_id: str,
+    ) -> list[str]:
+        raise NotImplementedError("FeishuSheetsConnector.get_header not yet implemented")

package/connectors/tencent_docs.py

@@ -0,0 +1,253 @@
+"""Tencent Docs (腾讯文档) sheet connector.
+
+API Reference (needs verification):
+  腾讯文档开放平台: https://docs.qq.com/open/wiki/
+
+TODO / NEED_VERIFY:
+  - OAuth2 token refresh flow: the current implementation assumes a pre-obtained
+    access_token passed via config. Production should implement refresh_token cycle.
+  - Exact API endpoints and request/response schemas are marked inline.
+  - Rate limit specifics (QPS, batch size caps) need confirmation from docs.
+  - Style/formatting API availability is uncertain — update_row_style is best-effort.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+
+import httpx
+
+from connectors.base import BaseSheetConnector, CellUpdate
+from config.mappings import col_index_to_letter
+from utils.logger import get_logger
+from utils.retry import default_retry
+
+logger = get_logger(__name__)
+
+# ── TODO / NEED_VERIFY ─────────────────────────────────────────────────────
+# Base URL for Tencent Docs Open API.
+# 腾讯文档智能表格(SmartSheet)和在线表格(Sheet)的API路径可能不同，
+# 需要根据实际文档类型确认。
+# 以下为在线表格(Sheet)的推测路径：
+_BASE_URL = "https://docs.qq.com/openapi/v2"
+
+# TODO: 确认实际的 API 路径格式
+# 读取单元格数据: GET /openapi/v2/files/{fileID}/sheets/{sheetID}/content
+# 写入单元格数据: PUT /openapi/v2/files/{fileID}/sheets/{sheetID}/content
+# 这些路径需要与腾讯文档开放平台文档核实
+# ────────────────────────────────────────────────────────────────────────────
+
+
+class TencentDocsConnector(BaseSheetConnector):
+    """Connector for 腾讯文档 online spreadsheets."""
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        access_token: str,
+        open_id: str = "",
+    ) -> None:
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._access_token = access_token
+        self._open_id = open_id
+        self._http = httpx.Client(
+            base_url=_BASE_URL,
+            timeout=30.0,
+            headers=self._build_headers(),
+        )
+
+    def _build_headers(self) -> dict[str, str]:
+        return {
+            "Content-Type": "application/json",
+            "Access-Token": self._access_token,
+            # TODO / NEED_VERIFY: 腾讯文档 API 的认证 header 名称
+            # 可能是 "Access-Token" 或 "Authorization: Bearer <token>"
+            # 需根据实际文档确认
+        }
+
+    # ── Token refresh (placeholder) ────────────────────────────────────────
+    def refresh_token(self) -> None:
+        """TODO: Implement OAuth2 token refresh using client_id + client_secret.
+
+        腾讯文档的 token 有效期通常较短，生产环境必须实现自动刷新。
+        当前版本依赖外部提供有效的 access_token。
+        """
+        # TODO / NEED_VERIFY:
+        # POST /oauth/v2/token
+        # {
+        #   "client_id": ...,
+        #   "client_secret": ...,
+        #   "grant_type": "refresh_token",
+        #   "refresh_token": ...
+        # }
+        raise NotImplementedError("Token refresh not yet implemented — supply valid access_token in .env")
+
+    # ── Read ───────────────────────────────────────────────────────────────
+    @default_retry(max_attempts=3)
+    def read_rows(
+        self,
+        file_id: str,
+        sheet_id: str,
+        *,
+        start_row: int = 0,
+        end_row: Optional[int] = None,
+    ) -> list[list[Any]]:
+        """Read rows from a Tencent Docs sheet.
+
+        TODO / NEED_VERIFY: 确认实际的读取 API endpoint 和参数格式。
+        以下为推测实现，需根据腾讯文档开放平台文档调整。
+        """
+        # TODO / NEED_VERIFY: 实际的 API 路径和参数
+        # 可能的路径: GET /files/{fileID}/sheets/{sheetID}/content
+        # 也可能需要指定 range，如 "A1:Z1000"
+        url = f"/files/{file_id}/sheets/{sheet_id}/content"
+        params: dict[str, Any] = {}
+        if end_row is not None:
+            # TODO: 腾讯文档可能使用 A1 notation 的 range 参数
+            # 例如 range = "A{start_row+1}:Z{end_row+1}"
+            params["range"] = f"A{start_row + 1}:ZZ{end_row + 1}"
+        else:
+            params["range"] = f"A{start_row + 1}:ZZ"
+
+        logger.info("Reading rows from file=%s sheet=%s range=%s", file_id, sheet_id, params.get("range"))
+
+        resp = self._http.get(url, params=params)
+        resp.raise_for_status()
+        data = resp.json()
+
+        # TODO / NEED_VERIFY: 解析响应数据结构
+        # 腾讯文档返回的数据格式需要确认，以下是推测：
+        # data = { "data": { "rows": [[cell, ...], ...] } }
+        # 或: data = { "data": [[cell, ...], ...] }
+        rows = data.get("data", {}).get("rows", [])
+        if not rows and isinstance(data.get("data"), list):
+            rows = data["data"]
+
+        logger.info("Read %d rows from file=%s sheet=%s", len(rows), file_id, sheet_id)
+        return rows
+
+    # ── Write ──────────────────────────────────────────────────────────────
+    @default_retry(max_attempts=3)
+    def write_cells(
+        self,
+        file_id: str,
+        sheet_id: str,
+        updates: list[CellUpdate],
+    ) -> None:
+        """Write cell values to a Tencent Docs sheet.
+
+        TODO / NEED_VERIFY: 确认写入 API 的 endpoint 和 request body 格式。
+        """
+        if not updates:
+            return
+
+        # TODO / NEED_VERIFY: 构建写入请求体
+        # 腾讯文档可能支持批量单元格更新，格式推测如下:
+        # PUT /files/{fileID}/sheets/{sheetID}/content
+        # body = { "data": [ {"range": "G2", "value": 123}, ... ] }
+        payload = self._build_write_payload(updates)
+        url = f"/files/{file_id}/sheets/{sheet_id}/content"
+
+        logger.info("Writing %d cells to file=%s sheet=%s", len(updates), file_id, sheet_id)
+
+        resp = self._http.put(url, json=payload)
+        resp.raise_for_status()
+
+        logger.info("Successfully wrote %d cells", len(updates))
+
+    @default_retry(max_attempts=3)
+    def batch_update(
+        self,
+        file_id: str,
+        sheet_id: str,
+        updates: list[CellUpdate],
+        batch_size: int = 100,
+    ) -> None:
+        """Write cells in batches to stay within API rate limits."""
+        total = len(updates)
+        for i in range(0, total, batch_size):
+            batch = updates[i : i + batch_size]
+            self.write_cells(file_id, sheet_id, batch)
+            if i + batch_size < total:
+                time.sleep(0.5)  # Basic rate-limit courtesy
+        logger.info("Batch update complete: %d cells in %d batches", total, (total + batch_size - 1) // batch_size)
+
+    # ── Column management ──────────────────────────────────────────────────
+    def ensure_column(
+        self,
+        file_id: str,
+        sheet_id: str,
+        col_letter: str,
+        header_name: str,
+    ) -> None:
+        """Ensure column header exists; write it if missing.
+
+        TODO / NEED_VERIFY: 可能需要先读取 header row，检查列是否存在，
+        如果不存在则需要插入列或写入 header。
+        """
+        header = self.get_header(file_id, sheet_id)
+        from config.mappings import col_letter_to_index
+        idx = col_letter_to_index(col_letter)
+
+        if idx < len(header) and header[idx] == header_name:
+            logger.debug("Column %s already has header '%s'", col_letter, header_name)
+            return
+
+        # Write the header cell
+        self.write_cells(file_id, sheet_id, [CellUpdate(row=0, col=idx, value=header_name)])
+        logger.info("Ensured column %s header = '%s'", col_letter, header_name)
+
+    def get_header(
+        self,
+        file_id: str,
+        sheet_id: str,
+    ) -> list[str]:
+        """Read the first row as header."""
+        rows = self.read_rows(file_id, sheet_id, start_row=0, end_row=1)
+        if rows:
+            return [str(v) if v is not None else "" for v in rows[0]]
+        return []
+
+    # ── Style (optional) ───────────────────────────────────────────────────
+    def update_row_style(
+        self,
+        file_id: str,
+        sheet_id: str,
+        row_index: int,
+        bg_color: Optional[str] = None,
+    ) -> None:
+        """Optional: set row background color.
+
+        TODO / NEED_VERIFY: 腾讯文档是否支持通过 API 设置单元格/行样式。
+        如果不支持，此方法将仅记录日志并跳过。
+        当前实现为 best-effort placeholder。
+        """
+        if bg_color is None:
+            logger.debug("update_row_style called with no color, skipping row=%d", row_index)
+            return
+
+        # TODO / NEED_VERIFY: 样式 API 路径和格式
+        # 可能的路径: PUT /files/{fileID}/sheets/{sheetID}/styles
+        # body = { "range": "A{row}:Z{row}", "style": {"backgroundColor": "#FF0000"} }
+        logger.info(
+            "Style update requested for row=%d bg=%s (file=%s) — "
+            "TODO: verify Tencent Docs style API support",
+            row_index, bg_color, file_id,
+        )
+
+    # ── Internal helpers ───────────────────────────────────────────────────
+    @staticmethod
+    def _build_write_payload(updates: list[CellUpdate]) -> dict[str, Any]:
+        """Build the API request body for a batch cell write.
+
+        TODO / NEED_VERIFY: 确认腾讯文档的批量写入 request body 格式。
+        """
+        cells = []
+        for u in updates:
+            col_letter = col_index_to_letter(u.col)
+            cell_ref = f"{col_letter}{u.row + 1}"  # A1 notation, 1-based
+            cells.append({"range": cell_ref, "value": u.value})
+        return {"data": cells}

package/main.py

@@ -0,0 +1,6 @@
+"""Entry point: prefer `tb ...`; `python main.py ...` remains supported."""
+
+from cli.commands import main
+
+if __name__ == "__main__":
+    main()

package/models/__init__.py

@@ -0,0 +1,12 @@
+from models.records import OrderRecord, RefundRecord
+from models.task_models import SyncTaskConfig, TaskResult
+from models.state_models import SyncState, RowFingerprint
+
+__all__ = [
+    "OrderRecord",
+    "RefundRecord",
+    "SyncTaskConfig",
+    "TaskResult",
+    "SyncState",
+    "RowFingerprint",
+]

package/models/records.py

@@ -0,0 +1,38 @@
+"""Core business data models."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+
+class OrderRecord(BaseModel):
+    """A 表一行订单记录的内部表示。"""
+
+    row_index: int = Field(..., description="原始表格行号 (0-based, 含表头)")
+    order_no: str = ""
+    product_price: Optional[str] = None
+    packaging_price: Optional[str] = None
+    freight: Optional[str] = None
+    customer_quote: Optional[str] = None
+    gross_profit: Optional[str] = None
+    refund_status: Optional[str] = None
+    raw_data: list[Any] = Field(default_factory=list)
+    source_platform: str = "tencent_docs"
+    source_sheet: str = ""
+
+
+class RefundRecord(BaseModel):
+    """B 表一行退款记录的内部表示。"""
+
+    row_index: int
+    order_no: str = ""
+    refund_order_no: Optional[str] = None
+    shop: Optional[str] = None
+    customer_wechat: Optional[str] = None
+    product: Optional[str] = None
+    reason: Optional[str] = None
+    amount: Optional[str] = None
+    refund_status: Optional[str] = None
+    raw_data: list[Any] = Field(default_factory=list)