tb-order-sync 0.4.1 → 0.4.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tb-order-sync",
-  "version": "0.4.1",
-  "description": "Tencent Docs order sync service with gross-profit automation, refund marking, startup self-check, autostart daemon, and tb CLI",
+  "version": "0.4.5",
+  "description": "Tencent Docs order sync CLI with one-command npm install, gross-profit automation, refund marking, self-check, and daemon mode",
   "bin": {
     "tb": "bin/tb.js"
   },
@@ -26,6 +26,7 @@
     "启动.command"
   ],
   "scripts": {
+    "postinstall": "node bin/postinstall.js",
     "tb": "node bin/tb.js",
     "check": "node bin/tb.js check",
     "pack:local": "npm pack"

package/services/daemon_service.py

@@ -14,7 +14,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
-from config.settings import PROJECT_ROOT, Settings
+from config.settings import APP_HOME, PACKAGE_ROOT, Settings
 from utils.logger import get_logger
 
 logger = get_logger(__name__)
@@ -131,10 +131,14 @@ class DaemonService:
         log_handle = self._log_path.open("ab")
         try:
             spawn_kwargs: dict[str, Any] = {
-                "cwd": str(PROJECT_ROOT),
+                "cwd": str(PACKAGE_ROOT),
                 "stdin": subprocess.DEVNULL,
                 "stdout": log_handle,
                 "stderr": log_handle,
+                "env": {
+                    **os.environ,
+                    "TB_HOME": str(APP_HOME),
+                },
             }
 
             if os.name == "nt":
@@ -332,7 +336,7 @@ class DaemonService:
     def _build_spawn_command(self) -> list[str]:
         if getattr(sys, "frozen", False):
             return [str(Path(sys.executable).resolve()), "schedule"]
-        return [sys.executable, str(PROJECT_ROOT / "main.py"), "schedule"]
+        return [sys.executable, str(PACKAGE_ROOT / "main.py"), "schedule"]
 
     def _autostart_command_line(self) -> str:
         return subprocess.list2cmdline(self._build_spawn_command())
@@ -355,7 +359,11 @@ class DaemonService:
             "  <array>\n"
             f"{args}\n"
             "  </array>\n"
-            f"  <key>WorkingDirectory</key>\n  <string>{PROJECT_ROOT}</string>\n"
+            "  <key>EnvironmentVariables</key>\n"
+            "  <dict>\n"
+            f"    <key>TB_HOME</key>\n    <string>{APP_HOME}</string>\n"
+            "  </dict>\n"
+            f"  <key>WorkingDirectory</key>\n  <string>{PACKAGE_ROOT}</string>\n"
             "  <key>RunAtLoad</key>\n  <true/>\n"
             "  <key>KeepAlive</key>\n  <false/>\n"
             f"  <key>StandardOutPath</key>\n  <string>{self._log_path}</string>\n"

package/services/gross_profit_service.py

@@ -22,6 +22,7 @@ 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
+from utils.sheet_selector import ResolvedSheetTarget, resolve_latest_month_sheet
 
 logger = get_logger(__name__)
 
@@ -55,7 +56,8 @@ class GrossProfitService:
 
         try:
             state = self._state_svc.load()
-            rows = self._read_a_table()
+            a_target = self._resolve_a_target()
+            rows = self._read_a_table(a_target.sheet_id)
             result.rows_read = len(rows)
             if not rows:
                 logger.warning("A table returned 0 data rows")
@@ -69,7 +71,7 @@ class GrossProfitService:
             result.rows_error = errors
 
             if updates and not dry_run:
-                self._write_updates(updates)
+                self._write_updates(a_target.sheet_id, updates)
                 state.last_run_at = datetime.now()
                 self._state_svc.save(state)
 
@@ -89,14 +91,29 @@ class GrossProfitService:
 
     # ── Internal ───────────────────────────────────────────────────────────
 
-    def _read_a_table(self) -> list[list[Any]]:
+    def _read_a_table(self, sheet_id: str) -> list[list[Any]]:
         rows = self._conn.read_rows(
             self._settings.tencent_a_file_id,
-            self._settings.tencent_a_sheet_id,
+            sheet_id,
         )
         # Skip header (row 0)
         return rows[1:] if rows else []
 
+    def _resolve_a_target(self) -> ResolvedSheetTarget:
+        target = resolve_latest_month_sheet(
+            self._conn,  # type: ignore[arg-type]
+            file_id=self._settings.tencent_a_file_id,
+            fallback_sheet_id=self._settings.tencent_a_sheet_id,
+            title_keyword=self._settings.tencent_a_sheet_name_keyword,
+        )
+        if target.source != "fixed":
+            logger.info(
+                "A 表自动选择最新月份工作表: %s (%s)",
+                target.title or target.sheet_id,
+                target.sheet_id,
+            )
+        return target
+
     def _parse_rows(self, rows: list[list[Any]]) -> list[OrderRecord]:
         m = self._map
         records: list[OrderRecord] = []
@@ -167,10 +184,10 @@ class GrossProfitService:
 
         return updates, changed, errors
 
-    def _write_updates(self, updates: list[CellUpdate]) -> None:
+    def _write_updates(self, sheet_id: str, updates: list[CellUpdate]) -> None:
         self._conn.batch_update(
             self._settings.tencent_a_file_id,
-            self._settings.tencent_a_sheet_id,
+            sheet_id,
             updates,
             batch_size=self._settings.write_batch_size,
         )

package/services/refund_match_service.py

@@ -23,6 +23,7 @@ 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
+from utils.sheet_selector import ResolvedSheetTarget, resolve_latest_month_sheet
 
 logger = get_logger(__name__)
 
@@ -59,14 +60,16 @@ class RefundMatchService:
 
         try:
             state = self._state_svc.load()
+            a_target = self._resolve_a_target()
+            b_target = self._resolve_b_target()
 
             # 1. Build refund set from B table
-            refund_set = self._build_refund_set()
+            refund_set = self._build_refund_set(b_target.sheet_id)
             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()
+            a_rows = self._read_a_table(a_target.sheet_id)
             result.rows_read = len(a_rows)
             a_scan_hash = self._build_a_scan_hash(a_rows)
 
@@ -89,12 +92,12 @@ class RefundMatchService:
                 if updates:
                     self._conn.batch_update(
                         self._settings.tencent_a_file_id,
-                        self._settings.tencent_a_sheet_id,
+                        a_target.sheet_id,
                         updates,
                         batch_size=self._settings.write_batch_size,
                     )
                 if self._settings.enable_style_update and style_ops:
-                    self._apply_styles(style_ops)
+                    self._apply_styles(a_target.sheet_id, style_ops)
 
                 state.b_table_refund_hash = new_refund_hash
                 state.b_table_refund_set = sorted(refund_set)
@@ -117,10 +120,10 @@ class RefundMatchService:
 
     # ── Internal ───────────────────────────────────────────────────────────
 
-    def _build_refund_set(self) -> set[str]:
+    def _build_refund_set(self, sheet_id: str) -> set[str]:
         rows = self._conn.read_rows(
             self._settings.tencent_b_file_id,
-            self._settings.tencent_b_sheet_id,
+            sheet_id,
         )
         # Skip header
         data_rows = rows[1:] if rows else []
@@ -133,13 +136,43 @@ class RefundMatchService:
                 refund_set.add(order_no)
         return refund_set
 
-    def _read_a_table(self) -> list[list[Any]]:
+    def _read_a_table(self, sheet_id: str) -> list[list[Any]]:
         rows = self._conn.read_rows(
             self._settings.tencent_a_file_id,
-            self._settings.tencent_a_sheet_id,
+            sheet_id,
         )
         return rows[1:] if rows else []
 
+    def _resolve_a_target(self) -> ResolvedSheetTarget:
+        target = resolve_latest_month_sheet(
+            self._conn,  # type: ignore[arg-type]
+            file_id=self._settings.tencent_a_file_id,
+            fallback_sheet_id=self._settings.tencent_a_sheet_id,
+            title_keyword=self._settings.tencent_a_sheet_name_keyword,
+        )
+        if target.source != "fixed":
+            logger.info(
+                "退款匹配使用 A 表最新月份工作表: %s (%s)",
+                target.title or target.sheet_id,
+                target.sheet_id,
+            )
+        return target
+
+    def _resolve_b_target(self) -> ResolvedSheetTarget:
+        target = resolve_latest_month_sheet(
+            self._conn,  # type: ignore[arg-type]
+            file_id=self._settings.tencent_b_file_id,
+            fallback_sheet_id=self._settings.tencent_b_sheet_id,
+            title_keyword=self._settings.tencent_b_sheet_name_keyword,
+        )
+        if target.source != "fixed":
+            logger.info(
+                "退款匹配使用 B 表最新月份工作表: %s (%s)",
+                target.title or target.sheet_id,
+                target.sheet_id,
+            )
+        return target
+
     def _build_a_scan_hash(self, a_rows: list[list[Any]]) -> str:
         m = self._map
         row_hashes = []
@@ -219,14 +252,14 @@ class RefundMatchService:
 
         return updates, style_ops, changed
 
-    def _apply_styles(self, ops: list[tuple[int, Optional[str]]]) -> None:
+    def _apply_styles(self, sheet_id: str, ops: list[tuple[int, Optional[str]]]) -> None:
         failures: list[str] = []
         total = len(ops)
         for index, (row_idx, color) in enumerate(ops):
             try:
                 self._conn.update_row_style(
                     self._settings.tencent_a_file_id,
-                    self._settings.tencent_a_sheet_id,
+                    sheet_id,
                     row_idx,
                     bg_color=color,
                 )

package/sync_service.spec

@@ -20,6 +20,7 @@ a = Analysis(
     pathex=[str(root)],
     binaries=[],
     datas=[
+        (str(root / 'package.json'), '.'),
         # Bundle .env.example so first-run setup can use it as template
         (str(root / '.env.example'), '.'),
         (str(root / '快速开始.txt'), '.'),

package/utils/sheet_selector.py

@@ -0,0 +1,125 @@
+"""Helpers for resolving monthly Tencent Docs sheet targets."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Iterable, Protocol
+
+
+_YEAR_MONTH_RE = re.compile(r"(?P<year>20\d{2})\s*[年./_-]?\s*(?P<month>1[0-2]|0?[1-9])\s*月?")
+_MONTH_ONLY_RE = re.compile(r"(?<!\d)(?P<month>1[0-2]|0?[1-9])\s*月")
+
+
+@dataclass(frozen=True, slots=True)
+class SheetInfo:
+    """Minimal spreadsheet tab metadata."""
+
+    sheet_id: str
+    title: str
+    index: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedSheetTarget:
+    """Resolved file/sheet target for one task run."""
+
+    file_id: str
+    sheet_id: str
+    title: str | None = None
+    source: str = "fixed"
+
+
+class SheetListingConnector(Protocol):
+    """Connector protocol for optional sheet-listing support."""
+
+    def list_sheets(self, file_id: str) -> list[SheetInfo]:
+        """Return spreadsheet tabs for a file."""
+
+
+def resolve_latest_month_sheet(
+    connector: SheetListingConnector,
+    *,
+    file_id: str,
+    fallback_sheet_id: str,
+    title_keyword: str,
+) -> ResolvedSheetTarget:
+    """Resolve the latest monthly sheet by title keyword.
+
+    If `title_keyword` is blank, the fixed `fallback_sheet_id` is returned unchanged.
+    """
+    keyword = title_keyword.strip()
+    if not keyword:
+        return ResolvedSheetTarget(file_id=file_id, sheet_id=fallback_sheet_id, source="fixed")
+
+    list_sheets = getattr(connector, "list_sheets", None)
+    if not callable(list_sheets):
+        raise RuntimeError("当前 connector 不支持按标题自动选择最新月份工作表")
+
+    sheets = list_sheets(file_id)
+    selected = select_latest_month_sheet(sheets, keyword=keyword)
+    return ResolvedSheetTarget(
+        file_id=file_id,
+        sheet_id=selected.sheet_id,
+        title=selected.title,
+        source="latest-month",
+    )
+
+
+def select_latest_month_sheet(sheets: Iterable[SheetInfo], *, keyword: str) -> SheetInfo:
+    """Choose the latest monthly sheet from matching titles.
+
+    Priority:
+    1. Prefer titles that include both year and month, such as `2026年3月` / `2026-03` / `2026/03`
+    2. Fall back to month-only titles such as `3月毛利率`
+
+    This keeps same-year monthly tabs automatic, while allowing accurate cross-year
+    selection when the sheet title carries the year.
+    """
+    needle = keyword.strip().lower()
+    candidates = [sheet for sheet in sheets if needle in sheet.title.lower()]
+    if not candidates:
+        raise ValueError(f"未找到包含关键字 '{keyword}' 的工作表")
+
+    ranked: list[tuple[int, int, int, SheetInfo]] = []
+    unparsed: list[SheetInfo] = []
+    for sheet in candidates:
+        period = extract_year_month(sheet.title)
+        if period is None:
+            unparsed.append(sheet)
+            continue
+        year, month = period
+        ranked.append((year, month, sheet.index, sheet))
+
+    if ranked:
+        ranked.sort(key=lambda item: (item[0], item[1], item[2]))
+        return ranked[-1][3]
+
+    if len(candidates) == 1:
+        return candidates[0]
+
+    titles = ", ".join(sheet.title for sheet in candidates[:5])
+    raise ValueError(
+        f"找到多个包含关键字 '{keyword}' 的工作表，但无法从标题解析月份: {titles}"
+    )
+
+
+def extract_year_month(title: str) -> tuple[int, int] | None:
+    """Extract `(year, month)` from a sheet title.
+
+    Supports examples like:
+    - 2026年3月毛利率
+    - 2026-03 毛利率
+    - 3月毛利率
+    """
+    year_month = _YEAR_MONTH_RE.search(title)
+    if year_month:
+        year = int(year_month.group("year"))
+        month = int(year_month.group("month"))
+        return year, month
+
+    month_only = _MONTH_ONLY_RE.search(title)
+    if month_only:
+        return 0, int(month_only.group("month"))
+
+    return None

package//345/220/257/345/212/250.bat

@@ -1,4 +1,5 @@
 @echo off
+setlocal EnableExtensions DisableDelayedExpansion
 chcp 65001 >nul 2>&1
 title 多表格同步服务
 cd /d "%~dp0"
@@ -12,12 +13,14 @@ echo.
 :: ── 优先级1：已有打包好的 exe ────────────────────────
 if exist "sync_service.exe" (
     set "CMD=sync_service.exe"
+    set "CMD_ARGS="
     goto :menu
 )
 
 :: ── 优先级2：已有虚拟环境 ───────────────────────────
 if exist ".venv\Scripts\python.exe" (
-    set "CMD=.venv\Scripts\python main.py"
+    set "CMD=.venv\Scripts\python.exe"
+    set "CMD_ARGS=main.py"
     goto :menu
 )
 
@@ -89,7 +92,8 @@ echo  [*] 使用嵌入式 Python 安装依赖...
 echo.
 python_embed\python.exe -m pip install -q -r requirements.txt --target=".deps" 2>nul
 set "PYTHONPATH=%~dp0.deps;%~dp0"
-set "CMD=python_embed\python.exe main.py"
+set "CMD=python_embed\python.exe"
+set "CMD_ARGS=main.py"
 goto :menu
 
 :venv_setup
@@ -111,15 +115,30 @@ if errorlevel 1 (
 
 echo  [3/3] 环境初始化完成!
 echo.
-set "CMD=.venv\Scripts\python main.py"
+set "CMD=.venv\Scripts\python.exe"
+set "CMD_ARGS=main.py"
 
 :: ── 启动 Rich 控制台 / 执行指定命令 ────────────────
+:menu
+if not defined CMD (
+    echo  [!] 启动命令未初始化成功
+    echo.
+    pause
+    exit /b 1
+)
+
 if "%~1"=="" (
-    %CMD%
+    call "%CMD%" %CMD_ARGS%
     echo.
     pause
     exit /b 0
 )
 
-%CMD% %*
-exit /b %errorlevel%
+call "%CMD%" %CMD_ARGS% %*
+set "EXIT_CODE=%errorlevel%"
+if not "%EXIT_CODE%"=="0" (
+    echo.
+    echo  [!] 程序退出，返回码: %EXIT_CODE%
+    pause
+)
+exit /b %EXIT_CODE%

package//345/277/253/351/200/237/345/274/200/345/247/213.txt

@@ -1,31 +1,38 @@
 TB Order Sync 快速开始
 
-1. 双击启动
+1. 一条命令安装 CLI（macOS / 已安装 Node.js）
+- npm install -g tb-order-sync
+- 安装完成后直接运行 `tb`
+- 运行环境会放到 `~/Library/Application Support/tb-order-sync/`
+
+2. 双击启动
 - Windows: 启动.bat
 - macOS: 启动.command
 
-2. 首次运行
+3. 首次运行
 - 如果本机还没配置，程序会自动进入 setup 配置向导
 - 配好腾讯文档信息后，建议先执行一次 `tb check`
 
-3. 常用命令
+4. 常用命令
 - tb all              执行毛利计算 + 退款匹配
 - tb all --dry-run    仅演练，不写回
 - tb daemon start     后台持续运行
 - tb daemon status    查看后台状态
 - tb daemon logs      查看后台日志
 
-4. 登录自启
+5. 登录自启
 - tb daemon autostart-enable
 - tb daemon autostart-status
 - tb daemon autostart-disable
 
-5. 日志与状态文件
-- state/scheduler.console.log
-- state/last_run.json
-- state/sync_state.json
+6. 日志与状态文件
+- npm 安装方式：~/Library/Application Support/tb-order-sync/state/
+- 常见文件：
+  - scheduler.console.log
+  - last_run.json
+  - sync_state.json
 
-6. 常见问题
+7. 常见问题
 - 缺配置：运行 tb setup
 - 想做启动自检：运行 tb check
 - 接口限流：稍等后重试，不要连续高频重复执行