# hotel.client

**Repository Path**: ArmyMedalMeiTeam/hotel.client

## Basic Information

- **Project Name**: hotel.client
- **Description**: 逸住荟酒店电脑桌面客户端控制程序
- **Primary Language**: Dart
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-16
- **Last Updated**: 2026-06-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AmmHotel Hotel Client

酒店管理系统客户端应用

## 📋 目录

- [项目说明](#项目说明)
- [编译 Icon](#编译-icon)
- [守护进程逻辑](#守护进程逻辑)
- [生产环境部署](#生产环境部署)
- [开发环境](#开发环境)

---

## 📱 项目说明

这是一个基于 Flutter 的酒店管理系统桌面客户端应用，支持以下功能：

- ✅ 锁屏界面管理
- ✅ PIN 码验证
- ✅ 设备绑定
- ✅ SignalR 实时通信
- ✅ 看门狗进程守护
- ✅ 自动重启功能

---

## 🎨 编译 Icon

### 方法一：使用 Flutter 内置命令

```bash
# 编译所有平台的 icon
flutter pub run flutter_launcher_icons:main
```

### 方法二：单独编译 Windows Icon

```bash
# Windows icon 编译命令
flutter pub run flutter_launcher_icons:main -f windows

# 自定义 icon 配置文件（在 pubspec.yaml 中）
flutter_launcher_icons:
  android: false
  ios: false
  windows:
    generate: true
    image_path: assets/logo.png
    icon_size: 128
  macos:
    generate: false
```

### Icon 配置说明

在 `pubspec.yaml` 中配置 icon：

```yaml
flutter_launcher_icons:
  android: false # 不生成 Android icon
  ios: false # 不生成 iOS icon
  windows:
    generate: true # 生成 Windows icon
    image_path: assets/logo.png # 源图片路径
    icon_size: 128 # icon 尺寸
  macos:
    generate: false # 不生成 macOS icon
```

### 源图片要求

- **格式**: PNG (推荐) 或 JPG
- **建议尺寸**: 至少 512x512 像素
- **位置**: `assets/logo.png` (或根据配置调整)
- **透明度**: 支持透明背景

---

## 🐕 守护进程逻辑

当前守护进程是随 Windows 原生构建一起生成的独立程序：`client_guardian.exe`。主程序和守护程序相互监听、相互拉起。

### 构建方式

```bash
flutter build windows --release
```

构建完成后，主程序和守护程序都会出现在：

```
build\windows\x64\runner\Release\
├── client.exe
└── client_guardian.exe
```

### 运行逻辑

1. `client.exe` 在 release 环境启动后调用 `Guardian.start()`。
2. `Guardian.start()` 查找同目录下的 `client_guardian.exe`。
3. 主程序以 detached 方式启动守护程序，并传入：
   - `--app-path=<client.exe 路径>`
   - `--parent-pid=<主程序 PID>`
   - `--check-interval=1000`
4. Dart 端把守护程序 PID 写入同目录 `guardian.lock`。
5. `client_guardian.exe` 每 1000ms 检查主程序 PID 是否存活。
6. 如果主程序退出，守护程序用 `--hidden` 参数静默拉起 `client.exe`。
7. 主程序每 10 秒调用 `Guardian.ensureRunning()` 检查守护程序是否存活。
8. 如果守护程序退出，主程序会重新启动 `client_guardian.exe`。

### 停止逻辑

管理面板中的“停止守护进程”会调用 `Guardian.stop()`：

- 读取 `guardian.lock` 中的守护程序 PID。
- 使用 `taskkill /PID <pid> /F` 停止守护程序。
- 删除 `guardian.lock`。
- 设置手动停止标记，避免当前主程序再次自动拉起守护程序。

### 相关文件

- `lib/utils/guardian.dart`：Dart 端守护进程启动、检测、停止逻辑。
- `windows/runner/guardian_main.cpp`：独立守护程序入口。
- `windows/runner/CMakeLists.txt`：生成 `client_guardian.exe`。
- `windows/CMakeLists.txt`：把 `client_guardian.exe` 安装到 release 输出目录。

---

## 🚀 生产环境部署

### 部署目录结构

```
部署目录/
├── client.exe              # 主程序
├── client_guardian.exe     # 独立守护程序
├── data/                   # Flutter 运行数据
├── flutter_windows.dll     # Flutter 运行库
├── *_plugin.dll            # 插件运行库
├── guardian.lock           # 守护程序 PID 文件（运行时生成）
└── logs/                   # 主程序日志目录（运行时生成）
```

### 部署步骤

#### 1. 编译 Windows 版本

```bash
flutter build windows --release
```

编译产物位于：

```
build\windows\x64\runner\Release\
```

#### 2. 复制 release 输出目录

将 `build\windows\x64\runner\Release\` 目录中的所有文件复制到部署目录，保持 `client.exe` 与 `client_guardian.exe` 在同一目录。

### 启动方式

正常启动主程序即可：

```bash
client.exe
```

主程序会在 release 环境自动启动 `client_guardian.exe`，不需要手动启动守护程序。

### 守护程序参数说明

这些参数由主程序自动传入，通常无需手动使用：

```
参数                         说明                         默认值
--------------------------------------------------------------------------
--app-path=<路径>          主程序完整路径               同目录 client.exe
--parent-pid=<PID>         当前要监控的主程序 PID        0
--check-interval=<毫秒>    检测间隔                     1000
```

---

## 💻 开发环境

### 依赖安装

```bash
flutter pub get
```

### 运行应用

```bash
# 开发模式运行
flutter run

# 指定设备
flutter run -d windows
```

### 构建发布版本

```bash
# Windows
flutter build windows --release

# 查看构建产物
ls build/windows/runner/Release/
```

---

## 🔧 常用命令

### Flutter 命令

```bash
# 获取依赖
flutter pub get

# 分析代码
flutter analyze

# 运行测试
flutter test

# 构建 Windows
flutter build windows --release

# 清理构建缓存
flutter clean
```

### Windows 构建检查

```bash
# 构建 release 版本
flutter build windows --release

# 检查主程序和守护程序是否同时生成
dir build\windows\x64\runner\Release\client*.exe
```

---

## 📁 项目结构

```
hotel.client/
├── assets/                # 静态资源
│   ├── fonts/            # 字体文件
│   ├── lock_bg_*.png     # 锁屏背景图片
│   └── logo.*            # Logo 图片
├── lib/                  # Dart 源代码
│   ├── api/             # API 接口
│   ├── components/       # UI 组件
│   ├── config/          # 配置文件
│   ├── models/          # 数据模型
│   ├── services/        # 服务类
│   ├── utils/           # 工具类
│   ├── views/           # 页面视图
│   └── main.dart        # 应用入口
├── windows/             # Windows 原生工程
│   ├── CMakeLists.txt   # Windows 打包安装配置
│   └── runner/          # Windows runner 源码
│       ├── guardian_main.cpp  # 独立守护程序入口
│       └── CMakeLists.txt     # 主程序和守护程序构建配置
├── build/               # 构建输出
├── pubspec.yaml         # Flutter 依赖配置
└── README.md           # 项目说明文档
```

---

## 🛠️ 技术栈

- **Flutter**: 3.7.2+
- **Dart**: 3.7.2+
- **状态管理**: GetX
- **HTTP 客户端**: Dio
- **窗口管理**: window_manager
- **系统托盘**: tray_manager
- **加密**: crypto
- **日志**: 自定义 LoggerManager

---

## 📞 支持

如遇问题，请检查：

1. **Flutter 环境**: `flutter doctor`
2. **Dart 环境**: `dart --version`
3. **依赖状态**: `flutter pub deps`
4. **守护程序状态**: `guardian.lock` 与任务管理器中的 `client_guardian.exe`
5. **主程序日志**: `logs/log_*.txt`

---

## 📄 许可证

本项目仅供内部使用。

---

**最后更新**: 2026-05-17