package com.kingdee.eas.custom.integration.base.service.detection;

import com.kingdee.eas.custom.integration.base.bizEnum.DeviceType;

/**
 * 平台检测策略接口，区分移动端和桌面端。
 *
 * <p>每种平台（钉钉、飞书、企业微信等）提供各自的 User-Agent 检测规则，
 * 由 {@link PlatformDetectionService} 统一收集并遍历匹配。</p>
 *
 * <p>新增平台时只需实现本接口并注册为 Spring Bean，
 * 无需修改已有检测器和 Controller。</p>
 *
 * <p>客户端 UA 示例：</p>
 * <ul>
 *   <li>钉钉移动端：{@code Mozilla/5.0 ... DingTalk/7.x ... Android/13}</li>
 *   <li>钉钉桌面端：{@code Mozilla/5.0 ... DingTalk/7.x ... Windows NT}</li>
 *   <li>飞书移动端：{@code Mozilla/5.0 ... Lark/7.x ... iOS/17}</li>
 *   <li>飞书桌面端：{@code Mozilla/5.0 ... Lark/7.x ... Mac OS X}</li>
 * </ul>
 */
public interface PlatformDetector {

    /**
     * 检测平台+终端复合标识。
     *
     * @param userAgent HTTP User-Agent 头
     * @return 复合标识（如 "dingtalk_mobile"、"feishu_desktop"），无法识别时返回 null
     */
    String detect(String userAgent);

    /**
     * 基础平台标识，与 oauth-config.json 中 platform 字段一致。
     */
    String platform();

    /**
     * 从 User-Agent 检测终端类型。
     *
     * @param userAgent HTTP User-Agent 头
     * @return {@link DeviceType#MOBILE} 或 {@link DeviceType#DESKTOP}，无法识别时返回 null
     */
    DeviceType detectDevice(String userAgent);
}
