tauri-client/call-client/PROJECT_GUIDE.md

call-client 项目说明

1. 项目概览

当前项目是一个基于 Tauri 2 + Vue 3 + TypeScript + Vite 的桌面客户端，已从原 Electron + Vue 项目迁移出主要业务骨架。

当前已完成的核心能力包括：

• 登录窗口、主窗口、票号列表窗口三窗口流程
• 前端业务页面迁移
• Tauri 宿主适配层
• 配置文件读写
• 本地日志写入
• Session 内存状态管理
• 主窗口与票号列表窗口之间的事件通信
• 基础 Linux 打包目标配置
• src-tauri/icons/ 图标资源已补齐

2. 根目录结构

以下是当前项目根目录中最重要的目录和文件：

call-client/
├─ electron-sourcecode/         # 原 Electron/Vue 源码备份目录，迁移参考用
├─ src/                         # 当前 Vue 前端源码
├─ src-tauri/                   # 当前 Tauri Rust 宿主源码
├─ dist/                        # 前端构建输出目录
├─ node_modules/                # 前端依赖
├─ package.json                 # 前端依赖与 npm 脚本
├─ package-lock.json            # npm 锁文件
├─ vite.config.ts               # Vite 构建配置
├─ tsconfig.json                # 前端 TS 配置
├─ tsconfig.node.json           # Node/Vite 侧 TS 配置
├─ TAURI-MIGRATION.md           # 迁移设计文档
├─ TAURI-MIGRATION-TASKS.md     # 当前迁移任务清单
└─ PROJECT_GUIDE.md             # 当前这份项目说明文档

3. 前端目录说明

src/ 下的关键结构如下：

src/
├─ api/
│  └─ index.ts                  # 后端接口封装
├─ assets/
│  ├─ base.css                  # 基础样式
│  ├─ main.css                  # 全局样式入口
│  └─ wavy-lines.svg            # 背景图资源
├─ host/
│  ├─ config.ts                 # Tauri 配置读写封装
│  ├─ dialog.ts                 # 原生确认框封装
│  ├─ events.ts                 # 窗口事件通信封装
│  ├─ logger.ts                 # 宿主日志封装
│  ├─ session.ts                # Session 读写封装
│  ├─ types.ts                  # 宿主层公共类型
│  └─ window.ts                 # 窗口控制封装
├─ router/
│  └─ index.ts                  # 路由和路由守卫
├─ types/
│  ├─ action.ts                 # 主叫号业务类型
│  ├─ rank.ts                   # 评价/排队统计类型
│  ├─ ticket.ts                 # 票池类型
│  ├─ user.ts                   # 登录用户类型
│  ├─ window.ts                 # 服务窗口类型
│  ├─ http.ts                   # HTTP 响应类型
│  └─ element-plus-locale.d.ts  # Element Plus locale 声明
├─ utils/
│  └─ service.ts                # axios 实例和 baseURL/token 处理
├─ views/
│  ├─ LoginView.vue             # 登录页
│  ├─ MainView.vue              # 主叫号页
│  ├─ ServerSetupView.vue       # 服务地址配置页
│  └─ TicketListView.vue        # 票号列表页
├─ App.vue                      # 路由出口
└─ main.ts                      # Vue 应用入口

4. src-tauri 目录说明

src-tauri/ 下的关键结构如下：

src-tauri/
├─ src/
│  ├─ commands/
│  │  ├─ config.rs              # 配置文件命令
│  │  ├─ events.rs              # 事件发送命令
│  │  ├─ logger.rs              # 文件日志命令
│  │  ├─ mod.rs                 # commands 模块导出
│  │  ├─ session.rs             # Session 命令
│  │  └─ window.rs              # 窗口创建/切换/退出命令
│  ├─ lib.rs                    # Tauri Builder 和命令注册入口
│  ├─ main.rs                   # Rust 程序入口
│  └─ state.rs                  # 全局内存状态
├─ capabilities/
│  └─ default.json              # Tauri capability 配置
├─ Cargo.toml                   # Rust 依赖配置
├─ build.rs                     # Tauri 构建脚本
└─ tauri.conf.json              # Tauri 应用与打包配置

补充说明：

• src-tauri/target/ 是 Rust 编译产物目录
• 该目录可能会很大，通常不需要手动修改

5. 当前窗口流程

当前实现的窗口生命周期如下：

1. 应用启动后默认打开 login 窗口
2. Rust 端会预创建隐藏的 main 窗口
3. 登录成功并选择窗口后，关闭 login，显示 main
4. 在 main 中可以打开 ticketList 子窗口
5. ticketList 可以通过事件驱动 main 执行呼叫或评价
6. 在 main 中退出登录时，会重新显示 login
7. 在 main 菜单中选择“退出程序”时，会真正退出整个应用

6. 如何运行开发环境

6.1 仅启动前端开发服务

在项目根目录执行：

npm run dev

说明：

• 该命令只启动 Vite 前端开发服务器
• 默认地址是 http://localhost:1420

6.2 构建前端

在项目根目录执行：

npm run build

说明：

• 会先执行 vue-tsc --noEmit
• 然后执行 vite build
• 构建结果输出到根目录 dist/

6.3 启动 Tauri 开发模式

在项目根目录执行：

npm run tauri dev

说明：

• 该命令会先执行 npm run dev
• 然后由 Tauri 启动桌面应用
• 需要本机已经安装 Rust / Cargo

如果本机没有安装 Rust/Cargo，tauri dev 无法运行。

7. 如何打包

7.1 前提条件

打包前需要满足以下条件：

1. 本机已安装 Rust / Cargo
2. 本机已安装 Tauri 所需系统依赖
3. 已补齐 src-tauri/icons/* 图标资源

当前项目的 tauri.conf.json 已配置 Linux 打包目标：

• deb
• appimage

当前状态：

• bundle.active 已开启
• 已配置 Linux 打包目标 deb 与 appimage
• src-tauri/icons/ 中已存在当前打包所需图标文件

7.2 构建前端产物

npm run build

7.3 执行 Tauri 打包

npm run tauri build

说明：

• 实际打包使用的是 src-tauri/tauri.conf.json
• 前端产物目录由 frontendDist: "../dist" 指向根目录 dist

8. 当前 npm 脚本

package.json 中当前可用脚本如下：

{
  "dev": "vite",
  "build": "vue-tsc --noEmit && vite build",
  "preview": "vite preview",
  "tauri": "tauri"
}

常用命令示例：

npm run dev
npm run build
npm run preview
npm run tauri dev
npm run tauri build

9. 关键配置文件

package.json

作用：

• 管理前端依赖
• 定义 npm 脚本

vite.config.ts

作用：

• 配置 Vite 开发端口
• 配置 Tauri 开发环境 HMR
• 配置前端拆包策略
• 配置 Element Plus 自动按需引入

src-tauri/tauri.conf.json

作用：

• 配置应用名、标识符、初始窗口
• 配置 tauri dev 的前端地址
• 配置 tauri build 的前端产物目录
• 配置 Linux 打包目标

TAURI-MIGRATION.md

作用：

• 说明从 Electron 迁移到 Tauri 的目标、范围和策略

TAURI-MIGRATION-TASKS.md

作用：

• 记录当前已完成项与待完成项

10. 当前已知注意事项

• 当前机器如果没有 Rust/Cargo，无法实际运行 tauri dev 或 tauri build
• electron-sourcecode/ 只是原项目参考目录，不参与当前 Tauri 运行
• dist/ 和 src-tauri/target/ 都是构建产物目录，不建议手改

11. 推荐使用顺序

日常开发建议按下面顺序进行：

1. 修改前端或 Rust 代码
2. 执行 npm run build 检查前端是否通过
3. 在已安装 Rust/Cargo 的环境执行 npm run tauri dev
4. 联调完成后执行 npm run tauri build