sionrui/frontend/hooks/web/README.md

# 公共 Hooks 模块

此目录包含可在 monorepo 各个应用中复用的 Vue Composition API Hooks。

## 📁 目录结构

```
hooks/web/
├── useCache.js      # 缓存管理 Hook
├── useUserInfo.js   # 用户信息获取 Hook
└── useVoiceText.ts  # 语音文本处理 Hook（已抽离为公共模块）
```

## 🚀 使用方式

### useUserInfo Hook

获取用户信息的公共 Hook，可在各个应用中复用。

#### 基础用法

```javascript
import { useUserInfo } from '@gold/hooks/web/useUserInfo'
import { getToken } from '@/utils/token-manager'

// 在组件中使用
const { fetchUserInfo, loading, error, userInfo } = useUserInfo({
  getToken, // 传入获取 token 的函数
})

// 获取用户信息
await fetchUserInfo()
```

#### 便捷函数

如果只需要获取一次用户信息，可以使用便捷函数：

```javascript
import { getUserInfo } from '@gold/hooks/web/useUserInfo'
import { getToken } from '@/utils/token-manager'

// 直接获取用户信息
const userInfo = await getUserInfo({
  getToken,
})
```

#### 自定义配置

```javascript
const { fetchUserInfo } = useUserInfo({
  baseUrl: '/custom-api/member', // 自定义 API 基础 URL
  getToken: () => {
    // 自定义获取 token 的逻辑
    return localStorage.getItem('token')
  },
})
```

## 📝 API 说明

### useUserInfo(options)

**参数：**
- `options.baseUrl` (string, 可选): API 基础 URL，默认使用 `API_BASE.APP_MEMBER`
- `options.getToken` (Function, 可选): 获取 token 的函数

**返回值：**
- `fetchUserInfo()` (Function): 获取用户信息的异步函数
- `loading` (Ref<boolean>): 加载状态
- `error` (Ref<Error | null>): 错误信息
- `userInfo` (Ref<Object | null>): 用户信息数据

### getUserInfo(options)

便捷函数，直接返回用户信息对象。

**参数：** 同 `useUserInfo`

**返回值：** `Promise<Object>` 用户信息对象

## 🔄 在 Store 中使用

```javascript
import { defineStore } from 'pinia'
import { getUserInfo } from '@gold/hooks/web/useUserInfo'
import { getToken } from '@/utils/token-manager'

export const useUserStore = defineStore('user', () => {
  const userInfo = ref(null)
  
  async function fetchUserInfo() {
    try {
      const data = await getUserInfo({ getToken })
      userInfo.value = data
    } catch (error) {
      console.error('获取用户信息失败:', error)
    }
  }
  
  return { userInfo, fetchUserInfo }
})
```

### useVoiceText Hook

语音文本转换 Hook，将音频文件转换为文本转录。

#### 使用方式

```javascript
import useVoiceText from '@gold/hooks/web/useVoiceText'
import type { AudioItem } from '@gold/config/types'

// 在组件中使用（无需任何初始化）
const { getVoiceText } = useVoiceText()

const audioList: AudioItem[] = [
  { audio_url: 'https://example.com/audio.mp3' }
]

const transcriptions = await getVoiceText(audioList)
// transcriptions: [{ key: 'url', value: 'transcribed text', audio_url: '...' }]
```

#### 说明

`useVoiceText` Hook 直接使用 mono 级别的 `TikHubService`，无需任何初始化或配置。
所有 API 服务都在 `@gold/api/services` 中统一管理，开箱即用。

#### 类型定义

```typescript
import type { 
  AudioItem, 
  TranscriptionResult 
} from '@gold/config/types'
```

## 📦 依赖

- `vue`: Vue 3 Composition API
- `axios`: HTTP 请求库（用于 useUserInfo）
- `@gold/config/api`: 公共 API 配置
- `@gold/api/services`: Mono 级别的 API 服务
- `@gold/api/axios/client`: Mono 级别的 Axios 客户端
- `@gold/config/types`: 公共类型定义

## 🔧 配置要求

确保在应用的 `vite.config.js` 中配置了 `@gold` 别名：

```javascript
resolve: {
  alias: {
    '@gold': fileURLToPath(new URL('../../', import.meta.url))
  }
}
```