# `call-client` 项目说明

## 1. 项目概览

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

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

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

## 2. 根目录结构

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

```text
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/` 下的关键结构如下：

```text
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/` 下的关键结构如下：

```text
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 仅启动前端开发服务

在项目根目录执行：

```bash
npm run dev
```

说明：

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

### 6.2 构建前端

在项目根目录执行：

```bash
npm run build
```

说明：

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

### 6.3 启动 Tauri 开发模式

在项目根目录执行：

```bash
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 构建前端产物

```bash
npm run build
```

### 7.3 执行 Tauri 打包

```bash
npm run tauri build
```

说明：

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

## 8. 当前 npm 脚本

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

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

常用命令示例：

```bash
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`