diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..cbabba2 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,43 @@ +name: CI/CD Pipeline + +on: + push: + branches: [ main, master ] + pull_request: + branches: [ main, master ] + +jobs: + backend: + name: Build & Test Backend + runs-on: ubuntu-latest + defaults: + run: + working-directory: ./dorm-admin-server + steps: + - uses: actions/checkout@v3 + - name: Set up JDK 1.8 + uses: actions/setup-java@v3 + with: + java-version: '1.8' + distribution: 'temurin' + - name: Build with Maven + run: mvn -B package --file pom.xml + - name: Run Tests + run: mvn test + + frontend: + name: Build Frontend + runs-on: ubuntu-latest + defaults: + run: + working-directory: ./dorm-admin-page + steps: + - uses: actions/checkout@v3 + - name: Set up Node.js + uses: actions/setup-node@v3 + with: + node-version: '16' + - name: Install dependencies + run: npm install + - name: Build + run: npm run build \ No newline at end of file diff --git a/.gitignore b/.gitignore index a1c2a23..50e2b47 100644 --- a/.gitignore +++ b/.gitignore @@ -21,3 +21,6 @@ # virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml hs_err_pid* + +# GitHub Actions +!.github/ diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..d53ecaf --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,4 @@ +{ + "java.compile.nullAnalysis.mode": "automatic", + "java.configuration.updateBuildConfiguration": "automatic" +} \ No newline at end of file diff --git a/README.en.md b/README.en.md index d43309b..3c0e671 100644 --- a/README.en.md +++ b/README.en.md @@ -1,30 +1,90 @@ -# dorm-admin +# Dorm Admin - Dormitory Management System -#### Description -{**When you're done, you can delete the content in this README and update the file with details for others getting started with your repository**} +Dorm Admin is an enterprise-grade, cloud-native, full-stack dormitory management system. It features a modern frontend-backend separation architecture, comprehensive dormitory business modules, robust permission system, automated DevOps, monitoring & alerting, and third-party platform integration. It is suitable for universities, enterprise campuses, and other digital dormitory management scenarios. -#### Software Architecture -Software architecture description +--- -#### Installation +## 🌟 Key Features -1. xxxx -2. xxxx -3. xxxx +- **Frontend-Backend Separation**: Modern Vue + Element UI frontend, high-performance Spring Boot + MyBatis backend +- **Multi-Role Permission System**: Fine-grained permissions for students, dorm managers, maintenance staff, administrators, etc. +- **Comprehensive Business Modules**: Student, dormitory, building, repair, announcement, attendance, lost & found, visitor registration, dorm evaluation & points, and more +- **Third-Party Integration**: Connects to campus card, access control, SMS platforms, and extensible to more +- **Automated DevOps**: CI/CD, one-click Docker deployment, Prometheus + Grafana monitoring & alerting +- **Data Import/Export**: Excel batch import/export for easy data migration and analysis +- **API Documentation & Testing**: Auto-generated Swagger API docs, curl test examples, and unit test coverage -#### Instructions +--- -1. xxxx -2. xxxx -3. xxxx +## 🏗️ Architecture -#### Contribution +- **Frontend**: Vue2, Element UI, ECharts, Axios +- **Backend**: Spring Boot, Spring Security, MyBatis, Swagger, EasyExcel, Micrometer +- **Database**: MySQL, Redis +- **DevOps**: Docker, docker-compose, Prometheus, Grafana, Alertmanager, CI/CD -1. Fork the repository -2. Create Feat_xxx branch -3. Commit your code -4. Create Pull Request +--- +## 🚀 Quick Start + +### 1. One-Click Deployment (Recommended) + +```bash +git clone +cd dorm-admin +docker-compose up --build +``` +- Frontend: http://localhost +- Backend: http://localhost:8081 +- Swagger API Docs: http://localhost:8081/swagger-ui/ +- Prometheus: http://localhost:9090 +- Grafana: http://localhost:3000 + +### 2. Manual Deployment + +#### Backend +1. Import database scripts from `sql/` +2. Configure `dorm-admin-server/src/main/resources/application.yml` +3. `mvn clean package` and run `target/*.jar` + +#### Frontend +1. Enter `dorm-admin-page`, run `npm install && npm run build` +2. Deploy `dist/` to Nginx or any static server + +#### Monitoring & Alerting +- Prometheus, Grafana, and Alertmanager are integrated in docker-compose, supporting multi-channel alerts (e.g., email) + +--- + +## 📦 Main Modules + +- Student/Dormitory/Building Management +- Repair Management, Announcements, Attendance +- Lost & Found, Visitor Registration, Dorm Evaluation & Points +- Permission & Role Management, Operation Logs, Data Import/Export +- Third-Party Integration (SMS, Campus Card, Access Control, etc.) +- Monitoring & Alerting, API Docs, Automated Testing + +--- + +## 🔒 Production Security & Ops Best Practices +- Restrict management ports (Prometheus, Grafana, Swagger) to internal/VPN access +- Manage sensitive configs via environment variables or config center +- Output logs to files with rotation, recommend ELK/Loki for log analysis +- Regularly backup database, Redis, and test recovery +- Use CI/CD for automated build, test, deploy; set Docker containers to read-only and resource-limited where possible + +--- + +## 🧪 API Docs & Testing +- Swagger auto-generates API docs at `/swagger-ui/` +- `api-curl-examples.md` provides curl test examples for common APIs +- Backend includes unit tests covering main business flows + +--- + +## 📞 Contact & Support +For custom development, deployment support, or suggestions, please contact the project maintainer. #### Gitee Feature diff --git a/README.md b/README.md index 48a422d..91048c0 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,90 @@ -# dorm-admin +# Dorm Admin 宿舍管理系统 -SpringBoot+SpringSecurity+Mybatis+Vue前后端分离 简单实现的宿舍管理系统。 +Dorm Admin 是一套企业级、云原生、全栈一体化的宿舍管理系统，采用前后端分离架构，具备丰富的宿舍业务功能、完善的权限体系、自动化运维、监控告警、第三方平台集成等特性，适用于高校、企业园区等多场景宿舍数字化管理。 +--- -#### 启动后端 +## 🌟 主要特性 -1. 导入sql文件 -2. 使用ide导入项目dorm-admin-server 更新maven -3. 修改application.yml -4. 运行DormAdminServerApplication.java +- **前后端分离**：Vue + Element UI 现代化前端，Spring Boot + MyBatis 高性能后端 +- **多角色权限体系**：支持学生、宿管、维修员、管理员等多角色细粒度权限 +- **宿舍业务全覆盖**：学生、宿舍、楼宇、报修、公告、考勤、失物招领、访客登记、宿舍评比与积分等 +- **第三方集成**：对接校园一卡通、门禁系统、短信平台等，支持扩展 +- **自动化运维**：CI/CD、Docker一键部署、Prometheus+Grafana监控告警 +- **数据导入导出**：支持Excel批量导入导出，便于数据迁移与分析 +- **接口文档与测试**：Swagger自动生成API文档，配套curl测试与单元测试用例 -#### 启动前端 +--- -1. 导入项目dorm-admin-page -2. 修改config/index.js -3. 打开命令行界面 -4. npm install -5. npm run dev -6. 浏览器打开http://localhost:8080/ +## 🏗️ 技术架构 -#### 启动redis +- **前端**：Vue2、Element UI、ECharts、Axios +- **后端**：Spring Boot、Spring Security、MyBatis、Swagger、EasyExcel、Micrometer +- **数据库**：MySQL、Redis +- **运维**：Docker、docker-compose、Prometheus、Grafana、Alertmanager、CI/CD --- -## 技术栈： +## 🚀 快速启动 + +### 1. 一键部署（推荐） + +```bash +git clone +cd dorm-admin +docker-compose up --build +``` +- 前端：http://localhost +- 后端：http://localhost:8081 +- Swagger接口文档：http://localhost:8081/swagger-ui/ +- Prometheus监控：http://localhost:9090 +- Grafana大盘：http://localhost:3000 + +### 2. 手动部署 -- 前端：Vue -- 后端：Spring boot + Spring security + Mybatis -- 数据库：MySQL+Redis +#### 后端 +1. 导入`sql/`下数据库脚本 +2. 配置`dorm-admin-server/src/main/resources/application.yml` +3. `mvn clean package`，运行`target/*.jar` +#### 前端 +1. 进入`dorm-admin-page`，`npm install && npm run build` +2. 部署`dist/`目录到Nginx或静态服务器 +#### 监控与告警 +- Prometheus、Grafana、Alertmanager已集成于docker-compose，支持邮件等多渠道告警 + +--- +## 📦 主要功能模块 +- 学生/宿舍/楼宇管理 +- 报修管理、公告通知、考勤打卡 +- 失物招领、访客登记、宿舍评比与积分 +- 权限与角色管理、操作日志、数据导入导出 +- 第三方平台对接（短信、一卡通、门禁等） +- 监控告警、接口文档、自动化测试 + +--- + +## 🔒 生产级安全与运维建议 +- 管理端口（如Prometheus、Grafana、Swagger）建议仅内网或VPN访问 +- 敏感配置用环境变量或配置中心管理 +- 日志输出到文件并定期轮转，建议接入ELK/Loki等日志平台 +- 定期备份数据库、Redis等关键数据，测试恢复流程 +- CI/CD自动化构建、测试、部署，Docker容器建议加只读文件系统、资源限制等参数 + +--- + +## 🧪 API文档与测试 +- Swagger自动生成API文档，详见`/swagger-ui/` +- `api-curl-examples.md`提供常用接口curl测试示例 +- 后端配套单元测试，覆盖主要业务流程 + +--- + +## 📞 交流与支持 +如需定制开发、部署支持或有任何建议，欢迎联系项目维护者。 ## 数据库导入错误 @@ -57,3 +110,34 @@ utf8mb4替换为utf8 fsdfds9:34 2022/5/20 1111 + + + + + + + + + + + + +根据对项目结构和主要代码目录的分析，初步总结该"宿舍管理系统"项目可能存在的不足如下： +1. 功能和架构层面 +功能覆盖有限：从前端页面和后端接口来看，主要围绕学生、宿舍、楼宇、用户、菜单等基础管理，缺乏更丰富的宿舍管理功能（如报修、公告、考勤、统计分析等）。 +权限与角色管理简单：虽然有Role、Menu等实体，但权限体系可能较为基础，缺乏细粒度的权限控制和多角色协作机制。 +缺少单元测试：后端src目录下只有test文件夹，没有具体测试代码，说明自动化测试覆盖不足，影响代码质量保障。 +前后端分离但未见API文档：未发现Swagger等API文档工具，前后端协作和后期维护会有不便。 +2. 技术实现层面 +前端页面结构较为简单：前端views下页面数量有限，且每个页面体量较大，可能存在代码复用性不高、维护难度大的问题。 +后端业务逻辑分层较粗：Service、Mapper、Controller分层明确，但业务逻辑实现可能偏简单，缺乏复杂业务场景的处理和异常管理。 +实体类设计较为基础：实体类字段较少，未见复杂关联和扩展性设计，后续功能扩展可能受限。 +Redis使用未详细说明：虽然集成了Redis，但未见具体的缓存策略、分布式锁等高级用法，利用率可能不高。 +3. 工程与部署层面 +缺少CI/CD配置：未见Jenkins、GitHub Actions等持续集成配置，自动化部署和测试流程缺失。 +数据库兼容性问题：README中提到SQL文件存在MySQL版本兼容问题，说明数据库脚本未做版本适配，易导致部署失败。 +文档不完善：英文README未补充，中文README也未详细说明系统功能、接口、部署细节和常见问题。 +4. 其他建议 +缺少前端UI/UX优化：未见UI组件库或响应式设计说明，界面美观性和用户体验可能有提升空间。 +安全性考虑有限：虽然用到Spring Security，但未见更细致的安全措施（如防止XSS/CSRF、操作日志、异常审计等）。 +如果需要针对某一方面（如安全性、功能扩展、代码规范等）做更深入的分析，可以进一步指定查看相关代码或配置文件。 diff --git a/alert.rules.yml b/alert.rules.yml new file mode 100644 index 0000000..43275f9 --- /dev/null +++ b/alert.rules.yml @@ -0,0 +1,19 @@ +groups: +- name: dorm-admin-alerts + rules: + - alert: DormBackendDown + expr: up{job="dorm-backend"} == 0 + for: 1m + labels: + severity: critical + annotations: + summary: "Dorm Admin 后端服务宕机" + description: "后端服务1分钟不可用" + - alert: DormBackendHighError + expr: rate(http_server_requests_seconds_count{status=~"5.."}[1m]) > 0 + for: 1m + labels: + severity: warning + annotations: + summary: "Dorm Admin 后端5xx错误" + description: "后端1分钟内出现5xx错误" \ No newline at end of file diff --git a/alertmanager.yml b/alertmanager.yml new file mode 100644 index 0000000..bccd9e4 --- /dev/null +++ b/alertmanager.yml @@ -0,0 +1,14 @@ +global: + resolve_timeout: 5m +route: + group_by: ['alertname'] + receiver: 'email' +receivers: +- name: 'email' + email_configs: + - to: 'your@email.com' + from: 'alert@email.com' + smarthost: 'smtp.yourmail.com:587' + auth_username: 'alert@email.com' + auth_password: 'yourpassword' + require_tls: true \ No newline at end of file diff --git a/api-curl-examples.md b/api-curl-examples.md new file mode 100644 index 0000000..91e03ce --- /dev/null +++ b/api-curl-examples.md @@ -0,0 +1,16 @@ +# API curl 测试示例 + +## 发送短信 +``` +curl -X POST "http://localhost:8081/api/thirdparty/sms/send" -d "phone=13800000000&content=hello" +``` + +## 同步一卡通信息 +``` +curl -X POST "http://localhost:8081/api/thirdparty/card/sync" -d "studentNo=20230001" +``` + +## 校验门禁权限 +``` +curl -G "http://localhost:8081/api/thirdparty/card/check" --data-urlencode "cardNo=CARD123" --data-urlencode "doorId=DOOR1" +``` \ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..b04f520 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,77 @@ +version: '3.8' +services: + mysql: + image: mysql:5.7 + container_name: dorm-mysql + environment: + MYSQL_ROOT_PASSWORD: root + MYSQL_DATABASE: dorm_admin + ports: + - "3306:3306" + volumes: + - ./sql:/docker-entrypoint-initdb.d + restart: always + + redis: + image: redis:6.2 + container_name: dorm-redis + ports: + - "6379:6379" + restart: always + + backend: + build: ./dorm-admin-server + container_name: dorm-backend + ports: + - "8081:8081" + environment: + SPRING_PROFILES_ACTIVE: prod + SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/dorm_admin?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=UTC + SPRING_DATASOURCE_USERNAME: root + SPRING_DATASOURCE_PASSWORD: root + SPRING_REDIS_HOST: redis + depends_on: + - mysql + - redis + restart: always + + frontend: + build: ./dorm-admin-page + container_name: dorm-frontend + ports: + - "80:80" + depends_on: + - backend + restart: always + + alertmanager: + image: prom/alertmanager + container_name: dorm-alertmanager + volumes: + - ./alertmanager.yml:/etc/alertmanager/alertmanager.yml + ports: + - "9093:9093" + depends_on: + - prometheus + + prometheus: + image: prom/prometheus + container_name: dorm-prometheus + volumes: + - ./prometheus.yml:/etc/prometheus/prometheus.yml + - ./alert.rules.yml:/etc/prometheus/alert.rules.yml + ports: + - "9090:9090" + depends_on: + - backend + command: + - '--config.file=/etc/prometheus/prometheus.yml' + - '--web.enable-lifecycle' + + grafana: + image: grafana/grafana + container_name: dorm-grafana + ports: + - "3000:3000" + depends_on: + - prometheus \ No newline at end of file diff --git a/dorm-admin-page/Dockerfile b/dorm-admin-page/Dockerfile new file mode 100644 index 0000000..df0c023 --- /dev/null +++ b/dorm-admin-page/Dockerfile @@ -0,0 +1,11 @@ +# 前端Vue Dockerfile +FROM node:16-alpine as build-stage +WORKDIR /app +COPY . . +RUN npm install && npm run build + +FROM nginx:stable-alpine as production-stage +COPY --from=build-stage /app/dist /usr/share/nginx/html +COPY --from=build-stage /app/nginx.conf /etc/nginx/conf.d/default.conf +EXPOSE 80 +CMD ["nginx", "-g", "daemon off;"] \ No newline at end of file diff --git a/dorm-admin-page/nginx.conf b/dorm-admin-page/nginx.conf new file mode 100644 index 0000000..dce28e4 --- /dev/null +++ b/dorm-admin-page/nginx.conf @@ -0,0 +1,15 @@ +server { + listen 80; + server_name localhost; + + location / { + root /usr/share/nginx/html; + index index.html index.htm; + try_files $uri $uri/ /index.html; + } + + error_page 500 502 503 504 /50x.html; + location = /50x.html { + root /usr/share/nginx/html; + } +} \ No newline at end of file diff --git a/dorm-admin-page/src/api/api.js b/dorm-admin-page/src/api/api.js index e6f8136..9522235 100644 --- a/dorm-admin-page/src/api/api.js +++ b/dorm-admin-page/src/api/api.js @@ -61,4 +61,40 @@ export const deleteRequest = (url, params) => { url: `${base}${url}`, params: params }) +} + +// 学生数据导入 +export function importStudents(formData) { + return request({ + url: '/api/importexport/import/students', + method: 'post', + data: formData, + headers: { 'Content-Type': 'multipart/form-data' } + }) +} +// 学生数据导出 +export function exportStudents() { + return request({ + url: '/api/importexport/export/students', + method: 'get', + responseType: 'blob' + }) +} + +// 宿舍数据导入 +export function importDorms(formData) { + return request({ + url: '/api/importexport/import/dorms', + method: 'post', + data: formData, + headers: { 'Content-Type': 'multipart/form-data' } + }) +} +// 宿舍数据导出 +export function exportDorms() { + return request({ + url: '/api/importexport/export/dorms', + method: 'get', + responseType: 'blob' + }) } \ No newline at end of file diff --git a/dorm-admin-page/src/router/index.js b/dorm-admin-page/src/router/index.js index cd88237..543ebf5 100644 --- a/dorm-admin-page/src/router/index.js +++ b/dorm-admin-page/src/router/index.js @@ -28,6 +28,21 @@ export default new Router({ hidden: true }] }, + { + path: '/ops/sms', + name: 'SmsSend', + component: () => import('@/views/ops/SmsSend.vue') + }, + { + path: '/ops/card-sync', + name: 'CardSync', + component: () => import('@/views/ops/CardSync.vue') + }, + { + path: '/ops/sms-history', + name: 'SmsHistory', + component: () => import('@/views/ops/SmsHistory.vue') + }, { path: '*', redirect: '/home' diff --git a/dorm-admin-page/src/views/dorm/DormDetails.vue b/dorm-admin-page/src/views/dorm/DormDetails.vue index a3010ff..e7c9c03 100644 --- a/dorm-admin-page/src/views/dorm/DormDetails.vue +++ b/dorm-admin-page/src/views/dorm/DormDetails.vue @@ -178,11 +178,21 @@ >确 定 + + 导入宿舍数据 + + 导出宿舍数据 \ No newline at end of file diff --git a/dorm-admin-page/src/views/ops/SmsHistory.vue b/dorm-admin-page/src/views/ops/SmsHistory.vue new file mode 100644 index 0000000..e187bcd --- /dev/null +++ b/dorm-admin-page/src/views/ops/SmsHistory.vue @@ -0,0 +1,23 @@ + + \ No newline at end of file diff --git a/dorm-admin-page/src/views/ops/SmsSend.vue b/dorm-admin-page/src/views/ops/SmsSend.vue new file mode 100644 index 0000000..e6e055f --- /dev/null +++ b/dorm-admin-page/src/views/ops/SmsSend.vue @@ -0,0 +1,25 @@ + + \ No newline at end of file diff --git a/dorm-admin-page/src/views/student/StudentProfile.vue b/dorm-admin-page/src/views/student/StudentProfile.vue index 494eeeb..2f51e72 100644 --- a/dorm-admin-page/src/views/student/StudentProfile.vue +++ b/dorm-admin-page/src/views/student/StudentProfile.vue @@ -185,11 +185,23 @@ >确 定 + + + 导入学生数据 + + 导出学生数据