智能煮粉机 Kiosk 展示系统 — 项目介绍

全栈桌面端应用 · Vue 3 + TypeScript + Electron · 智能餐饮自助终端

一、项目概述

本项目是一套智能煮粉机（自助米粉售卖设备）的 Kiosk 展示与管理系统，运行于店铺现场的触屏终端上。它集菜品轮播展示、管理员下单支付、订单实时追踪于一体，连接后端 Django REST API，实现从点餐到出餐的全流程数字化管理。

系统采用 桌面端应用 形态（Electron 封装），开机即自动全屏运行，适合餐饮门店的立式触屏一体机或平板终端。

二、核心功能

功能模块	说明
管理员登录	JWT Token 认证，自动刷新（30 分钟周期），支持多店铺选择
菜品轮播展示	全屏商品幻灯片自动播放，支持背景图、标题、价格（店铺覆盖价优先）、二维码
商品菜单面板	右侧固定菜单栏，展示商品缩略图，点击进入定制
商品定制下单	规格选择（口味/份量等）、配料加购（数量限制）、实时价格计算
管理员代付	生成支付二维码（顾客扫码）+ 管理员微信支付一键完成
订单实时看板	底部订单进度条，自动映射状态：已支付→制作中→请取餐（25%→60%→100%）
5 秒轮询刷新	自动拉取最新订单状态，实时反映后端进度
网络/设备状态	顶部状态栏显示网络连接、设备运行状态、当前时间

三、技术栈

前端

技术	版本	用途
Vue 3	^3.4.21	组合式 API + `<script setup>` 组件
TypeScript	^5.2	严格模式全量类型覆盖
Vite	^5.x	开发服务器与构建
Pinia 响应式	—	轻量级 reactive 状态管理（authStore）
Vitest	^4.1	单元测试 + 组件测试
Vue Test Utils	^2.4	Vue 组件挂载与交互测试
jsdom	^29	浏览器环境模拟

桌面端

技术	版本	用途
Electron	^30.5	桌面应用容器，全屏 Kiosk 模式
electron-builder	^24.13	跨平台打包（Windows NSIS / macOS DMG / Linux AppImage）
vite-plugin-electron	^0.28	Vite + Electron 集成开发

后端接口

Django REST Framework 后端 API
基础地址：https://freerain.cloud/api/
API 领域：用户认证、店铺商品、订单管理、支付、内容管理、优惠券

四、系统架构

┌─────────────────────────────────────────────────────────┐
│                  Electron 桌面应用容器                      │
│  ┌───────────────────────────────────────────────────┐  │
│  │                Vue 3 渲染进程                        │  │
│  │  ┌──────────┐  ┌──────────────┐  ┌─────────────┐  │  │
│  │  │TopStatus │  │DynamicContent│  │ MenuPanel   │  │  │
│  │  │Bar       │  │Zone (轮播)   │  │ (菜单/下单) │  │  │
│  │  ├──────────┤  ├──────────────┤  ├─────────────┤  │  │
│  │  │ OrderStatusBar (底栏订单进度)  │              │  │  │
│  │  └──────────────────────────────────────────────┘  │  │
│  │                       │                              │  │
│  │              ┌────────┴────────┐                    │  │
│  │              │   authStore     │                    │  │
│  │              │  (JWT + 店铺)   │                    │  │
│  │              └────────┬────────┘                    │  │
│  │                       │                              │  │
│  │              ┌────────┴────────┐                    │  │
│  │              │  API 层 (fetch) │                    │  │
│  │              └────────┬────────┘                    │  │
│  └───────────────────────┼────────────────────────────┘  │
│                          │ HTTP (Bearer Token)            │
└──────────────────────────┼──────────────────────────────┘
                           │
                  ┌────────┴────────┐
                  │  Django REST   │
                  │  Backend API   │
                  └─────────────────┘

数据流设计

认证流程：管理员输入账号密码 → POST /api/users/admin-login/ → 获取 JWT Token → 存入 localStorage + 启动 30 分钟自动刷新定时器
商品加载：fetchShopProducts(shopId) → 获取商品 ID 列表 → Promise.all 并发拉取详情 + 图片 + 规格 + 配料
下单支付：选择商品 → 选择规格/配料 → POST /api/admin/orders/ 创建订单 → POST /api/admin/payments/ 创建支付 → POST confirm 确认支付 → 订单进入 paid 状态
订单轮询：每 5 秒 GET /api/admin/orders/?shop=X → 获取 ID 列表 → 并发获取详情 → 过滤活跃状态 → 更新底部进度条

五、项目结构

├── src/                          # Vue 前端
│   ├── api/                      # REST API 调用层
│   │   ├── admin.ts              # 管理员订单/支付 API
│   │   ├── auth.ts               # 登录/刷新 Token
│   │   ├── content.ts            # 轮播图/公告/反馈
│   │   ├── coupons.ts            # 优惠券
│   │   ├── orders.ts             # 普通用户订单
│   │   └── shops.ts              # 店铺/商品/规格/配料
│   ├── components/               # 业务组件
│   │   ├── AdminLogin.vue        # 管理员登录页
│   │   ├── TopStatusBar.vue      # 顶部状态栏
│   │   ├── DynamicContentZone.vue # 商品全屏轮播
│   │   ├── MenuPanel.vue         # 菜单/定制/支付面板
│   │   └── OrderStatusBar.vue    # 底部订单进度条
│   ├── stores/
│   │   └── authStore.ts          # 认证状态管理（响应式）
│   ├── types/
│   │   └── api.ts                # 29 个 TypeScript 接口定义
│   ├── __tests__/                # 测试文件分布在各组件目录
│   ├── App.vue                   # 根组件（状态路由 + 轮询）
│   ├── main.ts                   # 应用入口
│   └── style.css                 # 全局样式（暗色主题）
├── electron/                     # Electron 主进程
│   ├── main.ts                   # 全屏窗口 + CSP 安全策略
│   └── preload.ts                # 安全 IPC 桥接
├── package.json                  # 依赖与脚本
├── vite.config.ts                # Vite + Vitest 配置
├── tsconfig.json                 # TypeScript 严格模式
└── electron-builder.json5        # 跨平台打包配置

六、技术亮点

1. 类型安全全覆盖

TypeScript 严格模式（strict: true）
29 个后端数据模型完整映射（AdminOrder、OrderItem、SpecGroup、Topping 等）
API 请求/响应全链路类型推导，无 any 类型

2. 响应式状态管理

基于 Vue 3 reactive() 的轻量级 authStore
JWT Token 自动刷新（30 分钟定时器链）
localStorage 持久化与会话恢复
无额外状态库依赖，保持包体积最小

3. 高性能 API 调用

"先列表后详情" 的批量拉取模式（Promise.all 并发）
统一的 getAuthHeaders() / getShopParam() 工具函数
5 秒订单轮询 + 1 秒时间更新，独立间隔互不阻塞

4. 组件化设计

五个核心组件各司其职，职责单一
Props + Emits 数据流清晰可追踪
多视图切换（菜单→定制→支付）状态无丢失

5. 全功能组件测试

4 个组件测试：加载/空/错误态覆盖、交互操作验证
6 个 API 测试：HTTP 方法、URL、Headers、请求体、错误处理
2 个 Store 测试：登录/登出、Token 刷新、持久化恢复
共 12 个测试文件，Vitest + jsdom 环境

6. 跨平台桌面部署

Electron 全屏 Kiosk 模式，隐藏菜单栏
Content Security Policy 安全头
一键打包 Windows / macOS / Linux 安装包

七、环境要求与运行

命令	说明
`npm run dev`	启动 Vite + Electron 开发模式
`npm run build`	TypeScript 检查 → Vite 构建 → electron-builder 打包
`npm run preview`	预览生产构建结果
`npm test`	运行全部 Vitest 测试

核心依赖

{
  "vue": "^3.4.21",
  "vite": "^5.x",
  "typescript": "^5.2",
  "electron": "^30.5",
  "electron-builder": "^24.13",
  "vitest": "^4.1",
  "vue/test-utils": "^2.4"
}

八、适合的场景

智能餐饮设备：自助点餐机、煮粉/煮面/煮饺子等即食设备
门店 Kiosk 系统：触屏终端展示 + 下单 + 支付一体化
排队叫号系统：订单进度可视化看板
IoT 设备前端：通过 Electron 封装后运行于嵌入式/工控设备

九、个人角色与技术成长

在本项目中，我承担了 全栈前端开发 角色，独立完成了：

架构设计：从零搭建 Vue 3 + Vite + Electron 的项目骨架，设计模块分层与数据流
组件开发：实现 5 个核心业务组件，覆盖登录、展示、下单、支付、追踪全链路
API 集成：对接 6 类后端 REST 接口，完成全量类型定义与错误处理
测试覆盖：践行 TDD（测试驱动开发），编写 12 个测试文件，保障核心逻辑可靠性
桌面打包：配置 Electron + electron-builder，实现 Windows/macOS/Linux 三平台构建

通过此项目，深入掌握了 Vue 3 组合式 API、TypeScript 严格模式下的类型体操、Electron 主进程与渲染进程通信、Vitest 组件测试，以及餐饮行业业务逻辑的前端建模能力。

十、关于我

邮箱：qinyu0504@163.com
微信：jasonqin2011
项目技术栈：Vue 3 · TypeScript · Vite · Electron · Pinia · Vitest
后端框架：Django REST Framework
部署形态：跨平台桌面应用（Kiosk 模式）
持续集成：TypeScript 静态检查 + 自动化测试