恭学教育基地管理系统

教培公司集训基地宿舍水电费精准计费系统，采用「人天数加权分摊」算法，按每位学生的实际入住天数公平分摊宿舍公共费用。

功能模块

模块	功能说明
数据面板	统计卡片、费用趋势图、宿舍排行、甘特图
宿舍总览	房态可视化网格，空置/在住/满员颜色区分
学生管理	增删改查、批量导入/删除
宿舍管理	增删改查，删除前检查在住人员
入住管理	入住登记、退宿、换房、一键导入名单
费用录入	宿舍公共费用（水/电/保洁等）+ 个人附加费
账单管理	自动生成、确认、标记已付、删除、批量操作
账单导出	Excel（汇总+明细双Sheet）、单条PDF账单
教室管理	教室信息维护、教室租赁记录
押金管理	押金收取与退还
操作日志	所有涉及钱的操作自动审计留痕
账号管理	用户增删改查、角色区分、启用/禁用、重置密码

技术架构

前端 (React + Vite)          后端 (NestJS)           数据库
┌─────────────────┐     ┌──────────────────┐     ┌──────────┐
│ React 19        │     │ NestJS 11        │     │ SQLite   │
│ Ant Design 6    │────▶│ TypeORM 0.3      │────▶│ (开发)   │
│ ECharts         │     │ JWT + Passport   │     │ MySQL 8  │
│ Vite 8          │     │ ExcelJS + PDFKit │     │ (生产)   │
└─────────────────┘     └──────────────────┘     └──────────┘

快速开始

环境要求

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

后端启动

cd backend
cp .env.example .env   # 复制并修改环境配置
npm install
npm run start:dev      # 开发模式启动，默认端口 3000

前端启动

cd frontend
npm install
npm run dev            # 开发模式启动，默认端口 5173

Docker 部署

docker-compose up -d   # 一键启动 MySQL + 后端 + 前端

项目结构

├── backend/            # 后端 NestJS 服务
│   ├── src/
│   │   ├── auth/       # 认证模块 (JWT)
│   │   ├── bills/      # 账单模块
│   │   ├── classrooms/ # 教室管理
│   │   ├── dashboard/  # 数据面板
│   │   ├── deposits/   # 押金管理
│   │   ├── entities/   # 数据实体
│   │   ├── expenses/   # 费用录入
│   │   ├── occupancies/# 入住管理
│   │   ├── rooms/      # 宿舍管理
│   │   ├── students/   # 学生管理
│   │   └── tenants/    # 租户管理
│   └── .env.example    # 环境配置模板
├── frontend/           # 前端 React 应用
│   └── src/
│       ├── api/        # API 请求封装
│       ├── layouts/    # 布局组件
│       └── pages/      # 页面组件
├── docker-compose.yml  # Docker 编排配置
└── 技术文档.md          # 详细技术文档

环境配置

复制 backend/.env.example 为 backend/.env，按需修改：

配置项	说明	默认值
DB_TYPE	数据库类型	mysql
DB_HOST	数据库地址	localhost
DB_PORT	数据库端口	3306
DB_USERNAME	数据库用户名	dorm_billing
DB_PASSWORD	数据库密码	-
DB_DATABASE	数据库名	dorm_billing
JWT_SECRET	JWT 密钥（务必替换）	-
JWT_EXPIRES_IN	Token 有效期	24h
ADMIN_PASSWORD	初始管理员密码	-
PORT	后端服务端口	3000

开发规范

• 后端代码使用 Prettier + ESLint 格式化
• 提交前确保 npm run lint 无报错
• 敏感配置（密码、密钥等）仅存放在 .env 文件，不提交到版本库