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

版本：v2.1.0

作者：Gary Yuan

日期：2026年6月

1. 项目概述

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

技术栈

分类	技术	说明
前端	Next.js 16 + React 19 + TypeScript	用户界面
后端	Express + Prisma ORM	API接口
数据库	SQLite（默认）/ PostgreSQL / MySQL	数据存储
认证	JWT + bcrypt	用户登录验证
样式	Tailwind CSS	页面样式
桌面端	Electron	exe安装包

核心功能

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

2. 快速开始

2.1 环境要求

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

2.2 安装步骤

bash 复制代码

# 1. 克隆项目
git clone https://github.com/Garyjie/airport-equipment-management.git
cd airport-equipment-management

# 2. 切换到开发分支
git checkout dev

# 3. 安装依赖
npm install

# 4. 初始化数据库（自动创建表结构）
npm run prisma:generate
npm run prisma:migrate
npm run prisma:seed

# 5. 启动后端服务（终端1）
npm run server

# 6. 启动前端服务（终端2）
npm run dev

# 7. 打开浏览器访问
# http://localhost:3000

2.3 默认账号

用户名	密码	角色
admin	admin123	管理员（所有权限）
operator	operator123	普通用户（部分权限）

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 文件：

env 复制代码

# SQLite（默认）
DATABASE_URL="file:./prisma/dev.db"

# PostgreSQL
DATABASE_URL="postgresql://用户名:密码@localhost:5432/数据库名"

# MySQL
DATABASE_URL="mysql://用户名:密码@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

生产环境：/api

5.2 接口列表

模块	接口	方法	需要认证
认证	/auth/login	POST	否
认证	/auth/logout	POST	是
认证	/auth/me	GET	是
用户	/users	GET	是（admin）
用户	/users	POST	是（admin）
用户	/users/:id	PUT	是（admin）
用户	/users/:id	DELETE	是（admin）
设备类型	/device-types	GET	是
设备类型	/device-types	POST	是（admin）
站点	/stations	GET	是
站点	/stations	POST	是（admin）
柜台	/counters	GET	是
柜台	/counters	POST	是（admin）
设备	/devices	GET	是
设备	/devices	POST	是
设备	/devices/:id/move	POST	是
设备	/devices/:id/status	POST	是

5.3 认证方式

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

复制代码

Authorization: Bearer <token>

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

6. 用户权限

6.1 权限区分

权限	admin	operator
查看设备列表	✅	✅
变更设备状态	✅	✅
移动设备位置	✅	✅
添加/删除设备	✅	❌
用户管理	✅	❌
站点管理	✅	❌
柜台管理	✅	❌

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

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

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

typescript 复制代码

const users = currentUser.role === 'admin' ? await userApi.getAll() : []

7. 设备状态流转

7.1 状态定义

状态	英文	颜色	说明
使用中	active	绿色	设备正在使用
备机	standby	蓝色	设备待命，可随时使用
损坏	damaged	橙色	设备损坏，需要维修
送修	repair	红色	设备已送修

7.2 状态流转规则

复制代码

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

7.3 状态变更时的站点处理

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

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

typescript 复制代码

const isActiveStatus = status === 'active'
const newCounterId = isActiveStatus ? device.counterId : null
const newStationId = 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 原因分析

前端 API 地址写死 localhost ：手机打开页面后，前端会请求 http://localhost:5000/api，也就是手机自己的端口，当然访问不了。
后端只监听本地 ：默认只监听 localhost，外部设备无法访问。

9.3 修复方案

步骤1：修改前端 API 地址

文件：lib/api.ts

typescript 复制代码

function getApiBaseUrl(): string {
  if (typeof window === '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.location
  return `${protocol}//${hostname}:5000/api`
}

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

文件：server/index.ts

typescript 复制代码

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

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

启动命令：

bash 复制代码

npm run dev -- -H 0.0.0.0

9.4 查看电脑 IP

Windows：

bash 复制代码

ipconfig | Select-String "IPv4"

Mac/Linux：

bash 复制代码

ifconfig | grep inet

9.5 手机访问

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

复制代码

http://你的电脑IP:3000

10. 打包发布

10.1 构建前端

bash 复制代码

npm run build

10.2 打包 Electron 桌面端

bash 复制代码

npm run electron:release

生成的文件在 release/ 目录：

复制代码

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

10.3 上传到 GitHub

bash 复制代码

# 提交代码
git add -A
git commit -m "v2.1.0: 修复局域网访问问题"
git push origin dev

# 创建标签
git tag -a v2.1.0 -m "v2.1.0"
git push origin v2.1.0

# 创建 Release（通过 GitHub 网页）

附录：Git 常用命令

bash 复制代码

# 查看当前分支
git branch

# 切换分支
git checkout dev

# 查看状态
git status

# 添加所有文件
git add -A

# 提交
git commit -m "描述信息"

# 推送到远程
git push origin dev

# 拉取最新代码
git pull origin dev

附录：项目版本记录

版本	日期	变更内容
v2.1.0	2026-06	修复局域网访问、修复状态变更逻辑、修复普通用户登录
v2.0.0	2026-06	前后端分离重构、添加数据库、JWT认证、Electron打包
v1.0.0	2026-06	演示版（localStorage存储）

祝你使用愉快！ 🎉