TypeScript项目局域网访问和GitHub提交和发布操作

版本：v2.1.0
作者：Gary Yuan
日期：2026年6月

目录

1. 项目概述
2. 快速开始
3. 项目结构
4. 数据库说明
5. API接口
6. 用户权限
7. 设备状态流转
8. 常见问题
9. 局域网访问
10. 打包发布

1. 项目概述

这是一个前后端分离的机场设备管理系统，用于管理机场的各种设备（值机柜台、登机口等）。

技术栈

核心功能

• ✅ 设备管理（增删改查、状态变更、位置移动）
• ✅ 站点管理（值机岛、登机口、自助服务区）
• ✅ 柜台管理（站点下的柜台）
• ✅ 用户管理（管理员、普通用户）
• ✅ 耗材管理（换纸记录、耗材记录）
• ✅ 变更记录（设备状态变更历史）
• ✅ 数据导入导出（CSV格式）

2. 快速开始

2.1 环境要求

• Node.js >= 18.x
• npm >= 9.x

2.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. 启动后端服务（终端1）npmrun server# 6. 启动前端服务（终端2）npmrun dev# 7. 打开浏览器访问# http://localhost:3000

2.3 默认账号

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_URL="file:./prisma/dev.db" # PostgreSQL DATABASE_URL="postgresql://用户名:密码@localhost:5432/数据库名" # MySQL DATABASE_URL="mysql://用户名:密码@localhost:3306/数据库名"

4.3 数据库表

4.4 初始化数据

执行npm run prisma:seed后会自动创建：

• 8 个站点（值机岛、登机口、自助服务区、库房）
• 25 个柜台/登机口
• 8 种设备类型
• 48 台设备
• 5 条换纸记录
• 3 条耗材记录

5. API接口

5.1 基础地址

开发环境：http://localhost:5000/api
生产环境：/api

5.2 接口列表

5.3 认证方式

使用 JWT Token，在请求头中携带：

Authorization: Bearer <token>

登录成功后，Token 会自动存储在 localStorage 中。

6. 用户权限

6.1 权限区分

6.2 常见问题：普通用户登录后数据为空

问题原因：前端加载数据时，普通用户也会尝试获取用户列表，但后端用户列表接口需要 admin 权限，返回 403 错误，导致所有数据加载失败。

修复方案：修改lib/store.ts，只有 admin 角色才获取用户列表：

constusers=currentUser.role==='admin'?awaituserApi.getAll():[]

7. 设备状态流转

7.1 状态定义

7.2 状态流转规则

使用中 → 备机区/损坏区/送修区 → 设备库房（站点清空） 损坏区 → 送修区 → 设备库房（站点清空） 送修区 → 备机区 → 设备库房（站点清空） 备机区 → 使用中 → 需要手动分配到柜台

7.3 状态变更时的站点处理

重要规则：只要新状态不是 “使用中”，设备的站点和柜台都会被清空，设备进入库房。

修改位置：server/routes/devices.ts

constisActiveStatus=status==='active'constnewCounterId=isActiveStatus?device.counterId:nullconstnewStationId=isActiveStatus?device.stationId:null

8. 常见问题

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:3000

9. 局域网访问

9.1 问题描述

手机和电脑在同一局域网下，但手机无法访问系统。

9.2 原因分析

1. 前端 API 地址写死 localhost：手机打开页面后，前端会请求http://localhost:5000/api，也就是手机自己的端口，当然访问不了。

2. 后端只监听本地：默认只监听localhost，外部设备无法访问。

9.3 修复方案

步骤1：修改前端 API 地址

文件：lib/api.ts

functiongetApiBaseUrl():string{if(typeofwindow==='undefined'){return'http://localhost:5000/api'}if(isElectron){return'http://localhost:5000/api'}if(process.env.NODE_ENV==='production'){return'/api'}const{protocol,hostname}=window.locationreturn`${protocol}//${hostname}:5000/api`}

步骤2：修改后端监听地址

文件：server/index.ts

app.listen(PORT,'0.0.0.0',()=>{console.log(`服务器运行在 http://localhost:${PORT}`)})

步骤3：修改前端监听地址

启动命令：

npmrun dev ---H0.0.0.0

9.4 查看电脑 IP

Windows：

ipconfig|Select-String"IPv4"

Mac/Linux：

ifconfig|grepinet

9.5 手机访问

确保手机和电脑在同一 Wi-Fi 下，打开手机浏览器：

http://你的电脑IP:3000

10. 打包发布

10.1 构建前端

npmrun build

10.2 打包 Electron 桌面端

npmrun electron:release

生成的文件在release/目录：

release/ ├── 机场设备管理系统 Setup 2.1.0.exe # NSIS安装包 └── win-unpacked/ # 免安装版 └── 机场设备管理系统.exe # 直接运行的exe

10.3 上传到 GitHub

# 提交代码gitadd-Agitcommit-m"v2.1.0: 修复局域网访问问题"gitpush origin dev# 创建标签gittag-av2.1.0-m"v2.1.0"gitpush origin v2.1.0# 创建 Release（通过 GitHub 网页）

附录：Git 常用命令

# 查看当前分支gitbranch# 切换分支gitcheckout dev# 查看状态gitstatus# 添加所有文件gitadd-A# 提交gitcommit-m"描述信息"# 推送到远程gitpush origin dev# 拉取最新代码gitpull origin dev

附录：项目版本记录

祝你使用愉快！🎉