版本v2.1.0作者Gary Yuan日期2026年6月目录项目概述快速开始项目结构数据库说明API接口用户权限设备状态流转常见问题局域网访问打包发布1. 项目概述这是一个前后端分离的机场设备管理系统用于管理机场的各种设备值机柜台、登机口等。技术栈分类技术说明前端Next.js 16 React 19 TypeScript用户界面后端Express Prisma ORMAPI接口数据库SQLite默认/ PostgreSQL / MySQL数据存储认证JWT bcrypt用户登录验证样式Tailwind CSS页面样式桌面端Electronexe安装包核心功能✅ 设备管理增删改查、状态变更、位置移动✅ 站点管理值机岛、登机口、自助服务区✅ 柜台管理站点下的柜台✅ 用户管理管理员、普通用户✅ 耗材管理换纸记录、耗材记录✅ 变更记录设备状态变更历史✅ 数据导入导出CSV格式2. 快速开始2.1 环境要求Node.js 18.xnpm 9.x2.2 安装步骤# 1. 克隆项目gitclone https://github.com/Garyjie/airport-equipment-management.gitcdairport-equipment-management# 2. 切换到开发分支gitcheckout dev# 3. 安装依赖npminstall# 4. 初始化数据库自动创建表结构npmrun prisma:generatenpmrun prisma:migratenpmrun prisma:seed# 5. 启动后端服务终端1npmrun server# 6. 启动前端服务终端2npmrun dev# 7. 打开浏览器访问# http://localhost:30002.3 默认账号用户名密码角色adminadmin123管理员所有权限operatoroperator123普通用户部分权限3. 项目结构airport-equipment-management/ ├── app/ # Next.js 前端页面 │ ├── devices/ # 设备管理页面 │ ├── stations/ # 站点管理页面 │ ├── users/ # 用户管理页面 │ └── layout.tsx # 全局布局 ├── components/ # React 组件 │ ├── dashboard/ # 仪表盘组件 │ ├── auth/ # 认证组件 │ └── ui/ # UI组件 ├── lib/ # 工具库 │ ├── api.ts # API请求封装 │ ├── store.ts # 全局状态管理 │ └── types.ts # TypeScript类型定义 ├── server/ # Express 后端 │ ├── routes/ # API路由 │ ├── middleware/ # 中间件认证等 │ ├── prisma/ # Prisma ORM │ └── index.ts # 服务器入口 ├── docs/ # 项目文档 │ ├── sql/ # SQL脚本 │ ├── 项目详解.md # 完整技术文档 │ └── 新手入门详解.md # 本文件 ├── electron-main.js # Electron主进程 ├── package.json # 项目配置 └── prisma/ # Prisma配置 ├── schema.prisma # 数据库模型定义 └── migrations/ # 数据库迁移记录4. 数据库说明4.1 默认使用 SQLite数据库文件位于prisma/dev.db这是一个文件型数据库不需要额外安装数据库软件。4.2 切换到 PostgreSQL/MySQL修改.env文件# SQLite默认 DATABASE_URLfile:./prisma/dev.db # PostgreSQL DATABASE_URLpostgresql://用户名:密码localhost:5432/数据库名 # MySQL DATABASE_URLmysql://用户名:密码localhost:3306/数据库名4.3 数据库表表名说明User用户表DeviceType设备类型表Station站点表Counter柜台表Device设备表DeviceChangeRecord设备变更记录表PaperChangeRecord换纸记录表ConsumableRecord耗材记录表4.4 初始化数据执行npm run prisma:seed后会自动创建8 个站点值机岛、登机口、自助服务区、库房25 个柜台/登机口8 种设备类型48 台设备5 条换纸记录3 条耗材记录5. API接口5.1 基础地址开发环境http://localhost:5000/api生产环境/api5.2 接口列表模块接口方法需要认证认证/auth/loginPOST否认证/auth/logoutPOST是认证/auth/meGET是用户/usersGET是admin用户/usersPOST是admin用户/users/:idPUT是admin用户/users/:idDELETE是admin设备类型/device-typesGET是设备类型/device-typesPOST是admin站点/stationsGET是站点/stationsPOST是admin柜台/countersGET是柜台/countersPOST是admin设备/devicesGET是设备/devicesPOST是设备/devices/:id/movePOST是设备/devices/:id/statusPOST是5.3 认证方式使用 JWT Token在请求头中携带Authorization: Bearer token登录成功后Token 会自动存储在 localStorage 中。6. 用户权限6.1 权限区分权限adminoperator查看设备列表✅✅变更设备状态✅✅移动设备位置✅✅添加/删除设备✅❌用户管理✅❌站点管理✅❌柜台管理✅❌6.2 常见问题普通用户登录后数据为空问题原因前端加载数据时普通用户也会尝试获取用户列表但后端用户列表接口需要 admin 权限返回 403 错误导致所有数据加载失败。修复方案修改lib/store.ts只有 admin 角色才获取用户列表constuserscurrentUser.roleadmin?awaituserApi.getAll():[]7. 设备状态流转7.1 状态定义状态英文颜色说明使用中active绿色设备正在使用备机standby蓝色设备待命可随时使用损坏damaged橙色设备损坏需要维修送修repair红色设备已送修7.2 状态流转规则使用中 → 备机区/损坏区/送修区 → 设备库房站点清空 损坏区 → 送修区 → 设备库房站点清空 送修区 → 备机区 → 设备库房站点清空 备机区 → 使用中 → 需要手动分配到柜台7.3 状态变更时的站点处理重要规则只要新状态不是 “使用中”设备的站点和柜台都会被清空设备进入库房。修改位置server/routes/devices.tsconstisActiveStatusstatusactiveconstnewCounterIdisActiveStatus?device.counterId:nullconstnewStationIdisActiveStatus?device.stationId:null8. 常见问题8.1 Q: 登录后页面数据为空A检查是否使用普通用户登录。普通用户看不到用户管理数据但设备数据应该正常显示。如果所有数据都为空检查后端服务是否正常运行。8.2 Q: 设备状态变更后站点没有变化A确保修改了server/routes/devices.ts中的状态变更逻辑。旧逻辑只有从 active 状态转出时才清空站点新逻辑只要新状态不是 active 就清空站点。8.3 Q: IDE 中代码显示红色波浪线A可能是 TypeScript 类型推断失败。检查lib/store.ts中的数据加载逻辑确保变量有正确的类型注解。8.4 Q: 导入 CSV 文件没反应A检查文件是否为 CSV 格式文件编码是否为 UTF-8 或 GBK。前端会自动检测编码并处理中文乱码。8.5 Q: 访问 http://localhost:5000 显示 Cannot GET /A正常现象5000 端口是后端 API 服务只返回 JSON 数据没有 HTML 页面。前端页面在 3000 端口http://localhost:30009. 局域网访问9.1 问题描述手机和电脑在同一局域网下但手机无法访问系统。9.2 原因分析前端 API 地址写死 localhost手机打开页面后前端会请求http://localhost:5000/api也就是手机自己的端口当然访问不了。后端只监听本地默认只监听localhost外部设备无法访问。9.3 修复方案步骤1修改前端 API 地址文件lib/api.tsfunctiongetApiBaseUrl():string{if(typeofwindowundefined){returnhttp://localhost:5000/api}if(isElectron){returnhttp://localhost:5000/api}if(process.env.NODE_ENVproduction){return/api}const{protocol,hostname}window.locationreturn${protocol}//${hostname}:5000/api}步骤2修改后端监听地址文件server/index.tsapp.listen(PORT,0.0.0.0,(){console.log(服务器运行在 http://localhost:${PORT})})步骤3修改前端监听地址启动命令npmrun dev ---H0.0.0.09.4 查看电脑 IPWindowsipconfig|Select-StringIPv4Mac/Linuxifconfig|grepinet9.5 手机访问确保手机和电脑在同一 Wi-Fi 下打开手机浏览器http://你的电脑IP:300010. 打包发布10.1 构建前端npmrun build10.2 打包 Electron 桌面端npmrun electron:release生成的文件在release/目录release/ ├── 机场设备管理系统 Setup 2.1.0.exe # NSIS安装包 └── win-unpacked/ # 免安装版 └── 机场设备管理系统.exe # 直接运行的exe10.3 上传到 GitHub# 提交代码gitadd-Agitcommit-mv2.1.0: 修复局域网访问问题gitpush origin dev# 创建标签gittag-av2.1.0-mv2.1.0gitpush origin v2.1.0# 创建 Release通过 GitHub 网页附录Git 常用命令# 查看当前分支gitbranch# 切换分支gitcheckout dev# 查看状态gitstatus# 添加所有文件gitadd-A# 提交gitcommit-m描述信息# 推送到远程gitpush origin dev# 拉取最新代码gitpull origin dev附录项目版本记录版本日期变更内容v2.1.02026-06修复局域网访问、修复状态变更逻辑、修复普通用户登录v2.0.02026-06前后端分离重构、添加数据库、JWT认证、Electron打包v1.0.02026-06演示版localStorage存储祝你使用愉快