package com.tencent.qian.webview.model

/**
 * SDK 内部事件,用于将容器层非协议性观测点上报给业务方。
 *
 * **设计要点**:
 * - 与 [SignResult] 解耦:协议回调走 [SignCallback.onSignResult],容器观测走 [SignCallback.onEvent]
 * - sealed class 便于客户用 `when` 穷尽匹配
 * - 字段保持纯数据,不持有 View / Context 引用,避免内存泄漏
 *
 * **跨端一致性**:与 iOS `SdkEvent` enum 语义对齐;
 * 各平台仅保留本端实际触发的 case,对方平台特有事件以注释说明等价关系。
 */
public sealed class SdkEvent {

    // ────────── 页面生命周期 ──────────

    /** WebView 开始加载某 URL(主框架) */
    public data class PageStarted(val url: String) : SdkEvent()

    /** WebView 主框架加载完成 */
    public data class PageFinished(val url: String) : SdkEvent()

    // ────────── 权限 ──────────

    /** Web 端请求的权限已被系统授予 */
    public data class PermissionGranted(val permissions: List<String>) : SdkEvent()

    /** Web 端请求的权限被用户拒绝 */
    public data class PermissionDenied(val permissions: List<String>) : SdkEvent()

    // ────────── Scheme 拦截 ──────────

    /**
     * 命中 SDK 已识别的 scheme(qianapp / externalSchemes)。
     *
     * @param scheme 例:`qianapp` / `weixin` / `alipays`
     * @param url 完整 URL,客户用于诊断
     */
    public data class SchemeIntercepted(val scheme: String, val url: String) : SdkEvent()

    /**
     * 命中未在 [externalSchemes] 白名单的 scheme,SDK 已丢弃。
     *
     * 客户可据此扩充 [externalSchemes] 配置。
     */
    public data class SchemeNotMatched(val url: String) : SdkEvent()

    // ────────── 网络与渲染错误 ──────────

    /** 主框架 [android.webkit.WebViewClient.onReceivedError] 上报 */
    public data class LoadError(
        val url: String,
        val errorCode: Int,
        val description: String
    ) : SdkEvent()

    /** 主框架 [android.webkit.WebViewClient.onReceivedHttpError] 上报 */
    public data class HttpError(
        val url: String,
        val statusCode: Int,
        val reasonPhrase: String
    ) : SdkEvent()

    /**
     * 主框架命中 SSL 错误。SDK 已强制 cancel,业务侧可弹「证书异常,请联系客服」之类提示。
     */
    public data class SslError(val url: String, val primaryError: Int) : SdkEvent()

    // ────────── 下载 ──────────
    // 注:Android 使用系统 DownloadManager 执行下载,下载完成由系统通知栏处理,
    // SDK 在 enqueue 后不再持有下载生命周期,因此不提供 DownloadCompleted 事件。
    // iOS 因进程内下载(WKDownload)需要 downloadCompleted 事件驱动分享 Sheet,属于平台差异。

    /** WebView DownloadListener 触发,SDK 准备通过 DownloadManager 下载(失败时 fallback 到 ACTION_VIEW) */
    public data class DownloadStart(
        val url: String,
        val mimeType: String,
        val contentDisposition: String
    ) : SdkEvent()

    /** 下载启动失败(无可处理 ActivityNotFoundException) */
    public data class DownloadFailed(val url: String, val reason: String) : SdkEvent()

    // ────────── 渲染进程崩溃 ──────────

    /**
     * WebView 渲染进程崩溃或被系统杀死(Android 8.0+ / API 26+)。
     *
     * @param didCrash `true` = 进程崩溃(OOM / GPU 驱动异常);`false` = 被系统回收(低内存)
     * @param url 崩溃时正在加载的 URL
     *
     * **iOS 等价**:`webContentProcessTerminated(url)`。
     */
    public data class RenderProcessGone(val didCrash: Boolean, val url: String) : SdkEvent()

    // ────────── UA 注入失败兜底(Phase 1.5 起 iOS 也复用)──────────

    /** UA 注入失败(默认 UA 拿不到等异常) */
    public data class UserAgentInjectFailed(val reason: String) : SdkEvent()
}
