tb-order-sync 0.4.1 → 0.4.5

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,73 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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
+
+- Added npm global-install bootstrap via `postinstall`, so `npm install -g tb-order-sync` can prepare the CLI runtime in one step on macOS.
+- Added dedicated runtime path handling for npm installs, using a writable user app-home instead of the npm package directory.
+- Added tests for `TB_HOME` path resolution and relative `state_dir` normalization.
+- Added `pytest.ini` to keep local release artifacts from polluting test discovery.
+
+### Changed
+
+- Changed the Node launcher to store `.env`, `state`, and `.venv` under the app home during npm-based CLI usage.
+- Changed documentation to describe the one-command npm install flow and the macOS runtime directory.
+
 ## [0.4.1] - 2026-03-19
 
 ### Added

package/README.md

@@ -54,6 +54,15 @@ tb daemon start
 tb daemon status
 ```
 
+在 macOS 上，`npm install -g tb-order-sync` 会同时完成两件事：
+- 安装全局 `tb` 命令
+- 自动把 CLI 运行环境部署到 `~/Library/Application Support/tb-order-sync/`
+
+运行时目录说明：
+- 配置文件：`~/Library/Application Support/tb-order-sync/.env`
+- 状态目录：`~/Library/Application Support/tb-order-sync/state/`
+- Python 运行环境：`~/Library/Application Support/tb-order-sync/.venv/`
+
 首次运行说明：
 - 如果本机还没有完整配置，直接执行 `tb` 会自动进入 `setup`
 - `tb check` 会执行启动自检，确认状态目录、A 表、B 表是否可用
@@ -196,7 +205,9 @@ tb-order-sync/
 ├── 启动.bat                       # Windows 一键启动
 ├── 启动.command                   # macOS 一键启动
 ├── bin/
-│   └── tb.js                      # npm / node 统一入口
+│   ├── tb.js                      # npm / node 统一入口
+│   ├── runtime.js                 # npm 运行时 bootstrap
+│   └── postinstall.js             # npm 全局安装自动部署
 │
 ├── config/
 │   ├── settings.py                # Pydantic Settings 全局配置
@@ -316,8 +327,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
@@ -339,6 +352,7 @@ B_COL_ORDER_NO=A
 
 补充说明：
 - `tb setup` 支持直接粘贴腾讯文档完整链接，自动拆出 `File ID / Sheet ID`
+- 如果填写 `TENCENT_A_SHEET_NAME_KEYWORD` / `TENCENT_B_SHEET_NAME_KEYWORD`，系统会在对应文件里自动选取标题中匹配关键字的“最新月份”工作表
 - `tb check` 会做启动自检，不只是看 `.env` 是否存在
 - 当前退款高亮效果是“整行红色文字”，不是背景填充
 

package/bin/postinstall.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+const { ensurePythonRuntime, getAppHome } = require("./runtime");
+
+const isGlobalInstall = process.env.npm_config_global === "true";
+const shouldSkip = process.env.TB_SKIP_POSTINSTALL_BOOTSTRAP === "1";
+
+if (!isGlobalInstall || shouldSkip) {
+  process.exit(0);
+}
+
+console.log("tb-order-sync: 正在准备 CLI 运行环境...");
+const result = ensurePythonRuntime({ quiet: false, exitOnError: false });
+
+if (!result.ok) {
+  console.warn("tb-order-sync: Python 运行环境未自动安装完成。");
+  console.warn("tb-order-sync: 安装仍已完成，后续执行 tb 时会再次尝试初始化。");
+  process.exit(0);
+}
+
+console.log(`tb-order-sync: CLI 已部署到 ${getAppHome()}`);

package/bin/runtime.js

@@ -0,0 +1,228 @@
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+const MIN_PYTHON = { major: 3, minor: 10 };
+
+function exists(target) {
+  try {
+    return fs.existsSync(target);
+  } catch {
+    return false;
+  }
+}
+
+function ensureDir(target) {
+  fs.mkdirSync(target, { recursive: true });
+}
+
+function getDefaultAppHome() {
+  const explicit = (process.env.TB_HOME || "").trim();
+  if (explicit) {
+    return path.resolve(explicit);
+  }
+
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Application Support", "tb-order-sync");
+  }
+  if (process.platform === "win32") {
+    return path.join(
+      process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming"),
+      "tb-order-sync",
+    );
+  }
+  return path.join(os.homedir(), ".tb-order-sync");
+}
+
+function getAppHome() {
+  return getDefaultAppHome();
+}
+
+function runtimeEnv(extra = {}) {
+  return {
+    ...process.env,
+    TB_HOME: getAppHome(),
+    ...extra,
+  };
+}
+
+function runChecked(command, commandArgs, options = {}) {
+  const result = spawnSync(command, commandArgs, {
+    cwd: PACKAGE_ROOT,
+    stdio: "inherit",
+    env: runtimeEnv(),
+    ...options,
+  });
+
+  if (result.error) {
+    return { ok: false, error: result.error };
+  }
+  if (typeof result.status === "number" && result.status !== 0) {
+    return { ok: false, code: result.status };
+  }
+  return { ok: true };
+}
+
+function probePythonVersion(command, prefixArgs) {
+  const probe = spawnSync(
+    command,
+    [
+      ...prefixArgs,
+      "-c",
+      "import sys; print('.'.join(map(str, sys.version_info[:3])))",
+    ],
+    {
+      cwd: PACKAGE_ROOT,
+      stdio: ["ignore", "pipe", "ignore"],
+      encoding: "utf-8",
+      env: runtimeEnv(),
+    },
+  );
+
+  if (probe.error || probe.status !== 0) {
+    return null;
+  }
+
+  const raw = (probe.stdout || "").trim();
+  const match = raw.match(/^(\d+)\.(\d+)\.(\d+)$/);
+  if (!match) {
+    return null;
+  }
+
+  const version = {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    raw,
+  };
+
+  const isSupported = (
+    version.major > MIN_PYTHON.major ||
+    (version.major === MIN_PYTHON.major && version.minor >= MIN_PYTHON.minor)
+  );
+
+  return {
+    ...version,
+    isSupported,
+  };
+}
+
+function findSystemPython() {
+  const candidates = process.platform === "win32"
+    ? [
+        { command: "py", prefixArgs: ["-3"] },
+        { command: "python", prefixArgs: [] },
+      ]
+    : [
+        { command: "python3.14", prefixArgs: [] },
+        { command: "python3.13", prefixArgs: [] },
+        { command: "python3.12", prefixArgs: [] },
+        { command: "python3.11", prefixArgs: [] },
+        { command: "python3.10", prefixArgs: [] },
+        { command: "python3", prefixArgs: [] },
+        { command: "python", prefixArgs: [] },
+      ];
+
+  for (const candidate of candidates) {
+    const version = probePythonVersion(candidate.command, candidate.prefixArgs);
+    if (version && version.isSupported) {
+      return { ...candidate, version: version.raw };
+    }
+  }
+  return null;
+}
+
+function getVenvDir() {
+  return path.join(getAppHome(), ".venv");
+}
+
+function getVenvPython() {
+  if (process.platform === "win32") {
+    return path.join(getVenvDir(), "Scripts", "python.exe");
+  }
+  return path.join(getVenvDir(), "bin", "python");
+}
+
+function getBundledExecutable() {
+  const candidates = process.platform === "win32"
+    ? [
+        path.join(PACKAGE_ROOT, "sync_service.exe"),
+        path.join(PACKAGE_ROOT, "dist", "sync_service", "sync_service.exe"),
+      ]
+    : [
+        path.join(PACKAGE_ROOT, "sync_service"),
+        path.join(PACKAGE_ROOT, "dist", "sync_service", "sync_service"),
+      ];
+
+  return candidates.find(exists) || null;
+}
+
+function ensurePythonRuntime(options = {}) {
+  const { quiet = false, exitOnError = true } = options;
+  const appHome = getAppHome();
+  const venvPython = getVenvPython();
+  ensureDir(appHome);
+
+  const fail = (lines) => {
+    const messages = Array.isArray(lines) ? lines : [lines];
+    if (!quiet) {
+      for (const line of messages) {
+        console.error(line);
+      }
+    }
+    if (exitOnError) {
+      process.exit(1);
+    }
+    return { ok: false, messages };
+  };
+
+  if (exists(venvPython)) {
+    return { ok: true, command: venvPython, prefixArgs: [] };
+  }
+
+  const systemPython = findSystemPython();
+  if (!systemPython) {
+    return fail([
+      "tb: 未找到可用的 Python 3.10+，无法自动部署 CLI 运行环境。",
+      "tb: 请先安装 Python 3.10+，然后重新执行 npm install -g tb-order-sync。",
+    ]);
+  }
+
+  if (!quiet) {
+    console.log(`tb: 使用 Python ${systemPython.version} 初始化运行环境...`);
+  }
+
+  let result = runChecked(
+    systemPython.command,
+    [...systemPython.prefixArgs, "-m", "venv", getVenvDir()],
+  );
+  if (!result.ok) {
+    return fail("tb: 创建虚拟环境失败。");
+  }
+
+  const freshVenvPython = getVenvPython();
+  if (!quiet) {
+    console.log("tb: 正在安装 Python 依赖...");
+  }
+  result = runChecked(
+    freshVenvPython,
+    ["-m", "pip", "install", "-q", "-r", path.join(PACKAGE_ROOT, "requirements.txt")],
+  );
+  if (!result.ok) {
+    return fail("tb: 安装依赖失败。");
+  }
+
+  return { ok: true, command: freshVenvPython, prefixArgs: [] };
+}
+
+module.exports = {
+  PACKAGE_ROOT,
+  exists,
+  getAppHome,
+  getBundledExecutable,
+  getVenvPython,
+  ensurePythonRuntime,
+  runtimeEnv,
+};

package/bin/tb.js

@@ -1,119 +1,22 @@
 #!/usr/bin/env node
 
-const fs = require("fs");
 const path = require("path");
-const { spawn, spawnSync } = require("child_process");
+const { spawn } = require("child_process");
+const {
+  PACKAGE_ROOT,
+  exists,
+  getBundledExecutable,
+  ensurePythonRuntime,
+  runtimeEnv,
+} = require("./runtime");
 
-const root = path.resolve(__dirname, "..");
 const args = process.argv.slice(2);
 
-function exists(target) {
-  try {
-    return fs.existsSync(target);
-  } catch {
-    return false;
-  }
-}
-
-function runChecked(command, commandArgs, options = {}) {
-  const result = spawnSync(command, commandArgs, {
-    cwd: root,
-    stdio: "inherit",
-    ...options,
-  });
-
-  if (result.error) {
-    return { ok: false, error: result.error };
-  }
-  if (typeof result.status === "number" && result.status !== 0) {
-    return { ok: false, code: result.status };
-  }
-  return { ok: true };
-}
-
-function findSystemPython() {
-  const candidates = process.platform === "win32"
-    ? [
-        { command: "py", prefixArgs: ["-3"] },
-        { command: "python", prefixArgs: [] },
-      ]
-    : [
-        { command: "python3.14", prefixArgs: [] },
-        { command: "python3.13", prefixArgs: [] },
-        { command: "python3.12", prefixArgs: [] },
-        { command: "python3.11", prefixArgs: [] },
-        { command: "python3", prefixArgs: [] },
-        { command: "python", prefixArgs: [] },
-      ];
-
-  for (const candidate of candidates) {
-    const probe = runChecked(candidate.command, [...candidate.prefixArgs, "--version"], {
-      stdio: "ignore",
-    });
-    if (probe.ok) {
-      return candidate;
-    }
-  }
-  return null;
-}
-
-function getVenvPython() {
-  if (process.platform === "win32") {
-    return path.join(root, ".venv", "Scripts", "python.exe");
-  }
-  return path.join(root, ".venv", "bin", "python");
-}
-
-function getBundledExecutable() {
-  const candidates = process.platform === "win32"
-    ? [
-        path.join(root, "sync_service.exe"),
-        path.join(root, "dist", "sync_service", "sync_service.exe"),
-      ]
-    : [
-        path.join(root, "sync_service"),
-        path.join(root, "dist", "sync_service", "sync_service"),
-      ];
-
-  return candidates.find(exists) || null;
-}
-
-function ensurePythonRuntime() {
-  const venvPython = getVenvPython();
-  if (exists(venvPython)) {
-    return { command: venvPython, prefixArgs: [] };
-  }
-
-  const systemPython = findSystemPython();
-  if (!systemPython) {
-    console.error("tb: 未找到可用的 Python 3.11+，也没有现成的打包可执行文件。");
-    console.error("tb: 请先安装 Python，或使用 build.py 构建可执行文件。");
-    process.exit(1);
-  }
-
-  console.log("tb: 正在初始化 Python 虚拟环境...");
-  let result = runChecked(systemPython.command, [...systemPython.prefixArgs, "-m", "venv", ".venv"]);
-  if (!result.ok) {
-    console.error("tb: 创建虚拟环境失败。");
-    process.exit(1);
-  }
-
-  const freshVenvPython = getVenvPython();
-  console.log("tb: 正在安装 Python 依赖...");
-  result = runChecked(freshVenvPython, ["-m", "pip", "install", "-q", "-r", "requirements.txt"]);
-  if (!result.ok) {
-    console.error("tb: 安装依赖失败。");
-    process.exit(1);
-  }
-
-  return { command: freshVenvPython, prefixArgs: [] };
-}
-
 function launch(command, commandArgs) {
   const child = spawn(command, commandArgs, {
-    cwd: root,
+    cwd: PACKAGE_ROOT,
     stdio: "inherit",
-    env: process.env,
+    env: runtimeEnv(),
   });
 
   child.on("error", (error) => {
@@ -126,7 +29,7 @@ function launch(command, commandArgs) {
   });
 }
 
-const mainEntry = path.join(root, "main.py");
+const mainEntry = path.join(PACKAGE_ROOT, "main.py");
 const preferBundled = process.env.TB_PREFER_BUNDLED === "1" || !exists(mainEntry);
 const bundledExecutable = getBundledExecutable();
 

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",