# AI Stock Assistant Desktop - Tauri v2

基于 **Tauri v2 + Rust + Vue 3** 的 AI 股票分析助手桌面应用

## 开发前必读

如果你只花 30 秒了解这个项目，先记住下面 6 条：

1. 这是本地优先的桌面研究工作台，不是普通 Web 后台。
2. 页面层不越级，只走 `src/renderer/src/api/client.ts`。
3. 长任务统一由 Rust 后台执行，SQLite 是本地状态中心。
4. 内部运维能力默认不对普通用户开放。
5. 涉及业务逻辑、共享契约、映射、筛选、状态推进或跨层编排的改动，必须跑 `npm run verify:logic`。
6. 禁止运行时兜底兼容，默认采用 fail fast。

进一步阅读：

- [AI / 代理协作约束](./AGENTS.md)
- [文档目录](./docs/README.md)
- [项目约束总表](./docs/constraints/README.md)
- [项目编码约束](./docs/constraints/coding-rules.md)
- [项目架构](./docs/overview/architecture.md)
- [业务沉淀入口](./docs/business/README.md)

## 🚀 技术优势

相比 Electron 版本，Tauri v2 版本具有以下优势：

| 指标 | Electron | Tauri v2 | 提升 |
|------|----------|----------|------|
| 包体积 | ~150MB | **~10MB** | **减少 93%** |
| 内存占用 | ~500MB | **~100MB** | **减少 80%** |
| 启动时间 | ~3s | **<1s** | **提升 5 倍** |
| 安全性 | 中 | **高** | **大幅提升** |

## 🛠️ 技术栈

- **前端框架**: Vue 3.5 + TypeScript
- **桌面框架**: Tauri v2
- **后端语言**: Rust
- **数据库**: SQLite (rusqlite)
- **UI 组件库**: Element Plus
- **图表库**: ECharts 6.0
- **交付方式**: 本地 macOS 安装包 + Windows 自助构建包

## 📦 项目结构

```
ai-stock-assistant-desktop-tauri/
├── src-tauri/                 # Rust 本地业务中台
│   ├── src/
│   │   ├── lib.rs            # Tauri 组装入口
│   │   ├── commands.rs       # IPC 命令入口
│   │   ├── db.rs             # SQLite 初始化与访问
│   │   ├── task_runtime.rs   # 后台任务运行轨迹
│   │   ├── notice_*.rs       # 公告同步、读模型和分析链路
│   │   └── market_*.rs       # 行情同步和市场相关服务
│   └── sql/                  # SQLite schema 与数据字典
├── src/renderer/             # Vue renderer
│   ├── src/
│   │   ├── api/             # 页面统一 API 门面
│   │   ├── platform/        # desktop bridge/runtime 适配
│   │   ├── views/           # 页面级组件
│   │   ├── components/      # 业务组件与基础组件
│   │   ├── router/          # 路由与权限守卫
│   │   └── stores/          # 前端界面态
│   └── index.html
├── src/shared/               # 前后端共享 desktop 契约
├── docs/                     # 约束、架构、业务、专项、运维文档
├── scripts/                  # 约束检查、验证与自动化脚本
└── package.json              # Node.js 依赖与命令入口
```

## 📚 文档

- [AI / 代理协作约束](./AGENTS.md)
- [文档目录](./docs/README.md)
- [项目约束总表](./docs/constraints/README.md)
- [项目编码约束](./docs/constraints/coding-rules.md)
- [项目架构](./docs/overview/architecture.md)
- [业务沉淀入口](./docs/business/README.md)
- [功能专项入口](./docs/features/README.md)
- [运维与验证入口](./docs/operations/README.md)

## 🔧 开发环境准备

### 1. 安装 Rust

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

### 2. 安装系统依赖

**macOS:**
```bash
xcode-select --install
```

**Windows:**
- 安装 [Visual Studio C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
- 安装 [WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)

**Linux:**
```bash
# Debian/Ubuntu
sudo apt update
sudo apt install -y libgtk-3-dev libwebkit2gtk-4.0-dev libappindicator3-dev librsvg2-dev patchelf

# Arch Linux
sudo pacman -S webkit2gtk base-devel curl wget
```

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

```bash
npm install
```

## 📝 常用命令

### 开发模式

```bash
npm run dev
```

这会同时启动 Vite 开发服务器和 Tauri 应用。

### 构建应用

```bash
npm run build
```

这条命令会先构建 renderer，再自动准备当前平台对应的独立 `aktools` sidecar，最后生成桌面安装包。

如果你只想单独准备正式分发用 sidecar：

```bash
npm run build:aktools-sidecar
```

如果你要在本机直接生成 macOS 正式安装包：

```bash
npm run build:local-release
```

如果你要把当前版本的 macOS 安装包和 Windows 自助构建包统一归集到一个目录：

```bash
node scripts/assemble_release_bundle.mjs --mode local-release
```

### 类型检查

```bash
npm run typecheck
```

### 逻辑准确性校验

```bash
npm run verify:logic
```

这条命令会顺序执行结构约束检查、类型检查和 Vitest，用来确认关键契约、核心逻辑分支和关键链路没有被改坏。

### 结构约束检查

```bash
npm run check:constraints
```

这条命令会校验页面 / 组件、`composables/*`、`stores/*` 和 `App.vue` 是否越级直接访问 Tauri、desktop bridge，以及是否重新引入已废弃的运行时契约兼容。

## 🎯 核心功能

### 1. 本地行情数据库

使用 SQLite 存储股票行情数据，支持：
- 日线行情数据
- K 线数据（支持多种周期）
- 批量导入/导出
- 高效查询

表结构声明文件：`src-tauri/sql/desktop_schema.sql`
字段数据字典：`src-tauri/sql/desktop_data_dictionary.md`

### 2. Tauri IPC 命令

Rust 后端通过 Tauri IPC 暴露行情、公告、任务调度、初始化包导入和更新检查等命令，命令实现集中在 `src-tauri/src/commands.rs`。

页面层开发时不要直接写 `invoke()`。前端统一通过下面两层消费这些能力：

- 页面 / 组件: `src/renderer/src/api/client.ts` 或局部 composable
- 协议适配层: `src/renderer/src/platform/desktop/createDesktopBridge.ts`

### 3. 当前交付方式

- macOS：本机打包 `dmg` 后直接交付
- Windows：交付自助构建包，由 Windows 用户本地执行 PowerShell 打包脚本
- 远程 GitHub Actions 自动发版链路不再作为当前仓库的正式交付方式

## 🔒 安全性

Tauri v2 默认提供：
- 前后端隔离
- 类型安全的 IPC 通信
- 最小权限原则
- CSP 策略支持

## 📊 性能对比

### 包体积
- Electron: ~150MB
- **Tauri v2: ~10MB** ⭐

### 内存占用
- Electron: ~500MB
- **Tauri v2: ~100MB** ⭐

### 启动时间
- Electron: ~3s
- **Tauri v2: <1s** ⭐

## 🐛 已知问题

1. **首次构建较慢**: Rust 需要编译依赖，首次构建可能需要 5-10 分钟
2. **WebView2 依赖**: Windows 需要安装 WebView2 Runtime（可自动安装）

## 📝 协作说明

项目内不再维护运行时任务看板文档；协作工具如需记录活跃任务、占位或回收状态，应在仓库文档之外维护自己的运行时状态。

文档目录和阅读顺序以 [docs/README.md](./docs/README.md) 为准。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

Copyright © 2026 wink

## 📞 联系方式

如有问题，请通过 Issue 反馈。
