Cline rules

1---
2description: "Use when: writing or modifying Rust code in src-tauri/. Covers Tauri command structure, state management, external process handling, logging, and compile-time config."
3globs: "src-tauri/**"
4alwaysApply: false
5---
6 
7# Backend Rules
8 
9<!-- Tauri v2 / Rust 后端规范，操作 src-tauri/ 目录时自动加载 -->
10 
11## Tauri Commands
12 
13Always declare Tauri commands in `src-tauri/src/lib.rs` and register them in `run()` via `.invoke_handler(tauri::generate_handler![...])`.
14 
15Always use `#[tauri::command]` on async functions. NEVER use sync commands for I/O-bound work.
16 
17```rust
18#[tauri::command]
19async fn my_command(app: tauri::AppHandle, ...) -> Result<T, String> { ... }
20```
21 
22Always receive `app: tauri::AppHandle` as the first parameter. Use `app.state::<MyState>()` to access managed state.
23 
24Prefer `Result<T, String>` as the return type for all commands. Use the `?` operator with `.map_err(|e| e.to_string())` or `.map_err(|e| format!("context: {e}"))` for error propagation.
25 
26Use `tauri::async_runtime::spawn()` for long-running background tasks spawned from commands (e.g., polling loops, sidecar process monitors). NEVER use `std::thread::spawn` or `tokio::spawn` directly.
27 
28## State Management
29 
30Always use Tauri managed state (`app.manage(...)` in `run()`) for shared data. Declare state structs with thread-safe wrappers:
31 
32```rust
33/// task_id → aria2 gid
34struct GidMap(Mutex<HashMap<String, String>>);
35 
36/// task_id → oneshot sender to stop the polling loop
37struct PollStops(Mutex<HashMap<String, oneshot::Sender<()>>>);
38 
39/// Flag to break re-entry loops
40struct Closing(AtomicBool);
41```
42 
43Never use global `static mut` or `lazy_static!` for mutable state — always go through `app.state::<T>()`.
44 
45## Frontend Communication
46 
47Always emit events to the frontend via `app.emit("event-name", payload)`. Define payload types with `#[derive(serde::Serialize, Clone)]`.
48 
49```rust
50#[derive(serde::Serialize, Clone)]
51struct MyEventPayload {
52    id: String,
53    value: u8,
54}
55 
56let _ = app.emit("my-event", MyEventPayload { id, value });
57```
58 
59Never call `app.emit()` from a synchronous context that holds a lock — always clone the `AppHandle` and emit from an async context or after releasing the lock.
60 
61## Logging
62 
63Always use the `log` crate macros: `debug!`, `info!`, `warn!`, `error!`.
64 
65Prefix log messages with a tag for filtering:
66 
67```rust
68info!("[add_magnet] task={task_id}");
69debug!("[{task_id}] gid handoff: {current_gid} → {new_gid}");
70error!("[merge][{}] 合并失败: {}", job.id, msg.trim());
71```
72 
73Use `debug!` for detailed diagnostics, `info!` for lifecycle events, `warn!` for recoverable issues, `error!` for failures.
74 
75Register `env_logger` in `run()` before the Tauri builder. Do NOT add additional logging frameworks.
76 
77## External Processes
78 
79Always use `tauri-plugin-shell` for spawning external binaries (aria2c, mkvmerge, etc.). NEVER use `std::process::Command` directly.
80 
81```rust
82use tauri_plugin_shell::{process::CommandEvent, ShellExt};
83 
84let sidecar_cmd = app.shell().sidecar("mkvmerge").map_err(|e| format!("sidecar error: {e}"))?;
85let (mut rx, _child) = sidecar_cmd.args(&args).spawn().map_err(|e| format!("spawn error: {e}"))?;
86```
87 
88External binaries (`aria2c`, `mkvmerge`) are bundled via `externalBin` in `tauri.conf.json`. Reference them by name via `app.shell().sidecar()`.
89 
90Always handle `CommandEvent::Stdout`, `Stderr`, `Terminated`, and the `None` case in the event loop.
91 
92## Compile-time Config
93 
94Compile-time configuration lives in `src-tauri/app-config.json`. Embed it at compile time with `include_str!`:
95 
96```rust
97fn load_app_config() -> Result<AppConfig, String> {
98    const RAW: &str = include_str!("../app-config.json");
99    serde_json::from_str(RAW).map_err(|e| format!("app-config.json 格式错误: {e}"))
100}
101```
102 
103Define a `#[derive(serde::Deserialize)]` struct matching the JSON shape. Changes to `app-config.json` take effect on the next `cargo build`.
104 
105## HTTP Client
106 
107Always use `reqwest` for outbound HTTP. Include `use reqwest::Client;` and build clients with `reqwest::Client::builder()`.
108 
109Include reasonable `User-Agent` headers for external scraping. Use `.timeout(Duration::from_secs(N))` on requests to aria2c and external services.
110 
111```rust
112let client = reqwest::Client::builder()
113    .user_agent("Mozilla/5.0 ...")
114    .build()
115    .map_err(|e| e.to_string())?;
116```
117 
118## Clippy & Code Quality
119 
120Always respect Clippy's `disallowed_macros` and `too-many-arguments` rules. If a lint is explicitly suppressed, add `#[allow(...)]` with a comment explaining why.
121 
122Keep argument counts low. Use helper structs or `app.state()` to pull dependencies into the function body rather than adding more parameters.
123 
124Avoid `unwrap()` on locks in async contexts — use `unwrap_or_else(|e| e.into_inner())` to handle poisoned mutexes gracefully.
125