智慧校园全栈解决方案 · 后端采用 Maven 多模块架构 · 默认端口 8100
- 多模块单体架构：父工程
backend/下包含 26 个业务模块，通过smart-campus-app聚合运行，支持按需装配。 - Spring Boot 3 + Java 21：全面使用 Spring Boot 3.5.0、Jakarta EE 10 生态，默认开启 Flyway、Springdoc、Knife4j、Resilience4j、Micrometer 等基础能力。
- 多数据源与中间件：内置 PostgreSQL/MySQL/Oracle 三套 Flyway 脚本，支持 Redis、MongoDB、RabbitMQ，可通过
.env灵活切换。 - 丰富业务域：已落地系统管理、统一认证、教务、考勤、一卡通、通知消息、宿舍、奖助学金、图书、后勤、AI 助手等核心场景，其他模块持续建设中。
- 一站式运维支持：
docker/提供 PostgreSQL、Redis、MongoDB、SkyWalking、Prometheus、Grafana、AlertManager 等依赖服务的 compose 编排，可一键启动开发环境。
📌 本仓库的 README 聚焦后端现状与使用方式，如需前端说明见 #前端工程。
smart-campus/
├── backend/ # Java 后端多模块工程
│ ├── pom.xml # 父 POM，声明所有子模块
│ ├── smart-campus-app/ # 聚合启动模块（Spring Boot 应用）
│ ├── smart-campus-common/ # 公共基础设施（异常、工具、缓存、配置）
│ ├── smart-campus-auth/ # 统一认证与 OAuth2 / JWT
│ ├── smart-campus-system/ # 系统管理（用户、角色、菜单、字典）
│ ├── ... # 其他业务模块，见下表
├── frontend/ # Vue 3 + Vite 多包前端工程（pnpm workspace）
├── docker/ # 开发依赖与监控组件的 Docker 编排
├── docs/ # 需求、设计、接口文档与原型
├── scripts/ # 辅助脚本
├── .env.example # 默认环境变量示例
└── README.md # 项目说明（当前文件）
| 模块 | 说明 | 当前状态 |
|---|---|---|
smart-campus-common |
公共异常、通用工具、缓存治理、基础实体、全局配置、AOP | ✅ 已投入使用 |
smart-campus-auth |
认证中心，提供 JWT/OAuth2 登录、账号安全策略、Token 管理 | ✅ 已提供主要接口 |
smart-campus-system |
用户、角色、菜单、组织、字典、日志等系统管理能力 | ✅ 核心功能可用 |
smart-campus-file |
文件存储抽象（本地/OSS/MinIO）、上传策略、文件预览 | ✅ 已集成于聚合应用 |
smart-campus-workflow |
Flowable 流程引擎集成、流程与任务管理 | 🔄 基础骨架已搭建 |
smart-campus-data |
数据中台、BI 仪表盘、风险评估接口 | 🔄 持续完善中 |
| 模块 | 说明 | 当前状态 |
|---|---|---|
smart-campus-edu |
课程、选课、排课/排考、成绩、教学计划等教务场景 | ✅ 核心流程已实现，持续补充 |
smart-campus-attendance |
课堂考勤、签到码生成与校验、请假审批、统计分析 | ✅ 可直接使用 |
smart-campus-dorm |
宿舍楼/床位管理、入住调换、报修、访客、卫生检查 | 🔄 主流程在完善 |
smart-campus-card |
一卡通卡片、充值消费、门禁访问、对账报表 | ✅ 主干逻辑可用 |
smart-campus-finance |
收费标准、账单、缴费、欠费策略 | 🔄 功能逐步完善 |
smart-campus-notice |
公告、站内信、邮件、短信、推送策略 | ✅ 已上线核心接口 |
smart-campus-ai |
多模型（OpenAI/Gemini/DeepSeek/Qwen 等）接入与 Agent 工具库 | ✅ 已可配置使用 |
smart-campus-library |
图书借阅、座位预约、罚金、推荐系统 | 🔄 主要接口已实现 |
smart-campus-sfa |
奖助学金（Scholarship & Financial Aid）申请、评审、发放 | ✅ 核心流程已打通 |
smart-campus-club |
社团活动、成员管理、活动审批 | 🔄 接口骨架可用 |
smart-campus-logistics |
后勤保障（餐饮、保洁、校医院、车辆调度） | 🔄 正在补充业务逻辑 |
smart-campus-monitoring |
运维监控 API、告警 Webhook、指标采集 | 🔄 与监控体系联动中 |
| 模块 | 说明 | 当前状态 |
|---|---|---|
smart-campus-public |
官网门户、招生信息公开、政策公示 | ✅ 已提供查询接口 |
smart-campus-enrollment |
招生迎新、离校清退流程 | 🔄 持续完善 |
smart-campus-integration |
第三方系统对接（短信、支付、云服务等适配层） | 🔄 适配器不断补充 |
smart-campus-gateway |
对外开放接口网关（API Key、调用统计、开放平台） | 🔄 Beta 阶段 |
smart-campus-app |
聚合应用，负责装配所有依赖、暴露统一入口 | ✅ 日常开发使用 |
ℹ️ 完整模块列表以
backend/pom.xml为准，README 仅列举主要能力模块。若需裁剪功能，可在父 POM 中移除不需要的子模块，然后调整smart-campus-app的依赖。
后端核心
- Spring Boot 3.5.0、Spring Security、Spring MVC & WebFlux (SSE)
- MyBatis-Plus、MyBatis 动态多租户支持、Flyway 数据迁移
- Redisson、Caffeine、Resilience4j、Micrometer、Quartz、RabbitMQ
数据与中间件
- PostgreSQL / MySQL / Oracle 三类型数据库
- Redis、MongoDB（AI 会话与操作日志）、RabbitMQ（异步事件）
- SkyWalking、Prometheus、Grafana、AlertManager（监控链路）
前端与工具
- Vue 3、Vite、TypeScript、Pinia、Element Plus（前端仓库）
- pnpm 多包管理、ESLint、Prettier
- Docker Compose 一键环境、H2 内存数据库（测试 profile）
| 组件 | 最低版本 | 说明 |
|---|---|---|
| JDK | 21 | 推荐 Temurin 21 LTS |
| Maven | 3.9+ | 支持 Maven Wrapper 或 mvnd |
| Node.js | 18+ | 前端构建需要（后端不强制） |
| pnpm | 8+ | 前端工作流默认包管理器 |
| Docker & Compose | 可选 | 用于启动数据库、缓存、监控等依赖 |
-
克隆仓库
git clone https://github.com/your-org/smart-campus.git cd smart-campus -
准备环境变量
cp .env.example .env # 按需修改数据库/Redis/邮件/AI 等配置 -
启动依赖服务（推荐）
cd docker docker compose up -d # PostgreSQL / Redis / MongoDB / 监控组件 cd .. # 回到项目根目录
-
构建后端
cd backend mvn clean install -DskipTests -
运行聚合应用
mvn -pl smart-campus-app spring-boot:run \ -Dspring-boot.run.profiles=dev- 默认端口：
http://localhost:8100 - H2 快速演示：
-Dspring-boot.run.profiles=test
- 默认端口：
-
访问接口文档
- Swagger UI：
http://localhost:8100/swagger-ui.html - Knife4j：
http://localhost:8100/doc.html
- Swagger UI：
✅ 首次启动时，Flyway 会根据
.env中的数据库类型自动建库建表并初始化基础数据。
常用环境变量摘录（详见 .env.example 与 smart-campus-app/src/main/resources/application*.yml）：
| 类型 | 变量 | 默认值 | 说明 |
|---|---|---|---|
| 数据库 | DB_TYPE |
postgresql |
可选 postgresql / mysql / oracle |
| 数据库 | DB_URL / DB_HOST 等 |
- | 数据库连接信息，支持直接填写 URL |
| 数据库 | FLYWAY_ENABLED |
true |
控制 Flyway 迁移，MySQL/Oracle 需设置 FLYWAY_LOCATION_SUFFIX |
| 缓存 | REDIS_HOST / REDIS_PASSWORD |
localhost / 空 |
Redis 连接信息 |
| AI | AI_ENABLED |
true |
AI 总开关；各模型需配置对应 *_API_KEY |
| 安全 | JWT_SECRET |
空 | JWT 签名密钥（生产必填） |
| 邮件 | MAIL_HOST / MAIL_USERNAME / MAIL_PASSWORD |
- | SMTP 配置，用于通知模块 |
| 消息队列 | RABBITMQ_* |
localhost/guest |
仅在启用异步任务时需要 |
更多可选项（MongoDB、SkyWalking、Prometheus、对象存储等）均可在 application.yml 中找到，对应的 ${ENV} 变量支持覆盖。
# 构建指定模块及其依赖
mvn -pl smart-campus-attendance -am clean package
# 运行单元测试
mvn -pl smart-campus-common test
# 启动聚合应用（dev 配置）
mvn -pl smart-campus-app spring-boot:run -Dspring-boot.run.profiles=dev
# 使用 H2 内存库快速演示（test 配置）
mvn -pl smart-campus-app spring-boot:run -Dspring-boot.run.profiles=test
# 生成并查看依赖树
mvn -pl smart-campus-app dependency:tree- OpenAPI/Swagger：
http://localhost:8100/v3/api-docs - Knife4j UI：
http://localhost:8100/doc.html（中文界面） - Postman/Apifox 导入：直接使用
v3/api-docsJSON 地址 - 认证流程：默认提供基于用户名/密码的登录接口，成功登录后返回 JWT，后续请求需在 Header 中携带
Authorization: Bearer <token>
docker/目录提供 PostgreSQL、Redis、MongoDB、SkyWalking、Prometheus、Grafana、AlertManager 等服务的 Docker Compose 编排。- 后端已集成 Micrometer + Prometheus 暴露指标，SkyWalking Agent 配置见
docker/README.md。 management.endpoints.web.exposure.include默认放开全部 Actuator，可按需调整。
- 代码位于
frontend/，采用 pnpm + Vite 组织多个子应用（后台、教师、学生门户等）。 - 常用命令：
cd frontend pnpm install pnpm dev # 启动开发环境 pnpm build # 生产构建
- 前后端通过 REST/JSON 通信，默认后台基地址
http://localhost:8100可在前端.env中配置。
- ✅ 已完成：公共基础设施、认证授权、系统管理、教务、考勤、一卡通、通知消息、AI 集成等核心模块。
- 🚧 正在推进：宿舍、财务、数据中台、工作流编排、开放网关等模块的业务细节与测试补充。
- 📚 待完善：统一日志规范、自动化测试覆盖率、更多第三方集成适配。
欢迎通过 Issue / Pull Request 反馈问题或提交改进建议，提交前请确保代码风格与现有模块保持一致，并附带必要的中文注释与文档。
项目基于 MIT License 开源，允许自由使用、修改与分发，请保留原作者版权声明。