Imported from qtcyy/PhotoMeeting (src-tauri/AGENTS.md). Install upstream with npx skills add qtcyy/PhotoMeeting --skill src-tauri. Copyright stays with the author.

PhotoMeeting Rust/Tauri 规则

本文件适用于 src-tauri/。同时遵守仓库根 AGENTS.md。

分层职责

• src/commands/ 只处理 Tauri 输入、状态/lease 获取、调用编排和错误映射。
• 相册库、导入、图库、媒体等业务规则保留在对应领域模块，不堆入 command handler 或 lib.rs。
• 新增或修改 command 时同步更新 tauri::generate_handler!、TypeScript DTO 和 src/lib/commands.ts 调用。
• Tauri 边界沿用 #[serde(rename_all = "camelCase")]；数据库枚举和值继续使用既有持久化格式。
• 长时间文件扫描、复制、哈希和媒体处理通过后台任务或 spawn_blocking 执行，不阻塞 UI 主线程。

SQLite 与相册库

• 由 Rust 独占 SQLite 访问，并保持 foreign_keys、完整性检查和单写入者约束。
• 多表、多步骤或读后写操作使用短事务，所有相关写入要么全部提交，要么全部回滚。
• schema 变化使用新的按序 migration，并同步更新旧库升级测试；不得只修改测试库的建表逻辑。
• migration 在独占锁内运行，写入前备份，失败时保留原数据库和可诊断错误。
• 持久化相册库文件路径必须是经过校验的库内相对路径；加入任何文件访问前先检查路径逃逸。

导入与媒体安全

• 导入继续遵守 hashing → staging → final rename → catalog commit → derivatives 的可恢复顺序。
• 复制前后验证源文件 fingerprint；去重命中仍按现有规则进行可靠复核。
• 取消、断电模拟和单文件失败不得留下错误的 ready 记录，也不能损坏已成功导入项目。
• Originals/ 中的文件只读；衍生图写入 Derivatives/，临时内容写入受控 staging/cache。
• 真实样片测试保持 #[ignore] 和只读，普通测试使用 tempfile 与最小合成 fixture。
• 解析损坏或不支持的媒体时限制失败范围；保留原件并返回明确状态，而不是让整个导入任务失败。

测试要求

• 业务规则修改优先在同模块增加或更新针对性测试。
• SQLite 测试使用真实临时数据库和 production migrations，不手写与生产 schema 漂移的替代建表逻辑。
• 导入、恢复、锁、路径或 migration 变更必须覆盖成功、拒绝/失败和幂等或恢复路径。
• command/DTO 边界变化除 Rust 测试外还要运行 pnpm build。
• 高风险修改完成后运行 cargo test --manifest-path src-tauri/Cargo.toml。