ForcePilot/backend/package/yuxi/channels/adapters/zalo_oa/setup.py

from __future__ import annotations

from typing import Any

from yuxi.channels.adapters.zalo_oa.probe import probe_zalo_oa


async def setup_wizard_validate(app_id: str, secret_key: str, config: dict[str, Any] | None = None) -> dict[str, Any]:
    result = await probe_zalo_oa(app_id, secret_key, config)
    if result.get("status") == "ok":
        return {
            "valid": True,
            "oa_id": result.get("oa_id", ""),
            "oa_name": result.get("name", ""),
            "follower_count": result.get("follower_count", 0),
        }
    return {
        "valid": False,
        "error": result.get("message", "Validation failed"),
    }


def setup_wizard_recommendations(oa_name: str) -> dict[str, Any]:
    return {
        "dm_policy_options": [
            {
                "value": "open",
                "label": "Open — all followers can chat",
                "recommended": False,
            },
            {
                "value": "allowlist",
                "label": "Allowlist — only approved followers can chat",
                "recommended": True,
            },
            {
                "value": "pairing",
                "label": "Pairing — followers must pair before chatting",
                "recommended": False,
            },
            {
                "value": "disabled",
                "label": "Disabled — no DMs accepted",
                "recommended": False,
            },
        ],
        "allowFrom_example": ["123456789", "987654321"],
        "webhook_url": "https://your-domain.com/api/channels/zalo_oa/webhook",
        "oa_name": oa_name,
    }


def setup_wizard_cli_prompt() -> dict[str, Any]:
    """生成交互式 CLI 设置引导提示，供前端/CLI 使用。

    返回包含步骤列表的配置向导，每个步骤包含:
    - step: 步骤序号
    - key: 配置项 key
    - label: 显示标签
    - description: 说明
    - required: 是否必填
    - default: 默认值
    - validate: 校验正则 (可选)
    """
    return {
        "title": "Zalo OA Setup Wizard",
        "description": "配置 Zalo Official Account 渠道，支持文本/图片/文件/贴纸/模板消息等富媒体交互",
        "steps": [
            {
                "step": 1,
                "key": "app_id",
                "label": "Zalo OA App ID",
                "description": "Your Zalo OA App ID from the Zalo Developer Console",
                "required": True,
                "validate_regex": r"^\d{10,}$",
                "validate_message": "App ID 应为 10 位以上数字",
                "env_var": "ZALO_OA_APP_ID",
                "cli_flag": "--app-id",
            },
            {
                "step": 2,
                "key": "secret_key",
                "label": "Zalo OA Secret Key",
                "description": "Your Zalo OA Secret Key from the Zalo Developer Console",
                "required": True,
                "sensitive": True,
                "validate_regex": r"^[a-zA-Z0-9]{20,}$",
                "validate_message": "Secret Key 格式不正确",
                "env_var": "ZALO_OA_SECRET_KEY",
                "cli_flag": "--secret-key",
            },
            {
                "step": 3,
                "key": "dm_policy",
                "label": "DM Policy",
                "description": "How to handle incoming Direct Messages",
                "required": False,
                "default": "open",
                "options": ["open", "allowlist", "pairing", "disabled"],
                "cli_flag": "--dm-policy",
            },
            {
                "step": 4,
                "key": "allow_from",
                "label": "Allowlist User IDs",
                "description": "Comma-separated user IDs allowed to chat (if allowlist policy)",
                "required": False,
                "default": "",
                "cli_flag": "--allow-from",
            },
            {
                "step": 5,
                "key": "webhook_url",
                "label": "Webhook URL",
                "description": "Public HTTPS URL for receiving Zalo webhook events (leave empty for polling mode)",
                "required": False,
                "default": "",
                "validate_regex": r"^(https?://.+|)$",
                "validate_message": "Webhook URL 必须以 http:// 或 https:// 开头",
                "cli_flag": "--webhook-url",
            },
            {
                "step": 6,
                "key": "webhook_mac_key",
                "label": "Webhook MAC Key",
                "description": "Secret key for verifying webhook signatures (recommended for production)",
                "required": False,
                "sensitive": True,
                "env_var": "ZALO_WEBHOOK_MAC_KEY",
                "cli_flag": "--webhook-mac-key",
            },
            {
                "step": 7,
                "key": "response_prefix",
                "label": "Response Prefix",
                "description": "Optional prefix added before every auto-reply message",
                "required": False,
                "default": "",
                "cli_flag": "--response-prefix",
            },
            {
                "step": 8,
                "key": "enabled",
                "label": "Enable Channel",
                "description": "Enable this channel after setup is complete",
                "required": False,
                "default": True,
                "type": "toggle",
                "cli_flag": "--enabled",
            },
        ],
        "post_setup_hints": [
            "Setup 完成后建议运行 doctor 诊断确认渠道状态",
            "生产环境强烈建议配置 Webhook MAC Key 和 Allowlist 白名单",
            "可通过 setup_entry.py 中的 ZaloOASetupPlugin 独立验证配置",
        ],
    }