tb-order-sync 0.3.0

package/services/gross_profit_service.py

@@ -0,0 +1,202 @@
+"""Gross profit calculation service.
+
+Business rule:
+    毛利 = 客户报价 - 运费 - 包装价格 - 产品价格
+    G = F - E - D - C
+
+If any of C/D/E/F is not a valid number, write "数据异常" to G.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Optional
+
+from config.mappings import ColumnMapping, get_column_mapping
+from config.settings import Settings, SyncMode, get_settings
+from connectors.base import BaseSheetConnector, CellUpdate
+from models.records import OrderRecord
+from models.state_models import SyncState
+from models.task_models import TaskName, TaskResult
+from services.state_service import StateService
+from utils.diff import row_fingerprint
+from utils.logger import get_logger
+from utils.parser import normalize_order_no, parse_number
+
+logger = get_logger(__name__)
+
+
+class GrossProfitService:
+    """Calculate and write gross profit for every row in A table."""
+
+    def __init__(
+        self,
+        connector: BaseSheetConnector,
+        state_service: StateService,
+        settings: Optional[Settings] = None,
+        mapping: Optional[ColumnMapping] = None,
+    ) -> None:
+        self._conn = connector
+        self._state_svc = state_service
+        self._settings = settings or get_settings()
+        self._map = mapping or get_column_mapping()
+
+    def run(
+        self,
+        mode: Optional[SyncMode] = None,
+        dry_run: Optional[bool] = None,
+    ) -> TaskResult:
+        """Execute gross profit calculation."""
+        mode = mode or self._settings.gross_profit_mode
+        dry_run = dry_run if dry_run is not None else self._settings.dry_run
+        result = TaskResult(task_name=TaskName.GROSS_PROFIT, mode=mode, dry_run=dry_run)
+
+        logger.info("=== Gross Profit Service START (mode=%s, dry_run=%s) ===", mode.value, dry_run)
+
+        try:
+            state = self._state_svc.load()
+            rows = self._read_a_table()
+            result.rows_read = len(rows)
+            if not rows:
+                logger.warning("A table returned 0 data rows")
+                result.finish()
+                return result
+
+            records = self._parse_rows(rows)
+            updates, changed, errors = self._compute(records, state, mode)
+
+            result.rows_changed = changed
+            result.rows_error = errors
+
+            if updates and not dry_run:
+                self._write_updates(updates)
+                state.last_run_at = datetime.now()
+                self._state_svc.save(state)
+
+            if dry_run:
+                logger.info("[DRY-RUN] Would write %d cells, %d changed, %d errors", len(updates), changed, errors)
+
+            result.finish()
+            logger.info(
+                "=== Gross Profit Service END — read=%d changed=%d errors=%d ===",
+                result.rows_read, result.rows_changed, result.rows_error,
+            )
+        except Exception as exc:
+            logger.exception("Gross Profit Service failed")
+            result.finish(success=False, error_message=str(exc))
+
+        return result
+
+    # ── Internal ───────────────────────────────────────────────────────────
+
+    def _read_a_table(self) -> list[list[Any]]:
+        rows = self._conn.read_rows(
+            self._settings.tencent_a_file_id,
+            self._settings.tencent_a_sheet_id,
+        )
+        # Skip header (row 0)
+        return rows[1:] if rows else []
+
+    def _parse_rows(self, rows: list[list[Any]]) -> list[OrderRecord]:
+        m = self._map
+        records: list[OrderRecord] = []
+        for idx, row in enumerate(rows):
+            row_num = idx + 1  # 1-based data row (0 is header)
+            records.append(OrderRecord(
+                row_index=row_num,
+                order_no=normalize_order_no(self._safe_get(row, m.a_order_no)),
+                product_price=self._safe_get_str(row, m.a_product_price),
+                packaging_price=self._safe_get_str(row, m.a_packaging_price),
+                freight=self._safe_get_str(row, m.a_freight),
+                customer_quote=self._safe_get_str(row, m.a_customer_quote),
+                gross_profit=self._safe_get_str(row, m.a_gross_profit),
+                refund_status=self._safe_get_str(row, m.a_refund_status),
+                raw_data=row,
+            ))
+        return records
+
+    def _compute(
+        self,
+        records: list[OrderRecord],
+        state: SyncState,
+        mode: SyncMode,
+    ) -> tuple[list[CellUpdate], int, int]:
+        """Compute gross profit for each record, return (updates, changed_count, error_count)."""
+        m = self._map
+        updates: list[CellUpdate] = []
+        changed = 0
+        errors = 0
+
+        for rec in records:
+            # Fingerprint for incremental check: C, D, E, F, H
+            fp = row_fingerprint([
+                rec.product_price, rec.packaging_price,
+                rec.freight, rec.customer_quote, rec.order_no,
+            ])
+
+            if mode == SyncMode.INCREMENTAL:
+                old_fp = state.a_table_fingerprints.get(str(rec.row_index), "")
+                if old_fp == fp:
+                    continue  # No change
+
+            # Parse numbers
+            c = parse_number(rec.product_price)
+            d = parse_number(rec.packaging_price)
+            e = parse_number(rec.freight)
+            f = parse_number(rec.customer_quote)
+
+            if any(v is None for v in (c, d, e, f)):
+                # Data error
+                new_val = self._settings.data_error_text
+                errors += 1
+                self._log_data_error(rec, c, d, e, f)
+            else:
+                gross = f - e - d - c  # type: ignore[operator]
+                new_val = round(gross, 2)
+
+            # Check if value actually changed
+            if str(new_val) != str(rec.gross_profit or ""):
+                updates.append(CellUpdate(row=rec.row_index, col=m.a_gross_profit, value=new_val))
+                changed += 1
+
+            # Update fingerprint
+            state.a_table_fingerprints[str(rec.row_index)] = fp
+
+        return updates, changed, errors
+
+    def _write_updates(self, updates: list[CellUpdate]) -> None:
+        self._conn.batch_update(
+            self._settings.tencent_a_file_id,
+            self._settings.tencent_a_sheet_id,
+            updates,
+            batch_size=self._settings.write_batch_size,
+        )
+
+    def _log_data_error(
+        self, rec: OrderRecord,
+        c: Optional[float], d: Optional[float],
+        e: Optional[float], f: Optional[float],
+    ) -> None:
+        bad_fields = []
+        labels = [
+            ("产品价格(C)", rec.product_price, c),
+            ("包装价格(D)", rec.packaging_price, d),
+            ("运费(E)", rec.freight, e),
+            ("客户报价(F)", rec.customer_quote, f),
+        ]
+        for name, raw, parsed in labels:
+            if parsed is None:
+                bad_fields.append(f"{name}='{raw}'")
+        logger.warning(
+            "Row %d (单号=%s) 数据异常: %s",
+            rec.row_index, rec.order_no, ", ".join(bad_fields),
+        )
+
+    @staticmethod
+    def _safe_get(row: list[Any], idx: int) -> Any:
+        return row[idx] if idx < len(row) else None
+
+    @staticmethod
+    def _safe_get_str(row: list[Any], idx: int) -> Optional[str]:
+        val = row[idx] if idx < len(row) else None
+        return str(val) if val is not None else None

package/services/refund_match_service.py

@@ -0,0 +1,196 @@
+"""Refund matching service.
+
+Business rules:
+  - Read B table column A (order numbers) to build refund set
+  - Scan A table column H (order numbers)
+  - If A row's order_no is in refund set → write "进入退款流程" to A table I column
+  - If not in refund set → clear I column
+  - Optional: set/clear row background color
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Optional
+
+from config.mappings import ColumnMapping, get_column_mapping
+from config.settings import Settings, SyncMode, get_settings
+from connectors.base import BaseSheetConnector, CellUpdate
+from models.task_models import TaskName, TaskResult
+from services.state_service import StateService
+from utils.diff import row_fingerprint, set_hash
+from utils.logger import get_logger
+from utils.parser import normalize_order_no
+
+logger = get_logger(__name__)
+
+# Background colors for optional style update
+_BG_RED = "#FF4D4F"
+_BG_DEFAULT = None  # None means reset / no color
+
+
+class RefundMatchService:
+    """Match refund orders from B table against A table and update refund status."""
+
+    def __init__(
+        self,
+        connector: BaseSheetConnector,
+        state_service: StateService,
+        settings: Optional[Settings] = None,
+        mapping: Optional[ColumnMapping] = None,
+    ) -> None:
+        self._conn = connector
+        self._state_svc = state_service
+        self._settings = settings or get_settings()
+        self._map = mapping or get_column_mapping()
+
+    def run(
+        self,
+        mode: Optional[SyncMode] = None,
+        dry_run: Optional[bool] = None,
+    ) -> TaskResult:
+        mode = mode or self._settings.refund_match_mode
+        dry_run = dry_run if dry_run is not None else self._settings.dry_run
+        result = TaskResult(task_name=TaskName.REFUND_MATCH, mode=mode, dry_run=dry_run)
+
+        logger.info("=== Refund Match Service START (mode=%s, dry_run=%s) ===", mode.value, dry_run)
+
+        try:
+            state = self._state_svc.load()
+
+            # 1. Build refund set from B table
+            refund_set = self._build_refund_set()
+            new_refund_hash = set_hash(list(refund_set))
+            logger.info("B table refund set: %d order numbers, hash=%s", len(refund_set), new_refund_hash[:8])
+
+            # 2. Read A table
+            a_rows = self._read_a_table()
+            result.rows_read = len(a_rows)
+
+            # 3. Incremental short-circuit: if refund set unchanged and mode=incremental
+            if mode == SyncMode.INCREMENTAL and new_refund_hash == state.b_table_refund_hash:
+                logger.info("Refund set unchanged, skipping (incremental mode)")
+                result.finish()
+                return result
+
+            # 4. Match and compute updates
+            updates, style_ops, changed = self._match(a_rows, refund_set, state, mode)
+            result.rows_changed = changed
+
+            # 5. Write
+            if not dry_run:
+                if updates:
+                    self._conn.batch_update(
+                        self._settings.tencent_a_file_id,
+                        self._settings.tencent_a_sheet_id,
+                        updates,
+                        batch_size=self._settings.write_batch_size,
+                    )
+                if self._settings.enable_style_update and style_ops:
+                    self._apply_styles(style_ops)
+
+                state.b_table_refund_hash = new_refund_hash
+                state.b_table_refund_set = sorted(refund_set)
+                state.last_run_at = datetime.now()
+                self._state_svc.save(state)
+            else:
+                logger.info("[DRY-RUN] Would write %d cells, %d style ops, %d changed", len(updates), len(style_ops), changed)
+
+            result.finish()
+            logger.info(
+                "=== Refund Match Service END — read=%d changed=%d ===",
+                result.rows_read, result.rows_changed,
+            )
+        except Exception as exc:
+            logger.exception("Refund Match Service failed")
+            result.finish(success=False, error_message=str(exc))
+
+        return result
+
+    # ── Internal ───────────────────────────────────────────────────────────
+
+    def _build_refund_set(self) -> set[str]:
+        rows = self._conn.read_rows(
+            self._settings.tencent_b_file_id,
+            self._settings.tencent_b_sheet_id,
+        )
+        # Skip header
+        data_rows = rows[1:] if rows else []
+        refund_set: set[str] = set()
+        col = self._map.b_order_no
+        for row in data_rows:
+            val = row[col] if col < len(row) else None
+            order_no = normalize_order_no(val)
+            if order_no:
+                refund_set.add(order_no)
+        return refund_set
+
+    def _read_a_table(self) -> list[list[Any]]:
+        rows = self._conn.read_rows(
+            self._settings.tencent_a_file_id,
+            self._settings.tencent_a_sheet_id,
+        )
+        return rows[1:] if rows else []
+
+    def _match(
+        self,
+        a_rows: list[list[Any]],
+        refund_set: set[str],
+        state: SyncState,
+        mode: SyncMode,
+    ) -> tuple[list[CellUpdate], list[tuple[int, Optional[str]]], int]:
+        """Compare each A-table row's order_no against refund_set.
+
+        Returns: (cell_updates, style_operations, changed_count)
+        """
+        m = self._map
+        updates: list[CellUpdate] = []
+        style_ops: list[tuple[int, Optional[str]]] = []
+        changed = 0
+        refund_text = self._settings.refund_status_text
+
+        for idx, row in enumerate(a_rows):
+            row_num = idx + 1  # 1-based (0 is header)
+            order_no = normalize_order_no(row[m.a_order_no] if m.a_order_no < len(row) else None)
+
+            if not order_no:
+                continue
+
+            current_status = str(row[m.a_refund_status]).strip() if m.a_refund_status < len(row) and row[m.a_refund_status] is not None else ""
+            is_refund = order_no in refund_set
+
+            if is_refund:
+                desired = refund_text
+                desired_color = _BG_RED
+            else:
+                desired = ""
+                desired_color = _BG_DEFAULT
+
+            if current_status == desired:
+                continue  # No change needed
+
+            # Incremental: if mode is incremental, still process because refund set changed
+            # (we already short-circuited above if hash unchanged)
+
+            updates.append(CellUpdate(row=row_num, col=m.a_refund_status, value=desired))
+            style_ops.append((row_num, desired_color))
+            changed += 1
+
+            if is_refund:
+                logger.info("Row %d (单号=%s): 标记退款", row_num, order_no)
+            else:
+                logger.info("Row %d (单号=%s): 取消退款标记", row_num, order_no)
+
+        return updates, style_ops, changed
+
+    def _apply_styles(self, ops: list[tuple[int, Optional[str]]]) -> None:
+        for row_idx, color in ops:
+            try:
+                self._conn.update_row_style(
+                    self._settings.tencent_a_file_id,
+                    self._settings.tencent_a_sheet_id,
+                    row_idx,
+                    bg_color=color,
+                )
+            except Exception as exc:
+                logger.warning("Failed to update style for row %d: %s", row_idx, exc)

package/services/scheduler_service.py

@@ -0,0 +1,76 @@
+"""APScheduler-based task scheduler."""
+
+from __future__ import annotations
+
+import random
+import time
+from typing import Optional
+
+from apscheduler.schedulers.blocking import BlockingScheduler
+from apscheduler.triggers.interval import IntervalTrigger
+
+from config.settings import Settings, SyncMode, get_settings
+from connectors.base import BaseSheetConnector
+from services.gross_profit_service import GrossProfitService
+from services.refund_match_service import RefundMatchService
+from services.state_service import StateService
+from utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class SchedulerService:
+    """Manages periodic execution of sync tasks."""
+
+    def __init__(
+        self,
+        connector: BaseSheetConnector,
+        state_service: StateService,
+        settings: Optional[Settings] = None,
+    ) -> None:
+        self._settings = settings or get_settings()
+        self._connector = connector
+        self._state_svc = state_service
+        self._scheduler = BlockingScheduler()
+
+        self._gp_svc = GrossProfitService(connector, state_service, self._settings)
+        self._rm_svc = RefundMatchService(connector, state_service, self._settings)
+
+    def _run_all(self) -> None:
+        """Execute all tasks in sequence."""
+        logger.info("--- Scheduled run: all tasks ---")
+        self._gp_svc.run()
+        self._rm_svc.run()
+
+    def start(self) -> None:
+        """Start the blocking scheduler with configured interval and jitter."""
+        jitter = self._settings.startup_jitter_seconds
+        if jitter > 0:
+            delay = random.uniform(0, jitter)
+            logger.info("Startup jitter: sleeping %.1f seconds", delay)
+            time.sleep(delay)
+
+        interval_minutes = self._settings.task_interval_minutes
+        self._scheduler.add_job(
+            self._run_all,
+            trigger=IntervalTrigger(minutes=interval_minutes),
+            id="sync_all",
+            name="Sync All Tasks",
+            max_instances=1,
+            coalesce=True,
+        )
+        logger.info("Scheduler started: interval=%d minutes", interval_minutes)
+
+        # Run once immediately
+        self._run_all()
+
+        try:
+            self._scheduler.start()
+        except (KeyboardInterrupt, SystemExit):
+            logger.info("Scheduler stopped by user")
+            self._scheduler.shutdown(wait=False)
+
+    def stop(self) -> None:
+        if self._scheduler.running:
+            self._scheduler.shutdown(wait=False)
+            logger.info("Scheduler stopped")

package/services/state_service.py

@@ -0,0 +1,50 @@
+"""Local JSON-based state persistence for incremental sync."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from models.state_models import SyncState
+from utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+STATE_FILENAME = "sync_state.json"
+
+
+class StateService:
+    """Read / write incremental sync state from a local JSON file."""
+
+    def __init__(self, state_dir: str) -> None:
+        self._dir = Path(state_dir)
+        self._dir.mkdir(parents=True, exist_ok=True)
+        self._path = self._dir / STATE_FILENAME
+
+    def load(self, *, quiet: bool = False) -> SyncState:
+        """Load state from disk. Returns fresh state if file missing / corrupt."""
+        if not self._path.exists():
+            if not quiet:
+                logger.info("No existing state file, starting fresh: %s", self._path)
+            return SyncState()
+        try:
+            raw = self._path.read_text(encoding="utf-8")
+            data = json.loads(raw)
+            state = SyncState.model_validate(data)
+            if not quiet:
+                logger.info("Loaded sync state from %s", self._path)
+            return state
+        except Exception as exc:
+            if not quiet:
+                logger.warning("Failed to load state (%s), starting fresh: %s", exc, self._path)
+            return SyncState()
+
+    def save(self, state: SyncState) -> None:
+        """Persist state to disk."""
+        try:
+            raw = state.model_dump_json(indent=2)
+            self._path.write_text(raw, encoding="utf-8")
+            logger.info("Saved sync state to %s", self._path)
+        except Exception as exc:
+            logger.error("Failed to save state: %s", exc)
+            raise

package/sync_service.spec

@@ -0,0 +1,93 @@
+# -*- mode: python ; coding: utf-8 -*-
+"""PyInstaller spec file for 多表格同步服务.
+
+Build:
+    pyinstaller sync_service.spec
+
+Output:
+    dist/sync_service/sync_service.exe  (Windows)
+    dist/sync_service/sync_service      (macOS/Linux)
+"""
+
+import sys
+from pathlib import Path
+
+block_cipher = None
+root = Path(SPECPATH)
+
+a = Analysis(
+    [str(root / 'main.py')],
+    pathex=[str(root)],
+    binaries=[],
+    datas=[
+        # Bundle .env.example so first-run setup can use it as template
+        (str(root / '.env.example'), '.'),
+    ],
+    hiddenimports=[
+        'config',
+        'config.settings',
+        'config.mappings',
+        'connectors',
+        'connectors.base',
+        'connectors.tencent_docs',
+        'connectors.feishu_sheets',
+        'models',
+        'models.records',
+        'models.task_models',
+        'models.state_models',
+        'services',
+        'services.gross_profit_service',
+        'services.refund_match_service',
+        'services.c_to_a_sync_service',
+        'services.scheduler_service',
+        'services.state_service',
+        'utils',
+        'utils.logger',
+        'utils.parser',
+        'utils.diff',
+        'utils.retry',
+        'cli',
+        'cli.commands',
+        'cli.setup',
+        # Pydantic v2 needs these
+        'pydantic',
+        'pydantic_settings',
+        'annotated_types',
+        'dotenv',
+    ],
+    hookspath=[],
+    hooksconfig={},
+    runtime_hooks=[],
+    excludes=[],
+    win_no_prefer_redirects=False,
+    win_private_assemblies=False,
+    cipher=block_cipher,
+    noarchive=False,
+)
+
+pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)
+
+exe = EXE(
+    pyz,
+    a.scripts,
+    [],
+    exclude_binaries=True,
+    name='sync_service',
+    debug=False,
+    bootloader_ignore_signals=False,
+    strip=False,
+    upx=True,
+    console=True,  # Must be console app for interactive CLI
+    icon=None,
+)
+
+coll = COLLECT(
+    exe,
+    a.binaries,
+    a.zipfiles,
+    a.datas,
+    strip=False,
+    upx=True,
+    upx_exclude=[],
+    name='sync_service',
+)

package/utils/diff.py

@@ -0,0 +1,27 @@
+"""Row fingerprinting and diff utilities for incremental sync."""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Any, Sequence
+
+
+def row_fingerprint(fields: Sequence[Any]) -> str:
+    """Generate an MD5 hex digest for a list of cell values.
+
+    Used to detect whether a row's key fields have changed since last sync.
+    """
+    raw = "|".join(_normalize(v) for v in fields)
+    return hashlib.md5(raw.encode("utf-8")).hexdigest()
+
+
+def set_hash(items: Sequence[str]) -> str:
+    """Generate a hash for an ordered set of strings (e.g. refund order nos)."""
+    combined = "\n".join(sorted(items))
+    return hashlib.md5(combined.encode("utf-8")).hexdigest()
+
+
+def _normalize(value: Any) -> str:
+    if value is None:
+        return ""
+    return str(value).strip()

package/utils/logger.py

@@ -0,0 +1,47 @@
+"""Centralized logging setup.
+
+Usage:
+    from utils.logger import get_logger
+    logger = get_logger(__name__)
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+
+_INITIALIZED = False
+
+
+def setup_logging(level: str = "INFO", log_dir: str | None = None) -> None:
+    """Configure root logger with console + optional file handler."""
+    global _INITIALIZED
+    if _INITIALIZED:
+        return
+    _INITIALIZED = True
+
+    root = logging.getLogger()
+    root.setLevel(getattr(logging, level.upper(), logging.INFO))
+
+    fmt = logging.Formatter(
+        fmt="%(asctime)s | %(levelname)-7s | %(name)s | %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    # Console handler
+    console = logging.StreamHandler(sys.stdout)
+    console.setFormatter(fmt)
+    root.addHandler(console)
+
+    # File handler (optional)
+    if log_dir:
+        log_path = Path(log_dir)
+        log_path.mkdir(parents=True, exist_ok=True)
+        fh = logging.FileHandler(log_path / "sync_service.log", encoding="utf-8")
+        fh.setFormatter(fmt)
+        root.addHandler(fh)
+
+
+def get_logger(name: str) -> logging.Logger:
+    return logging.getLogger(name)