# 美家卡-智剪 (Meijiaka Smart Cut) 项目开发实施方案

基于您的最新反馈与确认，本项目将以《golden-purring-crown.md》(方案A)为主要交互蓝本进行落地，明确采用 **手动匹配分镜视频**、**完全本地化数据存储** 和 **沿用现有架构新建仓库** 的策略。

## 目标与改动背景

**项目背景**：衍生自现有的「美家卡智影」，新项目「美家卡智剪」侧重针对用户已有的视频素材，利用 AI 进行配音、并完成拼接与后期制作。

核心工作流程（6 步）：
1. **脚本生成** (基于主题生成具有预估时长的分镜与旁白)
2. **视频剪辑 (新)** (用户手动为**每一个单分镜**导入对应长度的视频素材短片)
3. **音色配音 (新)** (用户本地维护音色特征，使用大模型 TTS 为所有分镜批量生成口播音频)
4. **字幕压制** (自动打轴并挂载 ASS 字幕，复用智影功能)
5. **封面制作** (根据首分镜首帧和文字生成封面，复用智影功能)
6. **视频合成** (所有片段首尾拼接成短视频，并将原有环境音替换/混音为合成音频，复用智影功能)

---

## 核心设计决策 (User Confirmed)

1. **交互模式**：不采用长视频自动切割算法。**必须采用单一分镜独立手动导入视频的交互**。
2. **数据存储**：**纯本地文件系统**。所有业务数据（项目元数据、分镜配置、克隆好的本地音色记录等）全部保存在用户本地磁盘路径下，**不保存在云端数据库中**。
3. **架构剥离**：通过拷贝文件系统级别进行剥离 (`rsync ai-meijiaka -> meijiaka-zj`)，保留现有混合路由和本地缓存设计。

---

## Proposed Changes

### 1. 架构剥离与仓库初始化
在同级目录下快速搭建衍生仓库，移除不相干的缓存依赖。

#### [NEW] `meijiaka-zj/` (新建本地项目根目录)
- 配置应用标识词修正（ `产品名: 美家卡智剪`, `Bundle Identifier: cn.meijiaka.ai-video-editor` 等）。
- 修改并初始化 git 记录。

---

### 2. 后端 API (Python FastAPI)

不再新建数据库表结构，将所有新 API 的核心转为与本地文件、大语言模型 API 之间的交互代理，由 AsyncEngine 发起。

#### [NEW] `python-api/app/scheduler/handlers/tts_handler.py`
创建用于处理批量语音生成的并发 Dispatcher。

#### [NEW] `python-api/app/services/voice_clone_service.py` & `tts_service.py`
包装调用 `KlingAIProvider`：
- 创建克隆音色的调用逻辑（由于无数据库，云端成功后的声纹特征及 `voice_id` 将通过 API 抛回前端并由 Tauri 存入本地 JSON 集合中）。
- 提供语音合成和查询能力的端点。

#### [NEW] `python-api/app/api/v1/voice.py`
仅暴露无状态/代理转发类型的路由给前端：克隆状态查询、提交合成等。无 DB 依赖。

---

### 3. Rust 系统能力扩展 (src-tauri)

由于采用本地存储，需要在 Rust 层扩展音频文件和声纹文件的安全存储指令。

#### [NEW] `tauri-app/src-tauri/src/storage/voice.rs`
新增声音本地缓存与描述管理，目录范例：`~/Documents/Meijiaka/voices/` (用于存储 voice meta.json 和相关的 reference audio)。

#### [NEW] `tauri-app/src-tauri/src/commands/voice.rs`
由 Tauri 提供存储IPC API给前端：读取本地音色列表、写入新克隆的音色等。

#### [MODIFY] `tauri-app/src-tauri/src/ffmpeg_cmd.rs`
**[重要机制更新]**: 实现目标音频覆盖处理，提供类似 `replace_audio_in_video` 的函数，依靠 `-c:v copy -c:a aac -shortest -map 0:v:0 -map 1:a:0` 剥离原声并在对应的短视频片段上压入新的 TTS 朗读声音。

---

### 4. 前端应用层 (tauri-app / React)

调整原应用状态数据，创建本地数据绑定。

#### [MODIFY] `tauri-app/src/store/projectStore.ts`
扩展原 `SmartCutShot` 阶段参数，支持记录新增加的独立视频源地址 (`mediaPath`) 和单独段落的合成语音地址 (`audioPath`)。

#### [NEW] `tauri-app/src/store/voiceStore.ts`
与 `src-tauri` 通过 IPC 交互：
- 从本地加载用户维护在 `voices/` 下的所有自定义音色。
- 处理前端的缓存与显示。

#### [NEW] `tauri-app/src/pages/VideoCreation/VideoEditing.tsx` (Step 2)
重定义分镜视频导入步骤：
- 为左侧每一个生成的分镜文案展示独立的 Upload/Select Box。
- 用户可以点选或拖动，调用系统弹窗将 `mp4` 一对一绑定给自己心仪的旁白节点。

#### [NEW] `tauri-app/src/pages/VideoCreation/VoiceDubbing.tsx` (Step 3)
批量克隆与TTS应用页面：
- 渲染本地和预定义的云端默认音库。
- 前端批量发起所有含旁白分镜的异步合成任务，获取 URL 后调用 Rust 保留至项目对应的 `audio/` 子目录中。

---

## Verification Plan

### Manual Verification (端到端走通测试)
- **环境**: 在新目录 `meijiaka-zj` 启动前后端服务。
- **Step 1**: 使用纯业务旁白的模版生成分镜文案。
- **Step 2**: 对列表中独立出现的 3 个分镜卡片，依次上传/拖入 3 个独立的 `.mp4` 文件以测试前端映射逻辑。
- **Step 3（关键测试）**: 选择一个克隆音色发起全局合成。观察 `tts_slots` 运转状况。完毕后查验对应项目的物理存储路径内正确生成了 `.mp3` 音轨。
- **Step 6**: 打包合成，测试 `ffmpeg_cmd.rs` 中音频替代逻辑是否执行无误，输出画面不掉帧、声音是合成口音的短片。