# AGENTS.md — 美家卡智影

> 本文档面向 AI Coding Agent。项目主要使用中文进行注释和界面文案，文档亦以中文撰写。

---

## 项目概述

**美家卡智影**（产品名）是一款基于 Tauri v2 + React 19 + TypeScript 的桌面端 AI 视频创作应用。

- **产品标识**: `cn.meijiaka.ai-video`
- **版本**: `1.6.7`
- **窗口尺寸**: 1200×800，不可缩放（`resizable: false`）
- **核心功能**: AI 脚本生成、AI 配音合成、视频生成、压制成片（FFmpeg）、项目本地持久化

### 技术栈

| 层级 | 技术 |
|------|------|
| 前端框架 | React 19 + TypeScript |
| 构建工具 | Vite 7 |
| 桌面壳 | Tauri v2 (Rust) |
| 状态管理 | Zustand 5 + Immer 11 |
| 路由 | `react-router-dom` (BrowserRouter) + 自定义 `NavigationContext` 做页面切换 |
| 数据请求 | 自研智能路由客户端 (`src/api/client.ts`) + SWR |
| 测试 | Vitest 4 + jsdom + `@testing-library/react` |
| 虚拟列表 | `@tanstack/react-virtual` |
| 外部依赖 | FFmpeg（以 Tauri Sidecar 形式打包） |

### 运行时架构

采用**混合通信架构**：

1. **纯数据 API**（脚本、配音、视频生成）→ 前端通过 HTTP **直连 Python 后端**（`http://127.0.0.1:8080/api/v1`）。
2. **需要本地系统能力**（FFmpeg 压制成片、文件系统读写、认证）→ 走 **Tauri IPC → Rust 层** 处理。

> 新增纯数据 API 时，**无需修改 Rust 代码**，直接在 `src/api/modules/` 下使用 `client.post/get` 调用即可。

---

## 目录结构

```
.
├── index.html              # Vite 入口 HTML
├── package.json            # Node 依赖与脚本
├── vite.config.ts          # Vite 配置（端口 1420，Tauri 适配）
├── vitest.config.ts        # 测试配置
├── tsconfig.json           # TypeScript 主配置（strict: true）
├── tsconfig.node.json      # Node 工具链 TS 配置
├── src/
│   ├── main.tsx            # React 挂载入口
│   ├── App.tsx             # 根组件：导航上下文、主题、侧边栏布局
│   ├── api/
│   │   ├── client.ts       # 智能路由客户端（HTTP / IPC 自动选择）
│   │   ├── types.ts        # 通用 API 类型
│   │   └── modules/        # 按领域拆分的 API 模块
│   │       ├── auth.ts
│   │       ├── script.ts   # 脚本生成（含 SSE 流式接口）
│   │       ├── voice.ts
│   │       ├── video.ts
│   │       ├── videoComposite.ts  # 压制成片（走 IPC）
│   │       ├── cover.ts
│   │       └── system.ts   # 项目持久化
│   ├── components/         # 可复用组件（PascalCase 文件夹）
│   │   ├── Layout/
│   │   ├── Modal/
│   │   ├── Toast/
│   │   ├── ErrorBoundary/
│   │   ├── VirtualShotList/
│   │   └── ...
│   ├── hooks/              # 自定义 React Hooks
│   ├── pages/              # 页面级组件（PascalCase 文件夹）
│   │   ├── VideoCreation/  # 核心创作流程（脚本→音频→封面→合成）
│   │   ├── ContentManagement/
│   │   │   ├── VoiceClone/
│   │   │   ├── DigitalHuman/
│   │   │   └── MyWorks/
│   │   ├── Settings/
│   │   ├── Profile/
│   │   └── Login/
│   ├── store/              # Zustand 状态管理
│   │   ├── authStore.ts
│   │   ├── projectStore.ts # 项目数据（分镜、空镜、音频、封面等）
│   │   ├── settingsStore.ts
│   │   ├── uiStore.ts      # Toast 等 UI 状态
│   │   ├── Provider.tsx
│   │   ├── index.ts
│   │   └── __tests__/      # Store 单元测试
│   ├── styles/
│   │   ├── variables.css   # CSS 变量（含主题变量）
│   │   └── global.css      # 全局样式
│   └── __tests__/
│       └── setup.ts        # Vitest 全局 setup（mock localStorage / Tauri API）
├── src-tauri/
│   ├── Cargo.toml          # Rust 依赖
│   ├── tauri.conf.json     # Tauri 应用配置（CSP、窗口、打包、sidecar）
│   ├── build.rs
│   ├── binaries/ffmpeg     # FFmpeg sidecar 二进制
│   ├── icons/              # 应用图标
│   └── src/
│       ├── main.rs         # 程序入口
│       ├── lib.rs          # Tauri Builder、Command 定义、Python 代理
│       ├── ffmpeg_cmd.rs   # FFmpeg 命令封装（拼接、音画合并、封面转视频）
│       └── persistence.rs  # 项目本地文件读写
└── public/                 # 静态资源
```

---

## 构建与开发命令

```bash
# 前端开发服务器（Vite，端口 1420）
npm run dev

# 生产构建（tsc + vite build）
npm run build

# Tauri 开发（启动 Rust + 前端）
npm run tauri dev

# Tauri 生产打包
npm run tauri build

# 运行测试
npm run test

# Vitest UI 模式
npm run test:ui

# 测试覆盖率
npm run test:coverage
```

### 关键配置说明

- **Vite 端口固定为 1420**（`strictPort: true`），与 Tauri `devUrl` 对齐。
- **Tauri 开发时忽略 `src-tauri/` 目录的 watch**，避免前端热更新与 Rust 编译互相干扰。
- **路径别名**: `@/` 映射到 `./src`（在 `vitest.config.ts` 中配置）。

---

## 代码风格与约定

### 命名规范

- **组件/页面文件夹**: `PascalCase`（如 `VideoCreation`、`ErrorBoundary`）
- **Store/Hooks/API 文件**: `camelCase`（如 `authStore.ts`、`useProjectData.ts`）
- **类型/接口**: `PascalCase`
- **常量**: `UPPER_SNAKE_CASE`（Rust 层）

### 注释语言

- 项目内**统一使用中文注释**。
- 关键架构决策需在代码中以多行注释说明（参考 `src/api/client.ts` 顶部的“混合模式智能路由”注释）。

### TypeScript 配置

- `strict: true` 已开启。
- `noUnusedLocals: true`、`noUnusedParameters: true` 已开启，未使用变量会报错。
- `jsx: "react-jsx"`，无需手动引入 `React`。

### 状态管理约定

- 使用 **Zustand + Immer** 进行不可变更新。
- `projectStore` 使用自定义 `persist` 存储，将项目数据通过 Tauri IPC 持久化到本地文件系统（`app_config_dir/current_project.json`），而不是 localStorage。
- 其他 Store（如 `authStore`、`settingsStore`）使用 `localStorage` 做持久化。

### API 开发流程

1. **判断是否需要本地能力**（FFmpeg、文件系统、系统调用）。
2. **不需要** → 直接在 `src/api/modules/` 使用 `client.get/post/put/delete` 调用 Python HTTP API。
3. **需要** → 将 endpoint 加入 `src/api/client.ts` 的 `RUST_IPC_APIS` 集合，并在 `src-tauri/src/lib.rs` 中实现对应的 `#[tauri::command]` 处理器。

---

## 测试说明

### 测试框架

- **Vitest**（globals: true，environment: `jsdom`）
- **@testing-library/react** 用于测试 Hooks 和组件
- **@testing-library/jest-dom** 提供自定义 matchers

### 测试文件位置

- 全局 setup: `src/__tests__/setup.ts`
- Store 测试: `src/store/__tests__/*.test.tsx`
- 组件/页面测试: 建议放在被测文件同目录或 `__tests__` 子目录中

### Mock 策略

`setup.ts` 中已全局 mock 以下内容：

- `localStorage`（完整 mock）
- `@tauri-apps/api/core` 的 `invoke` 方法
- `window.__TAURI_INTERNALS__`

每个测试后自动调用 `vi.clearAllMocks()`。

### 运行示例

```bash
# 单次运行
npm run test

# 交互式 UI
npm run test:ui
```

---

## 安全与部署

### CSP 配置

`src-tauri/tauri.conf.json` 中已配置 Content Security Policy：

- `default-src`: `'self'`
- `connect-src`: `'self' http://localhost:8080 http://127.0.0.1:8080`
- `img-src` / `media-src`: 允许 `http://localhost:8080` 及 `blob:`、`data:`

### 外部二进制

- FFmpeg 作为 **sidecar** 打包（`bundle.externalBin: ["binaries/ffmpeg"]`）。
- Rust 层通过 `tauri_plugin_shell` 的 `sidecar("ffmpeg")` 调用。
- 合成过程中会解析 FFmpeg stderr 输出中的 `time=` 字段，并通过 Tauri Event (`ffmpeg-progress`) 向前端发送进度。

### 项目文件存储路径

- **项目持久化文件**: `{app_config_dir}/current_project.json`（由 `persistence.rs` 管理）。
- **合成临时文件**: `{document_dir}/Meijiaka/Projects/`（由 `lib.rs` 中的 `get_project_dir` 管理）。

### 认证状态

当前登录接口 (`auth_login`) 返回 **Mock 数据**，仅用于开发阶段。生产环境需替换为真实认证逻辑。

---

## 给 Agent 的快速检查清单

在修改代码前，建议确认以下事项：

1. **新增 API 是否需要 Rust 层？** 不需要则只改前端 `src/api/modules/`。
2. **修改 Store 后是否影响持久化？** `projectStore` 的 `partialize` 字段决定哪些状态会被保存到本地文件。
3. **新增组件是否遵循 PascalCase 文件夹约定？**
4. **测试是否通过？** 运行 `npm run test`。
5. **Tauri 配置变更后是否需要重新 `tauri dev`？** 是的，`tauri.conf.json` 或 `Cargo.toml` 变更后需重启 Tauri 进程。
