tech-decision

name	tech-decision
description	技术决策记录技能，记录和管理项目中的技术选型与架构决策。 触发场景： - 用户需要进行技术选型评估 - 用户需要记录架构决策及其原因 - 用户需要回顾历史技术决策 触发词：技术选型、架构决策、ADR、方案对比、技术评估

技术决策记录

概述

Tauri Desktop App 的技术决策记录技能，使用 ADR（Architecture Decision Record）模式管理技术选型和架构决策。

---

ADR 模板

# ADR-{编号}: {决策标题}

## 状态
[提议中 / 已采纳 / 已废弃 / 已取代]

## 背景
[描述决策的背景和约束条件]

## 技术约束
- 后端: Rust + Tauri 2.x
- 前端: React 19 + TypeScript 5.8
- 平台: Windows / macOS / Linux

## 方案对比

| 方案 | 优点 | 缺点 | Rust 生态兼容 | 跨平台 |
|------|------|------|-------------|--------|
| A    |      |      |             |        |
| B    |      |      |             |        |

## 决策
[选择方案 X，理由...]

## 影响
- Rust 侧: ...
- React 侧: ...
- Capabilities: ...

---

本项目已采纳的技术决策

架构层面

决策领域	选择	理由
后端架构	三层架构（models → database → services → commands）	清晰的职责分离，便于测试和维护
数据库方案	rusqlite (直接使用，不用 tauri-plugin-sql)	更灵活的 SQL 控制，无需通过插件桥接
错误处理	thiserror 定义 AppError enum	类型安全的错误处理，避免 panic
状态管理（前端）	Zustand	轻量、API 简洁、TypeScript 友好
路由	React Router v7	成熟稳定，文档完善

UI 层面

决策领域	选择	理由
UI 组件库	Ant Design 5	企业级组件库，功能完善，开箱即用
样式方案	TailwindCSS 4	原子化 CSS，开发效率高
路径别名	@/ 指向 src/	简化导入路径

数据持久化

决策领域	选择	理由
键值存储	tauri-plugin-store	前端直接使用，适合应用配置
结构化数据	rusqlite	后端使用，适合业务数据

插件与工具

决策领域	选择	理由
日志系统	tauri-plugin-log	官方插件，支持日志文件
打开 URL	tauri-plugin-opener	安全地打开外部链接

---

技术选型对比表

UI 组件库

方案	优点	缺点	本项目选择
Ant Design	企业级、功能完善、中文文档	体积较大、样式定制复杂	✅ 已采纳
shadcn/ui	轻量、可定制、现代设计	需要手动配置、组件较少	⭕ 未采纳
MUI	成熟、Material Design	体积大、学习曲线陡	⭕ 未采纳
Headless UI	无样式、完全可定制	需要自己写样式	⭕ 未采纳

决策: 选择 Ant Design，因为需要快速搭建功能完善的企业级应用。

---

状态管理

方案	优点	缺点	本项目选择
Zustand	轻量、API 简洁、无 boilerplate	功能相对简单	✅ 已采纳
Redux Toolkit	功能强大、生态丰富	代码量大、学习成本高	⭕ 未采纳
Jotai	原子化状态、灵活	适合复杂场景，本项目不需要	⭕ 未采纳
React Context	内置、无需依赖	性能问题、不适合全局状态	⭕ 未采纳

决策: 选择 Zustand，因为项目状态管理需求简单，Zustand 足够轻量且易用。

---

路由方案

方案	优点	缺点	本项目选择
React Router v7	成熟稳定、文档完善、社区大	相对传统	✅ 已采纳
TanStack Router	类型安全、现代化	较新、生态较小	⭕ 未采纳

决策: 选择 React Router v7，因为成熟稳定，文档完善。

---

数据库方案

方案	优点	缺点	本项目选择
rusqlite	灵活、直接控制 SQL、无需插件	需要手动管理连接	✅ 已采纳
tauri-plugin-sql	官方插件、自动管理连接池	功能受限、需要通过 IPC 调用	⭕ 未采纳
IndexedDB (前端)	浏览器原生、无需后端	不适合桌面应用、API 复杂	⭕ 未采纳

决策: 选择 rusqlite，因为需要在 Rust 后端直接操作数据库，灵活性更高。

---

错误处理

方案	优点	缺点	本项目选择
thiserror	定义清晰的错误类型、派生宏	需要手动定义每个错误	✅ 已采纳
anyhow	灵活、快速开发	类型擦除、不适合库代码	⭕ 未采纳
Result<T, String>	简单直接	缺乏类型安全	⭕ 未采纳

决策: 选择 thiserror，因为需要类型安全的错误处理，方便调试和维护。

---

样式方案

方案	优点	缺点	本项目选择
TailwindCSS 4	原子化、快速开发、配置简单	类名冗长	✅ 已采纳
CSS Modules	作用域隔离、传统 CSS	需要管理多个 CSS 文件	⭕ 未采纳
styled-components	CSS-in-JS、动态样式	运行时开销	⭕ 未采纳

决策: 选择 TailwindCSS 4，因为开发效率高，与 Ant Design 搭配使用效果好。

---

日志系统

方案	优点	缺点	本项目选择
tauri-plugin-log	官方插件、支持日志文件	功能相对简单	✅ 已采纳
tracing	功能强大、异步支持	配置复杂、体积大	⭕ 未采纳
env_logger	轻量、简单	功能有限	⭕ 未采纳

决策: 选择 tauri-plugin-log，因为满足基本需求且集成简单。

---

测试框架

方案	优点	缺点	本项目选择
cargo test (Rust)	内置、无需配置	功能相对简单	✅ 已采纳
Vitest (前端)	快速、Vite 原生支持	需要配置	✅ 已采纳
Jest	成熟、生态丰富	配置复杂、速度慢	⭕ 未采纳

决策: 选择 cargo test + Vitest，因为分别是 Rust 和 Vite 的最佳选择。

---

常见错误

错误做法	正确做法
技术选型不记录原因	使用 ADR 记录决策背景和理由
选择不支持跨平台的方案	评估 Windows/macOS/Linux 兼容性
选 Rust crate 不考虑编译时间	权衡功能 vs 编译时间
决策后不追踪效果	定期回顾决策结果并更新状态
混用多种状态管理方案	统一使用一种（本项目用 Zustand）
混用多种样式方案	统一使用一种（本项目用 TailwindCSS）
混用多种数据库方案	统一使用一种（本项目用 rusqlite + tauri-plugin-store）