校园机动车综合管理平台

校园机动车综合管理平台面向校园保卫处、系统管理员和车主用户，覆盖车辆档案、通行权限、违规处罚、申诉处理、统计分析、审计日志和自然语言数据查询等核心场景。

当前版本已经将 React/Vite 工作台作为正式前端的一部分使用。前端源码位于 frontend/，其构建产物输出到 Spring Boot 静态资源目录，由 /dashboard 页面直接加载。

核心能力

模块	说明
首页工作台	/dashboard，React/Vite 构建，按 ADMIN、STAFF、OWNER 返回不同业务视图
车主管理 / 我的信息	ADMIN/STAFF 使用表格维护车主档案；OWNER 使用瀑布流卡片查看本人档案
车辆管理 / 我的车辆	登记车辆信息，按角色控制全局或本人数据范围
权限申请	车主提交通行申请，保卫处审核
临时车入校申请	未注册访客可在登录页免账号提交临时通行申请，ADMIN/STAFF 审批后生成临时通行权限
通行权限	维护车辆通行权限、有效期、状态和审批信息
违规记录	记录车辆违规类型、时间、地点、证据和处理状态
处罚处理	自动生成待处理处罚，支持缴费、免罚、申诉等状态流转
申诉处理	车主提交申诉，保卫处审核后同步处罚状态
数据统计	ADMIN/STAFF 查看车辆、权限、违规、处罚和申诉统计
操作日志	记录权限审核、违规录入、处罚处理、申诉审核等关键动作
查询智能体	自然语言查询业务数据，后端模板化生成只读 SQL 并做安全校验
用户管理	ADMIN 维护账号、角色和启停状态
数据导入	ADMIN 按 CSV 模板批量导入车主与车辆，并自动创建车主账号和通行权限

角色与账号

角色	默认账号	权限范围
ADMIN	admin / 123456	用户管理、数据导入、全局业务数据和统计
STAFF	staff / 123456	权限审核、违规录入、处罚处理、申诉审核和统计
OWNER	owner / 123456	仅查看和操作当前账号绑定车主名下的数据

OWNER 数据边界由后端控制器、查询智能体上下文和安全配置共同保证，不依赖前端隐藏按钮。OWNER 直接访问全局统计、数据导入、车辆新增等地址会被拒绝或限制到本人数据范围。

未注册临时来访车辆不需要账号，可从登录页进入「临时车辆入校申请」，填写姓名、联系电话、车牌、入校日期和事由。申请进入通行权限申请列表，由 ADMIN 或 STAFF 审批；审批通过后生成临时通行权限。

技术栈

后端：Java 17、Spring Boot 3.2.5、Spring Security 6、Spring Data JPA / Hibernate、H2 / MySQL 8、JSqlParser、Lombok。

前端：Thymeleaf、Bootstrap 5.3、Font Awesome 6.5、Material Web、React 18、Vite 5、Lucide React。

构建：Maven；Node.js + npm 只在开发或重新构建 frontend/ 时需要。

项目结构

databaseMS/
├── database/                 # 建库脚本和 CSV 导入模板
├── doc/                      # 开发规范和 Agent 项目指南
├── frontend/                 # React/Vite 正式工作台源码
├── src/main/java/...         # Spring Boot 后端代码
├── src/main/resources/       # Thymeleaf、静态资源、配置和初始化数据
├── run-h2.ps1
├── run-mysql.ps1
└── pom.xml

frontend/ 是正式 React 工作台源码。npm run build 会把资源输出到 src/main/resources/static/dashboard-app/，Spring Boot 页面 src/main/resources/templates/dashboard.html 会加载该目录下的 dashboard.js 和 dashboard.css。

快速启动

环境要求

• JDK 17+
• 项目内置 Maven：.tools/apache-maven-3.9.9
• Node.js 18+，仅在需要重新构建前端工作台时安装
• MySQL 8.x 可选；本地 H2 模式无需安装数据库

H2 本地模式

在项目根目录执行：

.\.tools\apache-maven-3.9.9\bin\mvn.cmd spring-boot:run

或使用脚本：

.\run-h2.ps1

访问地址：

http://localhost:8080

H2 控制台：http://localhost:8080/h2-console。JDBC URL 为 jdbc:h2:mem:campus_vehicle_system，用户名 sa，密码留空。

MySQL 模式

先初始化数据库：

mysql -u root -p < database/init.sql

确认 src/main/resources/application.yml 中 MySQL profile 的账号密码后启动：

.\run-mysql.ps1

前端工作台

后端仓库已经包含构建后的 src/main/resources/static/dashboard-app/，只启动 Spring Boot 即可访问正式工作台。需要修改 React 工作台时再进入 frontend/：

cd frontend
npm install
npm run dev -- --host 127.0.0.1 --port 5173

构建到 Spring Boot 静态资源目录：

cd frontend
npm run build

前端构建配置位于 frontend/vite.config.ts，base 为 /dashboard-app/，输出目录为 ../src/main/resources/static/dashboard-app。

查询智能体

入口：

• 页面：/query-agent
• 接口：POST /query-agent/query

安全策略：大模型只参与自然语言意图识别和回答组织，不直接执行模型生成 SQL；后端根据白名单模板生成只读 SQL；JSqlParser 只允许单条 SELECT；禁止 DDL、DML、多语句、注释绕过和访问敏感字段；ADMIN/STAFF 查询全局数据，OWNER 自动追加本人车主数据边界；默认最多返回 50 行。

配置位于 src/main/resources/application.yml：

query-agent:
  max-rows: 50
  deepseek:
    base-url: https://api.deepseek.com
    model: deepseek-v4-flash
    api-key: ${DEEPSEEK_API_KEY:演示默认值}

实际部署时建议通过环境变量 DEEPSEEK_API_KEY 覆盖默认值。

构建与测试

后端编译：

.\.tools\apache-maven-3.9.9\bin\mvn.cmd -DskipTests compile

完整测试：

.\.tools\apache-maven-3.9.9\bin\mvn.cmd test

前端构建：

cd frontend
npm run build

当前测试重点覆盖查询智能体 SQL 安全校验、模板生成、自然语言条件增强、OWNER 数据隔离、角色访问控制、操作日志写入、权限申请 / 违规处罚 / 申诉审核事务闭环和 403 友好页面。

数据与导入

本地数据初始化来源：

src/main/resources/data/mock-data.json

CSV 导入模板：

database/import_templates/
└── owner_vehicle_import_template.csv

登录 ADMIN 后可从「数据导入」页面导入 CSV。填写规则见 doc/mock数据填写与导入说明.md。

开发约定

项目开发规范位于 doc/开发规范.md 和 doc/AGENTS.md。