wangziqi
67435e46ca
UX 缺陷修复: - 校验失败不再卡死弹窗按钮(Users/Roles/Bills) - 押金收取/批量收取/添加分期防重复提交;切换房型重置勾选 - AI 表单/批量确认不再出现"假成功" - Dashboard 各数据模块独立加载,单接口失败不再整页清零 - 房间可视化加载失败显示错误态而非永久转圈 - 学生编辑表单回填前重置,避免字段残留污染 - 覆盖式导入增加二次确认;恢复默认考勤时段确认并同步表单 - 金数据匹配关闭前确认,同步中禁止误关 体验提升: - 新增统一 QueryErrorState/QueryEmpty,20+ 页面加载失败显示错误态与重试 - 全局 ErrorBoundary + RouteKeeper 逐页兜底 - 新增 usePageVisible/useVisibleRefetch,保活页面切回自动刷新数据 - 新增首次登录角色引导 RoleTour 与业务闭环 NextStepHint 引导卡 - 重构 A2UI:useSubmissionState/useXCardSurface 收敛状态与命令生命周期, ArtifactErrorBoundary 渲染降级,图表空数据占位 - AI 助手欢迎语与建议话术按角色定制,会话列表空态引导 - 更新 a2ui-contract.md 契约文档说明实现现状
恭学教育基地管理系统
教培公司集训基地宿舍水电费精准计费系统，采用「人天数加权分摊」算法，按每位学生的实际入住天数公平分摊宿舍公共费用。
功能模块
| 模块 | 功能说明 |
|---|---|
| 数据面板 | 统计卡片、费用趋势图、宿舍排行、甘特图 |
| 宿舍总览 | 房态可视化网格，空置/在住/满员颜色区分 |
| 学生管理 | 增删改查、批量导入/删除 |
| 宿舍管理 | 增删改查，删除前检查在住人员 |
| 入住管理 | 入住登记、退宿、换房、一键导入名单 |
| 费用录入 | 宿舍公共费用（水/电/保洁等）+ 个人附加费 |
| 账单管理 | 自动生成、确认、标记已付、删除、批量操作 |
| 账单导出 | Excel（汇总+明细双Sheet）、单条PDF账单 |
| 教室管理 | 教室信息维护、教室租赁记录 |
| 押金管理 | 押金收取与退还 |
| 操作日志 | 所有涉及钱的操作自动审计留痕 |
| 账号管理 | 用户增删改查、角色区分、启用/禁用、重置密码 |
技术架构
前端 (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
后端启动
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） | 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文件，不提交到版本库