meijiaka-zy/tauri-app/AGENTS.md

AGENTS.md — 美家卡智影

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

---

项目概述

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

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

技术栈

层级	技术
前端框架	React 19 + TypeScript
构建工具	Vite 7
桌面壳	Tauri v2 (Rust)
状态管理	Zustand 5 + Immer 11
路由	react-router-dom (BrowserRouter) + 自定义 NavigationContext 做页面切换
数据请求	HTTP 客户端 (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 客户端（camelCase ↔ snake_case 自动转换）
│   │   ├── types.ts        # 通用 API 类型
│   │   └── modules/        # 按领域拆分的 API 模块
│   │       ├── bgmMusic.ts
│   │       ├── config.ts
│   │       ├── cover.ts
│   │       ├── coverAvatar.ts
│   │       ├── localStorage.ts
│   │       ├── materials.ts
│   │       ├── points.ts
│   │       ├── script.ts   # 脚本生成（含 SSE 流式接口）
│   │       ├── task.ts
│   │       ├── videoCompose.ts   # 压制成片（走 IPC）
│   │       ├── videoComposite.ts
│   │       └── voice.ts
│   ├── components/         # 可复用组件（PascalCase 文件夹）
│   │   ├── DatePicker/
│   │   ├── ErrorBoundary/
│   │   ├── Layout/
│   │   ├── Modal/
│   │   ├── PointsCard/
│   │   ├── PricingModal/
│   │   ├── ProgressModal/
│   │   ├── RechargeModal/
│   │   ├── ShotStats/
│   │   ├── Slider/
│   │   ├── Toast/
│   │   └── UpdateDialog/
│   ├── hooks/              # 自定义 React Hooks
│   ├── pages/              # 页面级组件（PascalCase 文件夹）
│   │   ├── ContentManagement/
│   │   ├── Login/
│   │   ├── Profile/
│   │   ├── Settings/
│   │   ├── VideoCreation/  # 核心创作流程（脚本→音频→封面→合成）
│   │   └── VideoGeneration/
│   ├── store/              # Zustand 状态管理
│   │   ├── authStore.ts
│   │   ├── projectStore.ts # 项目数据（分镜、空镜、音频、封面等）
│   │   ├── settingsStore.ts
│   │   ├── uiStore.ts      # Toast 等 UI 状态
│   │   ├── Provider.tsx
│   │   └── index.ts
│   ├── 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 定义、公共类型
│       ├── ffmpeg_cmd.rs   # FFmpeg 命令封装（拼接、音画合并、封面转视频）
│       ├── video_processing.rs  # 压制成片业务逻辑
│       ├── utils.rs        # 通用工具
│       ├── commands/       # Tauri IPC 命令（按领域拆分）
│       └── storage/        # 本地存储引擎（项目、认证、配置、头像等）
└── public/                 # 静态资源

---

构建与开发命令

# 前端开发服务器（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 顶部的 HTTP 客户端与认证处理注释）。

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. 需要 → 在 src/api/modules/ 中通过 @tauri-apps/api/core 的 invoke 调用 Rust 命令，并在 src-tauri/src/commands/ 或 lib.rs 中实现对应的 #[tauri::command] 处理器。

---

测试说明

测试框架

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

测试文件位置

• 全局 setup: src/__tests__/setup.ts
• 组件/页面测试: 建议放在被测文件同目录或 __tests__ 子目录中

Mock 策略

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

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

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

运行示例

# 单次运行
npm run test

# 交互式 UI
npm run test:ui

---

安全与部署

CSP 配置

src-tauri/tauri.conf.json 中已配置 Content Security Policy，关键策略包括：

• default-src: 'self'
• script-src: 'self'
• style-src: 'self' 'unsafe-inline'
• connect-src: 'self' https: ws://localhost:* wss://localhost:* ipc://localhost ipc://localhost/* http://ipc.localhost
• img-src / media-src: 允许 https:、blob:、data:、asset: 及 http://asset.localhost
• font-src: 允许 asset: 及 http://asset.localhost

外部二进制

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

项目文件存储路径

• 项目持久化文件: {app_config_dir}/current_project.json（由 src-tauri/src/storage/project.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 进程。