flash-send/document/08-开发指南.md

# 开发指南

本文档介绍 Flash Send 的开发环境搭建、开发流程和构建部署。

## 环境要求

### 系统要求

| 平台 | 最低版本 |
|------|----------|
| Windows | Windows 10 |
| macOS | 10.15+ |
| Linux | Ubuntu 18.04+ |

### 开发工具

| 工具 | 版本要求 | 用途 |
|------|----------|------|
| Node.js | >= 18.0 | 前端构建 |
| Rust | >= 1.70 | 后端开发 |
| pnpm/npm/yarn | 最新版 | 包管理 |

### 推荐 IDE

- **VS Code** + 插件：
  - Vue - Official
  - rust-analyzer
  - Tailwind CSS IntelliSense
  - Tauri

- **RustRover** / **WebStorm**

---

## 环境搭建

### 1. 克隆项目

```bash
git clone https://github.com/your-repo/flash-send.git
cd flash-send
```

### 2. 安装 Node.js 依赖

```bash
npm install
# 或
pnpm install
# 或
yarn install
```

### 3. 安装 Rust

```bash
# Windows (使用 rustup-init.exe)
# https://rustup.rs/

# macOS / Linux
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 验证安装
rustc --version
cargo --version
```

### 4. 安装 Tauri CLI

```bash
npm install -g @tauri-apps/cli
# 或
cargo install tauri-cli
```

### 5. 系统依赖 (Linux)

```bash
# Ubuntu/Debian
sudo apt update
sudo apt install libwebkit2gtk-4.0-dev \
    build-essential \
    curl \
    wget \
    file \
    libssl-dev \
    libgtk-3-dev \
    libayatana-appindicator3-dev \
    librsvg2-dev
```

---

## 开发命令

### 启动开发服务器

```bash
npm run tauri dev
```

这会同时启动：
- Vite 开发服务器（前端热重载）
- Tauri 开发窗口（后端实时编译）

### 仅启动前端

```bash
npm run dev
```

### 类型检查

```bash
# 前端 TypeScript
npm run build  # 包含 vue-tsc --noEmit

# 后端 Rust
cd src-tauri
cargo check
```

### 代码格式化

```bash
# 前端
npx prettier --write src/

# 后端
cd src-tauri
cargo fmt
```

### 代码检查

```bash
# 后端
cd src-tauri
cargo clippy
```

---

## 项目结构说明

```
flash-send/
├── src/                    # Vue 前端源码
│   ├── api/               # Tauri API 封装
│   ├── components/        # Vue 组件
│   ├── pages/             # 页面组件
│   ├── stores/            # Pinia 状态
│   ├── hooks/             # 组合式函数
│   ├── types/             # TypeScript 类型
│   ├── router/            # Vue Router
│   ├── styles/            # 全局样式
│   ├── App.vue            # 根组件
│   └── main.ts            # 入口文件
│
├── src-tauri/             # Rust 后端源码
│   ├── src/
│   │   ├── commands/      # Tauri 命令
│   │   ├── discovery/     # 设备发现
│   │   ├── websocket/     # WebSocket
│   │   ├── http/          # HTTP 传输
│   │   ├── tls/           # TLS 加密
│   │   ├── database/      # SQLite
│   │   ├── models/        # 数据模型
│   │   ├── utils/         # 工具函数
│   │   ├── state.rs       # 全局状态
│   │   ├── main.rs        # 程序入口
│   │   └── lib.rs         # 库入口
│   ├── Cargo.toml         # Rust 依赖
│   └── tauri.conf.json    # Tauri 配置
│
├── document/              # 项目文档
├── public/                # 静态资源
├── index.html             # HTML 入口
├── package.json           # Node 依赖
├── vite.config.ts         # Vite 配置
├── tailwind.config.js     # Tailwind 配置
└── tsconfig.json          # TypeScript 配置
```

---

## 开发流程

### 1. 新增 Tauri 命令

**步骤 a**: 在 `src-tauri/src/commands/` 创建或编辑命令文件

```rust
// src-tauri/src/commands/my_commands.rs
#[tauri::command]
pub async fn my_command(param: String) -> CommandResult<String> {
    // 实现逻辑
    Ok(format!("Hello, {}!", param))
}
```

**步骤 b**: 在 `mod.rs` 注册命令

```rust
// src-tauri/src/commands/mod.rs
pub fn get_handlers() -> impl Fn(tauri::Builder<Wry>) -> tauri::Builder<Wry> {
    |builder| {
        builder.invoke_handler(tauri::generate_handler![
            // ... 其他命令
            my_command,
        ])
    }
}
```

**步骤 c**: 在前端调用

```typescript
// src/api/index.ts
export const myApi = {
  myCommand: (param: string) => invoke<string>('my_command', { param }),
}
```

### 2. 新增前端页面

**步骤 a**: 创建页面组件

```vue
<!-- src/pages/MyPage.vue -->
<script setup lang="ts">
import { ref, onMounted } from 'vue'

const data = ref('')

onMounted(async () => {
  // 初始化
})
</script>

<template>
  <div class="p-4">
    <h1>My Page</h1>
  </div>
</template>
```

**步骤 b**: 添加路由

```typescript
// src/router/index.ts
{
  path: '/my-page',
  name: 'myPage',
  component: () => import('../pages/MyPage.vue')
}
```

### 3. 新增后端事件

**步骤 a**: 定义事件

```rust
// src-tauri/src/models/events.rs
pub mod event_names {
    pub const MY_EVENT: &str = "my:event";
}
```

**步骤 b**: 发送事件

```rust
use tauri::Emitter;

app.emit("my:event", payload)?;
```

**步骤 c**: 前端监听

```typescript
import { listen } from '@tauri-apps/api/event'

const unlisten = await listen('my:event', (event) => {
  console.log(event.payload)
})
```

---

## 调试技巧

### 前端调试

1. **Chrome DevTools**: `Ctrl+Shift+I` 或 `F12`
2. **Vue DevTools**: 安装浏览器扩展
3. **Console 日志**: 使用 `console.log()`

### 后端调试

1. **日志输出**:
```rust
log::info!("Debug message: {:?}", value);
log::error!("Error: {}", err);
```

2. **环境变量**:
```bash
RUST_LOG=debug npm run tauri dev
```

3. **查看后端日志**: 在终端中查看 Tauri 输出

### 网络调试

1. **WebSocket**: 使用浏览器 DevTools Network 面板
2. **HTTP**: 使用 Postman 或 curl 测试
3. **UDP**: 使用 Wireshark 抓包

---

## 构建发布

### 构建生产版本

```bash
npm run tauri build
```

**输出目录**: `src-tauri/target/release/bundle/`

### 构建产物

| 平台 | 格式 |
|------|------|
| Windows | `.msi`, `.exe` (NSIS) |
| macOS | `.dmg`, `.app` |
| Linux | `.deb`, `.AppImage` |

### 配置构建

编辑 `src-tauri/tauri.conf.json`:

```json
{
  "productName": "Flash Send",
  "version": "1.0.0",
  "identifier": "com.flashsend.app",
  "bundle": {
    "active": true,
    "targets": "all",
    "icon": ["icons/icon.ico", "icons/icon.png"],
    "windows": {
      "certificateThumbprint": null,
      "digestAlgorithm": "sha256",
      "timestampUrl": ""
    }
  }
}
```

### 代码签名

#### Windows

```json
{
  "bundle": {
    "windows": {
      "certificateThumbprint": "YOUR_CERT_THUMBPRINT",
      "digestAlgorithm": "sha256",
      "timestampUrl": "http://timestamp.digicert.com"
    }
  }
}
```

#### macOS

```bash
export APPLE_SIGNING_IDENTITY="Developer ID Application: Your Name (XXXXXXXXXX)"
npm run tauri build
```

---

## 测试

### 单元测试 (Rust)

```bash
cd src-tauri
cargo test
```

### 集成测试

1. 启动两个实例（不同机器或虚拟机）
2. 测试设备发现
3. 测试聊天功能
4. 测试文件传输

### 测试清单

- [ ] 设备发现正常
- [ ] WebSocket 连接稳定
- [ ] 消息收发正常
- [ ] 文件传输完整
- [ ] 取消传输有效
- [ ] 深色模式正常
- [ ] 数据库持久化
- [ ] 重启后数据恢复

---

## 常见问题

### Q: 编译时出现 OpenSSL 错误

**A**: 安装 OpenSSL 开发库

```bash
# Ubuntu
sudo apt install libssl-dev

# macOS
brew install openssl
```

### Q: Windows 上编译失败

**A**: 安装 Visual Studio Build Tools

下载地址: https://visualstudio.microsoft.com/visual-cpp-build-tools/

### Q: 设备无法发现

**A**: 检查防火墙设置，确保 UDP 53317 端口开放

### Q: WebSocket 连接失败

**A**: 检查防火墙设置，确保 TCP 53318 端口开放

### Q: 文件传输失败

**A**: 
1. 检查防火墙设置，确保 TCP 53319 端口开放
2. 检查磁盘空间是否充足
3. 检查下载目录权限

---

## 贡献指南

### 提交规范

使用 Conventional Commits:

```
feat: 添加新功能
fix: 修复 bug
docs: 更新文档
style: 代码格式调整
refactor: 代码重构
test: 添加测试
chore: 构建/工具变更
```

### 分支策略

- `main`: 稳定版本
- `develop`: 开发分支
- `feature/*`: 功能分支
- `fix/*`: 修复分支

### PR 流程

1. Fork 项目
2. 创建功能分支
3. 提交变更
4. 创建 Pull Request
5. 代码审查
6. 合并到 develop

---

## 参考资源

- [Tauri 官方文档](https://tauri.app/v2/guides/)
- [Vue 3 文档](https://vuejs.org/)
- [Rust 官方文档](https://doc.rust-lang.org/)
- [TailwindCSS 文档](https://tailwindcss.com/docs)
- [Pinia 文档](https://pinia.vuejs.org/)