tb-order-sync 0.3.0

package/.env.example

@@ -0,0 +1,50 @@
+# ============================================================
+# 多表格同步与退款标记服务 — 环境配置
+# 复制此文件为 .env 并填入实际值
+# ============================================================
+
+# ── 基础配置 ──────────────────────────────────────────────
+APP_ENV=dev
+LOG_LEVEL=INFO
+STATE_DIR=state
+
+# ── 腾讯文档配置 ──────────────────────────────────────────
+TENCENT_CLIENT_ID=
+TENCENT_CLIENT_SECRET=
+TENCENT_OPEN_ID=
+TENCENT_ACCESS_TOKEN=
+TENCENT_A_FILE_ID=
+TENCENT_A_SHEET_ID=
+TENCENT_B_FILE_ID=
+TENCENT_B_SHEET_ID=
+
+# ── 飞书配置（预留） ─────────────────────────────────────
+FEISHU_APP_ID=
+FEISHU_APP_SECRET=
+FEISHU_C_FILE_TOKEN=
+FEISHU_C_SHEET_ID=
+
+# ── 运行配置 ──────────────────────────────────────────────
+GROSS_PROFIT_MODE=incremental
+REFUND_MATCH_MODE=incremental
+C_SYNC_MODE=incremental
+TASK_INTERVAL_MINUTES=10
+STARTUP_JITTER_SECONDS=15
+WRITE_BATCH_SIZE=100
+RETRY_TIMES=3
+DRY_RUN=false
+ENABLE_STYLE_UPDATE=false
+
+# ── 列映射配置 ────────────────────────────────────────────
+A_COL_PRODUCT_PRICE=C
+A_COL_PACKAGING_PRICE=D
+A_COL_FREIGHT=E
+A_COL_CUSTOMER_QUOTE=F
+A_COL_GROSS_PROFIT=G
+A_COL_ORDER_NO=H
+A_COL_REFUND_STATUS=I
+B_COL_ORDER_NO=A
+
+# ── 业务文案 ──────────────────────────────────────────────
+REFUND_STATUS_TEXT=进入退款流程
+DATA_ERROR_TEXT=数据异常

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.3.0] - 2026-03-19
+
+### Added
+
+- Added a Rich-based interactive dashboard with status cards, action panels, and log viewing.
+- Added cross-platform daemon management with `daemon start|stop|restart|status|logs`.
+- Added beginner onboarding links for Tencent Docs API and Feishu API inside the setup wizard.
+- Added optional browser-opening support for official documentation links during setup.
+- Added simplified CLI aliases such as `all`, `gp`, `rm`, `check`, `config`, and `menu`.
+- Added npm launcher packaging with a `tb` binary entry point.
+- Added `.gitignore` for Python build artifacts, runtime state, and local secrets.
+
+### Changed
+
+- Renamed the distribution package to `tb-order-sync` to match the order-sync use case and the `tb` launcher.
+- Changed no-argument startup to open the Rich dashboard by default.
+- Changed macOS and Windows launcher scripts to delegate to the unified in-app dashboard.
+- Changed README to document dashboard usage, daemon commands, API onboarding, and npm packaging.
+- Changed CLI command structure to keep backward compatibility while exposing shorter commands.
+
+### Fixed
+
+- Fixed heavy eager imports in the CLI so `--help` and setup-related flows return quickly.
+- Fixed dashboard rendering noise by adding a quiet state-load mode.
+- Fixed direct task/scheduler/daemon startup to block clearly when Tencent credentials are incomplete.

package/README.md

@@ -0,0 +1,392 @@
+# TB Order Sync
+
+**多表格同步与退款标记服务** — 自动同步腾讯文档 / 飞书多表格数据，计算毛利并标记退款订单。
+
+> 一键启动、零配置门槛、支持 Windows / macOS 双平台，可打包为独立 exe 免安装分发。
+
+---
+
+## 功能概览
+
+| 功能 | 说明 | 状态 |
+|------|------|------|
+| 毛利自动计算 | 读取 A 表字段，计算 `毛利 = 客户报价 - 运费 - 包装价格 - 产品价格`，异常数据标记 | ✅ 已实现 |
+| 退款自动匹配 | B 表退款单号匹配 A 表订单，写入退款状态 + 可选整行标红 | ✅ 已实现 |
+| 增量同步 | 基于行指纹 (MD5) 的变更检测，只处理变化行 | ✅ 已实现 |
+| 全量同步 | 忽略缓存，全表重新计算 | ✅ 已实现 |
+| 定时调度 | APScheduler 定时执行，支持 jitter 防冲突 | ✅ 已实现 |
+| 交互式配置向导 | `setup` 命令一站式引导配置所有参数，并可直接打开官方文档链接 | ✅ 已实现 |
+| Rich 控制台 | 无参启动即进入可视化 CLI 控制台 | ✅ 已实现 |
+| 进程守护 | 支持后台启动 / 停止 / 状态 / 日志查看 | ✅ 已实现 |
+| 一键启动脚本 | 双击即用，自动初始化环境，无需手动装 Python | ✅ 已实现 |
+| 打包为 exe | PyInstaller 打包，免安装分发 | ✅ 已实现 |
+| dry-run 模式 | 模拟执行不写入，安全验证 | ✅ 已实现 |
+| 飞书 C 表同步 | C 表 → A 表数据同步 | 🔲 骨架已预留 |
+
+## 快速开始
+
+### 方式零：安装 `tb` 命令
+
+```bash
+# 在项目根目录执行一次
+npm link
+
+# 之后直接使用
+tb
+tb menu
+tb setup
+tb all
+tb gp
+tb rm
+tb daemon start
+tb daemon status
+```
+
+如果你要生成可分发的 npm 包：
+
+```bash
+npm pack
+npm install -g ./tb-order-sync-0.3.0.tgz
+```
+
+### 方式一：一键启动（推荐）
+
+**无需任何技术背景，双击即用。**
+
+| 平台 | 操作 |
+|------|------|
+| **Windows** | 双击 `启动.bat` |
+| **macOS** | 双击 `启动.command` |
+
+首次运行会自动完成：
+1. 检测 / 下载 Python 环境（如果没有）
+2. 安装依赖
+3. 进入 Rich 控制台
+4. 在控制台中继续配置、执行任务、管理守护进程
+
+```bash
+tb
+# 或直接双击启动脚本
+# 默认进入 Rich 交互式控制台
+```
+
+### 方式二：命令行
+
+```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
+```
+
+### 方式三：打包为 exe 分发
+
+```bash
+# 构建（在目标平台上执行）
+pip install pyinstaller
+python build.py --clean
+
+# 产物在 dist/sync_service/ 目录
+# 连同 启动.bat（Windows）或 启动.command（macOS）一起分发
+# 用户无需安装 Python
+```
+
+## API 获取指引
+
+### 腾讯文档 API
+
+- 开发文档入口: [腾讯文档开放平台开发文档](https://docs.qq.com/open/document/app/)
+- 开发者平台: [腾讯文档开放生态](https://docs.qq.com/open/developers/)
+- 建议流程:
+  1. 先进入开发者平台创建应用
+  2. 在应用详情页获取 `Client ID` 和 `Client Secret`
+  3. 按官方 OAuth2 流程获取 `Access Token`
+  4. 再回到本项目执行 `tb setup`
+- 当前说明:
+  - 本项目 MVP 目前依赖你手工提供有效 `Access Token`
+  - `Open ID` 先作为可选项保留
+  - 腾讯文档实际 endpoint / request schema 代码里仍有 `TODO / NEED_VERIFY`
+
+### 飞书 API
+
+- 开发者平台: [Feishu Open Platform](https://open.feishu.cn/app)
+- Token 官方文档: [获取 tenant_access_token](https://open.feishu.cn/document/server-docs/authentication-management/access-token/tenant_access_token_internal)
+- 新手教程: [如何解析和使用动态 Token](https://www.feishu.cn/content/000214591773)
+- 建议流程:
+  1. 在飞书开放平台创建自建应用
+  2. 在应用凭证页获取 `App ID` 和 `App Secret`
+  3. 按官方文档获取 `tenant_access_token`
+  4. 后续接 C 表时再补齐 `File Token` / `Sheet ID`
+- 当前说明:
+  - 本项目里的飞书 connector 目前还是 skeleton
+  - 现阶段向导里先采集配置，为后续 C 表接入做准备
+
+## 业务规则
+
+### A 表结构（订单表）
+
+| 列 | 字段 | 说明 |
+|----|------|------|
+| A | 产品图 | — |
+| B | 订单地址 | — |
+| C | 产品价格 | 参与毛利计算 |
+| D | 包装价格 | 参与毛利计算 |
+| E | 运费 | 参与毛利计算 |
+| F | 客户报价 | 参与毛利计算 |
+| G | 毛利 | **自动计算写入** |
+| H | 单号 | 退款匹配关键字段 |
+| I | 退款状态 | **自动标记写入** |
+
+### B 表结构（退款表）
+
+| 列 | 字段 |
+|----|------|
+| A | 单号（用于匹配 A 表 H 列） |
+| B-L | 退货单号、店铺、原因、金额等 |
+
+### 毛利计算
+
+```
+毛利 = 客户报价(F) - 运费(E) - 包装价格(D) - 产品价格(C)
+```
+
+- 字段为合法数字（int / float / 数字字符串）→ 正常计算
+- 任一字段非法（空值、文本、None）→ 写入 `数据异常`，日志记录详情
+
+### 退款匹配
+
+- B 表 A 列单号存在于 A 表 H 列 → I 列写入 `进入退款流程`
+- 不存在 → 清空 I 列（同步取消）
+- 可选：`ENABLE_STYLE_UPDATE=true` 时额外设置行背景色标红
+
+## 项目结构
+
+```
+tb-order-sync/
+├── main.py                        # 入口
+├── build.py                       # PyInstaller 构建脚本
+├── sync_service.spec              # PyInstaller spec 文件
+├── package.json                   # npm bin 包定义（tb）
+├── CHANGELOG.md                   # 更新日志
+├── requirements.txt
+├── .env.example                   # 环境变量模板
+├── tb                             # 本地 Unix launcher
+├── tb.cmd                         # 本地 Windows launcher
+├── 启动.bat                       # Windows 一键启动
+├── 启动.command                   # macOS 一键启动
+├── bin/
+│   └── tb.js                      # npm / node 统一入口
+│
+├── config/
+│   ├── settings.py                # Pydantic Settings 全局配置
+│   └── mappings.py                # 列字母 ↔ 索引映射
+│
+├── connectors/
+│   ├── base.py                    # BaseSheetConnector 抽象接口
+│   ├── tencent_docs.py            # 腾讯文档连接器
+│   └── feishu_sheets.py           # 飞书连接器（骨架）
+│
+├── models/
+│   ├── records.py                 # OrderRecord / RefundRecord
+│   ├── task_models.py             # SyncTaskConfig / TaskResult
+│   └── state_models.py            # SyncState / RowFingerprint
+│
+├── services/
+│   ├── gross_profit_service.py    # 毛利计算服务
+│   ├── refund_match_service.py    # 退款匹配服务
+│   ├── c_to_a_sync_service.py     # C→A 同步（骨架）
+│   ├── scheduler_service.py       # APScheduler 定时调度
+│   ├── daemon_service.py          # 跨平台守护进程管理
+│   └── state_service.py           # 本地 JSON 状态持久化
+│
+├── utils/
+│   ├── logger.py                  # 日志配置
+│   ├── parser.py                  # 数值解析 / 单号标准化
+│   ├── diff.py                    # 行指纹 / 集合 hash
+│   └── retry.py                   # tenacity 重试装饰器
+│
+├── cli/
+│   ├── commands.py                # CLI 命令路由
+│   ├── dashboard.py               # Rich 控制台首页
+│   └── setup.py                   # 交互式配置向导
+│
+├── state/                         # 增量状态文件目录
+│   └── sync_state.json            # 自动生成
+│
+└── tests/
+    ├── test_parser.py             # 20 tests
+    ├── test_gross_profit_service.py  # 9 tests
+    └── test_refund_match_service.py  # 6 tests
+```
+
+## 架构设计
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  CLI / 启动  │────▶│   Services  │────▶│ Connectors  │
+│  commands.py │     │ (业务逻辑)   │     │ (平台隔离)   │
+└─────────────┘     └──────┬──────┘     └──────┬──────┘
+                           │                    │
+                    ┌──────▼──────┐     ┌──────▼──────┐
+                    │   Models    │     │ Tencent Docs │
+                    │ (数据结构)   │     │    Feishu    │
+                    └──────┬──────┘     │   (更多...)   │
+                           │            └─────────────┘
+                    ┌──────▼──────┐
+                    │ State / Utils│
+                    │ (状态/工具)   │
+                    └─────────────┘
+```
+
+**核心原则：**
+- **Connector 抽象** — 腾讯文档/飞书通过统一接口 `BaseSheetConnector` 隔离，新增平台只需实现接口
+- **业务与平台分离** — Services 不依赖任何平台 API 细节
+- **配置化** — 列映射、业务文案、运行模式全部可通过 `.env` 配置
+- **可扩展** — 新增 D 表、E 表时无需重构主程序
+
+## 增量策略
+
+| 目标 | 策略 | 存储 |
+|------|------|------|
+| A 表毛利 | 对每行关键字段 (C/D/E/F/H) 生成 MD5 指纹，仅处理指纹变化行 | `state/sync_state.json` |
+| B 表退款 | 对退款单号集合生成整体 hash，集合不变则跳过 | `state/sync_state.json` |
+
+## 守护进程
+
+- `tb daemon start`
+  - 在后台启动定时调度进程
+  - 自动写入 `state/scheduler.pid` 和 `state/scheduler.meta.json`
+- `tb daemon status`
+  - 查看是否运行中、PID 和日志文件位置
+- `tb daemon logs --lines 40`
+  - 查看后台日志尾部
+- `tb daemon stop`
+  - 停止后台调度
+- `tb daemon restart`
+  - 重启后台调度
+
+后台控制台输出默认写入：
+- `state/scheduler.console.log`
+
+## 配置说明
+
+运行 `tb setup` 可交互式完成所有配置。也可手动编辑 `.env`：
+
+```ini
+# 腾讯文档凭证
+TENCENT_CLIENT_ID=your_client_id
+TENCENT_CLIENT_SECRET=your_client_secret
+TENCENT_ACCESS_TOKEN=your_access_token
+TENCENT_A_FILE_ID=a_table_file_id
+TENCENT_A_SHEET_ID=a_table_sheet_id
+TENCENT_B_FILE_ID=b_table_file_id
+TENCENT_B_SHEET_ID=b_table_sheet_id
+
+# 运行模式
+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 = 退款行标红
+
+# 列映射（可自定义）
+A_COL_PRODUCT_PRICE=C
+A_COL_PACKAGING_PRICE=D
+A_COL_FREIGHT=E
+A_COL_CUSTOMER_QUOTE=F
+A_COL_GROSS_PROFIT=G
+A_COL_ORDER_NO=H
+A_COL_REFUND_STATUS=I
+B_COL_ORDER_NO=A
+```
+
+完整配置项见 [.env.example](.env.example)。
+
+## 测试
+
+```bash
+# 运行全部测试（35 tests）
+pytest tests/ -v
+
+# 单独运行
+pytest tests/test_parser.py -v
+pytest tests/test_gross_profit_service.py -v
+pytest tests/test_refund_match_service.py -v
+```
+
+## 技术栈
+
+| 组件 | 用途 |
+|------|------|
+| Python 3.11+ | 运行环境 |
+| pydantic / pydantic-settings | 数据模型 / 配置管理 |
+| httpx | HTTP 客户端 |
+| tenacity | 失败重试 |
+| APScheduler | 定时任务调度 |
+| rich | CLI 交互界面 |
+| python-dotenv | 环境变量加载 |
+| PyInstaller | 打包为可执行文件 |
+| pytest | 单元测试 |
+
+## 部署方式对比
+
+| 方式 | 需要 Python | 适用场景 |
+|------|------------|---------|
+| 双击启动脚本（源码） | 自动下载 | 开发/内部使用 |
+| 打包 exe 分发 | 不需要 | 给非技术用户 |
+| 命令行直接运行 | 需要 | 开发者 |
+
+## Roadmap
+
+- [x] 毛利自动计算
+- [x] 退款自动匹配
+- [x] 增量 / 全量模式
+- [x] 交互式配置向导
+- [x] 一键启动脚本（Windows + macOS）
+- [x] PyInstaller 打包
+- [x] 定时调度 + dry-run
+- [ ] 飞书 C 表 → A 表同步
+- [ ] 腾讯文档 OAuth2 token 自动刷新
+- [ ] 腾讯文档行样式 API 验证
+
+## 已知待确认项
+
+- 腾讯文档 Open API 的实际 endpoint 和 request/response 格式（代码中标注 `TODO / NEED_VERIFY`）
+- 腾讯文档是否支持通过 API 设置单元格样式
+- OAuth2 token 自动刷新流程
+
+## License
+
+MIT

package/bin/tb.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const { spawn, spawnSync } = require("child_process");
+
+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,
+    stdio: "inherit",
+    env: process.env,
+  });
+
+  child.on("error", (error) => {
+    console.error(`tb: 启动失败: ${error.message}`);
+    process.exit(1);
+  });
+
+  child.on("exit", (code) => {
+    process.exit(code ?? 0);
+  });
+}
+
+const mainEntry = path.join(root, "main.py");
+const preferBundled = process.env.TB_PREFER_BUNDLED === "1" || !exists(mainEntry);
+const bundledExecutable = getBundledExecutable();
+
+if (preferBundled && bundledExecutable) {
+  launch(bundledExecutable, args);
+} else if (exists(mainEntry)) {
+  const python = ensurePythonRuntime();
+  launch(python.command, [...python.prefixArgs, mainEntry, ...args]);
+} else if (bundledExecutable) {
+  launch(bundledExecutable, args);
+} else {
+  console.error("tb: 未找到 main.py，也未找到可执行分发产物。");
+  process.exit(1);
+}

package/build.py

@@ -0,0 +1,91 @@
+"""Cross-platform build script for packaging sync_service into an executable.
+
+Usage:
+    python build.py          # Build for current platform
+    python build.py --clean  # Clean build artifacts first
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+SPEC_FILE = ROOT / "sync_service.spec"
+DIST_DIR = ROOT / "dist"
+BUILD_DIR = ROOT / "build"
+
+
+def clean() -> None:
+    """Remove previous build artifacts."""
+    for d in (DIST_DIR, BUILD_DIR):
+        if d.exists():
+            print(f"Cleaning {d} ...")
+            shutil.rmtree(d)
+    print("Clean done.")
+
+
+def ensure_pyinstaller() -> None:
+    """Install PyInstaller if not present."""
+    try:
+        import PyInstaller  # noqa: F401
+    except ImportError:
+        print("Installing PyInstaller ...")
+        subprocess.check_call([sys.executable, "-m", "pip", "install", "pyinstaller"])
+
+
+def build() -> None:
+    """Run PyInstaller with the spec file."""
+    ensure_pyinstaller()
+    print(f"\nBuilding from {SPEC_FILE} ...")
+    subprocess.check_call([
+        sys.executable, "-m", "PyInstaller",
+        str(SPEC_FILE),
+        "--noconfirm",
+    ])
+
+    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")
+
+        # Create state directory
+        (output / "state").mkdir(exist_ok=True)
+
+        print(f"\n{'=' * 50}")
+        print(f"Build complete!")
+        print(f"Output: {output}")
+        print(f"{'=' * 50}")
+        print(f"\nNext steps:")
+        print(f"  1. cd {output}")
+        if sys.platform == "win32":
+            print(f"  2. sync_service.exe setup")
+            print(f"  3. sync_service.exe run all --dry-run")
+            print(f"  4. sync_service.exe run all")
+        else:
+            print(f"  2. ./sync_service setup")
+            print(f"  3. ./sync_service run all --dry-run")
+            print(f"  4. ./sync_service run all")
+    else:
+        print("Build may have failed — dist/sync_service not found")
+        sys.exit(1)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Build sync_service executable")
+    parser.add_argument("--clean", action="store_true", help="Clean build artifacts before building")
+    args = parser.parse_args()
+
+    if args.clean:
+        clean()
+
+    build()
+
+
+if __name__ == "__main__":
+    main()