tb-order-sync 0.4.2 → 0.4.6

package/.env.example

@@ -16,8 +16,12 @@ TENCENT_OPEN_ID=
 TENCENT_ACCESS_TOKEN=
 TENCENT_A_FILE_ID=
 TENCENT_A_SHEET_ID=
+# 可选：填写后会在 A 表文件中按标题关键字自动选择“最新月份”工作表
+TENCENT_A_SHEET_NAME_KEYWORD=
 TENCENT_B_FILE_ID=
 TENCENT_B_SHEET_ID=
+# 可选：填写后会在 B 表文件中按标题关键字自动选择“最新月份”工作表
+TENCENT_B_SHEET_NAME_KEYWORD=
 
 # ── 飞书配置（预留） ─────────────────────────────────────
 FEISHU_APP_ID=

package/CHANGELOG.md

@@ -2,6 +2,75 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.4.6] - 2026-03-20
+
+### 变更
+
+- 简化 `tb setup` 配置向导：链接选择统一改为“输入编号打开，直接回车跳过”，不再显示 `0` 和 `/skip` 等额外选项。
+- 简化腾讯文档凭证录入：向导现只要求填写 `Client ID`、`Open ID`、`Access Token`，不再弹出 `Client Secret` 输入。
+- 简化表格配置：A / B 表现改为直接粘贴完整腾讯文档链接并自动解析，不再要求用户手动输入 `File ID`。
+- 简化配置流程：隐藏飞书配置、运行环境、日志级别、C 表同步模式等当前不用的项目，减少新手初始化负担。
+- 优化中文文案：`A表（订单表）` 改为 `A表（订单表/毛利率表）`，`A/B 表按名称自动选最新月份` 改为 `A/B表表格关键字匹配`。
+- 优化运行模式选择：毛利计算模式和退款匹配模式现改为中文二选一说明，不再直接显示英文枚举。
+
+### 修复
+
+- 修复配置向导帮助说明过于技术化的问题，改成小白可理解的“打开表格 -> 复制完整链接 -> 粘贴自动解析”流程。
+- 修复 README 与当前向导行为不一致的问题，更新腾讯文档配置说明和最新测试结果。
+
+## [0.4.5] - 2026-03-20
+
+### 新增
+
+- 在 CLI 首页和配置向导的 LOGO 右下角新增版本号展示，便于直接确认当前运行版本。
+
+### 变更
+
+- 变更发布构建内容：打包产物现在会一并包含 `package.json`，保证 macOS / Windows 分发包中的 CLI 也能正确显示版本号。
+- 变更 README 的分发包说明，统一 macOS 资产命名为 `tb-order-sync-macos-x64-<version>.zip`。
+
+### 修复
+
+- 修复 `tb setup` 链接选择菜单的残留交互问题：现在支持 `0`、空回车、`/skip`、`q` 等跳过方式，并在输入流中断时安全退出，不再抛出 `EOFError` 栈追踪。
+
+## [0.4.4] - 2026-03-20
+
+### 修复
+
+- 修复 `tb setup` 在 Windows 环境下输入不稳定的问题：配置向导现统一使用原生 `input()` 读取，避免官网链接打开后无法继续输入、无法输入字母数字、无法粘贴的问题。
+- 修复 `tb setup` 的官网链接打开交互体验：保持数字菜单方式，支持跳过、打开全部、打开单个链接，并增强 Windows 下的浏览器启动回退逻辑。
+- 修复 Windows 双击 `启动.bat` 可能直接闪退的问题：补上缺失的 `:menu` 标签，并修正 Python / EXE 命令拼接与失败停留逻辑。
+
+## [0.4.3] - 2026-03-20
+
+### 新增
+
+- 新增按工作表标题关键字自动选择“最新月份” sheet 的能力，可分别作用于 A 表和 B 表。
+- 新增工作表月份解析工具，支持以下标题格式：
+  - `2026年3月毛利率`
+  - `2026-03 毛利率`
+  - `2026/03 客户退款`
+  - `3月毛利率`
+- 新增 `TENCENT_A_SHEET_NAME_KEYWORD` / `TENCENT_B_SHEET_NAME_KEYWORD` 两个可选配置项。
+- 新增月份选择相关单元测试，覆盖同年和跨年场景。
+
+### 变更
+
+- 变更毛利计算与退款匹配服务：当配置了 sheet 标题关键字后，运行时会优先选择匹配关键字的最新月份工作表，而不是只依赖固定 `sheet_id`。
+- 变更 `tb setup` 与 `tb check`：配置向导和启动自检现已支持并展示自动月表选择逻辑。
+- 变更 CLI 控制台视觉风格：首页新增 LOGO、状态徽章和更统一的配色。
+- 变更 CLI 次级页面视觉风格：执行结果、失败详情、守护结果、后台日志、配置未完成提示，统一为一致的模态面板样式。
+
+### 修复
+
+- 修复跨年月份选择歧义：当标题中包含年份时，优先按“年 + 月”判断最新工作表，而不是只比较月份数字。
+- 修复本地 CLI 体验不一致问题，使首页与二级页面在视觉上保持统一。
+- 修复 `tb setup` 中官网链接打开交互不明确的问题：现已改为数字菜单，支持打开全部、打开单个链接或暂时跳过。
+- 修复配置向导中凭证输入不可直接粘贴的问题：`Client ID` / `Open ID` / `Access Token` 等输入现改为可见输入，支持直接粘贴。
+- 修复配置向导中无法暂时跳过某一项的问题：现可输入 `/skip` 暂时跳过，后续再补充配置。
+- 修复 Windows 双击 `启动.bat` 可能直接闪退的问题：补上缺失的 `:menu` 标签，并修正 Python / EXE 启动命令拼接方式。
+- 修复 Windows 打包环境下 setup 输入不稳定的问题：现将配置向导输入统一切回原生 `input()`，避免链接打开后无法继续输入或无法粘贴。
+
 ## [0.4.2] - 2026-03-19
 
 ### Added

package/README.md

@@ -78,7 +78,7 @@ tb daemon status
 
 GitHub Release 现已提供标准完整分发包：
 - Windows: `tb-order-sync-windows-x64-<version>.zip`
-- macOS: `tb-order-sync-macos-bootstrap-<version>.zip`
+- macOS: `tb-order-sync-macos-x64-<version>.zip`
 
 ### 常用命令速查
 
@@ -127,13 +127,12 @@ tb daemon autostart-disable
 - 开发者平台: [腾讯文档开放生态](https://docs.qq.com/open/developers/)
 - 建议流程:
   1. 先进入开发者平台创建应用
-  2. 在应用详情页获取 `Client ID` 和 `Client Secret`
-  3. 按官方 OAuth2 流程获取 `Access Token`
+  2. 在应用详情页获取 `Client ID`
+  3. 完成授权后获取 `Open ID` 和 `Access Token`
   4. 再回到本项目执行 `tb setup`
 - 当前说明:
   - 本项目 MVP 目前依赖你手工提供有效 `Access Token`
   - 当前运行链路要求 `Client ID + Open ID + Access Token`
-  - `Client Secret` 目前保留为可选项，后续接自动刷新 token 时再使用
   - 在线表格 v3 读写链路已经完成真实联调验证
 
 ### 飞书 API
@@ -327,8 +326,10 @@ 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
+TENCENT_A_SHEET_NAME_KEYWORD=毛利率
 TENCENT_B_FILE_ID=b_table_file_id
 TENCENT_B_SHEET_ID=b_table_sheet_id
+TENCENT_B_SHEET_NAME_KEYWORD=客户退款
 
 # 运行模式
 GROSS_PROFIT_MODE=incremental    # incremental | full
@@ -349,7 +350,9 @@ B_COL_ORDER_NO=A
 ```
 
 补充说明：
-- `tb setup` 支持直接粘贴腾讯文档完整链接，自动拆出 `File ID / Sheet ID`
+- `tb setup` 会直接要求你粘贴腾讯文档完整链接，并自动解析 `File ID / Sheet ID`
+- `tb setup` 当前只保留腾讯文档最小必填项，不再展示飞书和其他暂时不用的高级配置
+- 如果填写 `TENCENT_A_SHEET_NAME_KEYWORD` / `TENCENT_B_SHEET_NAME_KEYWORD`，系统会在对应文件里自动选取标题中匹配关键字的“最新月份”工作表
 - `tb check` 会做启动自检，不只是看 `.env` 是否存在
 - 当前退款高亮效果是“整行红色文字”，不是背景填充
 
@@ -359,7 +362,7 @@ B_COL_ORDER_NO=A
 ## 🧪 测试
 
 ```bash
-# 运行全部测试（49 tests）
+# 运行全部测试
 pytest tests/ -v
 
 # 单独运行

package/build.py

@@ -18,6 +18,7 @@ SPEC_FILE = ROOT / "sync_service.spec"
 DIST_DIR = ROOT / "dist"
 BUILD_DIR = ROOT / "build"
 DIST_RUNTIME_FILES = [
+    "package.json",
     ".env.example",
     "启动.bat",
     "启动.command",

package/cli/dashboard.py

@@ -14,10 +14,25 @@ from rich.panel import Panel
 from rich.table import Table
 from rich.text import Text
 
-from config.settings import Settings, get_settings
+from config.settings import APP_VERSION, Settings, get_settings
 from services.daemon_service import DaemonService
 from services.state_service import StateService
 
+_LOGO_LINES = [
+    ("████████╗██████╗      ██████╗ ██████╗ ██████╗ ███████╗██████╗", "bold #8ecae6"),
+    ("╚══██╔══╝██╔══██╗    ██╔═══██╗██╔══██╗██╔══██╗██╔════╝██╔══██╗", "bold #6ccff6"),
+    ("   ██║   ██████╔╝    ██║   ██║██████╔╝██║  ██║█████╗  ██████╔╝", "bold #38bdf8"),
+    ("   ██║   ██╔══██╗    ██║   ██║██╔══██╗██║  ██║██╔══╝  ██╔══██╗", "bold #22d3ee"),
+    ("   ██║   ██████╔╝    ╚██████╔╝██║  ██║██████╔╝███████╗██║  ██║", "bold #2dd4bf"),
+    ("   ╚═╝   ╚═════╝      ╚═════╝ ╚═╝  ╚═╝╚═════╝ ╚══════╝╚═╝  ╚═╝", "bold #86efac"),
+]
+_MODAL_ICONS = {
+    "success": ("●", "#10b981"),
+    "warning": ("●", "#f59e0b"),
+    "error": ("●", "#ef4444"),
+    "info": ("●", "#38bdf8"),
+}
+
 
 class DashboardApp:
     """Interactive terminal UI for daily operations."""
@@ -57,38 +72,35 @@ class DashboardApp:
         last_run = self._state_svc.load_last_run(quiet=True)
         autostart_status = self._daemon.autostart_status()
 
-        title = Text("多表格同步与退款标记服务", style="bold white")
-        subtitle = Text("Scheduler Console", style="bold #8ecae6")
-        header = Panel(
-            Align.center(Group(title, subtitle)),
-            border_style="#219ebc",
-            box=box.HEAVY,
-            padding=(1, 2),
-        )
+        header = self._build_header(daemon_status, last_run)
 
         runtime_panel = Panel(
             self._build_runtime_table(),
             title="[bold #023047]运行配置[/bold #023047]",
             border_style="#8ecae6",
             box=box.ROUNDED,
+            padding=(1, 2),
         )
         daemon_panel = Panel(
             self._build_daemon_table(daemon_status, autostart_status),
             title="[bold #023047]守护进程[/bold #023047]",
             border_style="#90be6d" if daemon_status.running else "#f4a261",
             box=box.ROUNDED,
+            padding=(1, 2),
         )
         state_panel = Panel(
             self._build_state_table(state, last_run),
             title="[bold #023047]同步状态[/bold #023047]",
             border_style="#ffb703",
             box=box.ROUNDED,
+            padding=(1, 2),
         )
         config_panel = Panel(
             self._build_config_table(),
             title="[bold #023047]接入状态[/bold #023047]",
             border_style="#fb8500" if self._is_config_ready() else "#d62828",
             box=box.ROUNDED,
+            padding=(1, 2),
         )
 
         actions = Panel(
@@ -96,6 +108,7 @@ class DashboardApp:
             title="[bold #023047]操作台[/bold #023047]",
             border_style="#219ebc",
             box=box.ROUNDED,
+            padding=(1, 2),
         )
 
         footer = Panel(
@@ -116,6 +129,63 @@ class DashboardApp:
             footer,
         )
 
+    def _build_header(self, daemon_status, last_run) -> Panel:
+        logo = Text(justify="center")
+        for line, style in _LOGO_LINES:
+            logo.append(line, style=style)
+            logo.append("\n")
+        logo.append("Tencent Docs Order Sync Console", style="bold #e0fbfc")
+
+        hero = Group(
+            Align.center(logo),
+            Align.right(self._build_version_badge()),
+        )
+
+        badges = Table.grid(expand=True)
+        badges.add_column(justify="center")
+        badges.add_column(justify="center")
+        badges.add_column(justify="center")
+        badges.add_row(
+            self._build_badge("运行模式", f"{self._settings.gross_profit_mode.value} / {self._settings.refund_match_mode.value}", "#0ea5e9"),
+            self._build_badge("守护状态", "运行中" if daemon_status.running else "未运行", "#10b981" if daemon_status.running else "#f59e0b"),
+            self._build_badge("最近结果", self._last_run_label(last_run), "#22c55e" if last_run and last_run.success else "#ef4444" if last_run else "#64748b"),
+        )
+
+        subtitle = Text("多表格同步与退款标记服务", style="bold white", justify="center")
+        hint = Text("输入编号执行任务，所有结果与失败原因会在控制台内直接返回", style="dim", justify="center")
+
+        body = Group(
+            hero,
+            Align.center(subtitle),
+            Align.center(hint),
+            badges,
+        )
+        return Panel(
+            body,
+            border_style="#219ebc",
+            box=box.HEAVY,
+            padding=(1, 2),
+        )
+
+    @staticmethod
+    def _build_badge(label: str, value: str, color: str) -> Panel:
+        inner = Table.grid(padding=(0, 1))
+        inner.add_column(justify="center")
+        inner.add_row(Text(label, style="bold white"))
+        inner.add_row(Text(value, style="bold white"))
+        return Panel(inner, border_style=color, box=box.ROUNDED, padding=(0, 1))
+
+    @staticmethod
+    def _build_version_badge() -> Panel:
+        text = Text(f"v{APP_VERSION}", style="bold #0f172a", justify="center")
+        return Panel(text, border_style="#94d2bd", box=box.ROUNDED, padding=(0, 2), title="版本")
+
+    @staticmethod
+    def _last_run_label(last_run) -> str:
+        if last_run is None:
+            return "暂无记录"
+        return "成功" if last_run.success else "失败"
+
     def _build_runtime_table(self) -> Table:
         table = Table(box=None, show_header=False, pad_edge=False)
         table.add_column(style="bold white")
@@ -168,9 +238,9 @@ class DashboardApp:
         return table
 
     def _build_action_table(self) -> Table:
-        table = Table(box=box.SIMPLE_HEAVY, expand=True)
-        table.add_column("编号", justify="center", style="bold #219ebc", width=6)
-        table.add_column("动作", style="bold white")
+        table = Table(box=box.SIMPLE_HEAVY, expand=True, row_styles=["none", "dim"])
+        table.add_column("编号", justify="center", style="bold #38bdf8", width=6)
+        table.add_column("动作", style="bold white", width=18)
         table.add_column("说明", style="#023047")
         table.add_row("1", "执行全部任务", "毛利计算 + 退款匹配")
         table.add_row("2", "模拟执行", "全部任务 dry-run，不写入表格")
@@ -228,7 +298,7 @@ class DashboardApp:
         from cli.commands import execute_tasks
 
         results = execute_tasks(self._settings, task, dry_run=dry_run)
-        table = Table(box=box.SIMPLE_HEAVY, expand=True)
+        table = Table(box=box.SIMPLE_HEAVY, expand=True, row_styles=["none", "dim"])
         table.add_column("任务", style="bold cyan")
         table.add_column("结果", justify="center")
         table.add_column("读取", justify="right")
@@ -251,8 +321,19 @@ class DashboardApp:
             failure_table.add_column("失败原因", style="white")
             for item in failures:
                 failure_table.add_row(item.task_name.value, item.error_message or "")
-            body = Group(table, Panel(failure_table, title="失败详情", border_style="red", box=box.ROUNDED))
-        self._pause_with_panel(Panel(body, title="执行结果", border_style="#219ebc", box=box.ROUNDED))
+            body = Group(
+                self._build_modal_summary("执行完成，但存在失败项", style="error"),
+                table,
+                Panel(failure_table, title="失败详情", border_style="red", box=box.ROUNDED, padding=(1, 2)),
+            )
+            self._pause_with_panel(body, title="执行结果", border_style="#ef4444")
+            return
+
+        body = Group(
+            self._build_modal_summary("执行完成，结果已落地", style="success"),
+            table,
+        )
+        self._pause_with_panel(body, title="执行结果", border_style="#219ebc")
 
     def _daemon_action(self, action: str) -> None:
         if action in {"start", "autostart-enable"} and not self._ensure_config():
@@ -271,14 +352,47 @@ class DashboardApp:
         else:
             status = self._daemon.autostart_status()
 
-        self._pause_with_panel(Panel(status.message, title="守护结果", border_style="#90be6d", box=box.ROUNDED))
+        style = "success"
+        border = "#90be6d"
+        if "失败" in status.message or "未找到" in status.message:
+            style = "error"
+            border = "#ef4444"
+        elif "未启用" in status.message or "未运行" in status.message:
+            style = "warning"
+            border = "#f59e0b"
+
+        body = Group(
+            self._build_modal_summary(status.message, style=style),
+            self._build_kv_table({
+                "动作": action,
+                "目标": getattr(status, "target", "") or "-",
+            }),
+        )
+        self._pause_with_panel(body, title="守护结果", border_style=border)
 
     def _show_log_tail(self) -> None:
         content = self._daemon.read_log_tail(lines=40)
-        body = content if content else "后台日志暂时为空。"
-        self._pause_with_panel(
-            Panel(body, title=f"后台日志 · {self._daemon.log_file.name}", border_style="#ffb703", box=box.ROUNDED)
-        )
+        if content:
+            log_panel = Panel(
+                Text(content, style="#e5e7eb"),
+                title=f"后台日志 · {self._daemon.log_file.name}",
+                border_style="#ffb703",
+                box=box.ROUNDED,
+                padding=(1, 2),
+            )
+            body = Group(
+                self._build_modal_summary("以下为最近 40 行后台日志", style="info"),
+                log_panel,
+            )
+        else:
+            body = Group(
+                self._build_modal_summary("后台日志暂时为空", style="warning"),
+                self._build_kv_table({
+                    "日志文件": self._daemon.log_file.name,
+                    "日志目录": str(self._daemon.log_file.parent),
+                }),
+            )
+        self._pause_with_panel(body, title="后台日志", border_style="#ffb703")
 
     def _run_setup(self, *, check: bool) -> None:
         from cli.setup import cmd_setup
@@ -300,14 +414,14 @@ class DashboardApp:
     def _ensure_config(self) -> bool:
         if self._is_config_ready():
             return True
-        self._pause_with_panel(
-            Panel(
-                "腾讯文档必填配置尚未完成，请先运行配置向导。",
-                title="配置未完成",
-                border_style="red",
-                box=box.ROUNDED,
-            )
+        body = Group(
+            self._build_modal_summary("腾讯文档必填配置尚未完成", style="error"),
+            self._build_kv_table({
+                "建议动作": "先运行 tb setup",
+                "后续检查": "配置完成后运行 tb check",
+            }),
         )
+        self._pause_with_panel(body, title="配置未完成", border_style="#ef4444")
         return False
 
     def _is_config_ready(self) -> bool:
@@ -322,11 +436,35 @@ class DashboardApp:
         ]
         return all(bool(value.strip()) for value in fields)
 
-    def _pause_with_panel(self, panel: Panel) -> None:
+    def _pause_with_panel(self, body, *, title: str, border_style: str) -> None:
         self.console.clear()
-        self.console.print(panel)
+        self.console.print(
+            Panel(
+                body,
+                title=title,
+                border_style=border_style,
+                box=box.ROUNDED,
+                padding=(1, 2),
+            )
+        )
         self._wait()
 
+    def _build_modal_summary(self, message: str, *, style: str) -> Panel:
+        icon, color = _MODAL_ICONS[style]
+        text = Text(justify="center")
+        text.append(f"{icon} ", style=f"bold {color}")
+        text.append(message, style="bold white")
+        return Panel(text, border_style=color, box=box.ROUNDED, padding=(0, 1))
+
+    @staticmethod
+    def _build_kv_table(rows: dict[str, str]) -> Table:
+        table = Table(box=box.SIMPLE_HEAVY, expand=True, row_styles=["none", "dim"])
+        table.add_column("项目", style="bold cyan", width=18)
+        table.add_column("内容", style="white")
+        for key, value in rows.items():
+            table.add_row(key, value)
+        return table
+
     def _wait(self) -> None:
         self.console.input("[dim]按回车返回控制台[/dim]")