# uniapp+vue3 API 预加载通用方案 — 设计

- **日期**：2026-07-02
- **作者**：Claude Fable 5（与项目 owner 协作）
- **范围**：`frontend/`（uniapp + Vue 3 + Vite），主要服务于 App 端

---

## ★ 方案概述（必读）

### 要解决的问题

**业务问题**：
- 用户进入详情页时白屏 loading 闪烁（网络请求耗时 200-800ms），体验差
- 冷启动后首页数据（排行榜、用户配置等公共数据）每次都重新拉取，浪费带宽
- 用户在页面间反复切换时，相同接口被多次调用，服务端压力大

**技术问题**：
- uniapp 没有内置的请求缓存层，每个 `uni.request` 都是独立调用
- `uni.navigateTo` 跳转和页面数据加载是串行的（先跳转 → 再 `onLoad` 发请求），无法利用"用户点击到页面渲染"之间的时间窗口
- 没有统一的请求去重机制，同一数据源被多个组件同时请求时产生冗余网络调用

### 整体实现路径

| 阶段 | 内容 | 预估时间 |
|------|------|----------|
| Phase 1：核心缓存引擎 | `storage.js` + `core.js`（内存 Map + LRU + inFlight 去重 + TTL） | 1 天 |
| Phase 2：调度 & 路由集成 | `scheduler.js` + `navigate.js` + `config.js`（启动预热 / idle 预拉 / 页面切换预拉） | 0.5 天 |
| Phase 3：Vue 集成 | `usePreload.js` composable + `preload.config.js` 业务配置 + `App.vue` / `store/user.js` 集成 | 0.5 天 |
| Phase 4：测试 & 验收 | 单元测试 + 集成冒烟 + 真机验收 | 0.5 天 |
| **合计** | | **2.5 天** |

### 关键决策

| 决策 | 理由 | 详见 |
|------|------|------|
| 核心模块（core.js）零外部依赖 | 可独立测试、不耦合 uniapp / Vue，未来可迁移 | §2.2 |
| wrap navigateTo 不 await 预拉结果 | 点击立刻跳转，预拉后台并发，不增加跳转延迟 | §2.5 |
| 401/业务码7/16 统一 swallow | `api.js` 已同步 `reLaunch` 跳登录页，预加载层再抛错会造成双重跳转 | §5 |
| 内存 LRU + 文件 FIFO 双轨淘汰 | 内存注重热数据命中率（LRU），文件注重简单可靠（FIFO） | §7.1 |
| inFlight 去重（同 key 并发共享 Promise） | 避免启动期 / 页面切换时同一接口被多次调用 | §4.4 |
| 按 userId 物理隔离文件缓存 | 防止用户 A 读到用户 B 的缓存数据 | §6.5 |

### 核心架构图（TL;DR）

```
                        ┌──────────────────────────┐
                        │   preload.config.js       │
                        │   (业务声明 key/fetcher/ttl) │
                        └──────────┬───────────────┘
                                   │
   ┌───────────┐     ┌─────────────▼──────────────┐
   │ App.vue   │────►│       scheduler.js          │
   │ onLaunch  │     │  warmStartup() / warmIdle() │
   │ onShow    │     └─────────────┬──────────────┘
   └───────────┘                   │
                                   │
   ┌───────────┐     ┌─────────────▼──────────────┐
   │ navigate  │────►│         core.js             │
   │ .js       │     │  run / get / invalidate     │
   │ (wrap     │     │  Map<key,Entry> + LRU       │
   │  uni.nav*)│     │  inFlight dedup             │
   └───────────┘     └──────┬──────────┬──────────┘
                             │          │
                    ┌────────▼──┐  ┌────▼──────────┐
                    │ storage.js│  │ usePreload.js │
                    │ (_doc/    │  │ (composable:  │
                    │  preload/ │  │  data/loading │
                    │  {uid}/)  │  │  /error/refresh│
                    └───────────┘  └───────────────┘
```

### 文档说明

- **适用范围**：`frontend/` 下所有 API 调用场景（页面数据加载、启动预热、页面切换预拉），以 App 端（Android/iOS）为主，H5 / 小程序降级兼容
- **工作量估算**：约 2.5 天（核心 1 天 + 调度&路由 0.5 天 + Vue 集成 0.5 天 + 测试 0.5 天），约 800-1000 行新代码
- **前置版本/历史**：无。这是项目首个 API 预加载方案
- **目标读者**：前端开发（需了解如何配置新的预拉 key 和使用 `usePreload`）、架构评审

---

## 1. 目标与范围

为 uniapp + Vue 3 项目提供一套**通用、可配置、按场景分层的 API 预加载方案**，覆盖 4 类典型场景：

1. **页面切换前预先拉数据**：进入 A 页时按目标页 B 的清单提前拉好 B 的接口
2. **应用启动时批量预热常用数据**：`onLaunch` 期间并发拉启动清单
3. **通用响应缓存层**：相同 `url+params` 在 TTL 内复用结果
4. **idle 时机预拉**：首屏渲染完成后用空闲时间拉「可能下一屏」的数据

**非目标**：
- 不重写 `request()` 本身（保持 `utils/api.js` 签名和返回值不变，仅新增 `.abort()` 方法）
- 不做请求合并 / dedup beyond 同一 cacheKey（避免引入 dispatcher complexity）
- 不做离线缓存（断网时不读文件缓存兜底）

---

## 2. 架构与模块

### 2.1 目录结构

```
frontend/
├── utils/preloadApi/
│   ├── core.js              # 命令式核心（零 Vue 依赖）
│   ├── config.js            # 默认 config 导入与合并
│   ├── storage.js           # storage 适配器（用户隔离、namespace 隔离）
│   ├── scheduler.js         # idle / 启动期调度
│   ├── navigate.js          # wrap uni.navigateTo / switchTab / reLaunch
│   └── index.js             # 统一导出 preloadApi
├── composables/
│   └── usePreload.js        # Vue 3 包装：暴露响应式 state
└── config/
    └── preload.config.js    # 用户声明：key / fetcher / ttl / persistence / 触发时机
```

### 2.2 模块职责

| 模块 | 职责 |
| --- | --- |
| `core.js` | 注册/执行/查询/失效；维护内存 Map + LRU；并发去重 | **零外部依赖**（不依赖 Vue / uni / api.js / store；fetcher 返回的 Promise 自带 `.abort()`，core 仅存储调用）
| `config.js` | 把用户 `preload.config.js` 与内置默认值合并成一个运行时 config |
| `storage.js` | 文件缓存适配器：通过 `plus.io`（APP-PLUS）/ `uni.getFileSystemManager`（兜底）读写 `_doc/preload/{userId}/` 目录；按 userId + namespace 隔离 |
| `scheduler.js` | `warmStartup()`：跑 startup 清单；`warmIdle()`：用 `requestIdleCallback` 兜底跑 idle 清单 |
| `navigate.js` | 重写 `uni.navigateTo/switchTab/reLaunch`，命中目标页时按 pages 映射触发预拉 |
| `usePreload.js` | 包装 `core.get()`，对组件返回 `{ data, loading, error, refresh }` |

### 2.3 调用关系

```
App.vue onLaunch
   └─► scheduler.warmStartup()              ─┐
                                            ├─► core.run(key) ─► request() ─► api.js
preloadApi.navigateTo('/pages/foo?id=1')   ─┘
   └─► prefetchFor(targetPath, params)     ─┐
                                            ├─► core.run(key)
Page onLoad (composable)                    ─┘
   └─► usePreload(key, params)              ─► core.get(key)
```

### 2.4 对现有代码的侵入

| 文件 | 改动 |
| --- | --- |
| `App.vue` | ~10 行（Options API）：import `preloadApi` → `onLaunch` 中调用 `warmStartup()` → `onShow` 中调用 `warmIdle()`。注意 App.vue 使用 Options API（`export default { … }`），直接 `import` + 在生命周期方法内调用即可，**不**是 `<script setup>` composable 风格（详见 §6.5.1 App.vue 集成方式） |
| `store/modules/user.js` | ~5 行：在 `SET_USER_INFO` mutation 中注入 `preloadApi.clearForUser(oldUserId)`；在 `CLEAR_AUTH` mutation 中注入 `preloadApi.clearUser(userId)`（调用顺序约束见 §6.5） |
| `pages/*/...vue` | 把原本 `request({...})` 改成 `usePreload('key')`（setup / store action / watch 中的请求均适用）；把 `uni.navigateTo/switchTab/reLaunch` 全量替换为 `preloadApi.navigateTo/switchTab/reLaunch`（见 §2.5） |
| `utils/api.js` | `request()` 返回的 Promise 上挂 `.abort()` 方法（~8 行改动：捕获 `requestTask` + 挂 `abort()` + `fail` 中识别 abort 信号，详见 §4.4.1） |
| 其余 `utils/*` | **不动** |

### 2.5 wrappedNavigateTo 替换策略（已确定方案 A）

**严格 wrap，预拉 fire-and-forget 不 await**：

- `preloadApi.navigateTo(opts)` 内部：解析 `opts.url` 的 query string → 按目标页路径查 `config.pages` 映射 → **如果命中映射**对每个匹配项调用 `core.run(key, params)`（**不 await**）→ 立即调用原生 `uni.navigateTo(opts)
- **如果未命中 `config.pages` 映射**：直接透传调用原生 `uni.navigateTo(opts)`，不做任何预拉（预拉是 opt-in，不是 opt-out）
- 用户点击 → 立刻跳转；预拉在后台并发进行；目标页 `onLoad` 用 `usePreload(key, params)` 时大概率命中缓存
- **绝不**在 `navigateTo` 内 await 预拉结果，否则跳转延迟与设计目标矛盾
- 不保留 `uni.navigateTo` 兼容入口：要么用 `preloadApi.navigateTo`（触发预拉），要么不要预拉；保留兼容会让 "哪些跳转走预拉" 变得不可见

**全量替换规则**：用 ESLint 规则或 PR review checklist 强制 —— 全仓 `uni.navigateTo` → `preloadApi.navigateTo`（可用 codemod 一次性替换）。

**替换影响评估**（实施前确认）：
- 预计全仓 `uni.navigateTo` / `uni.switchTab` / `uni.reLaunch` 调用点在 40-80 处（分布在 `pages/` 下各 `.vue` 文件 + `App.vue`）
- 需手动 review 的特殊场景：
  - `App.vue` 第 149 行 `uni.navigateTo`（推送通知点击跳转，在 `setTimeout` 内）——应改为 `preloadApi.navigateTo`（无对应 pages 映射时自动透传，安全）
  - `App.vue` 第 92/114/143 行 `uni.reLaunch`（登录页跳转）——应改为 `preloadApi.reLaunch`（同上）
  - 任何在 `#ifdef` / `#ifndef` 块内的调用 —— codemod 可能漏掉，需手动检查
- 未命中 `config.pages` 映射时，`preloadApi.navigateTo` **直接透传**调用原生 `uni.navigateTo`（§4.1 已定义），因此即使替换出错也不会导致跳转失败，最多丢失预拉机会

---

## 3. 配置 schema

```js
// frontend/config/preload.config.js
import {
  getCastloveConfigApi,
  getUserProfileApi,
  getHotRankingApi,
  getAssetLikersApi,
  getActivityDetailApi,
  getActivityItemsApi,
  // ...按需 import
} from '@/utils/api'

export const preloadConfig = {
  // ── 全局默认 ──
  defaults: {
    ttl: 5 * 60 * 1000,          // 5 分钟
    persistence: 'memory',       // 'memory' | 'file'
    concurrency: 4,              // 单次批量最多并发数
    timeout: 10000,              // 单接口超时（ms），超时后取消预拉
    silent: true,                // 失败是否静默（true = 仅 warn，不抛）
    // ── 上限保护阈值（硬编码默认值，可在下面覆盖）──
    limits: {
      maxEntrySizeKB: 1024,      // 单 key 数据超过此值只写内存，不写文件（1 MB 上限，防止单文件过大拖慢读取）
      maxMemoryEntries: 100,     // 内存总条目上限，超出按 LRU 淘汰
      maxFileCacheMB: 50         // 文件缓存总容量上限（uni.storage 仅 4 MB 且与其他业务共享；本地 _doc/ 容量远超此值，50 MB 足够中等规模 API 响应缓存）
    }
  },

  // ── 启动期预热清单（App.vue onLaunch 跑）──
  startup: [
    { key: 'castlove.config', fetcher: getCastloveConfigApi,
      ttl: 60 * 60 * 1000, persistence: 'file' },
    { key: 'me.profile', fetcher: getUserProfileApi,
      ttl: 10 * 60 * 1000 }
  ],

  // ── idle 预拉清单（首屏渲染完后跑）──
  idle: [
    { key: 'ranking.hot', fetcher: () => getHotRankingApi('total', null, 1, 10),
      ttl: 10 * 60 * 1000 }
  ],

  // ── 页面切换预拉映射（wrappedNavigateTo 命中时触发）──
  pages: {
    '/pages/asset-detail/asset-detail': [
      { key: 'asset.likers', fetcher: (params) => getAssetLikersApi(Number(params.id)) }
    ],
    '/pages/activity-detail/activity-detail': [
      { key: 'activity.detail', fetcher: (params) => getActivityDetailApi(params.id) },
      { key: 'activity.items', fetcher: (params) => getActivityItemsApi(params.id) }
    ]
  }
}
```

**字段说明：**
- `key`：逻辑 key，业务引用缓存的唯一标识
- `fetcher(params)`：返回 Promise 的请求函数
- `ttl`：缓存有效期（ms）
- `persistence`：`'memory'`（仅内存 Map）/ `'file'`（持久化到本地文件缓存 `_doc/preload/`，走 `plus.io`）
- `concurrency`：单次批量内最大并发
- `timeout`：单接口超时（ms）
- `silent`：失败是否静默（`run` 时生效，`get` 始终抛错）
- `limits.maxEntrySizeKB / maxMemoryEntries / maxFileCacheMB`：上限保护阈值（详见 §7），默认 1024 KB / 100 条 / 50 MB；**仅在 `defaults.limits` 全局配置，不支持 per-key 覆盖**

---

## 4. 核心 API

### 4.1 命令式 API（utils/preloadApi/index.js 导出）

```js
preloadApi.run(key, params?)              // 触发一次预拉（写缓存）：①先查内存，未过期则跳过；②查 inFlight，已在请求中则共享 Promise（不重发）；③过期/未命中/未 inFlight 才发起新请求。401/7/16 静默吞掉。不返回数据
preloadApi.get(key, params?)              // 读缓存：命中直接返回；未命中/过期则拉取（同样走 inFlight 去重）；401/7/16 业务码静默吞掉（不抛给调用方）
preloadApi.refresh(key, params?, force?)  // 命令式刷新：force=true 跳过 TTL。非组件上下文使用；组件上下文用 usePreload.refresh()
preloadApi.prefetchFor(targetPath, params?)  // wrappedNavigateTo 内部调用
preloadApi.invalidate(key?)               // 失效单 key（仅内存）
preloadApi.invalidatePrefix(prefix)       // 失效某前缀（命中 logicalKey 前缀，仅内存）
preloadApi.invalidateAll()                // 清空全部内存缓存（不动文件缓存）
preloadApi.clearForUser(userId)           // 删除指定用户的文件缓存目录（`_doc/preload/{userId}/`）
preloadApi.clearUser(userId)              // 清空全部内存 + 删除指定用户的文件缓存目录（登出用）
preloadApi.warmStartup()                  // App.vue onLaunch 调用
preloadApi.warmIdle()                     // App.vue onShow 调用（每次回前台跑一次）
preloadApi.navigateTo(opts)               // 替代 uni.navigateTo（预拉 fire-and-forget）
preloadApi.switchTab(opts)                // 替代 uni.switchTab
preloadApi.reLaunch(opts)                 // 替代 uni.reLaunch
```

### 4.2 key 命名规则与物理 cache key

- 配置里写的 `key` 是"逻辑 key"
- 真正缓存的物理 key：
  ```
  ${userId || 'guest'}::${namespace}::${logicalKey}::${hash(params)}
  ```
- 同 key 不同 params 是不同缓存条目
- `namespace`：**硬编码为常量 `'preload'`**（与 §6.5 的文件目录名保持一致；预留扩展位，当前不在 schema 暴露）
- `hash(params)`：**先对 params 的 key 排序**再 `JSON.stringify` → djb2 → 16 进制（key 排序保证 `{a:1,b:2}` 与 `{b:2,a:1}` 生成相同 hash，避免命中率下降）

### 4.3 读缓存流程（`get`）

```
get(key, params)
  ├─ 计算 cacheKey
  ├─ 查内存 → 命中且未过期 → 同步 resolve（LRU touchLRU 标记访问）→ return
  ├─ 查文件缓存（async I/O）→ 命中且未过期 → 写回内存 + resolve
  ├─ 未命中 → 调 fetcher(params)
  │     ├─ 成功 → 写内存 + 异步写文件缓存（fire-and-forget）+ resolve
  │     ├─ "已登出"信号 → swallow 错误 + resolve(null)（见 _swallowAuth）
  │     └─ 其他错误 → reject(原错误)（业务方决定 toast）
  └─ 注：内存命中是唯一同步路径；文件缓存命中 / fetcher 路径均返回 async Promise，
       因此 composable §4.5 中只有内存命中能让首次渲染时 data 同步有值
```

**"已登出"信号匹配规则**（见 §5 `_swallowAuth`）：
- `err.code === 7`（业务 401：token 失效）
- `err.code === 16`（业务 403：账号被封）
- `err.message` 含 "登录已过期"（匹配 `utils/api.js` 第 86-122 行 HTTP 401 reject 时构造的 message）

**关键约束**：`run` 与 `get` 都必须 swallow "已登出"信号。理由：`utils/api.js` 第 86-122 行在检测到这些码时**已经同步调用 `uni.reLaunch` 跳登录页**，相当于"已处理"；预加载层再抛错会造成双重跳转或冷启动被中断。

### 4.3.1 `prefetchFor` 的入参约定

`preloadApi.prefetchFor(targetPath, params)`：
- `targetPath`：目标页的完整路径，如 `/pages/asset-detail/asset-detail`
- `params`：**只接受基本类型 key-value**（string / number / boolean），由 `navigate.js` 从跳转 URL 的 query string 解析得到
- 解析规则：
  - 用 `URLSearchParams` 解析 query string
  - 每个 value 用 `decodeURIComponent` 解码
  - 所有 value 统一为 string（fetcher 内部按需 `Number()` / `Boolean()` 转换）
- 示例：`uni.navigateTo({ url: '/pages/foo/bar?id=123&type=hot' })` → `{ id: '123', type: 'hot' }`
- 数组 / 嵌套对象走 `?arr=1,2,3` 这种字符串协议；不在本次 spec 范围内
- **URL 编码约束**：业务方拼 URL 时必须对 value 做 `encodeURIComponent`（特别是含 `&` / `=` / 中文 的 value）

调用链示例：
```js
navigateTo({ url: '/pages/asset-detail/asset-detail?id=123' })
// → prefetchFor('/pages/asset-detail/asset-detail', { id: '123' })
// → core.run('asset.likers', { id: '123' })
// → fetcher({ id: '123' }) = getAssetLikersApi('123')
```

### 4.4 并发去重

**适用范围**：`run` 与 `get` 共用同一套 inFlight 去重。同一个 cacheKey in-flight 时，第二个 `run` 或 `get` 共享同一个 Promise，**不重复发请求**。

**实现**：内部维护 `inFlight: Map<cacheKey, { promise, abort }>`。任何入口（run / get / prefetchFor / warmStartup / warmIdle）触发 fetch 时，先查 inFlight —— 命中则直接返回共享 Promise，未命中则创建新 Promise 并写入 inFlight。

**清理时机**：fetch **无论成功失败都在 finally 阶段清掉 inFlight**。否则失败后该 cacheKey 会永久 stuck，后续调用永远拿到同一个 reject 的 Promise。401 swallow 路径也是 finally 清掉。

**请求取消（abort）**：uniapp App 端 `uni.request` 返回的 `requestTask` 可调用 `.abort()`。当 composable 组件 unmount 或 `usePreload` 的 key/params 变化时，应 abort 前一个未完成的请求以避免浪费带宽。实现：
- `inFlight` 每个条目存 `{ promise, abort: () => { promise.abort?.(); } }`
- composable 在 `onBeforeUnmount` / watcher 中调 `abort()`
- abort 后清掉 inFlight 条目（abort 不走 finally 路径，需显式清理）

**`request()` 改造**（唯一对 `utils/api.js` 的改动，约 8 行）：

```js
// utils/api.js — request() 内部
export function request(options) {
  let _aborted = false                        // 新增：abort 标记
  const requestTask = uni.request({...})      // 改动：捕获 requestTask（原来直接调用不赋值）
  let abortFn = () => {
    _aborted = true                           // 新增：标记已 abort
    requestTask.abort()
  }
  const p = new Promise((resolve, reject) => {
    // ... 现有 success/fail 逻辑不变 ...
    // 改动：fail 回调中识别 abort 信号
    // fail: (err) => {
    //   if (_aborted) return                 // abort 触发的 fail 静默忽略
    //   reject(new Error(err.errMsg || '网络请求失败'))
    // }
  })
  p.abort = abortFn                           // 新增这一行
  return p
}
```

**关键细节**：
- `requestTask.abort()` 触发后，`uni.request` 的 `fail` 回调会以 `err.errMsg === 'request:fail abort'` 触发。必须在 `fail` 中通过 `_aborted` 标记识别并静默返回，否则 preload 层会收到一个 "网络请求失败" 的 reject。
- 所有现有调用方 `await request(...)` 语法不变；`abortFn` 仅由 preload 的 `core.js` 在组件 unmount / params 变化时调用。

### 4.4.1 abort 生命周期

### 4.5 composable API（composables/usePreload.js）

```js
// 在 <script setup> 中：
const { data, loading, error, refresh } = usePreload('asset.detail', { id: 123 })
```

返回：
- `data: Ref<any | null>`：命中缓存为缓存值；未命中拉到为 fetcher 返回值；401 swallow 为 null；其他失败为上一次值或 null
- `loading: Ref<boolean>`：true 表示当前有 in-flight 请求
- `error: Ref<Error | null>`：401 swallow 时为 null；其他错误为 Error 对象
- `refresh(force?: boolean)`：手动刷新（force=true 跳过 TTL 复用）

**初次渲染行为**（关键）：
- `core.get()` **命中内存缓存时**返回**已 resolved 的 Promise**。composable 在 `setup()` 同步阶段立即 `data.value = cached.data`，首次渲染时 `data` 就已有值、`loading` 为 false。这依赖 Vue 3 同步赋值而非下一 tick 更新。
- `core.get()` **未命中 / 文件缓存命中 / 未命中**时返回**未 resolved 的 Promise**。composable 在 `setup()` 同步阶段 `data` 初始为 null、`loading` 为 true；Promise resolve 后 **用 `.then()` 异步更新 `data.value`**，触发下一次渲染。
- 实现：`get` 内部命中内存路径直接 `return Promise.resolve(cached.data)`，未命中路径返回 `inFlightEntry.promise`
- **硬约束**：composable 内 data.value 的赋值必须包裹在 `.then()` 中（不能 `await` 后在 setup 同步代码中赋值），否则未命中路径会阻塞整个 setup 导致白屏。这等同于**不能阻塞 setup 的同步执行**。

**典型用法**：
```vue
<script setup>
const { data, loading, error, refresh } = usePreload('asset.detail', { id: route.params.id })
// 模板中：v-if="data" / v-else-if="error" / v-else="loading"
</script>
```

---

## 5. 错误处理

| 场景 | 行为 | 日志 |
| --- | --- | --- |
| 启动预热失败 | 静默（启动期不能阻塞） | `console.warn('[preload] startup fail:', key, err.message)` |
| idle 预拉失败 | 静默 | 同上 |
| 页面切换预拉失败 | 静默（用户可能不去目标页） | 同上 |
| `usePreload.get()` 在组件内失败（非 401 类） | 抛错给调用方，组件 `error` ref 更新 | 无（业务自行决定 toast） |
| **401 / 业务码 7 / 16（"已登出"信号）** | **所有链路（run / get / prefetchFor）必须 swallow，resolve(null)** | `console.warn('[preload] auth-expired, swallowed:', key)` |
| 网络断开 / 请求超时 | 抛错给调用方；**已存在的未过期缓存保持不变**（不会因为 fetch 失败而被清掉）；下次 `get` 重新尝试 | `console.warn('[preload] network error:', key, err.message)` |

**核心原则：预拉失败绝不能阻塞主链路；401 / 业务码 7 / 16 必须 swallow（避免与 `request()` 的 reLaunch 行为冲突导致冷启动被中断或双重跳转）。**

**实现位置**：`core.js` 的 `run / get` 共享一个内部 helper `_swallowAuth(err)`：

```js
function _swallowAuth(err) {
  if (err && (err.code === 7 || err.code === 16)) return null
  if (err && /登录已过期/.test(err.message || '')) return null
  return err
}
```

---

## 6. 失效策略

### 6.1 自动失效

- **TTL 到期**（per-key 配置）
- **用户登出** → `clearUser(oldUserId)`（清该用户的内存 + 删文件缓存目录）
- **切换粉丝身份** → `invalidatePrefix('me.')`（仅内存）
- **App.vue onShow** → `warmIdle()` 触发时**只对 TTL 到期的 key 自然过期**，不主动失效任何 cache

### 6.2 手动失效（业务调用）

- 点赞后：`invalidate('ranking.hot')`、`invalidatePrefix('asset.')`
- 提交评论后：`invalidatePrefix('activity.messages')`
- 进入个人页前可选主动失效 `me.*`

### 6.3 关键澄清：`invalidateAll()` vs `clearUser(userId)` vs `clearForUser(userId)`

| API | 内存 | 文件缓存 | 触发场景 |
| --- | --- | --- | --- |
| `invalidateAll()` | 清空全部 | **不动** | 极少使用；保留作为"内存全清"逃生口 |
| `clearForUser(userId)` | 不动 | 仅删指定用户的 `_doc/preload/{userId}/` 目录 | 单独清理某用户文件缓存（如切换账号但保留另一账号会话的边缘场景） |
| `clearUser(userId)` | 清空全部内存缓存（所有 userId 命名空间） + 删指定用户的文件缓存目录 | — | **登出专用** |

**核心约束**：
1. `invalidateAll()` **永远不动文件缓存**。理由：避免把当前会话（登录态改变前）的 persistence 缓存白白清掉；文件清理必须显式按 userId 走。
2. `clearUser(userId)` 的 `userId` **必须等于当前登录用户**。否则会清空当前用户的内存缓存（与文件删的目标用户不一致）。调用方需保证 userId 正确性；不在 API 层做防御。

### 6.4 数据一致性

```
写：先写内存 → 再异步写文件缓存（fire-and-forget，不 await）
读：先查内存 → 未命中查文件缓存 → 仍未命中才 fetch
清：组合清空（如 clearUser）时，先清内存 → 再删文件目录；仅清内存或仅删文件的 API（invalidateAll / clearForUser）按各自定义执行
```

文件写入失败仅 `console.warn`，不影响内存中的可用数据。文件读取失败（如文件被手动删除、权限异常）视为未命中，走 fetch 路径。

### 6.5 用户隔离

文件缓存目录结构：
```
_doc/preload/
  ├── guest/          # 未登录用户
  │   ├── {hash1}.json
  │   └── {hash2}.json
  ├── 1001/           # userId = 1001
  │   ├── {hash1}.json
  │   └── {hash2}.json
  └── 1002/           # userId = 1002
      └── {hash1}.json
```

一个缓存条目 = 一个 JSON 文件，文件名 = `{hash(cacheKey)}.json`，内容 = `{ data, ts, ttl }`。

```js
// storage.js — 文件缓存适配器
const BASE_DIR = '_doc/preload'

// 获取某个用户缓存目录下的所有条目
function listUserEntries(userId) {
  const dir = `${BASE_DIR}/${userId || 'guest'}`
  // plus.io.resolveLocalFileSystemURL 读取目录
  // 失败（目录不存在）视为空
}

// 读：解析条目 JSON 文件
async function readEntry(userId, cacheKey) {
  const path = `${BASE_DIR}/${userId || 'guest'}/${hash(cacheKey)}.json`
  // plus.io.FileReader 或 uni.getFileSystemManager().readFile
  try {
    const raw = await readFile(path, 'utf-8')
    return JSON.parse(raw)
  } catch {
    return null  // 文件不存在 / 损坏 → 视为未命中
  }
}

// 写：异步写 JSON 文件（fire-and-forget 调用，因此必须内建 .catch）
async function writeEntry(userId, cacheKey, data, ts, ttl) {
  const dir = `${BASE_DIR}/${userId || 'guest'}`
  const path = `${dir}/${hash(cacheKey)}.json`
  // 先确保目录存在（plus.io.File.createDirectory 或 mkdir）
  // 再写文件（plus.io.File.writeFile）
  // 注意：调用方不 await，因此必须在内部 .catch(e => console.warn(...))
  // 否则未捕获的文件写入异常会变成 unhandled promise rejection
}

// 登出时：删除整个用户目录
function clearForUser(userId) {
  const dir = `${BASE_DIR}/${userId || 'guest'}`
  // plus.io.resolveLocalFileSystemURL(dir, (entry) => { entry.removeRecursively(...) })
  // 或 uni.getFileSystemManager().rmdir(dir, { recursive: true })
}
```

**App.vue** 包装 `store/user` mutation，按 userId 变化分三种动作：

| 事件 | 动作 |
| --- | --- |
| `onLogin(userId)` | **不**主动清缓存。注意：**memory 总是按 userId 物理隔离**（物理 key 含 userId），新用户访问任何 key（包括 `ranking.hot` 这种"公共"数据）都需要重新拉取，**不会**自动复用前一会话或 guest 的内存条目。这是用户隔离的 by design 代价。 |
| `onSwitchUser(oldId, newId)` | `invalidatePrefix('me.')` + `clearForUser(oldId)` |
| `onLogout(userId)` | `clearUser(userId)` |

**实施注意**：
1. **store/user.js 当前没有事件总线**（只有 action / mutation，没有 emit/on）。实施方式：**包装 mutation**，在 `SET_USER_INFO` mutation 里 patch 一下：如果旧用户存在（`oldUserId != null`），调用 `preloadApi.clearForUser(oldUserId)`；在 `CLEAR_AUTH` mutation 里 patch 一下（注入 `preloadApi.clearUser(userId)` 调用）。注意：**登录场景下 `oldUserId` 为 null/undefined，必须 guard 住**，否则会误删 `_doc/preload/undefined/`。
2. **调用顺序约束**（重要）：CLEAR_AUTH 时**先 `clearUser(userId)` 再清 token / user**。原因：token 清掉之后任何业务发起的请求都会 401；preload 缓存如果在 token 清之前清理完，业务不会有 401 + 缓存不一致的窗口。
3. **CLEAR_AUTH 内部已经清了一堆 key**（`access_token / user / star_id` 等），与 `clearUser` 职责正交（preload 只在 `_doc/preload/` 下操作，不碰 uni.storage）。两者互不冲突，组合使用即可。
4. **API 选型**：`#ifdef APP-PLUS` 主路径走 `plus.io`（项目已有先例，`useShare.js` 里用了 `plus.io.copyTo` 操作 `_doc/`）；`#ifdef H5` / 小程序等降级用 `uni.getFileSystemManager`（仅当 persist=file 时走文件，memory 不变）。注意：`plus.io` API 均为回调风格，storage.js 内部需用 `new Promise((resolve, reject) => { plus.io.xxx(..., resolve, reject) })` 包装为 Promise（参照 `useShare.js` 中 `copyStaticToDoc` 的 promisify 模式）。`uni.getFileSystemManager` 在 APP-PLUS 也可用且支持 Promise，优先使用；仅在需要递归删目录等 `uni.getFileSystemManager` 不支持的操作时走 `plus.io`。

### 6.5.1 App.vue 集成方式（Options API）

**App.vue 当前使用 Options API**（`export default { … }`），与项目中 composable（`<script setup>`）风格不同，但集成方式很简单 —— 直接 `import` + 在生命周期方法内调用即可，不需要 ref/wrap 等：

```js
// App.vue <script> 顶部
import preloadApi from '@/utils/preloadApi'

export default {
  onLaunch: function() {
    // ... 现有逻辑 ...
    preloadApi.warmStartup()  // 新增：启动期预热
  },
  onShow: function() {
    // ... 现有逻辑 ...
    preloadApi.warmIdle()     // 新增：idle 预拉（幂等，多次调用安全）
  },
  // ...
}
```

**无需将 App.vue 迁移到 Composition API**。`import` + 直接函数调用即可覆盖所有集成需求。

### 6.6 与 `useBackgroundRefresh` 的协作

两个模块**完全独立**、可并存：
- `useBackgroundRefresh(refreshFn)`：从后台切回时调 `refreshFn`（通常是重新拉当前页数据）
- `preloadApi.invalidate(prefix)`：手动失效缓存

业务页面常用组合：
```js
useBackgroundRefresh(() => {
  // 从后台切回时，强制刷当前页 + 失效短期缓存
  preloadApi.invalidate('ranking.hot')
  preloadApi.invalidatePrefix('asset.')
  refresh(true)  // usePreload 的 refresh
})
```

---

## 7. 内存与文件缓存上限

内存泄漏防护 + 文件缓存容量控制（文件系统远比 uni.storage 大）：

| 限制 | 值 | 处理 |
| --- | --- | --- |
| 单 key 数据体积 | > 1024 KB | 只写内存，不写文件（即使 config 里设了 `persistence: 'file'` 也会降级，避免单 JSON 文件过大拖慢 I/O）。不报错、静默降级，下次冷启动走 fetch |
| 总内存条目数 | > 100 条 | 按 LRU 淘汰 |
| 总文件缓存容量 | > 50 MB | 按插入顺序淘汰最旧文件（FIFO） |

### 7.1 LRU 实现约束

**内存与文件缓存淘汰策略不同**：

| 层 | 淘汰策略 | 触发时机 |
| --- | --- | --- |
| 内存 | LRU（最近访问优先） | 命中时重排（delete + set） |
| 文件缓存 | FIFO（最早写入优先） | 不在读时重排；淘汰时一次性 scan 目录，按文件 `stat.mtime` 排序找出最旧文件删除。文件数不大（≤ 几百），scan 开销可接受。也可维护一个轻量 `_index.json` 记录插入顺序，但 scan 方式更简单更健壮 |

JS `Map` 的迭代顺序是**插入顺序**而非**访问顺序**。内存 LRU 正确实现：

```js
// 命中访问时：删除再插入，重排到最新
function touchLRU(map, k, v) {
  if (map.has(k)) map.delete(k)
  map.set(k, v)
  if (map.size > MAX_ENTRIES) {
    // Map 迭代顺序 = 插入顺序，最久未访问的是第一个
    const oldestKey = map.keys().next().value
    map.delete(oldestKey)
  }
}
```

### 7.2 并发粒度

`defaults.concurrency`（默认 4）按 **scheduler 入口粒度**生效：

| 入口 | 并发限制 |
| --- | --- |
| `warmStartup()` | 整个 startup 数组最多 4 并发 |
| `warmIdle()` | 整个 idle 数组最多 4 并发 |
| `prefetchFor(targetPath)` | 单目标页内的多个 key 最多 4 并发 |

实现：`scheduler.js` 用一个简单的 semaphore（计数器 + 等待队列）控制并发。

### 7.3 idle 调度触发点与 App 端 fallback

`warmIdle()` 调用点：**`App.vue` 的 `onShow` 中**（每次从后台回前台都跑一次；首次冷启动 onLaunch 之后 onShow 也会触发，等价于"首屏渲染完后"）。

**首次冷启动 onLaunch→onShow 连续触发**：onLaunch 里 `warmStartup` 跑 startup 清单，紧接着 onShow 里 `warmIdle` 跑 idle 清单。如果 idle 清单与 startup 清单有重叠 key，`run` 的"查内存 → 未过期则跳过"机制自动处理（run 看到 startup 已写入的未过期缓存直接返回，不重拉）。如果无重叠，两者并行进行，composable 在首次渲染时可能受益于 startup 的预热而 idle 还在后台跑。

**去重 / 防抖**：warmIdle 必须**幂等**——同一进程内多次调用，对已在 in-flight 的 key 直接跳过、不重发；对已在内存且未过期的 key 也跳过（靠 `run` 语义）。理由：用户高频切前后台会触发多次 onShow，warmIdle 不应每次都发起新请求。

App 端 fallback（`#ifdef APP-PLUS`）：uniapp App 端**没有** `requestIdleCallback`，scheduler 内部统一用：
```js
const idle = typeof requestIdleCallback === 'function'
  ? requestIdleCallback
  : (cb) => setTimeout(() => cb({ didTimeout: false, timeRemaining: () => 50 }), 0)
```

---

## 8. 测试策略

### 8.1 层级与覆盖目标

| 层 | 范围 | 工具 |
| --- | --- | --- |
| 核心单元测试 | `core.js` 的 run/get/invalidate/并发去重/LRU/TTL | 手动 mock `uni.*` / `plus.io` |
| 文件缓存适配器测试 | 目录创建 / 读写条目 / 清空逻辑 / 大小阈值 | 同上（mock `plus.io` File API） |
| navigate 测试 | wrappedNavigateTo 命中/未命中均正确 | mock `uni.navigateTo` |
| composable 测试 | `usePreload` 暴露的响应式 state 正确性 | mock core |
| 集成冒烟 | App.vue 启动预热、wrappedNavigateTo 跳转 | HBuilderX 真机 |

### 8.2 验收清单

- [ ] `preloadApi.run` / `get` / `invalidate*` 单测通过
- [ ] wrappedNavigateTo 命中/未命中均通过单测
- [ ] usePreload composable 暴露响应式 state 通过单测
- [ ] 401 / 业务码 7、16 被 `_swallowAuth` 正确吞掉（核心 + navigate + composable 各 1 个 case）
- [ ] query string 含 `encodeURIComponent` 字符（如中文）解析正确
- [ ] App.vue 真机：onLaunch 后立即访问 startup 项 key，命中内存缓存
- [ ] wrappedNavigateTo 真机：列表页跳详情页，详情页 onLoad 时立即命中预拉缓存（loading 闪烁 < 50ms）
- [ ] 登出后 `_doc/preload/{userId}/` 目录被删除
- [ ] LRU 淘汰边界：
  - 塞 100 个 key：第 1 个**不**被淘汰
  - 塞 101 个 key：第 1 个被淘汰
- [ ] warmIdle 幂等：同进程内连续调 3 次，fetcher 只被调用 1 次
- [ ] 用户切换（onSwitchUser）：me.* 前缀全失效、oldUser 的文件缓存目录已删除、newUser 缓存不受影响

### 8.3 调试与可观测性

**开发者工具**（`import.meta.env.DEV` 时启用）：

```js
// 实时查看缓存命中率、top-N hot keys
window.__PRELOAD_DEBUG__ = {
  dumpMemory: () => Array.from(memoryMap.entries()).map(([k, v]) => ({
    key: k, age: Date.now() - v.ts, ttl: v.ttl, persistence: v.persistence
  })),
  stats: () => ({
    hits: hitCount, misses: missCount, memorySize: memoryMap.size, fileCacheBytes: totalFileCacheBytes
  }),
  // 一键 dump 所有 key + inFlight 当前几条
  all: () => ({ ... }, inFlight: Array.from(inFlightMap.keys()))
}
```

**日志规范**（生产环境统一前缀 `[preload]`）：
- 缓存命中：不记日志（高频、无意义）
- 缓存过期 / 未命中：不记日志（正常路径）
- fetch 完成：`console.log('[preload] fetch done:', key, elapsedMs)`
- fetch 失败（swallow）：`console.warn('[preload] fetch fail (swallowed):', key, err.message)`
- fetch 失败（throw）：不记日志（业务方自行处理）
- 清理事件：不记日志（正常路径）
- LRU 淘汰：`console.log('[preload] LRU evict:', oldestKey)`

---

## 9. 风险与缓解

| 风险 | 缓解 |
| --- | --- |
| 401 链路被 `request()` 同步 reLaunch 中断冷启动 | `core.run / get` 通过 `_swallowAuth` swallow：业务码 `code === 7 \|\| 16` **或** message 含 "登录已过期"（HTTP 401 走此路径，见 §5） |
| 用户隔离在登出 / 切账号时混乱 | `clearUser / clearForUser / invalidateAll` 三层职责严格分离（见 §6.3） |
| `wrappedNavigateTo` 全量替换回归风险 | 严格方案 A：预拉 fire-and-forget 不 await（见 §2.5） |
| 预拉时机太早导致请求用户未登录 | 401 swallow（§5）；启动清单里依赖登录态的 key 必须 `silent=true` |
| 启动期批量预拉阻塞冷启动 | `startup` 全部 `silent=true`、并发受 `concurrency` 控制、超时 `timeout` |
| 文件缓存体积膨胀 | 1024 KB / 100 条 / 50 MB 三层上限；登出 `clearUser` 删除目录 |
| `usePreload` 在非 `setup()` 上下文误用 | composable 内部 `getCurrentInstance()` 检查 + 警告 |
| 与 `avatarCache` / `screen-cache` 命名冲突 | 文件缓存统一放在 `_doc/preload/{userId}/` 目录下，与 uni.storage 隔离（见 §6.5） |
| 与 `utils/api.js` 的 mock import 耦合（bundle 体积） | `preload.config.js` 的 fetcher 引用按需 import；必要时在 vite 分包配置里隔离 |
| `JSON.stringify(params)` key 顺序敏感导致命中率下降 | 实现里对 params key 排序后再 stringify（见 §4.2 hash 约定） |

---

## 10. 实施清单（落到 writing-plans 阶段再细化）

0. `frontend/utils/api.js` — `request()` 返回的 Promise 上挂 `.abort()` 方法（~8 行改动：捕获 requestTask + 挂 abort() + fail 中识别 `_aborted` 标记，详见 §4.4.1）
1. `frontend/utils/preloadApi/storage.js`（plus.io 回调 promisify 处理，详见 §6.5）
2. `frontend/utils/preloadApi/core.js`
3. `frontend/utils/preloadApi/scheduler.js`
4. `frontend/utils/preloadApi/navigate.js`
5. `frontend/utils/preloadApi/index.js`
6. `frontend/composables/usePreload.js`
7. `frontend/config/preload.config.js`（初始内容，含 castlove.config / me.profile / ranking.hot / asset-detail / activity-detail）
8. `frontend/App.vue`（Options API 集成：import + onLaunch 调用 warmStartup() + onShow 调用 warmIdle()，详见 §6.5.1）
9. `frontend/store/modules/user.js`（SET_USER_INFO / CLEAR_AUTH mutation patch 注入 preload 缓存失效，详见 §6.5）
10. `frontend/utils/preloadApi/__tests__/`（核心 + 文件缓存适配器 + navigate + composable）
11. README 文档片段（放在 `frontend/utils/preloadApi/README.md`，供业务开发查阅 config schema + API 速查表）