meijiaka-zy/docs/naming-consistency-report.md

项目名词统一梳理报告

本文档梳理了美家卡智影项目中所有核心功能在用户界面和开发代码中的命名现状，识别出不一致问题，并提出统一标准方案。

---

一、核心功能总览（10个业务域）

#	source_type	用户界面名称	开发层关键命名	计费模式
1	script	脚本生成	ScriptCreation.tsx, scriptApi	固定 5
2	polish	文案润色	scriptApi.polish, polish_content	固定 1
3	title	标题生成	scriptApi.generateTitle, generate_title	固定 1
4	tts	音频合成 / 配音	VoiceDubbing.tsx, synthesizeTTS, voice.ts	按秒计费
5	voice_clone	声音复刻 / 声音克隆	VoiceMaterialLibrary.tsx, voice.ts 声音克隆 API	固定 200
6	video	视频生成 / 对口型	VideoGeneration.tsx, vidu.ts, lipSync	按秒计费
7	caption	字幕生成	createTask('subtitle', ...)	免费
8	subtitle_burn	字幕烧录	SubtitleBurning.tsx, subtitle_burn	固定 2
9	cover_design	封面设计 / 封面制作 / 封面生成	CoverDesign.tsx, cover_design	固定 2
10	compose	压制成片 / 视频合成	VideoComposite.tsx, videoComposite.ts, videoCompose.ts, video_processing.rs, video_compose.rs	固定 5

---

二、问题分类

A类：后端分类映射错误（数据层污染）

文件：python-api/app/services/point_service.py 中的 _CATEGORY_MAP

source_type	当前映射	正确映射	影响
polish	"脚本生成" ❌	"文案润色"	用户流水显示错误分类
title	"脚本生成" ❌	"标题生成"	用户流水显示错误分类
voice_clone	"音频合成" ❌	"声音复刻"	用户流水显示错误分类

严重程度：高。这会导致积分明细中用户无法区分自己到底消费了什么服务。

---

B类：同一功能多词混用（用户层混乱）

B1. TTS / 音频合成 / 配音

位置	用词
步骤标签（Step 2）	音频合成
页面文件名	VoiceDubbing.tsx
页面注释	"语音配音页面"
进度弹窗	"生成配音"、"配音已就绪"
按钮文案	"生成配音"
字段标签	"配音文案"
错误提示	"请返回第二步重新生成配音"
TermsModal	"AI 配音（TTS）"
API 模块注释	"TTS 合成"
积分明细（UsageDetail）筛选	"音频合成"

问题：步骤标签用"音频合成"，但页面内全部用"配音"。用户从步骤导航点进来，看到的内容全是"配音"，会产生"这是同一个功能吗？"的困惑。

B2. 封面设计 / 封面制作 / 封面生成

位置	用词
步骤标签（Step 5）	封面制作
页面文件名	CoverDesign.tsx
页面注释	"封面制作页面"
进度弹窗	"封面生成"、"封面生成完成"
积分 description	"封面设计"
按钮文案	"立即生成封面图"
预览区标题	"封面预览"

问题："制作"、"设计"、"生成"三个词混用。

B3. 声音复刻 / 声音克隆

位置	用词
侧边栏 Sidebar	声音克隆
积分明细 UsageDetail	声音复刻
API 模块注释（voice.ts）	"声音克隆 API"
页面标题（VoiceMaterialLibrary.tsx）	"声音克隆"

问题：同一功能两个不同的中文名称。

B4. 视频生成 / 对口型

位置	用词
步骤标签（Step 3）	视频生成
积分明细	视频生成
技术实现注释/日志	"对口型任务"、"对口型视频"、"对口型处理中..."
错误提示	"对口型任务失败"、"对口型任务超时"
字段名	lipSyncTaskId, lipSyncVideoPath

问题：技术实现术语"对口型"泄露到用户可见文案中。

---

C类：开发命名与业务命名不匹配

业务名称	开发命名现状	问题
压制成片	compose (source_type) / composite (API 模块名) / videoComposite.ts / videoCompose.ts / video_processing.rs / video_compose.rs / VideoComposite.tsx	同一业务 5 种不同命名，开发人员无法一眼看出这些代码对应同一个功能
音频合成	tts (source_type) / VoiceDubbing.tsx (页面) / synthesizeTTS (函数) / voice.ts (API 模块)	页面文件名 VoiceDubbing 与步骤名"音频合成"语义不匹配
文案润色	polish (source_type/API) / polish_content (service)	基本对应，但"polish"在代码中同时指"画面描述润色"和"配音文案润色"

---

D类：术语在注释/文案中的不统一

• ScriptCreation.tsx 中：voiceover 字段的注释混用"配音文案"、"画外音"
• VideoGeneration.tsx 中：用户错误提示混用"返回第二步重新生成配音"和"回到第2步重新生成音频"
• voice.ts 中：API 模块标题为"TTS 合成、批量合成、声音克隆"，但对应的功能页面叫"音频合成"

---

三、统一标准方案

3.1 用户层统一名称（用户可见的所有文案）

source_type	统一名称	子类型/说明
script	脚本生成	—
polish	文案润色	含画面描述润色、配音文案润色
title	标题生成	封面主/副标题
tts	配音合成	步骤标签、页面标题、按钮、进度统一用此
voice_clone	声音复刻	统一用"复刻"，不用"克隆"
video	视频生成	技术实现是对口型，但用户界面禁止出现"对口型"
caption	字幕生成	从视频提取字幕文本
subtitle_burn	字幕烧录	将字幕文件烧录到视频画面中
cover_design	封面设计	统一用"设计"，不用"制作/生成"
compose	压制成片	FFmpeg 拼接输出最终成品视频

说明：

• 配音合成：选择这个词是因为它比"音频合成"更贴近用户理解（"我给视频配个音"），又比单独的"配音"更像一个功能名称。步骤标签从"音频合成"改为"配音合成"。
• 声音复刻："复刻"比"克隆"更符合国内 AI 产品用语习惯（如剪映用"声音克隆"，但通义/讯飞多用"声音复刻"）。考虑到积分明细已用"复刻"，统一到此。
• 封面设计：文件名已经是 CoverDesign，积分 description 也是"封面设计"，步骤标签从"封面制作"改为此，形成统一。
• 视频生成：技术实现是 Vidu 对口型，但所有用户文案（含错误提示、进度提示）统一用"视频生成"。

3.2 开发层统一命名

source_type（数据库/API 层，已较规范，保持不变）

script / polish / title / tts / voice_clone / video / caption / subtitle_burn / cover_design / compose

前端文件/模块命名

业务	当前文件名	建议文件名	理由
脚本生成	ScriptCreation.tsx	✅ 保持不变	语义清晰
文案润色	无独立页面（在 ScriptCreation 内）	—	—
标题生成	无独立页面（在 CoverDesign/SubtitleBurning 内调用）	—	—
配音合成	VoiceDubbing.tsx	VoiceSynthesis.tsx	VoiceDubbing 侧重"配音"动作，不够功能化；Synthesis 与 synthesizeTTS 对应
声音复刻	VoiceMaterialLibrary.tsx	✅ 保持不变	页面本身是素材库，其中包含声音复刻功能，可以接受
视频生成	VideoGeneration.tsx	✅ 保持不变	语义清晰
字幕生成	无独立页面（在 VoiceDubbing 内调用）	—	—
字幕烧录	SubtitleBurning.tsx	✅ 保持不变	语义清晰
封面设计	CoverDesign.tsx	✅ 保持不变	语义清晰
压制成片	VideoComposite.tsx	VideoCompose.tsx	与 source_type compose 一致。注意当前已有 videoCompose.ts（上传模块），需先厘清两者边界

⚠️ 关于 videoCompose.ts vs videoComposite.ts：

• videoCompose.ts：提供 uploadVideoFile（上传本地视频到后端→七牛云），文件注释写"压制成片 IPC 模块"，实际做的是上传，命名混乱。
• videoComposite.ts：提供 compositeApi.synthesis（调用 Rust 压制成片），命名与业务对应。 建议：videoCompose.ts 改名为 videoUpload.ts（或合并到七牛上传模块），VideoComposite.tsx 改名为 VideoCompose.tsx。

后端文件/模块命名

业务	当前命名	建议	理由
压制成片	video_compose.rs + video_processing.rs	✅ 保持两个文件，但统一对外 command 名	video_processing.rs 是业务逻辑层，video_compose.rs 是 command 层，分层合理。只需统一 Rust command 名和响应消息

---

四、具体修改清单

必改（数据层错误）

1. python-api/app/services/point_service.py

   • _CATEGORY_MAP["polish"] → "文案润色"
   • _CATEGORY_MAP["title"] → "标题生成"
   • _CATEGORY_MAP["voice_clone"] → "声音复刻"

2. python-api/app/api/v1/script.py（如果 description 硬编码了错误分类）

   • description="【文案润色】" ✅ 已正确
   • title 端点消费记录需要确认 description 格式

用户文案统一

3. Step 标签（tauri-app/src/pages/VideoCreation/index.tsx）

   • Step 2: "音频合成" → "配音合成"
   • Step 5: "封面制作" → "封面设计"

4. 配音合成页面（tauri-app/src/pages/VideoCreation/VoiceDubbing.tsx）

   • 页面注释："语音配音页面" → "配音合成页面"
   • 进度：show('生成配音') → show('配音合成')
   • 进度：update('正在生成配音...') → update('正在合成配音...')
   • 成功：success('配音已就绪') → success('配音合成完成')
   • 按钮：生成配音 → 合成配音
   • 右侧标题：配音文案 → 配音文本
   • 字段标签：配音 → 配音文本
   • 错误提示中所有"配音"保持不动（"重新生成配音"是动作描述，不需要改）

5. 封面设计页面（tauri-app/src/pages/VideoCreation/CoverDesign.tsx）

   • 进度：show('封面生成') → show('封面设计')
   • 成功：success('封面生成完成') → success('封面设计完成')
   • 错误：封面生成失败 → 封面设计失败
   • 按钮：立即生成封面图 → 立即设计封面
   • 积分 description：封面设计 ✅ 已正确

6. 声音复刻（tauri-app/src/components/Layout/Sidebar.tsx + tauri-app/src/pages/ContentManagement/VoiceMaterialLibrary.tsx + tauri-app/src/api/modules/voice.ts）

   • Sidebar: "声音克隆" → "声音复刻"
   • voice.ts 注释："声音克隆" → "声音复刻"
   • VoiceMaterialLibrary.tsx 标题和文案

7. 视频生成页面（tauri-app/src/pages/VideoCreation/VideoGeneration.tsx）

   • 所有用户可见的"对口型"改为"视频生成"：
     • 进度：show('视频生成') ✅ 已正确
     • 进度：update('正在提交对口型任务...') → update('正在提交视频生成任务...')
     • 进度：update('正在等待对口型处理...') → update('正在等待视频处理...')
     • 进度：update('对口型处理中...') → update('视频处理中...')
     • 进度：update('正在下载对口型视频...') → update('正在下载生成视频...')
     • 错误：对口型任务失败 → 视频生成失败
     • 错误：对口型任务超时 → 视频生成超时
   • 日志/注释中的"对口型"可以保留（开发层）

8. 压制成片页面（tauri-app/src/pages/VideoCreation/VideoComposite.tsx）

   • 镜头列表中的配音标签 → 配音文本

9. TermsModal（tauri-app/src/components/Modal/TermsModal.tsx）

   • "AI 配音（TTS）" → "AI 配音合成（TTS）"
   • "声音复刻" ✅ 已正确

10. 积分明细（tauri-app/src/pages/Profile/UsageDetail.tsx）

    • voice_clone 筛选标签："声音复刻" ✅ 已正确
    • tts 筛选标签："音频合成" → "配音合成"
    • cover_design 筛选标签："封面设计" ✅ 已正确

11. 我的作品（tauri-app/src/pages/ContentManagement/MyWorks.tsx）

    • 空状态文案 ✅ 已改为"压制成片"

开发层整理（建议项，不影响用户）

12. tauri-app/src/api/modules/videoCompose.ts

    • 文件注释写"压制成片 IPC 模块"，实际做的是上传视频。建议改名或修正注释。

13. tauri-app/src/pages/VideoCreation/VideoComposite.tsx

    • 建议未来改名为 VideoCompose.tsx，与 source_type compose 一致。

---

五、确认清单

请确认以下决策：

1. Step 2 标签："音频合成" → "配音合成"（还是保持"音频合成"？）
2. Step 5 标签："封面制作" → "封面设计"（是否接受？）
3. 声音功能：统一为"声音复刻"（放弃"声音克隆"）？
4. 视频生成：所有用户文案中的"对口型"全部替换为"视频生成"？
5. 文件改名：VoiceDubbing.tsx → VoiceSynthesis.tsx、VideoComposite.tsx → VideoCompose.tsx 是否执行？