// 前端判 204 的正确姿势
const res = await fetch('/api/item/1', { method: 'DELETE' });
if (res.status === 204) return null;      // 无 body，不能调 res.json()
if (!res.ok) throw new Error(`HTTP ${res.status}`);
return res.json();

第一次访问 http://old.com/a  （301 → https://new.com/a）
浏览器：发请求 → 收到 301 → 记录到重定向缓存 → 请求新地址

第二次访问 http://old.com/a
浏览器：不发网络请求，直接内部跳到 https://new.com/a
        DevTools Network 里 old.com 这条会显示 "(disk cache)" 或根本不出现

HTTP/1.1 301 Moved Permanently
Location: https://new.example.com/a
Cache-Control: max-age=3600      # 只缓存 1 小时，给自己留后路

// Node/Express 演示：POST 表单遇到不同重定向的结果
app.post('/submit', (req, res) => res.redirect(302, '/target'));
// 浏览器实际发出：GET /target，body 丢失 ❌

app.post('/submit', (req, res) => res.redirect(307, '/target'));
// 浏览器实际发出：POST /target，body 完整保留 ✅

Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

Client                                              Server
  |                                                   |
  |------------- ClientHello ------------------------>|
  |   支持的 TLS 版本、密码套件列表、Client Random、    |
  |   扩展（SNI 指明访问哪个域名、ALPN 协商 h2/http1.1）|
  |                                                   |
  |<------------ ServerHello --------------------------|
  |   选定版本 + 选定密码套件、Server Random           |
  |<------------ Certificate --------------------------|
  |   服务器证书链（叶子证书 + 中间 CA）               |
  |<------------ ServerKeyExchange --------------------|
  |   （仅 ECDHE 套件）服务端 ECDHE 公钥 +             |
  |    用证书私钥对参数的签名                          |
  |<------------ ServerHelloDone ----------------------|
  |                                                   |
  | [ 客户端验证证书：域名匹配？未过期？未吊销？        |
  |   签名链能追溯到本地信任的根 CA？ ]                |
  |                                                   |
  |------------- ClientKeyExchange ------------------>|
  |   RSA 套件：用服务器公钥加密 Pre-Master Secret     |
  |   ECDHE 套件：发送客户端 ECDHE 公钥                |
  |------------- ChangeCipherSpec ------------------->|
  |------------- Finished（加密） ------------------->|
  |                                                   |
  |<------------ ChangeCipherSpec ---------------------|
  |<------------ Finished（加密） ---------------------|
  |                                                   |
  |============ 应用数据（AES-GCM 对称加密） =========>|

Master Secret = PRF(Pre-Master Secret, "master secret",
                    Client Random + Server Random)

会话密钥组 = PRF(Master Secret, "key expansion",
                 Server Random + Client Random)
           → 客户端写密钥、服务端写密钥、各自的 IV

根 CA 证书（预置在操作系统/浏览器信任库，自签名）
   └─ 签发 → 中间 CA 证书（服务器需要一并下发，缺失会导致部分客户端报错）
          └─ 签发 → 叶子证书（你的 example.com 证书）

客户端 --请求公钥--> [中间人] --请求公钥--> 服务器
客户端 <--中间人公钥-- [中间人] <--服务器公钥-- 服务器
（此后中间人可解密、篡改、再加密转发，双方完全无感）

HTTP/1.1 200 OK
Content-Type: text/event-stream; charset=utf-8
Cache-Control: no-cache, no-transform
Connection: keep-alive
X-Accel-Buffering: no        # 关键：关闭 Nginx 响应缓冲，否则消息会被攒着不下发

: 这是注释行，常用来做心跳保活

event: message
id: 1024
retry: 3000
data: {"delta":"你"}

data: {"delta":"好"}

data: 第一行
data: 第二行

event: done
data: [DONE]

app.get('/api/chat/stream', async (req, res) => {
  res.writeHead(200, {
    'Content-Type': 'text/event-stream; charset=utf-8',
    'Cache-Control': 'no-cache, no-transform',
    Connection: 'keep-alive',
    'X-Accel-Buffering': 'no',
  });
  res.flushHeaders(); // 立刻把响应头发出去，别等 body

  // 断线重连时客户端会带上这个头，用于续传
  const lastId = Number(req.headers['last-event-id'] || 0);

  // 心跳：每 15s 发一个注释帧，防止网关空闲超时断连
  const heartbeat = setInterval(() => res.write(': ping\n\n'), 15000);

  // 客户端主动断开（关页面、abort）时清理资源，务必做，否则泄漏
  req.on('close', () => {
    clearInterval(heartbeat);
    res.end();
  });

  try {
    let id = lastId;
    for await (const token of callLLM(req.query.q, { from: lastId })) {
      id += 1;
      // 注意：data 内不能出现裸换行，用 JSON.stringify 天然规避
      res.write(`id: ${id}\n`);
      res.write(`data: ${JSON.stringify({ delta: token })}\n\n`);
    }
    res.write('event: done\ndata: [DONE]\n\n');
  } catch (e) {
    res.write(`event: error\ndata: ${JSON.stringify({ msg: e.message })}\n\n`);
  } finally {
    clearInterval(heartbeat);
    res.end();
  }
});

// 优点：浏览器原生，自动重连、自动带 Last-Event-ID
// 限制：只能 GET，不能自定义请求头（无法带 Authorization），跨域要靠 CORS
const es = new EventSource('/api/chat/stream?q=hello', {
  withCredentials: true, // 跨域时携带 Cookie，服务端需配合 CORS 凭证配置
});

// 默认事件（服务端没写 event 字段时）
es.onmessage = (e) => {
  const { delta } = JSON.parse(e.data);
  render(delta);
};

// 自定义事件
es.addEventListener('done', () => {
  es.close(); // 必须手动关，否则浏览器会尝试重连
});

es.addEventListener('error', (e) => {
  // 注意：网络断开时也会触发 error，浏览器随后自动重连
  // readyState: 0=CONNECTING(重连中) 1=OPEN 2=CLOSED(不会再重连)
  if (es.readyState === EventSource.CLOSED) {
    console.error('连接已彻底关闭');
  }
});

// 优点：可 POST、可自定义 Header（带 Authorization）、可用 AbortController 中断
// 代价：断线重连、Last-Event-ID 续传要自己实现
async function chatStream(body, { onDelta, onDone, signal }) {
  const res = await fetch('/api/chat/stream', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${getAccessToken()}`,
      Accept: 'text/event-stream',
    },
    body: JSON.stringify(body),
    signal, // 配合 AbortController 实现"停止生成"
  });

  if (!res.ok) throw new Error(`HTTP ${res.status}`);

  const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
  let buffer = '';

  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    buffer += value;

    // 以空行切分消息帧；\r\n\r\n 兼容部分服务端
    let idx;
    while ((idx = buffer.search(/\r?\n\r?\n/)) !== -1) {
      const raw = buffer.slice(0, idx);
      buffer = buffer.slice(idx).replace(/^\r?\n\r?\n/, '');

      let eventName = 'message';
      const dataLines = [];
      for (const line of raw.split(/\r?\n/)) {
        if (line.startsWith(':')) continue;              // 注释/心跳，跳过
        const i = line.indexOf(':');
        const field = i === -1 ? line : line.slice(0, i);
        // 规范：冒号后若有一个空格需去掉
        const val = i === -1 ? '' : line.slice(i + 1).replace(/^ /, '');
        if (field === 'event') eventName = val;
        else if (field === 'data') dataLines.push(val);
      }
      const data = dataLines.join('\n');
      if (!data) continue;

      if (eventName === 'done' || data === '[DONE]') return onDone?.();
      if (eventName === 'error') throw new Error(data);
      onDelta(JSON.parse(data).delta);
    }
  }
  onDone?.();
}

// 使用：支持"停止生成"
const ctrl = new AbortController();
chatStream({ q: '你好' }, { onDelta: render, signal: ctrl.signal });
// 点击停止按钮
stopBtn.onclick = () => ctrl.abort();

location /api/chat/stream {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Connection '';   # 清掉，避免 Connection: close
    proxy_buffering off;              # 关闭响应缓冲，逐块下发
    proxy_cache off;
    gzip off;                         # 压缩缓冲区同样会攒数据
    proxy_read_timeout 3600s;         # 别让长连接被超时掐断
    chunked_transfer_encoding on;
}

基准： https://a.example.com:443/p/1
https://a.example.com/p/2        ✅ 同源（443 是 https 默认端口）
http://a.example.com/p/1         ❌ 协议不同
https://b.example.com/p/1        ❌ 主机不同（子域不同也算跨域）
https://a.example.com:8443/p/1   ❌ 端口不同

# 1) 预检请求（浏览器自动发，业务代码看不到）
OPTIONS /api/data HTTP/1.1
Origin: https://web.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type, authorization

# 2) 预检响应
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://web.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 86400        # 预检结果缓存 1 天，减少 OPTIONS 往返

# 3) 通过后才发真实请求
POST /api/data HTTP/1.1
Origin: https://web.example.com
...

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://web.example.com
Access-Control-Expose-Headers: X-Total-Count, X-Request-Id   # 不写的话 JS 读不到这些自定义响应头

// Express 手写 CORS（含白名单，比无脑 * 安全）
const WHITELIST = ['https://web.example.com', 'https://admin.example.com'];
app.use((req, res, next) => {
  const origin = req.headers.origin;
  if (WHITELIST.includes(origin)) {
    res.setHeader('Access-Control-Allow-Origin', origin); // 回显，不用 *
    res.setHeader('Vary', 'Origin');                      // 关键：避免 CDN 把某个源的响应缓存给别人
    res.setHeader('Access-Control-Allow-Credentials', 'true');
    res.setHeader('Access-Control-Allow-Methods', 'GET,POST,PUT,DELETE,OPTIONS');
    res.setHeader('Access-Control-Allow-Headers', 'Content-Type,Authorization');
    res.setHeader('Access-Control-Expose-Headers', 'X-Request-Id');
    res.setHeader('Access-Control-Max-Age', '86400');
  }
  if (req.method === 'OPTIONS') return res.sendStatus(204); // 预检直接结束
  next();
});

function jsonp(url, params = {}, timeout = 8000) {
  return new Promise((resolve, reject) => {
    // 1. 生成全局唯一回调名，挂到 window 上
    const cbName = `__jsonp_${Date.now()}_${Math.random().toString(36).slice(2)}`;
    const script = document.createElement('script');
    let timer;

    const cleanup = () => {
      delete window[cbName];
      script.remove();
      clearTimeout(timer);
    };

    // 2. 服务端返回的 JS 会调用这个函数，参数就是数据
    window[cbName] = (data) => { cleanup(); resolve(data); };

    // 3. 拼 URL，把回调名告诉服务端
    const qs = new URLSearchParams({ ...params, callback: cbName }).toString();
    script.src = `${url}?${qs}`;
    script.onerror = () => { cleanup(); reject(new Error('JSONP 加载失败')); };

    // 4. JSONP 没有原生超时，必须自己兜底，否则回调永远挂在 window 上
    timer = setTimeout(() => { cleanup(); reject(new Error('JSONP 超时')); }, timeout);

    document.body.appendChild(script);
  });
}

// 服务端返回的内容形如（Content-Type: application/javascript）：
// __jsonp_1700000000_abc({"code":0,"data":[1,2,3]})

<script src="https://cdn.example.com/lib.js"
        integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC"
        crossorigin="anonymous"></script>
<!-- 哈希不匹配则拒绝执行；crossorigin 是 SRI 校验的前提 -->

<!-- as 属性是必需的：决定优先级、Accept 头、CSP 策略、是否复用 -->
<link rel="preload" href="/fonts/Inter.woff2" as="font" type="font/woff2" crossorigin>
<link rel="preload" href="/img/hero.webp" as="image">
<link rel="preload" href="/js/critical.js" as="script">
<link rel="preload" href="/css/above-fold.css" as="style">

<!-- 下一个路由的 chunk：空闲时预取，不影响当前页 -->
<link rel="prefetch" href="/assets/detail-page.a1b2c3.js" as="script">
<!-- 明确用户下一步大概率会去详情页时使用 -->

// webpack magic comment
import(/* webpackPrefetch: true */ './DetailPage');  // 生成 <link rel=prefetch>，父 chunk 加载完后插入
import(/* webpackPreload: true */ './Chart');        // 生成 <link rel=preload>，与父 chunk 并行加载

<link rel="dns-prefetch" href="https://cdn.example.com">   <!-- 只做 DNS 解析，开销极小 -->
<link rel="preconnect" href="https://cdn.example.com" crossorigin>
<!-- 提前完成 DNS + TCP + TLS 握手，省 100~500ms。但每个连接有成本，
     只对 2~4 个确定会用到的关键第三方域使用，滥用反而抢占带宽 -->

<link rel="modulepreload" href="/js/app.js">
<!-- ES Module 专用：不仅下载，还会解析模块并递归预载其依赖图，比 preload 更彻底 -->

<script type="speculationrules">
{
  "prefetch": [{ "where": { "href_matches": "/products/*" }, "eagerness": "moderate" }],
  "prerender": [{ "where": { "selector_matches": ".nav-primary a" }, "eagerness": "conservative" }]
}
</script>
<!-- Chrome 支持；prerender 会在后台真正渲染整个页面，点击瞬间呈现 -->

// prefetch 命中的资源，transferSize 为 0（没有网络传输）但 decodedBodySize > 0
const entries = performance.getEntriesByType('resource');
entries
  .filter((e) => e.transferSize === 0 && e.decodedBodySize > 0)
  .forEach((e) => console.log('走了缓存：', e.name, e.duration.toFixed(1) + 'ms'));

// 更精确地看 initiatorType
const hit = entries.find((e) => e.name.includes('detail-page'));
console.log(hit.initiatorType, hit.transferSize, hit.duration);

{
  "sub": "10086",              // 用户 ID
  "roles": ["editor"],
  "perms": ["article:write"],  // 权限量大时别塞进来，token 会超大，改为服务端查
  "sid": "sess_7f3a...",       // 会话 ID，用于批量吊销
  "iat": 1735689600,
  "exp": 1735691400,           // 30 分钟
  "iss": "auth.example.com",
  "aud": "api.example.com"
}

Access Token  → 内存变量（页面刷新后用 Refresh 静默换回来）
Refresh Token → Set-Cookie: rt=xxx; HttpOnly; Secure; SameSite=Strict; Path=/auth/refresh; Max-Age=604800

① 登录
   POST /auth/login {username, password}
   ← 200 { accessToken }  +  Set-Cookie: rt=...; HttpOnly; Path=/auth/refresh

② 正常请求
   GET /api/orders   Authorization: Bearer <accessToken>
   ← 200

③ Access 过期
   GET /api/orders   Authorization: Bearer <过期的>
   ← 401 { code: 'TOKEN_EXPIRED' }

④ 静默刷新（浏览器自动带上 rt Cookie）
   POST /auth/refresh
   ← 200 { accessToken: 新的 }  + Set-Cookie: rt=新的（轮换！旧的立即作废）

⑤ 用新 Access 重放原请求 → 200，用户完全无感

⑥ Refresh 也过期 / 被吊销
   ← 401 → 清空状态，跳登录页（带上 redirect 参数以便登录后回来）

import axios from 'axios';

const http = axios.create({ baseURL: '/api', withCredentials: true });

let accessToken = null;            // 内存存储
let refreshPromise = null;         // 关键：正在进行的刷新，用于合并并发

export const setAccessToken = (t) => { accessToken = t; };

// 请求拦截：注入 token
http.interceptors.request.use((config) => {
  if (accessToken) config.headers.Authorization = `Bearer ${accessToken}`;
  return config;
});

// 单例刷新：无论多少个请求同时 401，只会真正发一次 refresh
function refreshToken() {
  if (!refreshPromise) {
    refreshPromise = axios
      // 注意用裸 axios，避免走自己的拦截器造成递归
      .post('/auth/refresh', null, { withCredentials: true })
      .then((res) => {
        accessToken = res.data.accessToken;
        return accessToken;
      })
      .finally(() => {
        refreshPromise = null;     // 无论成败都要释放，否则后续永远刷不了
      });
  }
  return refreshPromise;
}

// 响应拦截：401 → 刷新 → 重放
http.interceptors.response.use(
  (res) => res,
  async (error) => {
    const { config, response } = error;

    // 只处理 401；403 是有权限问题，不该刷新
    if (response?.status !== 401 || !config) return Promise.reject(error);

    // 防止无限循环：刷新接口本身 401，或已重试过一次
    if (config._retried || config.url.includes('/auth/refresh')) {
      logout();
      return Promise.reject(error);
    }
    config._retried = true;

    try {
      const token = await refreshToken();          // 并发请求在此处排队等同一个 Promise
      config.headers.Authorization = `Bearer ${token}`;
      return http(config);                          // 重放原请求
    } catch (e) {
      logout();                                     // 刷新失败，彻底登出
      return Promise.reject(e);
    }
  }
);

function logout() {
  accessToken = null;
  const from = encodeURIComponent(location.pathname + location.search);
  location.replace(`/login?redirect=${from}`);
}

服务端为每个登录会话维护一个 family（家族）：
  family_id: 一次登录对应一个
  当前有效 refresh 的 jti（唯一 ID）

刷新时：
  1. 校验传入的 refresh 签名、未过期
  2. 查这个 jti 是否是该 family 的"当前有效"
     - 是   → 签发新 access + 新 refresh，把 family 的当前 jti 更新为新的，旧 jti 标记已用
     - 不是（说明这是一个已被用过的旧 refresh）
            → 判定为 token 泄露/重放，**吊销整个 family**，强制该用户所有设备重新登录，并告警

用户访问 app-a.example.com/orders（未登录）
   ↓ 302
https://sso.example.com/authorize
    ?client_id=app-a
    &redirect_uri=https://app-a.example.com/callback
    &response_type=code
    &state=<随机串，防 CSRF>
    &code_challenge=<S256(verifier)>&code_challenge_method=S256   ← PKCE，前端应用必备
   ↓
SSO 检查自己域下的会话 Cookie（sso.example.com 的 HttpOnly Cookie）
   ├─ 无会话 → 展示登录页 → 用户输入账密 → 建立 SSO 会话 Cookie
   └─ 有会话 → 直接跳过登录（这就是"单点"的来源）
   ↓ 302 回跳
https://app-a.example.com/callback?code=xxx&state=<校验一致>
   ↓ 前端用 code + code_verifier 换 token
POST https://sso.example.com/token
   ← { accessToken, refreshToken, idToken }
   ↓
app-a 拿到自己的双 Token，之后照常业务

用户再访问 app-b.example.com
   ↓ 同样跳 SSO，但 SSO 会话 Cookie 还在
   ↓ 无需再次输入密码，直接回跳 code
   → app-b 也拿到属于自己的双 Token（各系统 token 相互独立）

// Vue Router 动态路由 + 守卫
router.beforeEach(async (to) => {
  if (to.meta.public) return true;                 // 白名单页面
  if (!userStore.token) return { path: '/login', query: { redirect: to.fullPath } };

  if (!userStore.routesLoaded) {
    const { menus, perms } = await api.getUserPermission();
    userStore.perms = new Set(perms);
    // 按权限过滤出可访问路由并注入
    filterRoutes(asyncRoutes, userStore.perms).forEach((r) => router.addRoute(r));
    userStore.routesLoaded = true;
    // 关键：此时 to 对应的路由刚注册，必须重新导航一次才能匹配到
    return { ...to, replace: true };
  }
  return true;
});

// 兜底：所有动态路由注册完后再加通配 404，否则会被提前匹配
// router.addRoute({ path: '/:pathMatch(.*)*', component: NotFound })

// Vue 3 自定义指令：v-permission="'order:delete'"
app.directive('permission', {
  mounted(el, binding) {
    const need = binding.value;
    const has = Array.isArray(need)
      ? need.some((p) => userStore.perms.has(p))    // 数组语义：任一即可
      : userStore.perms.has(need);
    // 移除而非隐藏：display:none 用户改 DevTools 就能点出来（虽然接口层仍会拦）
    if (!has) el.parentNode?.removeChild(el);
  },
});

// React：组件包裹更符合声明式，且支持 fallback
function Auth({ perm, fallback = null, children }) {
  const { perms } = useAuth();
  const list = Array.isArray(perm) ? perm : [perm];
  return list.some((p) => perms.has(p)) ? <>{children}</> : fallback;
}

// 用法
<Auth perm="order:delete" fallback={<Button disabled>删除</Button>}>
  <Button danger onClick={onDelete}>删除</Button>
</Auth>

选择文件
  ↓
切片（Blob.slice）
  ↓
Web Worker 计算文件 hash（spark-md5 增量 / crypto.subtle）
  ↓
POST /upload/check  { hash, filename, total }
  ├─ { uploaded: true, url }         → 秒传，直接结束 ✅
  └─ { uploaded: false, exist: [0,1,2,5] }  → 已有分片列表
  ↓
过滤掉 exist 中的分片，剩余的进任务池并发上传（限流 4 个）
每片：POST /upload/chunk  FormData{ hash, index, chunk }
  ↓ 全部成功
POST /upload/merge  { hash, filename, total, chunkSize }
  ← { url }

const CHUNK_SIZE = 5 * 1024 * 1024; // 5MB。太小则请求数爆炸，太大则单片失败代价高

function createChunks(file, size = CHUNK_SIZE) {
  const chunks = [];
  for (let cur = 0, index = 0; cur < file.size; cur += size, index++) {
    // Blob.slice 是零拷贝的视图操作，不会真的把数据读进内存
    chunks.push({ index, blob: file.slice(cur, cur + size) });
  }
  return chunks;
}

// hash.worker.js —— 必须放 Worker，10GB 文件在主线程算 hash 会让页面完全卡死
import SparkMD5 from 'spark-md5';

self.onmessage = async ({ data: { chunks } }) => {
  const spark = new SparkMD5.ArrayBuffer();  // 增量计算，避免一次性读入整个文件爆内存
  for (let i = 0; i < chunks.length; i++) {
    const buf = await chunks[i].blob.arrayBuffer();
    spark.append(buf);
    self.postMessage({ type: 'progress', percent: ((i + 1) / chunks.length) * 100 });
  }
  self.postMessage({ type: 'done', hash: spark.end() });
};

// 主线程调用
function calcHash(chunks, onProgress) {
  return new Promise((resolve) => {
    const worker = new Worker(new URL('./hash.worker.js', import.meta.url), { type: 'module' });
    worker.postMessage({ chunks });
    worker.onmessage = ({ data }) => {
      if (data.type === 'progress') onProgress?.(data.percent);
      else { resolve(data.hash); worker.terminate(); }
    };
  });
}

// 全量 hash 一个 10GB 文件可能要几分钟，用户等不了
// 抽样策略：第一片全取 + 最后一片全取 + 中间每片取首中尾各 2 字节
// 速度提升上百倍，碰撞率对业务可接受；风险是极端情况下误判秒传
async function calcSampleHash(file, size = 2 * 1024 * 1024) {
  const spark = new SparkMD5.ArrayBuffer();
  const chunks = [file.slice(0, size)];                       // 第一片完整
  let cur = size;
  while (cur < file.size - size) {
    chunks.push(file.slice(cur, cur + 2));                    // 中间：首
    chunks.push(file.slice(cur + size / 2, cur + size / 2 + 2)); // 中间：中
    chunks.push(file.slice(cur + size - 2, cur + size));      // 中间：尾
    cur += size;
  }
  chunks.push(file.slice(-size));                             // 最后一片完整
  spark.append(await new Blob(chunks).arrayBuffer());
  // 把文件大小也混进去，进一步降低碰撞
  return spark.end() + '-' + file.size;
}

// 限制并发数，支持失败重试和整体中断
async function runPool(tasks, limit = 4, { signal, retry = 3 } = {}) {
  let cursor = 0;
  const results = new Array(tasks.length);

  async function worker() {
    while (cursor < tasks.length) {
      if (signal?.aborted) throw new DOMException('已取消', 'AbortError');
      const i = cursor++;                       // 取号，天然避免竞争
      let lastErr;
      for (let attempt = 0; attempt <= retry; attempt++) {
        try {
          results[i] = await tasks[i]();
          lastErr = null;
          break;
        } catch (e) {
          if (e.name === 'AbortError') throw e; // 主动取消不重试
          lastErr = e;
          // 指数退避 + 抖动，避免所有失败分片同时重试打爆服务端
          await new Promise((r) => setTimeout(r, 2 ** attempt * 300 + Math.random() * 200));
        }
      }
      if (lastErr) throw lastErr;
    }
  }

  // 开 limit 个"工人"并行消费同一个游标
  await Promise.all(Array.from({ length: Math.min(limit, tasks.length) }, worker));
  return results;
}

const CHUNK_SIZE = 5 * 1024 * 1024;

export async function uploadLargeFile(file, { onProgress, signal } = {}) {
  // ---- 1. 切片 ----
  const chunks = createChunks(file, CHUNK_SIZE);

  // ---- 2. 计算 hash（Worker 中进行，不阻塞主线程）----
  const hash = await calcHash(chunks, (p) => onProgress?.({ stage: 'hash', percent: p }));

  // ---- 3. 秒传 & 续传检查 ----
  const { uploaded, url, exist = [] } = await fetch('/upload/check', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ hash, filename: file.name, total: chunks.length, size: file.size }),
    signal,
  }).then((r) => r.json());

  if (uploaded) {
    onProgress?.({ stage: 'upload', percent: 100 });
    return url;                                 // 秒传命中，零传输 ✅
  }

  // ---- 4. 断点续传：跳过服务端已有的分片 ----
  const existSet = new Set(exist);
  const pending = chunks.filter((c) => !existSet.has(c.index));

  // 进度基线要把已存在的分片算进去，否则续传时进度会从 0 开始，体验很差
  let doneBytes = existSet.size * CHUNK_SIZE;
  const report = () =>
    onProgress?.({
      stage: 'upload',
      percent: Math.min(100, (doneBytes / file.size) * 100),
    });
  report();

  // ---- 5. 并发上传 ----
  const tasks = pending.map((chunk) => async () => {
    const fd = new FormData();
    fd.append('hash', hash);
    fd.append('index', String(chunk.index));
    fd.append('chunk', chunk.blob);             // 字段顺序：文件放最后，便于服务端流式解析先拿到元信息
    const res = await fetch('/upload/chunk', { method: 'POST', body: fd, signal });
    if (!res.ok) throw new Error(`分片 ${chunk.index} 上传失败: ${res.status}`);
    doneBytes += chunk.blob.size;
    report();
  });

  await runPool(tasks, 4, { signal });

  // ---- 6. 通知合并 ----
  const merged = await fetch('/upload/merge', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ hash, filename: file.name, total: chunks.length, chunkSize: CHUNK_SIZE }),
    signal,
  }).then((r) => r.json());

  return merged.url;
}

const ctrl = new AbortController();
uploadLargeFile(file, {
  signal: ctrl.signal,
  onProgress: ({ stage, percent }) => setTip(`${stage === 'hash' ? '解析中' : '上传中'} ${percent.toFixed(1)}%`),
})
  .then((url) => console.log('完成', url))
  .catch((e) => {
    if (e.name === 'AbortError') console.log('已暂停');   // 已上传分片仍在服务端，下次自动续传
    else console.error(e);
  });

pauseBtn.onclick = () => ctrl.abort();   // 暂停 = abort；恢复 = 重新调用，check 接口会返回已传分片

// 分片接收：以 hash 为目录名，index 为文件名落盘
app.post('/upload/chunk', upload.single('chunk'), async (req, res) => {
  const { hash, index } = req.body;
  const dir = path.join(TEMP_DIR, hash);
  await fs.promises.mkdir(dir, { recursive: true });
  // 先写临时名再 rename，保证"文件存在"等价于"内容完整"，避免半截文件被 check 误判为已上传
  const tmp = path.join(dir, `${index}.part`);
  await fs.promises.rename(req.file.path, tmp);
  res.json({ code: 0 });
});

// 合并：必须按 index 数字序，且用流式追加，不能全读进内存
app.post('/upload/merge', async (req, res) => {
  const { hash, filename, total } = req.body;
  const dir = path.join(TEMP_DIR, hash);

  const files = await fs.promises.readdir(dir);
  if (files.length !== Number(total)) {
    return res.status(400).json({ code: 1, msg: '分片不完整' });
  }

  const target = path.join(UPLOAD_DIR, `${hash}${path.extname(filename)}`);
  const ws = fs.createWriteStream(target);
  for (let i = 0; i < total; i++) {
    // 串行 pipe，保证顺序；用 { end: false } 避免中途关闭写流
    await new Promise((resolve, reject) => {
      const rs = fs.createReadStream(path.join(dir, `${i}.part`));
      rs.on('error', reject);
      rs.on('end', resolve);
      rs.pipe(ws, { end: false });
    });
  }
  ws.end();

  await fs.promises.rm(dir, { recursive: true, force: true });   // 清理临时分片
  res.json({ code: 0, url: `/files/${path.basename(target)}` });
});

前端 → 后端申请上传凭证（STS 临时 token 或预签名 URL，权限最小化、有效期几分钟）
     → 前端直接 PUT 到 OSS（走 OSS 的 Multipart Upload 分片协议）
     → 上传完成回调后端登记