WuYongJie/SheBeiGuanLi

Fork 0

WuYongJie 3307ca6359 first commit

2026-03-10 15:51:03 +08:00

7.8 KiB

Raw Permalink Blame History

摄影设备借还系统 - 项目启动指南

项目概述

本项目是一个摄影设备借还管理系统，采用前后端分离架构，前端严格遵循Apple官方UI设计规范。

技术栈

前端

Vue.js 3 + TypeScript
Vite (构建工具)
Tailwind CSS (Apple Design System)
Pinia (状态管理)
Vue Router 4 (路由)
Axios (HTTP客户端)
ECharts (图表库)
JsBarcode (条码生成)

后端

Node.js + Express + TypeScript
Prisma ORM
MySQL 8.0

环境要求

Node.js 18+
MySQL 8.0+
npm 或 yarn

快速开始

1. Keycloak 身份认证配置

项目使用 Keycloak 作为开源本地身份认证系统，提供 SSO、角色管理等能力。首次启动前请完成以下步骤：

启动 Keycloak（示例使用 Docker）：

docker run -d \
  --name keycloak \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:23.0.7 start-dev

在 Keycloak 控制台中创建 Realm equipment-management
创建前端客户端 equipment-client
- 类型：Public Client（或机密客户端并配置 KEYCLOAK_CLIENT_SECRET）
- 有效重定向 URI：http://localhost:5173/*
创建用户并分配角色（例如 admin、user）

提示：建议为开发环境导入一份测试 Realm 配置，或参考文档快速创建必要资源。

2. 环境变量准备

backend/.env

DATABASE_URL="mysql://root:password@localhost:3306/equipment_management?charset=utf8mb4"
SESSION_SECRET=equipment-management-secret
KEYCLOAK_URL=http://localhost:8080
KEYCLOAK_REALM=equipment-management
KEYCLOAK_CLIENT_ID=equipment-client
# 若为机密客户端，请同时配置 KEYCLOAK_CLIENT_SECRET

frontend/.env

VITE_API_BASE_URL=http://localhost:3000/api
VITE_KEYCLOAK_URL=http://localhost:8080
VITE_KEYCLOAK_REALM=equipment-management
VITE_KEYCLOAK_CLIENT_ID=equipment-client

3. 数据库准备

创建MySQL数据库：

CREATE DATABASE equipment_management CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

4. 后端配置

cd backend

# 安装依赖（使用国内镜像）
npm install --registry=https://registry.npmmirror.com

# Prisma 初始化
npx prisma generate
npx prisma migrate dev --name init

# 启动开发服务器
npm run dev

后端服务运行在: http://localhost:3000

5. 前端配置

cd frontend

# 安装依赖（使用国内镜像）
npm install --registry=https://registry.npmmirror.com

# 启动开发服务器
npm run dev

前端服务运行在: http://localhost:5173

项目结构

shebeiguanli/
├── frontend/              # 前端项目
│   ├── src/
│   │   ├── api/          # API接口定义
│   │   ├── components/   # 组件
│   │   ├── layouts/      # 布局组件
│   │   ├── router/       # 路由配置
│   │   ├── stores/       # Pinia状态管理
│   │   ├── types/        # TypeScript类型定义
│   │   ├── utils/        # 工具函数
│   │   └── views/        # 页面组件
│   ├── tailwind.config.js # Tailwind配置（Apple Design System）
│   └── vite.config.ts    # Vite配置
│
├── backend/               # 后端项目
│   ├── src/
│   │   ├── controllers/  # 控制器
│   │   ├── routes/       # 路由
│   │   ├── utils/        # 工具函数
│   │   └── index.ts      # 入口文件
│   ├── prisma/
│   │   └── schema.prisma  # 数据库模型定义
│   └── .env              # 环境变量配置
│
└── 开发文档.md            # 详细开发文档

主要功能

✅ 已实现功能

设备管理
- 设备列表查看
- 设备新增/编辑/删除
- 设备编码自动生成和自定义录入
- 设备价格信息管理
- 设备搜索和筛选
借用归还管理
- 设备借用
- 设备归还
- 红外扫码枪扫码出库
- 红外扫码枪扫码入库
- 批量扫码功能
- 借用记录查询
统计分析
- 首页仪表板（设备状态统计）
- 设备价值统计
- 设备使用率分析
- 数据可视化图表
条码打印
- 条码生成（前端JsBarcode）
- 条码预览
- 条码打印
用户认证与权限管理
- Keycloak 集成本地身份认证系统
- 支持 OAuth 2.0 / OpenID Connect 登录
- 前端使用 keycloak-js 自动登录、刷新 Token
- 后端使用 keycloak-connect 验证访问令牌、保护 API 路由
Apple Design System UI
- 严格遵循Apple官方UI设计规范
- 系统字体（SF Pro）
- Apple色彩系统
- 圆角、阴影、毛玻璃效果
- 流畅的动画和过渡

⏳ 待实现功能

操作日志与审计
设备批量导入/导出
数据备份和恢复
消息通知与提醒

API接口

设备管理

GET /api/equipment/list - 获取设备列表
GET /api/equipment/:id - 获取设备详情
POST /api/equipment - 新增设备
PUT /api/equipment/:id - 更新设备
DELETE /api/equipment/:id - 删除设备
POST /api/equipment/generate-code - 生成设备编码
POST /api/equipment/verify-code - 验证设备编码
GET /api/equipment/scan/:equipment_code - 扫码查询设备

借用归还

POST /api/borrow - 借用设备
POST /api/borrow/scan - 扫码出库
POST /api/borrow/scan-batch - 批量扫码出库
GET /api/borrow/scan/:equipment_code - 查询借用记录
GET /api/borrow/records - 获取借用记录列表
POST /api/return - 归还设备
POST /api/return/scan - 扫码入库
POST /api/return/scan-batch - 批量扫码入库

统计分析

GET /api/statistics/dashboard - 获取首页统计数据
GET /api/statistics/value - 获取设备价值统计

条码打印

GET /api/barcode/:equipment_code - 获取设备信息（用于生成条码）
POST /api/barcode/batch - 批量获取设备信息

开发注意事项

前端开发

Apple UI设计规范
- 使用Tailwind CSS的Apple Design System类
- 遵循Apple的色彩、字体、间距规范
- 使用系统字体（-apple-system）
扫码功能
- 红外扫码枪模拟键盘输入
- 监听input框的keyup事件
- 检测回车键触发扫码完成
- 自动聚焦到扫码输入框
条码生成
- 使用JsBarcode在前端生成条码
- 支持Code128格式
- 支持打印功能

后端开发

数据库操作
- 使用Prisma ORM
- 所有数据库操作通过Prisma Client
- 价值字段由应用层计算

API响应格式

{
  "code": 200,
  "message": "操作成功",
  "data": {}
}

错误处理
- 统一使用errorResponse返回错误
- HTTP状态码和业务错误码分离

常见问题

1. 数据库连接失败

检查MySQL服务是否启动
检查.env文件中的DATABASE_URL配置
确认数据库用户权限

2. Prisma迁移失败

检查数据库连接
确认数据库已创建
查看Prisma错误日志

3. 前端API请求失败

检查后端服务是否启动
检查.env文件中的VITE_API_BASE_URL配置
检查 Keycloak 是否运行且配置正确
查看浏览器控制台错误信息

4. 扫码功能不工作

确认红外扫码枪已连接
检查扫码输入框是否获得焦点
确认扫码枪设置为键盘输入模式

5. 无法登录系统

确认 Keycloak 服务已启动
检查 Realm、Client 与用户配置是否正确
查看浏览器网络请求与后端日志

下一步开发计划

集成Keycloak认证系统
完善用户权限管理
添加操作日志功能
实现数据导入/导出
优化性能和用户体验

技术支持

如有问题，请参考开发文档或联系开发团队。

7.8 KiB Raw Permalink Blame History Unescape Escape