提示词保存

frontend/api/README.md

@@ -0,0 +1,129 @@
+# Mono 级别 API 架构
+
+## 📁 目录结构
+
+```
+frontend/api/
+├── axios/
+│   └── client.js          # Mono 级别的 C 端 Axios 实例
+├── services/
+│   ├── tikhub.js          # TikHub API 服务
+│   └── index.js           # 服务统一导出
+└── README.md              # 本文档
+```
+
+## 🎯 设计理念
+
+### 1. 分层清晰
+- **Mono 级别** (`frontend/api/`): 可在 monorepo 中所有应用复用的代码
+- **应用级别** (`frontend/app/web-gold/src/api/`): 应用特定的 API 封装
+
+### 2. 模块化设计
+- **Axios 实例**: 统一的 HTTP 客户端配置
+- **API 服务**: 按功能模块组织（如 `TikHubService`）
+- **Hooks**: 直接使用服务，无需全局注入
+
+### 3. 人类可读
+- 清晰的命名和注释
+- 直观的导入路径
+- 易于理解和维护
+
+## 🚀 使用方式
+
+### 在 Mono 级别使用
+
+```javascript
+// 直接使用服务
+import { TikHubService } from '@gold/api/services'
+
+const result = await TikHubService.videoToCharacters({
+  fileLinkList: ['https://example.com/audio.mp3']
+})
+```
+
+### 在应用层使用
+
+```javascript
+// 使用应用层封装的服务
+import { CommonService } from '@/api/common'
+
+const result = await CommonService.videoToCharacters({
+  fileLinkList: ['https://example.com/audio.mp3']
+})
+```
+
+### 在 Hooks 中使用
+
+```typescript
+// useVoiceText 直接使用 TikHubService，无需配置
+import useVoiceText from '@gold/hooks/web/useVoiceText'
+
+const { getVoiceText } = useVoiceText()
+const transcriptions = await getVoiceText([
+  { audio_url: 'https://example.com/audio.mp3' }
+])
+```
+
+## 📦 添加新的 API 服务
+
+### 1. 创建服务文件
+
+```javascript
+// frontend/api/services/my-service.js
+import { clientAxios } from '@gold/api/axios/client'
+import { API_BASE } from '@gold/config/api'
+
+const BASE_URL = API_BASE.MY_SERVICE || ''
+
+export const MyService = {
+  async getData(params) {
+    return await clientAxios.get(`${BASE_URL}/data`, { params })
+  },
+  
+  async createData(data) {
+    return await clientAxios.post(`${BASE_URL}/data`, data)
+  },
+}
+
+export default MyService
+```
+
+### 2. 导出服务
+
+```javascript
+// frontend/api/services/index.js
+export { TikHubService } from './tikhub'
+export { MyService } from './my-service'
+```
+
+### 3. 使用服务
+
+```javascript
+import { MyService } from '@gold/api/services'
+
+const data = await MyService.getData({ id: 1 })
+```
+
+## 🔧 自定义 Axios 实例
+
+如果需要创建自定义的 Axios 实例：
+
+```javascript
+import { createClientAxios } from '@gold/api/axios/client'
+
+const customAxios = createClientAxios({
+  baseURL: '/custom-api',
+  timeout: 60000,
+  on401: () => {
+    // 自定义 401 处理
+  }
+})
+```
+
+## 📝 注意事项
+
+1. **Mono 级别代码**应该保持通用，不依赖特定应用的逻辑
+2. **应用层代码**可以依赖应用特定的 store、组件等
+3. **服务模块**应该按功能划分，保持单一职责
+4. **Axios 实例**统一管理，避免重复配置
+