"""
scheduled-tasks 业务占位模块

约定：
- 只面向客户端 exe / backend-client 的定时任务场景；
- 不在此处编写 admin 工程的定时逻辑。

当前版本仅保留框架占位，不包含具体业务实现。
后续若有“客户端 exe 相关的定时执行代码”，请在本模块中按任务维度逐步补充。
"""

from datetime import datetime, timezone, timedelta
from typing import Any, Dict, List


def _beijing_now_naive() -> datetime:
    """当前北京时间（naive）"""
    return datetime.now(timezone(timedelta(hours=8))).replace(tzinfo=None)


def list_tasks() -> List[str]:
    """
    返回当前可用的定时任务名称列表。

    初始版本仅作为占位，返回空列表。
    """
    return []


def run_task(name: str, *, now: datetime | None = None) -> Dict[str, Any]:
    """
    运行指定名称的定时任务。

    初始版本不执行任何实际业务，仅返回占位结果。
    未来在此根据 name 分发到具体任务实现。
    """
    if now is None:
        now = _beijing_now_naive()

    return {
        "task": name,
        "status": "noop",
        "run_at": now.isoformat(),
        "detail": "scheduled-tasks currently contains no concrete business logic.",
    }