120 lines
4.4 KiB
Markdown
120 lines
4.4 KiB
Markdown
# 恭学教育基地管理系统
|
||
|
||
教培公司集训基地宿舍水电费精准计费系统，采用「人天数加权分摊」算法，按每位学生的实际入住天数公平分摊宿舍公共费用。
|
||
|
||
## 功能模块
|
||
|
||
| 模块 | 功能说明 |
|
||
|------|---------|
|
||
| 数据面板 | 统计卡片、费用趋势图、宿舍排行、甘特图 |
|
||
| 宿舍总览 | 房态可视化网格，空置/在住/满员颜色区分 |
|
||
| 学生管理 | 增删改查、批量导入/删除 |
|
||
| 宿舍管理 | 增删改查，删除前检查在住人员 |
|
||
| 入住管理 | 入住登记、退宿、换房、一键导入名单 |
|
||
| 费用录入 | 宿舍公共费用（水/电/保洁等）+ 个人附加费 |
|
||
| 账单管理 | 自动生成、确认、标记已付、删除、批量操作 |
|
||
| 账单导出 | Excel（汇总+明细双Sheet）、单条PDF账单 |
|
||
| 教室管理 | 教室信息维护、教室租赁记录 |
|
||
| 押金管理 | 押金收取与退还 |
|
||
| 班级/排课 | 班级档案、分班、教室日程与排课 |
|
||
| 考勤管理 | 手工考勤、钉钉考勤同步、自动匹配 |
|
||
| 教室租赁 | 租赁订单、合同、租赁日程 |
|
||
| AI 助手 | 对话式查询、表单/导入向导/图表、业务待办引导 |
|
||
| 组织/校区 | 组织机构与数据范围 |
|
||
| 操作日志 | 所有涉及钱的操作自动审计留痕 |
|
||
| 账号管理 | 用户增删改查、角色区分、启用/禁用、重置密码 |
|
||
|
||
## 技术架构
|
||
|
||
```
|
||
前端 (React + Vite) 后端 (NestJS) 数据库
|
||
┌─────────────────┐ ┌──────────────────┐ ┌──────────┐
|
||
│ React 19 │ │ NestJS 11 │ │ MySQL 8 │
|
||
│ Ant Design 6 │────▶│ TypeORM 0.3 │────▶│ │
|
||
│ ECharts │ │ JWT + Passport │ │ │
|
||
│ Vite 8 │ │ ExcelJS + PDFKit │ │ │
|
||
└─────────────────┘ └──────────────────┘ └──────────┘
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Node.js >= 18
|
||
- npm >= 9
|
||
- MySQL 8.0
|
||
|
||
### 后端启动
|
||
|
||
```bash
|
||
cd apps/server
|
||
cp .env.example .env # 复制并修改环境配置
|
||
npm install
|
||
npm run start:dev # 开发模式启动，默认端口 3000
|
||
```
|
||
|
||
### 前端启动
|
||
|
||
```bash
|
||
cd apps/admin
|
||
npm install
|
||
npm run dev # 开发模式启动，默认端口 5173
|
||
```
|
||
|
||
### 常用命令
|
||
|
||
```bash
|
||
npm run typecheck # 全仓类型检查
|
||
npm run lint # 全仓 lint
|
||
npm run test # 全仓测试
|
||
npm run build # 全仓构建
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
├── apps/server/ # 后端 NestJS 服务
|
||
│ ├── src/
|
||
│ │ ├── ai-chat/ # AI 对话、表单/导入向导/图表
|
||
│ │ ├── attendance/ # 考勤与钉钉同步
|
||
│ │ ├── bills/ # 账单模块
|
||
│ │ ├── dashboard/ # 数据面板
|
||
│ │ ├── entities/ # 数据实体
|
||
│ │ ├── occupancies/# 入住管理
|
||
│ │ ├── rbac/ # 角色权限
|
||
│ │ ├── rooms/ # 宿舍管理
|
||
│ │ └── students/ # 学生管理
|
||
│ └── .env.example # 环境配置模板
|
||
├── apps/admin/ # 前端 React 应用
|
||
│ └── src/
|
||
│ ├── api/ # API 请求封装
|
||
│ ├── components/ # 通用组件
|
||
│ ├── layouts/ # 布局组件
|
||
│ └── pages/ # 页面组件
|
||
├── packages/ # 共享配置包
|
||
└── 技术文档.md # 详细技术文档
|
||
```
|
||
|
||
## 环境配置
|
||
|
||
复制 `apps/server/.env.example` 为 `apps/server/.env`，按需修改：
|
||
|
||
| 配置项 | 说明 | 默认值 |
|
||
|--------|------|--------|
|
||
| `DB_TYPE` | 数据库类型（仅支持 MySQL） | `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` 文件，不提交到版本库
|