From 7a5a9bcacf237dfe55404835e744b1e8f106d696 Mon Sep 17 00:00:00 2001
From: xiaoxia <dev@xiaoxiajianji.com>
Date: Sun, 26 Jul 2026 17:19:40 +0800
Subject: [PATCH] =?UTF-8?q?refactor(api):=20=E6=8B=86=E5=88=86=20bgm/proje?=
 =?UTF-8?q?cts/tags=20=E4=B8=BA=E7=9B=AE=E5=BD=95=E7=BB=93=E6=9E=84?=
 =?UTF-8?q?=EF=BC=88API=20=E5=B1=82=E5=85=A8=E9=9D=A2=E7=9B=AE=E5=BD=95?=
 =?UTF-8?q?=E5=8C=96=E6=94=B6=E5=B0=BE=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

批量拆分三个小 API 文件：
- bgm.ts (68行) → types/constants/bgm/index
- projects.ts (60行) → types/utils/projects/index
- tags.ts (40行) → types/tags/index

全部保持 @/api/xxx 导入路径向后兼容。

至此前端 API 层所有单文件模块全部目录化，共 13 个 API 模块统一结构。
---
 apps/web/src/api/bgm.ts                     | 68 ---------------------
 apps/web/src/api/bgm/bgm.ts                 | 14 +++++
 apps/web/src/api/bgm/constants.ts           | 14 +++++
 apps/web/src/api/bgm/index.ts               | 13 ++++
 apps/web/src/api/bgm/types.ts               | 43 +++++++++++++
 apps/web/src/api/projects/index.ts          | 13 ++++
 apps/web/src/api/{ => projects}/projects.ts | 30 ++-------
 apps/web/src/api/projects/types.ts          | 21 +++++++
 apps/web/src/api/projects/utils.ts          | 10 +++
 apps/web/src/api/tags/index.ts              | 10 +++
 apps/web/src/api/{ => tags}/tags.ts         | 12 +---
 apps/web/src/api/tags/types.ts              | 10 +++
 12 files changed, 155 insertions(+), 103 deletions(-)
 delete mode 100644 apps/web/src/api/bgm.ts
 create mode 100644 apps/web/src/api/bgm/bgm.ts
 create mode 100644 apps/web/src/api/bgm/constants.ts
 create mode 100644 apps/web/src/api/bgm/index.ts
 create mode 100644 apps/web/src/api/bgm/types.ts
 create mode 100644 apps/web/src/api/projects/index.ts
 rename apps/web/src/api/{ => projects}/projects.ts (64%)
 create mode 100644 apps/web/src/api/projects/types.ts
 create mode 100644 apps/web/src/api/projects/utils.ts
 create mode 100644 apps/web/src/api/tags/index.ts
 rename apps/web/src/api/{ => tags}/tags.ts (86%)
 create mode 100644 apps/web/src/api/tags/types.ts

diff --git a/apps/web/src/api/bgm.ts b/apps/web/src/api/bgm.ts
deleted file mode 100644
index f56af3a54..000000000
--- a/apps/web/src/api/bgm.ts
+++ /dev/null
@@ -1,68 +0,0 @@
-/**
- * BGM 预设音乐 API
- * 对接后端 BGM 混音能力：预设列表查询（按风格分类 + 关键词搜索）
- */
-import apiClient from "./client"
-
-/* ──────────── 类型 ──────────── */
-
-/** BGM 风格分类 */
-export type BgmCategory = "轻快" | "治愈" | "科技" | "电商"
-
-/** BGM 预设项 */
-export interface BgmPreset {
-  id: string
-  name: string
-  category: BgmCategory
-  /** 音频文件 URL */
-  url: string
-  /** 时长（秒） */
-  duration: number
-  /** 关键词标签 */
-  tags: string[]
-  /** 封面图 URL */
-  cover_url?: string
-}
-
-/** BGM 预设列表查询参数 */
-export interface BgmPresetsQuery {
-  category?: BgmCategory | string
-  keyword?: string
-}
-
-/** BGM 混音配置（嵌入模板） */
-export interface BgmMixConfig {
-  /** 是否启用 BGM */
-  enabled: boolean
-  /** 选中的 BGM ID */
-  music_id: string
-  /** BGM 音量 0-100 */
-  volume: number
-  /** 淡入时长（秒） 0-3 */
-  fade_in: number
-  /** 淡出时长（秒） 0-3 */
-  fade_out: number
-  /** 人声闪避（sidechain） */
-  voice_dodge: boolean
-}
-
-/** 默认 BGM 混音配置 */
-export const DEFAULT_BGM_MIX_CONFIG: BgmMixConfig = {
-  enabled: false,
-  music_id: "",
-  volume: 50,
-  fade_in: 0.5,
-  fade_out: 0.5,
-  voice_dodge: true,
-}
-
-/* ──────────── API ──────────── */
-
-/** 获取 BGM 预设列表 */
-export const getBgmPresets = async (params?: BgmPresetsQuery): Promise<BgmPreset[]> => {
-  const searchParams: Record<string, string> = {}
-  if (params?.category) searchParams.category = params.category
-  if (params?.keyword) searchParams.keyword = params.keyword
-  const res = await apiClient.get("/bgm/presets", { params: searchParams })
-  return res.data?.data ?? res.data ?? []
-}
diff --git a/apps/web/src/api/bgm/bgm.ts b/apps/web/src/api/bgm/bgm.ts
new file mode 100644
index 000000000..d9dc58e62
--- /dev/null
+++ b/apps/web/src/api/bgm/bgm.ts
@@ -0,0 +1,14 @@
+/**
+ * BGM 预设音乐 API 函数
+ */
+import apiClient from "../client"
+import type { BgmPreset, BgmPresetsQuery } from "./types"
+
+/** 获取 BGM 预设列表 */
+export const getBgmPresets = async (params?: BgmPresetsQuery): Promise<BgmPreset[]> => {
+  const searchParams: Record<string, string> = {}
+  if (params?.category) searchParams.category = params.category
+  if (params?.keyword) searchParams.keyword = params.keyword
+  const res = await apiClient.get("/bgm/presets", { params: searchParams })
+  return res.data?.data ?? res.data ?? []
+}
diff --git a/apps/web/src/api/bgm/constants.ts b/apps/web/src/api/bgm/constants.ts
new file mode 100644
index 000000000..8b3c8cb55
--- /dev/null
+++ b/apps/web/src/api/bgm/constants.ts
@@ -0,0 +1,14 @@
+/**
+ * BGM 相关常量
+ */
+import type { BgmMixConfig } from "./types"
+
+/** 默认 BGM 混音配置 */
+export const DEFAULT_BGM_MIX_CONFIG: BgmMixConfig = {
+  enabled: false,
+  music_id: "",
+  volume: 50,
+  fade_in: 0.5,
+  fade_out: 0.5,
+  voice_dodge: true,
+}
diff --git a/apps/web/src/api/bgm/index.ts b/apps/web/src/api/bgm/index.ts
new file mode 100644
index 000000000..ad23ca565
--- /dev/null
+++ b/apps/web/src/api/bgm/index.ts
@@ -0,0 +1,13 @@
+/**
+ * BGM API — 目录化入口
+ * 保持与原 bgm.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type { BgmCategory, BgmPreset, BgmPresetsQuery, BgmMixConfig } from "./types"
+
+// 常量
+export { DEFAULT_BGM_MIX_CONFIG } from "./constants"
+
+// API 函数
+export { getBgmPresets } from "./bgm"
diff --git a/apps/web/src/api/bgm/types.ts b/apps/web/src/api/bgm/types.ts
new file mode 100644
index 000000000..4a14bac17
--- /dev/null
+++ b/apps/web/src/api/bgm/types.ts
@@ -0,0 +1,43 @@
+/**
+ * BGM 相关类型定义
+ */
+
+/** BGM 风格分类 */
+export type BgmCategory = "轻快" | "治愈" | "科技" | "电商"
+
+/** BGM 预设项 */
+export interface BgmPreset {
+  id: string
+  name: string
+  category: BgmCategory
+  /** 音频文件 URL */
+  url: string
+  /** 时长（秒） */
+  duration: number
+  /** 关键词标签 */
+  tags: string[]
+  /** 封面图 URL */
+  cover_url?: string
+}
+
+/** BGM 预设列表查询参数 */
+export interface BgmPresetsQuery {
+  category?: BgmCategory | string
+  keyword?: string
+}
+
+/** BGM 混音配置（嵌入模板） */
+export interface BgmMixConfig {
+  /** 是否启用 BGM */
+  enabled: boolean
+  /** 选中的 BGM ID */
+  music_id: string
+  /** BGM 音量 0-100 */
+  volume: number
+  /** 淡入时长（秒） 0-3 */
+  fade_in: number
+  /** 淡出时长（秒） 0-3 */
+  fade_out: number
+  /** 人声闪避（sidechain） */
+  voice_dodge: boolean
+}
diff --git a/apps/web/src/api/projects/index.ts b/apps/web/src/api/projects/index.ts
new file mode 100644
index 000000000..83c85af3f
--- /dev/null
+++ b/apps/web/src/api/projects/index.ts
@@ -0,0 +1,13 @@
+/**
+ * 项目 API — 目录化入口
+ * 保持与原 projects.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type { ProjectItem, BackendProjectResponse, BackendListProjectsResponse } from "./types"
+
+// 工具函数
+export { toProjectItem } from "./utils"
+
+// API 函数
+export { getProjects, createProject, getOrCreateDefaultProject } from "./projects"
diff --git a/apps/web/src/api/projects.ts b/apps/web/src/api/projects/projects.ts
similarity index 64%
rename from apps/web/src/api/projects.ts
rename to apps/web/src/api/projects/projects.ts
index 45fca2901..a5fd66568 100644
--- a/apps/web/src/api/projects.ts
+++ b/apps/web/src/api/projects/projects.ts
@@ -1,32 +1,10 @@
 /**
- * 项目相关 API
+ * 项目相关 API 函数
  * 素材库需要 project_id，前端自动管理默认项目
  */
-import apiClient from "./client"
-
-export interface ProjectItem {
-  id: string
-  name: string
-  description: string
-}
-
-/** 后端 ProjectResponse 只返回 id, name, description */
-interface BackendProjectResponse {
-  id: string
-  name: string
-  description: string
-}
-
-/** 后端 ListProjectsResponse 返回 { items: [...] } */
-interface BackendListProjectsResponse {
-  items: BackendProjectResponse[]
-}
-
-const toProjectItem = (item: BackendProjectResponse): ProjectItem => ({
-  id: item.id,
-  name: item.name,
-  description: item.description,
-})
+import apiClient from "../client"
+import type { BackendListProjectsResponse, BackendProjectResponse, ProjectItem } from "./types"
+import { toProjectItem } from "./utils"
 
 /** 获取当前用户的项目列表 */
 export const getProjects = async (): Promise<ProjectItem[]> => {
diff --git a/apps/web/src/api/projects/types.ts b/apps/web/src/api/projects/types.ts
new file mode 100644
index 000000000..f2236016b
--- /dev/null
+++ b/apps/web/src/api/projects/types.ts
@@ -0,0 +1,21 @@
+/**
+ * 项目相关类型定义
+ */
+
+export interface ProjectItem {
+  id: string
+  name: string
+  description: string
+}
+
+/** 后端 ProjectResponse 只返回 id, name, description */
+export interface BackendProjectResponse {
+  id: string
+  name: string
+  description: string
+}
+
+/** 后端 ListProjectsResponse 返回 { items: [...] } */
+export interface BackendListProjectsResponse {
+  items: BackendProjectResponse[]
+}
diff --git a/apps/web/src/api/projects/utils.ts b/apps/web/src/api/projects/utils.ts
new file mode 100644
index 000000000..342e88637
--- /dev/null
+++ b/apps/web/src/api/projects/utils.ts
@@ -0,0 +1,10 @@
+/**
+ * 项目相关工具函数
+ */
+import type { BackendProjectResponse, ProjectItem } from "./types"
+
+export const toProjectItem = (item: BackendProjectResponse): ProjectItem => ({
+  id: item.id,
+  name: item.name,
+  description: item.description,
+})
diff --git a/apps/web/src/api/tags/index.ts b/apps/web/src/api/tags/index.ts
new file mode 100644
index 000000000..cb84c7b0d
--- /dev/null
+++ b/apps/web/src/api/tags/index.ts
@@ -0,0 +1,10 @@
+/**
+ * 标签 API — 目录化入口
+ * 保持与原 tags.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type { TagItem } from "./types"
+
+// API 函数
+export { getTags, createTag, deleteTag, tagAsset, untagAsset } from "./tags"
diff --git a/apps/web/src/api/tags.ts b/apps/web/src/api/tags/tags.ts
similarity index 86%
rename from apps/web/src/api/tags.ts
rename to apps/web/src/api/tags/tags.ts
index 4e6c812d0..b5e1f442f 100644
--- a/apps/web/src/api/tags.ts
+++ b/apps/web/src/api/tags/tags.ts
@@ -1,15 +1,9 @@
 /**
- * 标签 CRUD API
+ * 标签 CRUD API 函数
  * P3 标签体系：对接后端标签表
  */
-import apiClient from "./client"
-
-export interface TagItem {
-  id: string
-  name: string
-  created_at?: string
-  usage_count?: number
-}
+import apiClient from "../client"
+import type { TagItem } from "./types"
 
 /** 获取当前用户所有标签 */
 export const getTags = async (): Promise<TagItem[]> => {
diff --git a/apps/web/src/api/tags/types.ts b/apps/web/src/api/tags/types.ts
new file mode 100644
index 000000000..7dc38bdf0
--- /dev/null
+++ b/apps/web/src/api/tags/types.ts
@@ -0,0 +1,10 @@
+/**
+ * 标签相关类型定义
+ */
+
+export interface TagItem {
+  id: string
+  name: string
+  created_at?: string
+  usage_count?: number
+}
-- 
2.54.0