# preloadApi — API 预加载模块

## 快速开始

### 1. 在页面中使用缓存数据

```vue
<script setup>
import { usePreload } from '@/composables/usePreload'

const { data, loading, error, refresh } = usePreload('asset.detail', { id: route.params.id })
</script>

<template>
  <view v-if="data">{{ data.name }}</view>
  <view v-else-if="loading">加载中...</view>
  <view v-else-if="error">加载失败: {{ error.message }}</view>
</template>
```

### 2. 手动失效缓存

```js
import { getPreloadApi } from '@/utils/preloadApi/index'

const api = getPreloadApi()

// 失效单个 key
api.invalidate('ranking.hot')

// 失效某个前缀的所有 key
api.invalidatePrefix('asset.')

// 清空全部内存缓存
api.invalidateAll()
```

### 3. 添加新的预拉配置

在 `frontend/config/preload.config.js` 中：

```js
pages: {
  '/pages/new-page/new-page': [
    { key: 'new.data', fetcher: (params) => getNewDataApi(params.id) }
  ]
}
```

### 4. 替换页面跳转

```js
// 旧写法
uni.navigateTo({ url: '/pages/detail/detail?id=123' })

// 新写法（自动触发预拉）
import { getPreloadApi } from '@/utils/preloadApi/index'
const api = getPreloadApi()
api.navigateTo({ url: '/pages/detail/detail?id=123' })
```

## API 速查

| 方法 | 说明 |
|------|------|
| `preloadApi.run(key, params?)` | 触发预拉（fire-and-forget），不返回数据 |
| `preloadApi.get(key, params?)` | 读缓存，未命中则拉取 |
| `preloadApi.invalidate(key, params?)` | 失效单个 key（内存） |
| `preloadApi.invalidatePrefix(prefix)` | 失效前缀匹配的所有 key（内存） |
| `preloadApi.invalidateAll()` | 清空全部内存缓存 |
| `preloadApi.clearUser(userId)` | 登出：清空内存 + 删文件缓存目录 |
| `preloadApi.navigateTo(opts)` | 替代 uni.navigateTo |
| `preloadApi.switchTab(opts)` | 替代 uni.switchTab |
| `preloadApi.reLaunch(opts)` | 替代 uni.reLaunch |

## 配置字段

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `key` | string | (必填) | 逻辑 key，业务引用缓存的唯一标识 |
| `fetcher` | (params) => Promise | (必填) | 请求函数 |
| `ttl` | number | 300000 | 缓存有效期 (ms) |
| `persistence` | 'memory'\|'file' | 'memory' | 缓存存储方式 |
| `timeout` | number | 10000 | 单接口超时 (ms) |
| `silent` | boolean | true | 失败是否静默 |