// 导入 GZIP 处理库（浏览器/Node.js 通用，需提前安装：npm install pako @types/pako）
// import * as pako from "pako";

/**
 * 协议常量类：存储协议核心配置（不可修改，确保前后端一致）
 */
export class ProtocolConst {
  /** 协议版本：v1（4位，对应字节3~4的低4位，剩余位保留用于后续升级） */
  static readonly PROTOCOL_VERSION = 0b0001;

  /** 头部固定长度：8字节（字节1~8，结构严格定义，不可修改） */
  static readonly HEADER_SIZE = 8;

  /** 最大包体大小：10MB（防止内存溢出，与 Python 端 MAX_BODY_SIZE 一致） */
  static readonly MAX_BODY_SIZE = 1024 * 1024 * 10;

  /** 字符串编码格式：UTF-8（统一前后端字符串编解码，避免乱码） */
  static readonly STRING_ENCODING = "utf-8" as const; // as const 固定字符串类型，避免类型拓宽
}

/**
 * 消息类型枚举（4位，存储在字节1高4位）
 * 与 Python 端 MessageType 枚举值完全对齐，支持16种类型（当前用5种，剩余预留扩展）
 */
export enum MessageType {
  PING = 0b0000, // 心跳消息（用于检测连接存活）
  AUDIO_DATA = 0b0001, // 纯音频数据（PCM 二进制流，对应 RAW 序列化）
  TEXT_MESSAGE = 0b0010, // 纯文本消息（对应 STRING 序列化，无 JSON 包装）
  AUDIO_TEXT_MIX = 0b0011, // 音频+文本混合数据（复杂结构，对应 JSON 序列化）
  CONTROL_CMD = 0b0100, // 控制指令（暂停/继续/停止等，对应 JSON 序列化）
}

/**
 * 序列化方式枚举（4位，存储在字节2高4位）
 * 按数据类型选择最优序列化方式，减少开销
 */
export enum SerializationType {
  RAW = 0b0000, // 原始二进制（无需编解码，直接透传，适合音频等二进制数据）
  JSON = 0b0001, // JSON 格式（适合字典、列表等复杂结构，如控制指令、混合数据）
  STRING = 0b0010, // 直接字符串（UTF-8 编码，无 JSON 包装，适合纯文本消息）
}

/**
 * 压缩方式枚举（4位，存储在字节2低4位）
 * 按需选择压缩策略，平衡性能和传输体积
 */
export enum CompressionType {
  NONE = 0b0000, // 无压缩（小数据包如控制指令、短文本，避免压缩开销）
  GZIP = 0b0001, // GZIP 压缩（大数据包如长文本、混合数据，减少网络传输量）
}

/**
 * 控制指令枚举（配合 MessageType.CONTROL_CMD 使用）
 * 定义业务层面的控制指令，与 Python 端控制指令值一致
 */
export enum ControlCommand {
  HEARTBEAT = 0b0001, // 心跳响应（回复 PING 消息）
  PAUSE = 0b0010, // 暂停指令（如暂停音频播放）
  RESUME = 0b0011, // 继续指令（如恢复音频播放）
  STOP = 0b0100, // 停止指令（如停止音频传输）
}

/**
 * 解包返回结果接口（强类型约束，明确返回数据结构）
 * 让 IDE 提供自动提示，避免类型错误
 */
export interface UnpackedResult {
  msgType: MessageType; // 消息类型（枚举值，便于逻辑判断）
  msgTypeName: keyof typeof MessageType; // 消息类型名称（字符串，如 "TEXT_MESSAGE"，便于日志打印）
  serialization: SerializationType; // 序列化方式（枚举值）
  serializationName: keyof typeof SerializationType; // 序列化方式名称（字符串）
  compression: CompressionType; // 压缩方式（枚举值）
  compressionName: keyof typeof CompressionType; // 压缩方式名称（字符串）
  body: Uint8Array | string | object | unknown[]; // 解包后的原始包体（根据序列化方式动态变化）
}

/**
 * 打包入参类型别名（简化方法入参类型定义，提高可读性）
 */
// 包体支持的类型：二进制、字符串、对象、数组
type PackBody = Uint8Array | string | object | unknown[];
// 序列化方式可选值：枚举值、null、undefined（null/undefined 时自动推导）
type OptionalSerialization = SerializationType | null | undefined;

/**
 * 协议编解码工具类（静态类，无需实例化，提供 pack/unpack 静态方法）
 * 核心功能：将业务数据打包为符合协议的二进制包，或解析二进制包为业务数据
 * 特点：与 Python/JS 端完全兼容，性能高效，类型安全
 */
export class ProtocolCodec {
  /**
   * 打包协议包：将业务数据按协议格式封装为二进制包
   * @param msgType 消息类型（必须指定，枚举值）
   * @param body 业务数据（根据消息类型对应不同类型，如字符串、对象、Uint8Array）
   * @param serialization 序列化方式（可选，默认自动推导：纯文本→STRING，音频→RAW，复杂结构→JSON）
   * @param compression 压缩方式（可选，默认无压缩）
   * @returns 完整协议包（Uint8Array 类型，便于网络传输）
   * @throws 类型错误、不支持的枚举值、包体过大等异常
   */
  static pack(
    msgType: MessageType,
    body: PackBody,
    serialization: OptionalSerialization = null,
    compression: CompressionType = CompressionType.NONE
  ): Uint8Array {
    // 1. 自动推导序列化方式（减少调用方心智负担，按消息类型默认最优解）
    if (serialization === null || serialization === undefined) {
      if (msgType === MessageType.AUDIO_DATA) {
        // 音频数据→RAW 序列化（无需编解码，性能最优）
        serialization = SerializationType.RAW;
      } else if (msgType === MessageType.TEXT_MESSAGE) {
        // 纯文本消息→STRING 序列化（直接 UTF-8 编码，无冗余）
        serialization = SerializationType.STRING;
      } else if (msgType === MessageType.CONTROL_CMD || msgType === MessageType.AUDIO_TEXT_MIX) {
        // 控制指令/混合数据→JSON 序列化（支持复杂结构）
        serialization = SerializationType.JSON;
      } else {
        // 非法消息类型：抛出异常，提前阻断错误
        throw new Error(`不支持的消息类型：${MessageType[msgType]}（值：${msgType}）`);
      }
    }

    // 2. 序列化包体：将业务数据转为二进制（按序列化方式处理）
    let serializedBody: Uint8Array; // 序列化后的二进制数据
    const textEncoder = new TextEncoder(ProtocolConst.STRING_ENCODING); // UTF-8 编码器

    switch (serialization) {
      case SerializationType.RAW:
        // RAW 序列化：必须传入 Uint8Array（二进制数据直接透传）
        if (!(body instanceof Uint8Array)) {
          throw new TypeError(`RAW 序列化要求 body 必须是 Uint8Array 类型，当前传入：${typeof body}`);
        }
        serializedBody = body;
        break;

      case SerializationType.STRING:
        // STRING 序列化：必须传入字符串，直接 UTF-8 编码（无 JSON 包装）
        if (typeof body !== "string") {
          throw new TypeError(`STRING 序列化要求 body 必须是 string 类型，当前传入：${typeof body}`);
        }
        serializedBody = textEncoder.encode(body);
        break;

      case SerializationType.JSON:
        // JSON 序列化：支持字符串、对象、数组，转为 JSON 字符串后 UTF-8 编码
        if (typeof body === "string") {
          // 已为字符串，直接编码
          serializedBody = textEncoder.encode(body);
        } else if (typeof body === "object" && body !== null) {
          // 对象/数组→JSON 字符串→编码（用 JSON.stringify 序列化）
          const jsonStr = JSON.stringify(body);
          serializedBody = textEncoder.encode(jsonStr);
        } else {
          throw new TypeError(`JSON 序列化要求 body 必须是 string/object/array 类型，当前传入：${typeof body}`);
        }
        break;

      default:
        // 非法序列化方式：抛出异常
        throw new Error(`不支持的序列化方式：${SerializationType[serialization]}（值：${serialization}）`);
    }

    // 3. 压缩包体：按指定压缩方式处理（GZIP 或无压缩）
    let compressedBody: Uint8Array; // 压缩后的二进制数据
    if (compression === CompressionType.NONE) {
      // 无压缩：直接透传序列化后的二进制数据
      compressedBody = serializedBody;
    } else {
      // 非法压缩方式：抛出异常
      throw new Error(`不支持的压缩方式：${CompressionType[compression]}（值：${compression}）`);
    }

    // 4. 校验包体大小：防止超过最大限制（避免内存溢出）
    const bodyLen = compressedBody.length; // 压缩后的包体长度
    if (bodyLen > ProtocolConst.MAX_BODY_SIZE) {
      throw new Error(
        `包体过大（${bodyLen}字节），最大支持${ProtocolConst.MAX_BODY_SIZE}字节（10MB）`
      );
    }

    // 5. 构造头部：8字节固定结构（严格按协议定义，大端序，与 Python 端一致）
    const header = new Uint8Array(ProtocolConst.HEADER_SIZE); // 头部缓冲区（8字节）

    // 字节1：消息类型(4位) + 保留位(4位)
    // 消息类型左移4位（占高4位），保留位填0（后续扩展用）
    header[0] = (msgType << 4) | 0x00;

    // 字节2：序列化方式(4位) + 压缩方式(4位)
    // 序列化方式左移4位（占高4位），压缩方式占低4位（&0x0F 确保仅4位）
    header[1] = (serialization << 4) | (compression & 0x0F);

    // 字节3~4：协议版本（16位大端序）
    // 大端序：高位字节在前，低位字节在后（网络传输标准字节序）
    header[2] = (ProtocolConst.PROTOCOL_VERSION >> 8) & 0xFF; // 版本高8位（当前版本为1，高8位为0）
    header[3] = ProtocolConst.PROTOCOL_VERSION & 0xFF; // 版本低8位（当前版本为1）

    // 字节5~8：包体长度（32位大端序）
    // 32位整数：最高位字节（第5字节）→ 最低位字节（第8字节）
    header[4] = (bodyLen >> 24) & 0xFF; // 包体长度第24~31位
    header[5] = (bodyLen >> 16) & 0xFF; // 包体长度第16~23位
    header[6] = (bodyLen >> 8) & 0xFF; // 包体长度第8~15位
    header[7] = bodyLen & 0xFF; // 包体长度第0~7位

    // 6. 拼接头部和包体：生成完整协议包
    const totalLen = ProtocolConst.HEADER_SIZE + bodyLen; // 总长度 = 头部8字节 + 包体长度
    const packet = new Uint8Array(totalLen); // 完整包缓冲区

    packet.set(header, 0); // 从索引0开始写入头部（占前8字节）
    packet.set(compressedBody, ProtocolConst.HEADER_SIZE); // 从索引8开始写入包体

    return packet; // 返回完整协议包（Uint8Array，网络传输高效）
  }

  /**
   * 解包协议包：将二进制协议包解析为业务数据
   * @param packet 完整协议包（网络接收的二进制数据，支持 Uint8Array 或 ArrayBuffer）
   * @returns 结构化解包结果（UnpackedResult 接口，包含消息类型、包体等信息）
   * @throws 包长度过短、版本不匹配、解压缩失败、反序列化失败等异常
   */
  static unpack(packet: Uint8Array | ArrayBuffer): UnpackedResult {
    // 统一数据类型：将 ArrayBuffer 转为 Uint8Array（便于按字节操作）
    const uint8Packet = packet instanceof ArrayBuffer 
      ? new Uint8Array(packet) 
      : packet;

    // 1. 校验包长度：至少包含8字节头部
    if (uint8Packet.length < ProtocolConst.HEADER_SIZE) {
      throw new Error(
        `包长度过短（${uint8Packet.length}字节），至少需要${ProtocolConst.HEADER_SIZE}字节头部`
      );
    }

    // 2. 拆分头部和包体：前8字节为头部，剩余为包体
    const header = uint8Packet.subarray(0, ProtocolConst.HEADER_SIZE); // 头部（0~7索引）
    const bodyBuffer = uint8Packet.subarray(ProtocolConst.HEADER_SIZE); // 包体（8索引开始）

    // 3. 解析头部字段（按协议结构逐字节解析，大端序）
    // 字节1：消息类型(4位) + 保留位(4位)
    const byte1 = header[0];
    const msgType = (byte1 >> 4) & 0x0F; // 右移4位取高4位（消息类型），&0x0F 确保仅4位
    // 校验消息类型合法性（防止非法包注入）
    if (!Object.values(MessageType).includes(msgType as MessageType)) {
      throw new Error(`非法消息类型：${msgType}（无对应枚举值）`);
    }

    // 字节2：序列化方式(4位) + 压缩方式(4位)
    const byte2 = header[1];
    const serialization = (byte2 >> 4) & 0x0F; // 右移4位取高4位（序列化方式）
    const compression = byte2 & 0x0F; // 取低4位（压缩方式）
    // 校验序列化方式合法性
    if (!Object.values(SerializationType).includes(serialization as SerializationType)) {
      throw new Error(`非法序列化方式：${serialization}（无对应枚举值）`);
    }
    // 校验压缩方式合法性
    if (!Object.values(CompressionType).includes(compression as CompressionType)) {
      throw new Error(`非法压缩方式：${compression}（无对应枚举值）`);
    }

    // 字节3~4：协议版本（16位大端序）
    const version = (header[2] << 8) | header[3]; // 大端序解析：高位字节<<8 + 低位字节
    // 校验版本兼容性（仅支持当前协议版本）
    if (version !== ProtocolConst.PROTOCOL_VERSION) {
      throw new Error(
        `协议版本不匹配：收到v${version}，当前支持v${ProtocolConst.PROTOCOL_VERSION}`
      );
    }

    // 字节5~8：包体长度（32位大端序）
    const bodyLen = (header[4] << 24) | (header[5] << 16) | (header[6] << 8) | header[7];
    // 校验包体长度一致性（头部声明长度 vs 实际包体长度）
    if (bodyBuffer.length !== bodyLen) {
      throw new Error(
        `包体长度不匹配：头部声明${bodyLen}字节，实际接收${bodyBuffer.length}字节（可能包丢失或非法包）`
      );
    }

    // 4. 解压包体：按头部指定的压缩方式解压
    let decompressedBody: Uint8Array; // 解压后的二进制数据
    if (compression === CompressionType.NONE) {
      // 无压缩：直接透传包体数据
      decompressedBody = bodyBuffer;
    } else {
      // 此处理论上不会触发（已提前校验压缩方式合法性）
      throw new Error(`不支持的压缩方式：${CompressionType[compression]}（值：${compression}）`);
    }

    // 5. 反序列化包体：将二进制数据转为业务数据（按序列化方式处理）
    let body: UnpackedResult["body"]; // 反序列化后的原始业务数据
    const textDecoder = new TextDecoder(ProtocolConst.STRING_ENCODING); // UTF-8 解码器

    switch (serialization) {
      case SerializationType.RAW:
        // RAW 反序列化：直接返回 Uint8Array（二进制数据，如音频 PCM）
        body = decompressedBody;
        break;

      case SerializationType.STRING:
        // STRING 反序列化：UTF-8 解码为字符串（无 JSON 解析步骤）
        try {
          body = textDecoder.decode(decompressedBody);
        } catch (e) {
          throw new Error(`STRING 反序列化失败：${(e as Error).message}（UTF-8 解码错误，可能是非法字符串数据）`);
        }
        break;

      case SerializationType.JSON:
        // JSON 反序列化：先 UTF-8 解码为字符串，再 JSON.parse 转为对象/数组
        try {
          const jsonStr = textDecoder.decode(decompressedBody); // 二进制→JSON 字符串
          body = JSON.parse(jsonStr); // JSON 字符串→对象/数组
        } catch (e) {
          if (e instanceof TypeError) {
            throw new Error(`JSON 反序列化失败：${ProtocolConst.STRING_ENCODING} 解码错误（非法 UTF-8 数据）`);
          } else if (e instanceof SyntaxError) {
            throw new Error(`JSON 反序列化失败：格式错误（${(e as Error).message}），请检查 JSON 语法`);
          } else {
            throw new Error(`JSON 反序列化失败：${(e as Error).message}`);
          }
        }
        break;

      default:
        // 此处理论上不会触发（已提前校验序列化方式合法性）
        throw new Error(`不支持的序列化方式：${SerializationType[serialization]}（值：${serialization}）`);
    }

    // 6. 构造并返回解包结果（利用枚举反向映射获取名称，便于日志和展示）
    return {
      msgType: msgType as MessageType, // 消息类型枚举值
      msgTypeName: MessageType[msgType] as keyof typeof MessageType, // 消息类型名称（如 "TEXT_MESSAGE"）
      serialization: serialization as SerializationType, // 序列化方式枚举值
      serializationName: SerializationType[serialization] as keyof typeof SerializationType, // 序列化方式名称
      compression: compression as CompressionType, // 压缩方式枚举值
      compressionName: CompressionType[compression] as keyof typeof CompressionType, // 压缩方式名称
      body: body, // 反序列化后的原始业务数据
    };
  }
}