tb-order-sync 0.3.0

package/cli/commands.py

@@ -0,0 +1,258 @@
+"""CLI entry points for the sync service."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import TYPE_CHECKING, Optional
+
+from config.settings import Settings, SyncMode, get_settings
+from models.task_models import TaskResult
+from services.daemon_service import DaemonService
+from services.state_service import StateService
+from utils.logger import get_logger, setup_logging
+
+if TYPE_CHECKING:
+    from connectors.tencent_docs import TencentDocsConnector
+
+logger = get_logger(__name__)
+
+
+def _build_connector(settings: Settings) -> TencentDocsConnector:
+    from connectors.tencent_docs import TencentDocsConnector
+
+    return TencentDocsConnector(
+        client_id=settings.tencent_client_id,
+        client_secret=settings.tencent_client_secret,
+        access_token=settings.tencent_access_token,
+        open_id=settings.tencent_open_id,
+    )
+
+
+def _build_state_service(settings: Settings) -> StateService:
+    return StateService(state_dir=settings.state_dir)
+
+
+def _add_run_options(parser: argparse.ArgumentParser) -> None:
+    """Attach common execution flags to a parser."""
+    parser.add_argument("--dry-run", action="store_true", help="Simulate without writing")
+    parser.add_argument("--mode", choices=["incremental", "full"], help="Override sync mode")
+
+
+def _normalize_task_name(command: str) -> str:
+    """Map shorthand commands to internal task names."""
+    if command in ("gross-profit", "gp"):
+        return "gross-profit"
+    if command in ("refund-match", "rm"):
+        return "refund-match"
+    if command == "all":
+        return "all"
+    return command
+
+
+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_access_token,
+        settings.tencent_a_file_id,
+        settings.tencent_a_sheet_id,
+        settings.tencent_b_file_id,
+        settings.tencent_b_sheet_id,
+    ]
+    return all(bool(value.strip()) for value in required)
+
+
+def _ensure_runtime_config(settings: Settings) -> bool:
+    if has_required_runtime_config(settings):
+        return True
+    logger.error("缺少腾讯文档必填配置，请先运行 `setup` 或 `config` 完成配置。")
+    return False
+
+
+def execute_tasks(
+    settings: Settings,
+    task: str,
+    *,
+    dry_run: bool = False,
+    mode: Optional[SyncMode] = None,
+) -> list[TaskResult]:
+    """Run one or more tasks and return their results."""
+    if not _ensure_runtime_config(settings):
+        return []
+
+    from services.gross_profit_service import GrossProfitService
+    from services.refund_match_service import RefundMatchService
+
+    connector = _build_connector(settings)
+    state_svc = _build_state_service(settings)
+    results: list[TaskResult] = []
+
+    if task in ("gross-profit", "all"):
+        svc = GrossProfitService(connector, state_svc, settings)
+        result = svc.run(mode=mode or settings.gross_profit_mode, dry_run=dry_run)
+        _print_result(result)
+        results.append(result)
+
+    if task in ("refund-match", "all"):
+        svc = RefundMatchService(connector, state_svc, settings)
+        result = svc.run(mode=mode or settings.refund_match_mode, dry_run=dry_run)
+        _print_result(result)
+        results.append(result)
+
+    return results
+
+
+def cmd_run(args: argparse.Namespace, settings: Settings) -> None:
+    """Run one or more tasks."""
+    dry_run = args.dry_run or settings.dry_run
+    mode: Optional[SyncMode] = None
+    if args.mode:
+        mode = SyncMode(args.mode)
+
+    execute_tasks(settings, args.task, dry_run=dry_run, mode=mode)
+
+
+def start_scheduler(settings: Settings) -> None:
+    """Start the foreground scheduler."""
+    if not _ensure_runtime_config(settings):
+        return
+
+    from services.scheduler_service import SchedulerService
+
+    connector = _build_connector(settings)
+    state_svc = _build_state_service(settings)
+    scheduler = SchedulerService(connector, state_svc, settings)
+    scheduler.start()
+
+
+def cmd_schedule(args: argparse.Namespace, settings: Settings) -> None:
+    """Start periodic scheduler."""
+    start_scheduler(settings)
+
+
+def cmd_daemon(args: argparse.Namespace, settings: Settings) -> None:
+    """Manage the scheduler daemon process."""
+    daemon = DaemonService(settings)
+    action = args.daemon_action
+
+    if action == "start":
+        if not _ensure_runtime_config(settings):
+            return
+        status = daemon.start(force=getattr(args, "force", False))
+        logger.info(status.message)
+    elif action == "stop":
+        status = daemon.stop(force=getattr(args, "force", False))
+        logger.info(status.message)
+    elif action == "restart":
+        status = daemon.restart(force=True)
+        logger.info(status.message)
+    elif action == "status":
+        status = daemon.status()
+        logger.info(status.message)
+        if status.running:
+            logger.info("daemon pid=%s log=%s", status.pid, status.log_file)
+    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)
+
+
+def _print_result(result: TaskResult) -> None:
+    status = "OK" if result.success else "FAILED"
+    logger.info(
+        "[%s] %s — read=%d changed=%d errors=%d dry_run=%s",
+        status, result.task_name.value, result.rows_read,
+        result.rows_changed, result.rows_error, result.dry_run,
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sync-service",
+        description="多表格同步与退款标记服务",
+    )
+    sub = parser.add_subparsers(dest="command", required=False)
+
+    run_parser = sub.add_parser("run", help="Run task(s)")
+    run_parser.add_argument(
+        "task",
+        choices=["gross-profit", "refund-match", "all"],
+        help="Which task to run",
+    )
+    _add_run_options(run_parser)
+
+    all_parser = sub.add_parser("all", help="直接执行全部任务")
+    _add_run_options(all_parser)
+
+    gp_parser = sub.add_parser("gross-profit", aliases=["gp"], help="直接执行毛利计算")
+    _add_run_options(gp_parser)
+
+    rm_parser = sub.add_parser("refund-match", aliases=["rm"], help="直接执行退款匹配")
+    _add_run_options(rm_parser)
+
+    sub.add_parser("schedule", aliases=["start"], help="前台启动定时调度")
+
+    daemon_parser = sub.add_parser("daemon", help="守护进程管理")
+    daemon_sub = daemon_parser.add_subparsers(dest="daemon_action", required=True)
+    daemon_start = daemon_sub.add_parser("start", help="启动后台守护进程")
+    daemon_start.add_argument("--force", action="store_true", help="已运行时先停止再重启")
+    daemon_stop = daemon_sub.add_parser("stop", help="停止后台守护进程")
+    daemon_stop.add_argument("--force", action="store_true", help="必要时强制终止")
+    daemon_sub.add_parser("restart", help="重启后台守护进程")
+    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 行日志")
+
+    setup_parser = sub.add_parser("setup", aliases=["config"], help="交互式配置向导")
+    setup_parser.add_argument("--check", action="store_true", help="验证当前配置状态")
+
+    sub.add_parser("check", help="验证当前配置状态")
+    sub.add_parser("menu", aliases=["ui", "dashboard"], help="打开交互式控制台")
+
+    return parser
+
+
+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)
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command in ("setup", "config"):
+        from cli.setup import cmd_setup
+
+        cmd_setup(args)
+        return
+
+    if args.command == "check":
+        from cli.setup import cmd_setup
+
+        args.check = True
+        cmd_setup(args)
+        return
+
+    if args.command in ("menu", "ui", "dashboard"):
+        from cli.dashboard import cmd_menu
+
+        cmd_menu(args, settings)
+        return
+
+    if args.command == "run":
+        cmd_run(args, settings)
+    elif args.command in ("all", "gross-profit", "gp", "refund-match", "rm"):
+        args.task = _normalize_task_name(args.command)
+        cmd_run(args, settings)
+    elif args.command in ("schedule", "start"):
+        cmd_schedule(args, settings)
+    elif args.command == "daemon":
+        cmd_daemon(args, settings)

package/cli/dashboard.py

@@ -0,0 +1,327 @@
+"""Rich-powered interactive dashboard for the sync service."""
+
+from __future__ import annotations
+
+import argparse
+from datetime import datetime
+from pathlib import Path
+
+from rich import box
+from rich.align import Align
+from rich.columns import Columns
+from rich.console import Console, Group
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from config.settings import Settings, get_settings
+from services.daemon_service import DaemonService
+from services.state_service import StateService
+
+
+class DashboardApp:
+    """Interactive terminal UI for daily operations."""
+
+    def __init__(self, settings: Settings) -> None:
+        self.console = Console()
+        self._settings = settings
+        self._refresh_services()
+
+    def run(self) -> None:
+        """Render dashboard and handle user actions until exit."""
+        while True:
+            self._refresh_settings()
+            self.console.clear()
+            self.console.print(self._build_screen())
+
+            choice = self._ask(
+                "选择操作",
+                default="1",
+                choices={"1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "0"},
+            )
+            if not self._handle_choice(choice):
+                break
+
+    def _refresh_settings(self) -> None:
+        get_settings.cache_clear()
+        self._settings = get_settings()
+        self._refresh_services()
+
+    def _refresh_services(self) -> None:
+        self._daemon = DaemonService(self._settings)
+        self._state_svc = StateService(self._settings.state_dir)
+
+    def _build_screen(self) -> Group:
+        daemon_status = self._daemon.status()
+        state = self._state_svc.load(quiet=True)
+
+        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),
+        )
+
+        runtime_panel = Panel(
+            self._build_runtime_table(),
+            title="[bold #023047]运行配置[/bold #023047]",
+            border_style="#8ecae6",
+            box=box.ROUNDED,
+        )
+        daemon_panel = Panel(
+            self._build_daemon_table(daemon_status),
+            title="[bold #023047]守护进程[/bold #023047]",
+            border_style="#90be6d" if daemon_status.running else "#f4a261",
+            box=box.ROUNDED,
+        )
+        state_panel = Panel(
+            self._build_state_table(state),
+            title="[bold #023047]同步状态[/bold #023047]",
+            border_style="#ffb703",
+            box=box.ROUNDED,
+        )
+        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,
+        )
+
+        actions = Panel(
+            self._build_action_table(),
+            title="[bold #023047]操作台[/bold #023047]",
+            border_style="#219ebc",
+            box=box.ROUNDED,
+        )
+
+        footer = Panel(
+            Text(
+                f"日志目录: {Path(self._settings.state_dir).resolve()}    "
+                f"后台日志: {self._daemon.log_file.name}",
+                style="dim",
+            ),
+            border_style="#577590",
+            box=box.SIMPLE,
+        )
+
+        return Group(
+            header,
+            Columns([runtime_panel, daemon_panel], equal=True, expand=True),
+            Columns([state_panel, config_panel], equal=True, expand=True),
+            actions,
+            footer,
+        )
+
+    def _build_runtime_table(self) -> Table:
+        table = Table(box=None, show_header=False, pad_edge=False)
+        table.add_column(style="bold white")
+        table.add_column(style="#023047")
+        table.add_row("环境", self._settings.app_env.value)
+        table.add_row("间隔", f"{self._settings.task_interval_minutes} 分钟")
+        table.add_row("抖动", f"{self._settings.startup_jitter_seconds} 秒")
+        table.add_row("毛利模式", self._settings.gross_profit_mode.value)
+        table.add_row("退款模式", self._settings.refund_match_mode.value)
+        table.add_row("Dry Run", "开启" if self._settings.dry_run else "关闭")
+        return table
+
+    def _build_daemon_table(self, status) -> Table:
+        table = Table(box=None, show_header=False, pad_edge=False)
+        table.add_column(style="bold white")
+        table.add_column(style="#023047")
+        table.add_row("状态", "[green]运行中[/green]" if status.running else "[yellow]未运行[/yellow]")
+        table.add_row("PID", str(status.pid or "-"))
+        table.add_row("启动时间", status.started_at or "-")
+        table.add_row("日志文件", status.log_file.name)
+        table.add_row("PID 文件", status.pid_file.name)
+        return table
+
+    def _build_state_table(self, state) -> Table:
+        table = Table(box=None, show_header=False, pad_edge=False)
+        table.add_column(style="bold white")
+        table.add_column(style="#023047")
+        table.add_row("上次运行", self._fmt_time(state.last_run_at))
+        table.add_row("A 表指纹", str(len(state.a_table_fingerprints)))
+        table.add_row("退款快照", str(len(state.b_table_refund_set)))
+        table.add_row("退款哈希", state.b_table_refund_hash[:12] if state.b_table_refund_hash else "-")
+        table.add_row("C 表预留", str(len(state.c_table_fingerprints)))
+        return table
+
+    def _build_config_table(self) -> Table:
+        ready = self._is_config_ready()
+        table = Table(box=None, show_header=False, pad_edge=False)
+        table.add_column(style="bold white")
+        table.add_column(style="#023047")
+        table.add_row("腾讯 A/B 表", "[green]已配置[/green]" if ready else "[red]未完成[/red]")
+        table.add_row("飞书 C 表", "[green]已录入[/green]" if self._settings.feishu_app_id else "[yellow]待接入[/yellow]")
+        table.add_row("样式更新", "开启" if self._settings.enable_style_update else "关闭")
+        table.add_row("批量写入", str(self._settings.write_batch_size))
+        table.add_row("重试次数", str(self._settings.retry_times))
+        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.add_column("说明", style="#023047")
+        table.add_row("1", "执行全部任务", "毛利计算 + 退款匹配")
+        table.add_row("2", "模拟执行", "全部任务 dry-run，不写入表格")
+        table.add_row("3", "仅毛利计算", "按当前模式处理 A 表")
+        table.add_row("4", "仅退款匹配", "刷新退款状态列")
+        table.add_row("5", "启动守护", "后台持续运行定时调度")
+        table.add_row("6", "停止守护", "停止后台调度进程")
+        table.add_row("7", "重启守护", "重启后台调度进程")
+        table.add_row("8", "查看后台日志", "显示守护日志末尾 40 行")
+        table.add_row("9", "配置向导", "打开交互式 setup")
+        table.add_row("10", "配置检查", "检查 .env 完整性")
+        table.add_row("11", "前台调度", "当前终端直接运行 scheduler")
+        table.add_row("0", "退出", "返回系统")
+        return table
+
+    def _handle_choice(self, choice: str) -> bool:
+        if choice == "0":
+            return False
+        if choice == "1":
+            self._run_task("all")
+        elif choice == "2":
+            self._run_task("all", dry_run=True)
+        elif choice == "3":
+            self._run_task("gross-profit")
+        elif choice == "4":
+            self._run_task("refund-match")
+        elif choice == "5":
+            self._daemon_action("start")
+        elif choice == "6":
+            self._daemon_action("stop")
+        elif choice == "7":
+            self._daemon_action("restart")
+        elif choice == "8":
+            self._show_log_tail()
+        elif choice == "9":
+            self._run_setup(check=False)
+        elif choice == "10":
+            self._run_setup(check=True)
+        elif choice == "11":
+            self._run_foreground_scheduler()
+        return True
+
+    def _run_task(self, task: str, *, dry_run: bool = False) -> None:
+        if not self._ensure_config():
+            return
+        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.add_column("任务", style="bold cyan")
+        table.add_column("结果", justify="center")
+        table.add_column("读取", justify="right")
+        table.add_column("变更", justify="right")
+        table.add_column("异常", justify="right")
+        for item in results:
+            status = "[green]成功[/green]" if item.success else "[red]失败[/red]"
+            table.add_row(
+                item.task_name.value,
+                status,
+                str(item.rows_read),
+                str(item.rows_changed),
+                str(item.rows_error),
+            )
+        self._pause_with_panel(Panel(table, title="执行结果", border_style="#219ebc", box=box.ROUNDED))
+
+    def _daemon_action(self, action: str) -> None:
+        if action == "start" and not self._ensure_config():
+            return
+
+        if action == "start":
+            status = self._daemon.start()
+        elif action == "stop":
+            status = self._daemon.stop(force=True)
+        else:
+            status = self._daemon.restart()
+
+        self._pause_with_panel(Panel(status.message, title="守护结果", border_style="#90be6d", box=box.ROUNDED))
+
+    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)
+        )
+
+    def _run_setup(self, *, check: bool) -> None:
+        from cli.setup import cmd_setup
+
+        args = argparse.Namespace(check=check)
+        cmd_setup(args)
+        self._refresh_settings()
+        self._wait()
+
+    def _run_foreground_scheduler(self) -> None:
+        if not self._ensure_config():
+            return
+        if not self._confirm("前台调度会占用当前终端，确认继续？", default=False):
+            return
+        from cli.commands import start_scheduler
+
+        start_scheduler(self._settings)
+
+    def _ensure_config(self) -> bool:
+        if self._is_config_ready():
+            return True
+        self._pause_with_panel(
+            Panel(
+                "腾讯文档必填配置尚未完成，请先运行配置向导。",
+                title="配置未完成",
+                border_style="red",
+                box=box.ROUNDED,
+            )
+        )
+        return False
+
+    def _is_config_ready(self) -> bool:
+        fields = [
+            self._settings.tencent_client_id,
+            self._settings.tencent_client_secret,
+            self._settings.tencent_access_token,
+            self._settings.tencent_a_file_id,
+            self._settings.tencent_a_sheet_id,
+            self._settings.tencent_b_file_id,
+            self._settings.tencent_b_sheet_id,
+        ]
+        return all(bool(value.strip()) for value in fields)
+
+    def _pause_with_panel(self, panel: Panel) -> None:
+        self.console.clear()
+        self.console.print(panel)
+        self._wait()
+
+    def _wait(self) -> None:
+        self.console.input("[dim]按回车返回控制台[/dim]")
+
+    def _ask(self, label: str, *, default: str, choices: set[str]) -> str:
+        prompt = f"[bold cyan]{label}[/bold cyan] [dim](默认 {default})[/dim]: "
+        while True:
+            raw = self.console.input(prompt).strip()
+            value = raw or default
+            if value in choices:
+                return value
+            self.console.print("[red]输入无效，请重新输入。[/red]")
+
+    def _confirm(self, label: str, *, default: bool = False) -> bool:
+        hint = "Y/n" if default else "y/N"
+        raw = self.console.input(f"[bold cyan]{label}[/bold cyan] [dim]{hint}[/dim]: ").strip().lower()
+        if not raw:
+            return default
+        return raw in {"y", "yes", "是"}
+
+    @staticmethod
+    def _fmt_time(value: datetime | None) -> str:
+        if value is None:
+            return "-"
+        return value.strftime("%Y-%m-%d %H:%M:%S")
+
+
+def cmd_menu(args: argparse.Namespace, settings: Settings) -> None:
+    """Entry point for the interactive dashboard."""
+    DashboardApp(settings).run()