tb-order-sync 0.3.1 → 0.4.0

package/.env.example

@@ -10,6 +10,7 @@ STATE_DIR=state
 
 # ── 腾讯文档配置 ──────────────────────────────────────────
 TENCENT_CLIENT_ID=
+# 当前运行链路可不填；如后续接 OAuth 自动刷新可再补齐
 TENCENT_CLIENT_SECRET=
 TENCENT_OPEN_ID=
 TENCENT_ACCESS_TOKEN=
@@ -33,7 +34,7 @@ STARTUP_JITTER_SECONDS=15
 WRITE_BATCH_SIZE=100
 RETRY_TIMES=3
 DRY_RUN=false
-ENABLE_STYLE_UPDATE=false
+ENABLE_STYLE_UPDATE=true
 
 # ── 列映射配置 ────────────────────────────────────────────
 A_COL_PRODUCT_PRICE=C
@@ -46,5 +47,5 @@ A_COL_REFUND_STATUS=I
 B_COL_ORDER_NO=A
 
 # ── 业务文案 ──────────────────────────────────────────────
-REFUND_STATUS_TEXT=进入退款流程
+REFUND_STATUS_TEXT=已退款
 DATA_ERROR_TEXT=数据异常

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.4.0] - 2026-03-19
+
+### Added
+
+- Added startup self-check in `tb check`, including state directory write validation and live Tencent Docs A/B sheet read checks.
+- Added Tencent Docs URL parsing in setup so users can paste full sheet links and auto-fill `File ID` / `Sheet ID`.
+- Added login auto-start support via `tb daemon autostart-enable|status|disable` for Windows Task Scheduler and macOS LaunchAgent.
+- Added `state/last_run.json` execution summaries for manual and scheduled runs.
+- Added packaged `快速开始.txt` to distribution outputs for non-technical users.
+
+### Changed
+
+- Changed no-argument startup to enter `setup` automatically when required runtime config is missing.
+- Changed config validation so `TENCENT_CLIENT_SECRET` is now optional for the current live Tencent Docs runtime path.
+- Changed dashboard and daemon status output to surface recent run status and login auto-start state.
+- Changed launcher and README onboarding to emphasize `tb check` as the first runtime self-check after setup.
+
+### Fixed
+
+- Fixed Tencent Docs rate-limit handling by retrying `400007 Requests Over Limit` responses with exponential backoff.
+- Fixed repeated batch writes being too aggressive by slowing inter-batch pacing.
+- Fixed user-facing error reporting so failed tasks now include clearer cause hints in CLI output.
+
 ## [0.3.1] - 2026-03-19
 
 ### Added

package/README.md

@@ -4,130 +4,109 @@
 [![GitHub Repo](https://img.shields.io/badge/GitHub-SOULRAi%2Ftb--order--sync-181717?logo=github)](https://github.com/SOULRAi/tb-order-sync)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/SOULRAi/tb-order-sync/blob/main/LICENSE)
 
-**多表格同步与退款标记服务** — 自动同步腾讯文档 / 飞书多表格数据，计算毛利并标记退款订单。
+**多表格同步与退款标记服务**  
+面向订单运营场景的轻量自动化服务，负责同步云表格、计算毛利、标记退款状态，并支持后台守护运行。
 
-> 一键启动、零配置门槛、支持 Windows / macOS 双平台，可打包为独立 exe 免安装分发。
+> 支持 `tb` 短命令、Rich 控制台、启动自检、守护进程、登录自启、Windows / macOS 一键启动，以及后续接入飞书 C 表的扩展路径。
 
----
+**快速导航**
 
-## 功能概览
+- [🚀 快速开始](#quick-start)
+- [✨ 核心能力](#capabilities)
+- [🔐 API 获取指引](#api-guide)
+- [🧠 业务规则](#business-rules)
+- [🧩 架构设计](#architecture)
+- [🛡️ 守护进程](#daemon)
+- [⚙️ 配置说明](#configuration)
+- [🧪 测试](#testing)
 
-| 功能 | 说明 | 状态 |
+<a id="capabilities"></a>
+## ✨ 核心能力
+
+| 能力 | 说明 | 状态 |
 |------|------|------|
-| 毛利自动计算 | 读取 A 表字段，计算 `毛利 = 客户报价 - 运费 - 包装价格 - 产品价格`，异常数据标记 | ✅ 已实现 |
-| 退款自动匹配 | B 表退款单号匹配 A 表订单，写入退款状态 + 可选整行标红 | ✅ 已实现 |
-| 增量同步 | 基于行指纹 (MD5) 的变更检测，只处理变化行 | ✅ 已实现 |
-| 全量同步 | 忽略缓存，全表重新计算 | ✅ 已实现 |
-| 定时调度 | APScheduler 定时执行，支持 jitter 防冲突 | ✅ 已实现 |
-| 交互式配置向导 | `setup` 命令一站式引导配置所有参数，并可直接打开官方文档链接 | ✅ 已实现 |
-| Rich 控制台 | 无参启动即进入可视化 CLI 控制台 | ✅ 已实现 |
-| 进程守护 | 支持后台启动 / 停止 / 状态 / 日志查看 | ✅ 已实现 |
-| 一键启动脚本 | 双击即用，自动初始化环境，无需手动装 Python | ✅ 已实现 |
-| 打包为 exe | PyInstaller 打包，免安装分发 | ✅ 已实现 |
-| dry-run 模式 | 模拟执行不写入，安全验证 | ✅ 已实现 |
-| 飞书 C 表同步 | C 表 → A 表数据同步 | 🔲 骨架已预留 |
-
-## 快速开始
-
-### 方式零：安装 `tb` 命令
+| 💰 毛利自动计算 | 读取 A 表字段，按固定业务公式回写毛利列 | ✅ 已实现 |
+| 🔁 退款自动匹配 | B 表退款单号匹配 A 表订单，写入退款状态列 | ✅ 已实现 |
+| 🧾 数据异常标记 | 非法数字直接写入 `数据异常`，并记录日志 | ✅ 已实现 |
+| ⚡ 增量同步 | 基于行指纹和退款集合 hash，仅处理变化数据 | ✅ 已实现 |
+| 🧨 全量重建 | 支持忽略缓存，对全表重新扫描和回写 | ✅ 已实现 |
+| 🖥️ Rich 控制台 | 无参启动即进入交互式控制台首页 | ✅ 已实现 |
+| 🩺 启动自检 | 配置检查 + 状态目录写入 + 腾讯文档 A/B 表读取 | ✅ 已实现 |
+| 🛡️ 守护进程 | 支持后台启动、停止、状态检查、日志查看 | ✅ 已实现 |
+| 🔌 登录自启 | 支持 Windows 任务计划 / macOS LaunchAgent | ✅ 已实现 |
+| 📦 一键分发 | 支持双击脚本、npm launcher、PyInstaller 打包 | ✅ 已实现 |
+| 🐦 飞书预留接口 | C 表同步抽象层和 connector skeleton 已预留 | 🔲 骨架已预留 |
+
+<a id="quick-start"></a>
+## 🚀 快速开始
+
+### 推荐命令
 
 ```bash
-# 在项目根目录执行一次
-npm link
+npm install -g tb-order-sync
 
-# 之后直接使用
 tb
-tb menu
 tb setup
+tb check
+tb all --dry-run
 tb all
-tb gp
-tb rm
 tb daemon start
 tb daemon status
 ```
 
-如果你要生成可分发的 npm 包：
-
-```bash
-npm pack
-npm install -g ./tb-order-sync-0.3.1.tgz
-```
-
-### 方式一：一键启动（推荐）
-
-**无需任何技术背景，双击即用。**
-
-| 平台 | 操作 |
-|------|------|
-| **Windows** | 双击 `启动.bat` |
-| **macOS** | 双击 `启动.command` |
+首次运行说明：
+- 如果本机还没有完整配置，直接执行 `tb` 会自动进入 `setup`
+- `tb check` 会执行启动自检，确认状态目录、A 表、B 表是否可用
 
-首次运行会自动完成：
-1. 检测 / 下载 Python 环境（如果没有）
-2. 安装依赖
-3. 进入 Rich 控制台
-4. 在控制台中继续配置、执行任务、管理守护进程
+### 启动方式
 
-```bash
-tb
-# 或直接双击启动脚本
-# 默认进入 Rich 交互式控制台
-```
+| 方式 | 适用场景 | 入口 |
+|------|----------|------|
+| `tb` 命令 | 开发、运维、长期使用 | `tb` / `tb setup` / `tb all` |
+| 双击启动 | 非技术用户 | `启动.bat` / `启动.command` |
+| Python 兼容入口 | 调试或源码环境 | `python main.py` |
+| 打包分发 | 免安装交付 | `dist/sync_service/` |
 
-### 方式二：命令行
+### 常用命令速查
 
 ```bash
-# 推荐入口
+# 控制台
 tb
 tb menu
 
-# 交互式配置
+# 配置
 tb setup
-tb config
-
-# 验证配置
 tb check
-tb setup --check
 
-# 执行任务
+# 执行
 tb all
 tb gp
 tb rm
 tb all --dry-run
 tb all --mode full
-tb gp --mode full
 
-# 定时调度
+# 调度 / 守护
 tb start
-tb schedule
-
-# 后台守护
 tb daemon start
 tb daemon status
 tb daemon logs --lines 80
 tb daemon stop
-tb daemon restart
-
-# 兼容旧写法
-python main.py
-python main.py run all
-python main.py run gross-profit
-python main.py run refund-match
+tb daemon autostart-enable
+tb daemon autostart-status
+tb daemon autostart-disable
 ```
 
-### 方式三：打包为 exe 分发
+### 双击启动
 
-```bash
-# 构建（在目标平台上执行）
-pip install pyinstaller
-python build.py --clean
+| 平台 | 文件 |
+|------|------|
+| Windows | `启动.bat` |
+| macOS | `启动.command` |
 
-# 产物在 dist/sync_service/ 目录
-# 连同 启动.bat（Windows）或 启动.command（macOS）一起分发
-# 用户无需安装 Python
-```
+首次运行会自动补齐 Python 运行环境；如果本机尚未配置，会直接进入配置向导。
 
-## API 获取指引
+<a id="api-guide"></a>
+## 🔐 API 获取指引
 
 ### 腾讯文档 API
 
@@ -140,8 +119,9 @@ python build.py --clean
   4. 再回到本项目执行 `tb setup`
 - 当前说明:
   - 本项目 MVP 目前依赖你手工提供有效 `Access Token`
-  - `Open ID` 先作为可选项保留
-  - 腾讯文档实际 endpoint / request schema 代码里仍有 `TODO / NEED_VERIFY`
+  - 当前运行链路要求 `Client ID + Open ID + Access Token`
+  - `Client Secret` 目前保留为可选项，后续接自动刷新 token 时再使用
+  - 在线表格 v3 读写链路已经完成真实联调验证
 
 ### 飞书 API
 
@@ -157,7 +137,8 @@ python build.py --clean
   - 本项目里的飞书 connector 目前还是 skeleton
   - 现阶段向导里先采集配置，为后续 C 表接入做准备
 
-## 业务规则
+<a id="business-rules"></a>
+## 🧠 业务规则
 
 ### A 表结构（订单表）
 
@@ -191,11 +172,11 @@ python build.py --clean
 
 ### 退款匹配
 
-- B 表 A 列单号存在于 A 表 H 列 → I 列写入 `进入退款流程`
+- B 表 A 列单号存在于 A 表 H 列 → I 列写入 `已退款`
 - 不存在 → 清空 I 列（同步取消）
-- 可选：`ENABLE_STYLE_UPDATE=true` 时额外设置行背景色标红
+- `ENABLE_STYLE_UPDATE=true` 时会把匹配行整行改成红色文字
 
-## 项目结构
+## 🗂️ 项目结构
 
 ```
 tb-order-sync/
@@ -255,7 +236,8 @@ tb-order-sync/
     └── test_refund_match_service.py  # 6 tests
 ```
 
-## 架构设计
+<a id="architecture"></a>
+## 🧩 架构设计
 
 ```
 ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
@@ -280,14 +262,15 @@ tb-order-sync/
 - **配置化** — 列映射、业务文案、运行模式全部可通过 `.env` 配置
 - **可扩展** — 新增 D 表、E 表时无需重构主程序
 
-## 增量策略
+## 🔄 增量策略
 
 | 目标 | 策略 | 存储 |
 |------|------|------|
 | A 表毛利 | 对每行关键字段 (C/D/E/F/H) 生成 MD5 指纹，仅处理指纹变化行 | `state/sync_state.json` |
-| B 表退款 | 对退款单号集合生成整体 hash，集合不变则跳过 | `state/sync_state.json` |
+| B 表退款 | 同时比较退款集合 hash 和 A 表单号/退款状态扫描 hash，避免漏处理 A 表变化 | `state/sync_state.json` |
 
-## 守护进程
+<a id="daemon"></a>
+## 🛡️ 守护进程
 
 - `tb daemon start`
   - 在后台启动定时调度进程
@@ -300,18 +283,32 @@ tb-order-sync/
   - 停止后台调度
 - `tb daemon restart`
   - 重启后台调度
+- `tb daemon autostart-enable`
+  - 启用当前用户登录自启
+- `tb daemon autostart-status`
+  - 查看登录自启状态
+- `tb daemon autostart-disable`
+  - 关闭登录自启
 
 后台控制台输出默认写入：
 - `state/scheduler.console.log`
+- `state/last_run.json`
+
+启动建议：
+- 先执行 `tb check`，确认配置和连接正常
+- 再执行 `tb daemon start`
+- 如需电脑登录后自动运行，再执行 `tb daemon autostart-enable`
 
-## 配置说明
+<a id="configuration"></a>
+## ⚙️ 配置说明
 
 运行 `tb setup` 可交互式完成所有配置。也可手动编辑 `.env`：
 
 ```ini
 # 腾讯文档凭证
 TENCENT_CLIENT_ID=your_client_id
-TENCENT_CLIENT_SECRET=your_client_secret
+TENCENT_CLIENT_SECRET=
+TENCENT_OPEN_ID=your_open_id
 TENCENT_ACCESS_TOKEN=your_access_token
 TENCENT_A_FILE_ID=a_table_file_id
 TENCENT_A_SHEET_ID=a_table_sheet_id
@@ -323,7 +320,7 @@ GROSS_PROFIT_MODE=incremental    # incremental | full
 REFUND_MATCH_MODE=incremental    # incremental | full
 TASK_INTERVAL_MINUTES=10         # 定时调度间隔
 DRY_RUN=false                    # true = 模拟执行不写入
-ENABLE_STYLE_UPDATE=false        # true = 退款行标红
+ENABLE_STYLE_UPDATE=true         # true = 退款行标红
 
 # 列映射（可自定义）
 A_COL_PRODUCT_PRICE=C
@@ -336,12 +333,18 @@ A_COL_REFUND_STATUS=I
 B_COL_ORDER_NO=A
 ```
 
+补充说明：
+- `tb setup` 支持直接粘贴腾讯文档完整链接，自动拆出 `File ID / Sheet ID`
+- `tb check` 会做启动自检，不只是看 `.env` 是否存在
+- 当前退款高亮效果是“整行红色文字”，不是背景填充
+
 完整配置项见 [.env.example](.env.example)。
 
-## 测试
+<a id="testing"></a>
+## 🧪 测试
 
 ```bash
-# 运行全部测试（35 tests）
+# 运行全部测试（49 tests）
 pytest tests/ -v
 
 # 单独运行
@@ -350,7 +353,7 @@ pytest tests/test_gross_profit_service.py -v
 pytest tests/test_refund_match_service.py -v
 ```
 
-## 技术栈
+## 🧱 技术栈
 
 | 组件 | 用途 |
 |------|------|
@@ -364,15 +367,15 @@ pytest tests/test_refund_match_service.py -v
 | PyInstaller | 打包为可执行文件 |
 | pytest | 单元测试 |
 
-## 部署方式对比
+## 📦 部署方式对比
 
 | 方式 | 需要 Python | 适用场景 |
 |------|------------|---------|
-| 双击启动脚本（源码） | 自动下载 | 开发/内部使用 |
-| 打包 exe 分发 | 不需要 | 给非技术用户 |
+| 双击启动脚本（源码） | 自动下载 / 初始化 | 开发/内部使用 |
+| 打包分发（Windows / macOS） | 不需要 | 给非技术用户 |
 | 命令行直接运行 | 需要 | 开发者 |
 
-## Roadmap
+## 🗺️ Roadmap
 
 - [x] 毛利自动计算
 - [x] 退款自动匹配
@@ -385,12 +388,12 @@ pytest tests/test_refund_match_service.py -v
 - [ ] 腾讯文档 OAuth2 token 自动刷新
 - [ ] 腾讯文档行样式 API 验证
 
-## 已知待确认项
+## ⚠️ 已知待确认项
 
 - 腾讯文档 Open API 的实际 endpoint 和 request/response 格式（代码中标注 `TODO / NEED_VERIFY`）
 - 腾讯文档是否支持通过 API 设置单元格样式
 - OAuth2 token 自动刷新流程
 
-## License
+## 📄 License
 
 MIT

package/build.py

@@ -17,6 +17,12 @@ ROOT = Path(__file__).resolve().parent
 SPEC_FILE = ROOT / "sync_service.spec"
 DIST_DIR = ROOT / "dist"
 BUILD_DIR = ROOT / "build"
+DIST_RUNTIME_FILES = [
+    ".env.example",
+    "启动.bat",
+    "启动.command",
+    "快速开始.txt",
+]
 
 
 def clean() -> None:
@@ -49,10 +55,10 @@ def build() -> None:
 
     output = DIST_DIR / "sync_service"
     if output.exists():
-        # Copy .env.example to dist folder for convenience
-        example = ROOT / ".env.example"
-        if example.exists():
-            shutil.copy2(example, output / ".env.example")
+        for name in DIST_RUNTIME_FILES:
+            source = ROOT / name
+            if source.exists():
+                shutil.copy2(source, output / name)
 
         # Create state directory
         (output / "state").mkdir(exist_ok=True)

package/cli/commands.py

@@ -4,10 +4,11 @@ from __future__ import annotations
 
 import argparse
 import sys
+from datetime import datetime
 from typing import TYPE_CHECKING, Optional
 
 from config.settings import Settings, SyncMode, get_settings
-from models.task_models import TaskResult
+from models.task_models import RunSummary, TaskResult
 from services.daemon_service import DaemonService
 from services.state_service import StateService
 from utils.logger import get_logger, setup_logging
@@ -54,7 +55,7 @@ def has_required_runtime_config(settings: Settings) -> bool:
     """Return whether Tencent runtime essentials are configured."""
     required = [
         settings.tencent_client_id,
-        settings.tencent_client_secret,
+        settings.tencent_open_id,
         settings.tencent_access_token,
         settings.tencent_a_file_id,
         settings.tencent_a_sheet_id,
@@ -101,6 +102,12 @@ def execute_tasks(
         _print_result(result)
         results.append(result)
 
+    if results:
+        try:
+            state_svc.save_last_run(_build_run_summary(results, trigger="manual"))
+        except Exception as exc:
+            logger.warning("Failed to save last run summary: %s", exc)
+
     return results
 
 
@@ -137,9 +144,11 @@ def cmd_daemon(args: argparse.Namespace, settings: Settings) -> None:
     daemon = DaemonService(settings)
     action = args.daemon_action
 
-    if action == "start":
+    if action in {"start", "restart", "autostart-enable"}:
         if not _ensure_runtime_config(settings):
             return
+
+    if action == "start":
         status = daemon.start(force=getattr(args, "force", False))
         logger.info(status.message)
     elif action == "stop":
@@ -153,12 +162,58 @@ def cmd_daemon(args: argparse.Namespace, settings: Settings) -> None:
         logger.info(status.message)
         if status.running:
             logger.info("daemon pid=%s log=%s", status.pid, status.log_file)
+        autostart = daemon.autostart_status()
+        logger.info("%s (%s)", autostart.message, autostart.target)
+        _print_last_run_summary(settings)
     elif action == "logs":
         content = daemon.read_log_tail(lines=args.lines)
         if content:
             print(content, end="")
         else:
             logger.info("No daemon log output yet: %s", daemon.log_file)
+    elif action == "autostart-enable":
+        status = daemon.enable_autostart()
+        logger.info(status.message)
+    elif action == "autostart-disable":
+        status = daemon.disable_autostart()
+        logger.info(status.message)
+    elif action == "autostart-status":
+        status = daemon.autostart_status()
+        logger.info("%s (%s)", status.message, status.target)
+
+
+def _build_run_summary(results: list[TaskResult], *, trigger: str) -> RunSummary:
+    finished_values = [item.finished_at for item in results if item.finished_at is not None]
+    success = all(item.success for item in results)
+    message = None
+    if not success:
+        errors = [f"{item.task_name.value}: {item.error_message}" for item in results if item.error_message]
+        message = " | ".join(errors) if errors else "存在任务失败，请检查日志。"
+    return RunSummary(
+        trigger=trigger,
+        success=success,
+        started_at=min((item.started_at for item in results), default=datetime.now()),
+        finished_at=max(finished_values) if finished_values else None,
+        task_count=len(results),
+        rows_read=sum(item.rows_read for item in results),
+        rows_changed=sum(item.rows_changed for item in results),
+        rows_error=sum(item.rows_error for item in results),
+        tasks=results,
+        message=message,
+    )
+
+
+def _print_last_run_summary(settings: Settings) -> None:
+    summary = _build_state_service(settings).load_last_run(quiet=True)
+    if summary is None:
+        return
+    status = "成功" if summary.success else "失败"
+    logger.info(
+        "最近一次执行：%s trigger=%s read=%d changed=%d errors=%d",
+        status, summary.trigger, summary.rows_read, summary.rows_changed, summary.rows_error,
+    )
+    if summary.message:
+        logger.info("最近失败信息：%s", summary.message)
 
 
 def _print_result(result: TaskResult) -> None:
@@ -168,6 +223,8 @@ def _print_result(result: TaskResult) -> None:
         status, result.task_name.value, result.rows_read,
         result.rows_changed, result.rows_error, result.dry_run,
     )
+    if result.error_message:
+        logger.error("%s failed: %s", result.task_name.value, result.error_message)
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -206,6 +263,9 @@ def build_parser() -> argparse.ArgumentParser:
     daemon_sub.add_parser("status", help="查看后台守护状态")
     daemon_logs = daemon_sub.add_parser("logs", help="查看后台日志")
     daemon_logs.add_argument("--lines", type=int, default=40, help="显示最后 N 行日志")
+    daemon_sub.add_parser("autostart-enable", help="启用登录自启")
+    daemon_sub.add_parser("autostart-disable", help="停用登录自启")
+    daemon_sub.add_parser("autostart-status", help="查看登录自启状态")
 
     setup_parser = sub.add_parser("setup", aliases=["config"], help="交互式配置向导")
     setup_parser.add_argument("--check", action="store_true", help="验证当前配置状态")
@@ -219,12 +279,12 @@ def build_parser() -> argparse.ArgumentParser:
 def main(argv: list[str] | None = None) -> None:
     """CLI main entry point."""
     argv = list(sys.argv[1:] if argv is None else argv)
-    if not argv:
-        argv = ["menu"]
-
     settings = get_settings()
     setup_logging(level=settings.log_level, log_dir=settings.state_dir)
 
+    if not argv:
+        argv = ["menu"] if has_required_runtime_config(settings) else ["setup"]
+
     parser = build_parser()
     args = parser.parse_args(argv)