# 开发指南

## 环境要求

- Node.js ≥ 22.13（见 `.nvmrc`）
- pnpm（workspace：pnpm-workspace.yaml，仅声明前端包；packageManager pnpm@11.16.0）
- Rust stable（edition 2024）
- macOS：Xcode Command Line Tools（+ 可选 keychain 权限）

## 常用命令

```bash
pnpm dev               # 仅启动 Vite dev server（前端单独开发）
pnpm tauri dev         # 完整桌面应用开发（HMR）
pnpm build             # tsc --noEmit + vite build
pnpm tauri build       # 生产构建（bundle 于 src-tauri/target/release/bundle/）
pnpm test              # vitest --run（前端单测+集成）
pnpm test:e2e          # Playwright E2E（首次需 pnpm exec playwright install chromium）
cd src-tauri && cargo test   # Rust 测试
cd src-tauri && cargo clippy # 静态检查
```

## 发布流程（自动化）

- GitHub Actions `release.yml`：tag 推送触发，构建 macOS（arm64/x64）与 Windows 安装包并上传 release assets
- `scripts/release-notes.mjs`：从 CHANGELOG.md 自动提取当前版本说明（`## [x.y.z]` 段），用于 PR 发布说明
- 版本号三处保持一致：Cargo.toml / tauri.conf.json / package.json

## 工作流（TDD）

1. 写失败测试（红）→ 运行确认失败
2. 最小实现（绿）
3. 重构 + 补边界/失败路径测试
4. 全量回归：`pnpm test` + `cargo test`

## 目录约定

| 路径 | 职责 |
| --- | --- |
| `src/` | 前端（React 19 + TS strict） |
| `src/stores/` | Zustand 状态（唯一业务逻辑层） |
| `src/components/` | 无业务逻辑组件 |
| `src/i18n/` | 多语言文案表与翻译工具 |
| `src/types/` | 与 Rust 模型对齐的类型 |
| `src/test/` | 单测 + 集成 + mocks |
| `e2e/` | Playwright 场景 |
| `scripts/` | 发布说明提取等工具脚本 |
| `src-tauri/src/core/` | Rust 核心服务 |
| `src-tauri/src/commands/` | Tauri 命令（薄封装） |
| `src-tauri/src/models/` | serde 模型 |
| `src-tauri/src/storage/` | 持久化 + 安全存储 |
| `.github/workflows/` | CI / 发布流水线 |
| `.wiki/` | 工程文档（独立 git 仓库，映射 GitHub Wiki） |

## 代码规则

- Rust：不滥用 unwrap、使用 `Result` 传播、模块边界清晰；每个方法带中文注释（目的、关键参数、副作用）
- 前端：React 函数组件 + Hooks、Zustand 不可变更新、严格 TS、组件内无业务逻辑；文案一律走 i18n，不硬编码
- 依赖：只启用代码实际使用的 features，禁止伞形 feature（如 tokio `full`），新增依赖需说明用途
- 新服务必须走 taskId + 状态机（pending → running → done | failed）
- 新增事件命名：`<domain>:<action>`（如 `sftp:progress`）
- 跨边界错误必须走 AppErrorInfo（稳定英文 code + detail），禁止直接回传本地化文案或底层库错误
- 不提交：dist/、node_modules/、src-tauri/target/、.wiki/（独立仓库）

## 提交约定

仓库历史遵循 conventional commits（`feat:` / `fix:` / `refactor:` / `test:` / `chore:`）。看板分支：`main`（稳定）、`dev`（活跃开发）。

## 常见问题

- **端口 5173 被占用**：`lsof -ti:5173 | xargs kill -9`
- **SSH 连不上**：检查防火墙、sshd 状态、凭据；连接错误会以 `session:status` 事件（error 字段）+ `session:progress` 阶段诊断呈现
- **Rust 编译报错**：`rustup update stable`
- **playwright 首次运行**：`pnpm exec playwright install chromium`
- **新增错误场景**：先扩展 `AppError` 变体与 `code()`，前端 i18n 文案表补充 `error.<Code>` 条目，否则回退 `error.Unknown`