package com.tencent.qian.webview.model

/**
 * `qianapp://` 协议解析结果。
 *
 * **协议形态**:`qianapp://<custom-path>?flowId=...&action=...&result=...&from=tencent_ess&<extras>`
 *
 * **字段说明**:
 * - [rawUrl]:原始 URL 字面量,客户可用来兜底排查
 * - [customPath]:host + path 拼接(如 `qianapp://callback/sign` → `callback/sign`)
 * - [flowId]:流程 ID;recognized field
 * - [action]:动作 String 直透;与 [SignAction] 常量比对;未知值原样透出
 * - [result]:结果 String 直透;与 [SignResultStatus] 常量比对;未知值原样透出
 * - [from]:固定 `tencent_ess`;recognized field
 * - [extras]:除上述 4 个 recognized field 之外的客户自定义 query 透传
 *
 * **设计要点**:
 * - **不**包含 `errorCode` / `errorMsg`(原方案文档草稿有,已废弃)
 * - [action] / [result] **保持 String** 不转 enum,空字符串与未知值原样保留
 * - 重复 query key 取首个,与 H5 团队约定一致
 *
 * **Phase 2 翻译**:Java 端机械翻译为 POJO + getter/setter;iOS Swift 同名 struct。
 *
 * **跨端一致性**:与 iOS `SignResult` struct 字段 1:1 对齐。
 */
public data class SignResult(
    /** 原始 qianapp:// URL */
    val rawUrl: String,

    /** host + path,例 `callback/sign` */
    val customPath: String,

    /** 流程 ID;协议未给则为空字符串 */
    val flowId: String,

    /**
     * 动作类型(String 直透,未识别值原样透出)。
     *
     * 已知值见 [SignAction]:`fill` / `sign` / `reject_fill` / `reject_sign` / `view` / `""`。
     */
    val action: String,

    /**
     * 结果状态(String 直透,未识别值原样透出)。
     *
     * 已知值见 [SignResultStatus]:`success` / `fail` / `""`。
     */
    val result: String,

    /** 来源标识,通常为 `tencent_ess`;协议未给则为空字符串 */
    val from: String,

    /**
     * 客户自定义 query 透传(已剔除 4 个 recognized field)。
     *
     * 重复 key 保留首个,UTF-8 percent-decoded。
     */
    val extras: Map<String, String>
) {

    public companion object {
        /**
         * 全空 fallback,用于非法 URL 解析失败场景。
         *
         * 客户拿到空 result 时应当对照 [rawUrl] 判断是否解析失败。
         */
        @JvmField
        public val EMPTY: SignResult = SignResult(
            rawUrl = "",
            customPath = "",
            flowId = "",
            action = "",
            result = "",
            from = "",
            extras = emptyMap()
        )
    }
}
