下载引擎架构

┌─────────────────────────────────────────────────┐
│                   下载引擎                        │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ 分片下载  │→│ 分片处理  │→│ 文件写入       │  │
│  │ 模块     │  │ 模块     │  │ 模块           │  │
│  │          │  │          │  │                │  │
│  │ · 并发   │  │ · 解密   │  │ · FSA 流式    │  │
│  │ · 重试   │  │ · 拼接   │  │ · StreamSaver │  │
│  │ · 限速   │  │ · 转封装  │  │ · Blob 兜底   │  │
│  └──────────┘  └──────────┘  └───────────────┘  │
│                                                  │
│  ┌─────────────────────────────────────────────┐ │
│  │              内存安全管理器                  │ │
│  │  · 大小预估  · 阈值检查  · 策略选择         │ │
│  └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘

用户点击下载
    │
    ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ 1. 清单解析   │ ──→ │ 2. 分片下载   │ ──→ │ 3. 分片处理   │
│              │     │              │     │              │
│ · 下载 M3U8  │     │ · Worker Pool│     │ · AES 解密   │
│ · 解析分片列表│     │ · 并发控制   │     │ · TS 拼接    │
│ · 提取密钥   │     │ · 指数退避   │     │ · FFmpeg 转封│
│ · 预估大小   │     │ · 进度上报   │     │ · 音视频合并  │
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                  │
                                                  ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ 6. 完成通知   │ ←── │ 5. 清理回收   │ ←── │ 4. 文件写入   │
│              │     │              │     │              │
│ · 桌面通知   │     │ · 释放内存   │     │ · FSA 流式   │
│ · 路径复制   │     │ · 清理临时文件│     │ · StreamSaver│
│ · 队列推进   │     │ · 重置状态   │     │ · Blob 兜底  │
└──────────────┘     └──────────────┘     └──────────────┘

  [空闲]
    │ 用户触发下载
    ▼
  [初始化] ──── 加载 WASM、检查 API 可用性、选择写入策略
    │
    ▼
  [清单解析] ── 下载并解析 M3U8/MPD，提取分片列表和密钥
    │
    ▼
  [分片下载] ── Worker Pool 并发下载，实时上报进度
    │
    ▼
  [分片处理] ── 解密 → 拼接/转封装 → 写入磁盘
    │
    ├── 成功 → [清理] → [完成] → [空闲]
    │
    ├── 取消 → [清理] → [空闲]
    │
    └── 失败 → [清理] → [错误] → [空闲]

const downloadSegmentsConcurrently = async (
  segments: SegmentInfo[],
  onSegmentDownloaded: (buffer: ArrayBuffer, index: number) => void
) => {
  const concurrency = Math.min(config.concurrency, 8)
  let nextIndex = 0

  const worker = async () => {
    while (nextIndex < segments.length) {
      const index = nextIndex++
      const buffer = await downloadWithRetry(segments[index]!)
      onSegmentDownloaded(buffer, index)
    }
  }

  const workers = Array.from(
    { length: Math.min(concurrency, segments.length) },
    () => worker()
  )
  await Promise.all(workers)
}

预先分片（不推荐）：
Worker 1: [分片 0-49]   ← 如果这些分片较大，Worker 1 成为瓶颈
Worker 2: [分片 50-99]  ← 可能提前完成，然后空闲等待

共享计数器（FlowPick 采用）：
Worker 1: 分片 0 → 分片 3 → 分片 5 → ...
Worker 2: 分片 1 → 分片 4 → 分片 7 → ...
Worker 3: 分片 2 → 分片 6 → 分片 8 → ...

async function* segmentGenerator(
  segments: SegmentInfo[],
  signal?: AbortSignal
): AsyncGenerator<ArrayBuffer> {
  for (const segment of segments) {
    if (signal?.aborted) break
    const buffer = await downloadWithRetry(segment)
    yield buffer
  }
}

const downloadWithRetry = async (
  segment: SegmentInfo,
  maxRetries = 3
): Promise<ArrayBuffer> => {
  let lastError: unknown
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await downloadAndDecryptSegment(segment)
    } catch (e) {
      lastError = e
      if (attempt < maxRetries - 1) {
        // 指数退避：400ms, 800ms, 1600ms
        await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 400))
      }
    }
  }
  throw lastError
}

class FetchError extends Error {
  constructor(
    message: string,
    public status: number,
    public url: string
  ) {
    super(message)
    this.name = 'FetchError'
  }
}

const decryptAES128 = async (
  encryptedData: ArrayBuffer,
  key: ArrayBuffer,
  iv?: Uint8Array
): Promise<ArrayBuffer> => {
  const keyBytes = await crypto.subtle.importKey(
    'raw', key,
    { name: 'AES-CBC' },
    false,
    ['decrypt']
  )

  const ivBuffer = iv ? new Uint8Array(iv) : new Uint8Array(16)

  const decrypted = await crypto.subtle.decrypt(
    { name: 'AES-CBC', iv: ivBuffer },
    keyBytes,
    encryptedData
  )

  return decrypted
}

// 伪代码
const merged = new Uint8Array(totalSize)
let offset = 0
for (const segment of segments) {
  merged.set(new Uint8Array(segment), offset)
  offset += segment.byteLength
}

HLS 流处理：
  分片 0 → 分片 1 → 分片 2 → ... → 拼接 → 输出

DASH 流处理（音视频分离）：
  初始化段 → 视频分片 0 → 视频分片 1 → ... ─┐
                                              ├→ FFmpeg 合并 → 输出
  初始化段 → 音频分片 0 → 音频分片 1 → ... ─┘

async function createFSAStream(
  filename: string,
  dirHandle?: FileSystemDirectoryHandle | null
): Promise<WritableStream<Uint8Array>> {
  let handle: FileSystemFileHandle

  if (dirHandle) {
    // 已有目录权限，直接创建文件
    handle = await dirHandle.getFileHandle(filename, { create: true })
  } else {
    // 弹窗让用户选择保存位置
    handle = await window.showSaveFilePicker!({
      suggestedName: filename,
      types: [{
        description: 'Video',
        accept: { 'video/mp4': ['.mp4'] }
      }]
    })
  }

  const writable = await handle.createWritable()

  return new WritableStream<Uint8Array>({
    async write(chunk) { await writable.write(chunk) },
    async close() { await writable.close() },
    async abort(reason) { await writable.abort(reason) }
  }, {
    highWaterMark: 16 * 1024 * 1024 // 16MB 缓冲区
  })
}

async function createStreamSaverStream(
  filename: string,
  fileSize?: number
): Promise<WritableStream<Uint8Array>> {
  const ss = await getStreamSaver()
  const fileStream = ss.createWriteStream(filename, { size: fileSize })
  return fileStream
}

// 伪代码
const blob = new Blob([mergedData], { type: 'video/mp4' })
const url = URL.createObjectURL(blob)
const a = document.createElement('a')
a.href = url
a.download = filename
a.click()
URL.revokeObjectURL(url)

async function estimateSegmentsSize(
  segments: ArrayBuffer[] | AsyncGenerator<ArrayBuffer>,
  totalCount: number
): Promise<{ estimatedSize: number; isEstimate: boolean }> {
  // 采样数量：min(5, max(1, totalCount * 0.1))
  const sampleCount = Math.min(5, Math.max(1, Math.floor(totalCount * 0.1)))

  // 下载前几个分片并计算平均大小
  let sampledTotal = 0
  for (let i = 0; i < sampleCount; i++) {
    sampledTotal += sampleSegment.byteLength
  }

  const avgSample = sampledTotal / sampleCount
  return {
    estimatedSize: Math.round(avgSample * totalCount),
    isEstimate: true
  }
}

预估大小 < 800MB  → 任意策略均可
预估大小 800MB-1.5GB → 优先流式写入，Blob 模式显示警告
预估大小 > 1.5GB → 强制流式写入，Blob 模式拒绝

const MEMORY_CONFIG = {
  maxBlobSize: 1500 * 1024 * 1024,    // 1.5GB 硬限制
  warnBlobSize: 800 * 1024 * 1024,    // 800MB 警告阈值
}

const checkMemoryPressure = (): 'normal' | 'warning' | 'critical' => {
  // 检查当前已分配的分片缓冲区总大小
  const allocatedMB = allocatedBuffers.reduce((sum, buf) => sum + buf.byteLength, 0) / 1048576

  if (allocatedMB > 1200) return 'critical'
  if (allocatedMB > 600) return 'warning'
  return 'normal'
}

const updateSpeedAndTime = () => {
  const elapsed = (Date.now() - downloadStartTime) / 1000
  const bytesPerSecond = downloadedBytes / elapsed

  // 格式化速度显示
  if (bytesPerSecond > 1024 * 1024) {
    speed = `${(bytesPerSecond / 1048576).toFixed(1)} MB/s`
  } else if (bytesPerSecond > 1024) {
    speed = `${(bytesPerSecond / 1024).toFixed(1)} KB/s`
  } else {
    speed = `${bytesPerSecond.toFixed(0)} B/s`
  }
}

剩余时间 = (剩余分片数 × 平均分片大小) / 当前速度

export interface StreamMergeProgress {
  phase: 'downloading' | 'merging'
  percent: number
  downloadedBytes: number
  totalBytes: number
  speed: string
  eta: string
}

// 选择目录并请求持久化权限
async function pickSaveDirectory(): Promise<string | null> {
  const handle = await window.showDirectoryPicker!({
    mode: 'readwrite',
    id: 'flowpick-save-dir',
    startIn: 'downloads'
  })

  const permissionState = await handle.requestPermission({
    mode: 'readwrite'
  })

  if (permissionState === 'granted') {
    savedDirHandle = handle
    localStorage.setItem('flowpick_save_dir_name', handle.name)
    return handle.name
  }
}

async function checkSavedDirPermission(): Promise<boolean> {
  if (!savedDirHandle) return false

  try {
    const status = await navigator.permissions.query({
      name: 'file-system',
      handle: savedDirHandle
    })
    return status.state === 'granted'
  } catch {
    // query 失败时用实际操作测试
    const testFile = await savedDirHandle
      .getFileHandle(`__fp_test_${Date.now()}__`, { create: true })
    const w = await testFile.createWritable()
    await w.close()
    return true
  }
}

首次使用：
  用户点击"选择目录" → showDirectoryPicker() 弹窗 → 用户选择 → 权限授予 → 缓存句柄

再次打开页面：
  读取缓存的目录名 → permissions.query() 静默检查 → 权限有效 → 直接使用

权限失效时：
  permissions.query() 返回 'denied' → 清除缓存 → 提示用户重新选择目录

export interface StreamMergeOptions {
  segments: ArrayBuffer[] | AsyncGenerator<ArrayBuffer>
  totalSegments: number
  filename: string
  outputFormat?: 'mp4' | 'ts'
  onProgress?: (progress: StreamMergeProgress) => void
  signal?: AbortSignal  // 取消信号
}

用户点击取消
    │
    ▼
1. signal.abort() 触发
    │
    ▼
2. 中断所有进行中的 fetch 请求
   └── AbortController 关联的所有 fetch 立即抛出 AbortError
    │
    ▼
3. 停止 Worker Pool
   └── 所有 Worker 检测到 signal.aborted，退出循环
    │
    ▼
4. 清理 FFmpeg 虚拟文件系统
   └── 删除 filelist.txt、segment_*.ts、output.* 等临时文件
    │
    ▼
5. 释放已分配的内存缓冲区
   └── 将所有 ArrayBuffer 引用置空，等待 GC 回收
    │
    ▼
6. 丢弃不完整的文件
   └── FSA 模式：调用 writable.abort()
   └── StreamSaver 模式：调用 writable.abort()
   └── Blob 模式：不触发下载，直接释放 Blob
    │
    ▼
7. 重置引擎状态
   └── 清除进度数据、速度统计、错误信息

UI 层 AbortController
    │
    ├──→ 分片下载 Worker Pool（中断 fetch）
    ├──→ 分片处理管线（跳过剩余分片）
    ├──→ FFmpeg WASM（终止转封装）
    └──→ 文件写入流（abort 写入）

并发数 1：████████████████████████████  慢，带宽利用率低
并发数 2：██████████████████  较快，基本可用
并发数 4：██████████  快，推荐默认值
并发数 6：████████  很快，接近最优
并发数 8：████████  与 6 基本持平，边际收益递减
并发数 12+：████████  可能触发 CDN 限速，反而变慢

┌─────────────────────────────────────────────┐
│                 UI 层                        │
│  · 展示用户提示（Toast/弹窗）                │
│  · 更新下载状态为"失败"                      │
│  · 提供重试/反馈入口                         │
└──────────────────┬──────────────────────────┘
                   │ 捕获所有异常
┌──────────────────▼──────────────────────────┐
│              引擎门面层                       │
│  · 统一异常格式（StreamMergeError）          │
│  · 附加上下文信息（URL、分片索引、阶段）      │
│  · 决定是否可重试                            │
└──────────────────┬──────────────────────────┘
                   │
    ┌──────────────┼──────────────┐
    ▼              ▼              ▼
┌────────┐  ┌──────────┐  ┌──────────┐
│下载模块│  │处理模块  │  │写入模块  │
│        │  │          │  │          │
│FetchErr│  │CryptoErr │  │WriteErr  │
└────────┘  └──────────┘  └──────────┘