一个基于 Go（Gin）与 Vue 3（Vite + Element Plus）的校园综合服务平台，面向学生、商家、宿管维保与管理员四类角色，支持商品浏览与下单、工单提交与处理、用户管理与审核、审计日志等核心功能，并提供「费用充值」学生专页。
- 项目亮点与功能
- 技术栈与工程化
- 项目结构
- 环境准备与配置
- 快速启动
- 前后端架构与路由
- 数据库与迁移/初始化
- 测试与质量保障
- 部署与运维建议
- 常见问题与故障排查
- 多角色支持：学生、商家、宿管维保、管理员
- 认证与守卫：JWT + 路由角色守卫（前端/后端双层）
- 商品与订单：商品浏览、购物车、订单创建与我的订单
- 工单闭环：学生提单、宿管处理、状态流转与评价
- 审计记录：受保护接口统一审计中间件（基础字段）
- 学生充值：专页
/student/recharge，网费/电费单位充值，含寝室/收货地址与备注 - 体验优化：充值页使用本地 SVG 图标避免图片闪烁；商品页隐藏充值类产品
说明：统计看板、部分管理员模块等按设计文档规划中，代码已预留入口与结构。
- 语言：Go 1.21
- 框架：Gin
- ORM：GORM（MySQL）
- 认证：JWT（
Authorization: Bearer <token>） - 日志：标准库
log+ GORM/Gin 日志
- 框架：Vue 3（Composition API）
- 构建：Vite
- UI：Element Plus
- 状态：Pinia
- 路由：Vue Router（角色与认证元信息）
- 测试：Vitest、Playwright
DB_Exp/
├── backend/ # 后端 Go 服务
│ ├── cmd/ # 应用入口（main、seed、migrate、integration）
│ ├── internal/ # 业务实现
│ │ ├── api/ # 路由与处理器
│ │ ├── config/ # 配置加载与注入
│ │ ├── database/ # 连接与自动迁移
│ │ ├── middleware/ # JWT、CORS、审计
│ │ ├── model/ # GORM 模型与响应结构
│ │ └── service/ # 业务服务
│ ├── go.mod # 模块与依赖
│ └── scripts/ # 辅助脚本（可选）
├── frontend/ # 前端 Vue 应用
│ ├── public/ # 静态资源（icons、banners、products）
│ ├── src/
│ │ ├── api/ # 接口定义与 HTTP 客户端
│ │ ├── router/ # 前端路由与守卫
│ │ ├── stores/ # Pinia 状态
│ │ ├── views/ # 页面组件（含学生/商家/宿管/管理员）
│ │ └── components/ # 复用组件
├── docs/ # 项目与设计文档
└── README.md # 项目说明（本文件）
- Node.js：
^20.19.0 || >=22.12.0 - Go：
1.21 - MySQL：
8.0+
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=dormitory_system
SERVER_PORT=8081
SERVER_MODE=debug # 或 release
JWT_SECRET=your_jwt_secret
JWT_EXPIRE_HOURS=24
# 逗号分隔的允许前端来源，用于 CORS
CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
VITE_API_BASE_URL=/api/v1（默认使用 Vite 代理转发到后端）
frontend/vite.config.ts 已配置：将前端 /api/* 代理到后端 http://localhost:8081。
cd backend
go mod tidy
go run cmd/main.go
# 访问健康检查：GET http://localhost:8081/healthcd frontend
npm install
npm run dev
# 默认 http://localhost:5173/（占用时自动切换端口）- 所有接口以
/api/v1为前缀。
/auth/*：注册、登录、个人信息、修改密码、退出登录- 受保护分组（需 JWT）：
/users：管理员/宿管的用户管理与审核/tickets/*：工单创建/处理/评价等/orders/*：订单创建与学生订单查询，商家子订单等/merchant/*：商家相关接口（商品与订单）/admin/*：管理员相关接口（预留）
中间件：JWTAuth（认证）、RequireRole（角色）、Audit（基础审计）、CORS。
- 未登录默认跳转
/login；登录后按角色跳转：/student、/merchant、/manager、/admin - 学生端包含：
'/student/home'：主页'/student/shop'：商品浏览（已隐藏充值类商品）'/student/recharge'：费用充值（网费/电费）'/student/orders'：我的订单'/student/tickets'：我的工单'/student/profile'：个人信息
后端启动时自动迁移核心表（users 等）及业务表（products、orders/sub_orders、tickets、audit_logs 等）。
# 执行枚举或默认值修复等迁移
go run cmd/migrate/main.go
# 写入演示/联调所需的种子数据
go run cmd/seed/main.go- 单元测试：
npm run test:unit - 端到端测试：
npx playwright install npm run build npm run test:e2e
- 代码规范与格式：
npm run lint、npm run format
- 建议使用
go test编写与运行单元测试（当前仓库以集成入口演示交互流程：cmd/integration/main.go）。
- 后端：
SERVER_MODE=release，反向代理暴露/api/v1，配置数据库连接与JWT_SECRET - 前端：
npm run build产出静态资源，部署到 Nginx/静态托管，反向代理/api指向后端 - 安全：开启 CORS 白名单、合理设置 JWT 过期、限制文件上传大小（按需求扩展）
- 前端图片闪烁：充值页改用本地 SVG（
public/images/icons/network.svg、electricity.svg） - 充值商品干扰：
学生/Shop.vue中过滤「费用充值」分类与名称包含“充值”的商品 - 跨域问题：确认后端
CORS_ORIGINS包含前端来源；或检查反向代理配置 - 接口 401：前端需携带
Authorization: Bearer <token>，登录态过期后重新登录 - 开发端口占用：Vite 会自动切换端口（如 5173 → 5174），请关注控制台提示
git add -A
git commit -m "docs: 重写完整 README"
git remote add origin https://github.com/<your-username>/<repo>.git # 首次
git branch -M master # 或 main
git push -u origin master如出现认证提示，请使用 GitHub 登录或 PAT 令牌完成认证。
- 🔐 用户认证与授权
- 👥 多角色管理（学生、商家、管理员）
- 🍔 商品管理
- 🛒 购物车功能
- 📦 订单管理
- 💰 支付集成
- 📊 数据统计
- 📱 响应式设计