resource-platform/AGENTS.md

AGENTS.md

项目概述

团队内部云资源与服务套餐台账系统，前后端分离架构。

项目结构

├── backend/          # Spring Boot 3 + MyBatis-Plus 后端服务
├── frontend/         # Vue 3 + Vite 前端应用
├── sql/              # 数据库 schema 与迁移脚本
└── deploy/           # 部署配置（Nginx、systemd）

核心模块

模块	职责
resource	资源管理（增删改查、到期刷新、邮件提醒）
project	项目管理（多项目关联）
provider	供应商管理
dashboard	数据看板（工作台统计、费用分析）
user	用户管理（权限分级：管理员/普通用户、JWT 鉴权）

技术栈

• 后端: Java 17 · Spring Boot 3 · MyBatis-Plus · Spring Security (JWT) · MySQL 8+
• 前端: Vue 3 · Vite · Element Plus · Pinia
• 数据库: MySQL 8.0+

构建与启动命令

方式一：Maven（推荐，需 JDK 17 + Maven）

# 数据库初始化
# 执行 sql/schema.sql

# 后端（开发模式，热重载）
cd backend
mvn spring-boot:run

# 或打包后运行
mvn clean package -DskipTests
java -jar target/resource-platform.jar

方式二：离线构建脚本（无 Maven 环境时使用）

cd backend

# 构建（自动基于最新 jar 递增版本号）
python build.py

# 指定版本号
python build.py --version 12

# 启动（自动检测最新版本）
bash start.sh

# 启动指定版本
bash start.sh 11

构建脚本说明： build.py 是统一入口，合并了历史版本 build_v6~v11 的全部逻辑（javac 编译 + fat jar 重打包 + 资源注入 + 新增类补打）。start.sh 是统一启动脚本，支持 PORT 环境变量自定义端口。

前端

cd frontend
npm install
npm run dev

测试与验证

变更代码后应运行测试确认无回归：

# 前端单元测试（Vitest）——覆盖 API 层和路由守卫
cd frontend
npx vitest run          # 或 npm test

# 后端单元测试（JUnit 5 + Mockito）——覆盖 ResourceServiceImpl 核心业务逻辑
cd backend
# 注意：需要 JAVA_HOME 指向 JDK 17，当前环境 JAVA_HOME 默认为 1.8，需临时切换
$env:JAVA_HOME = "D:\Program Files\Java\jdk-17"; mvn test

测试文件位置：

• 前端：frontend/src/api/__tests__/、frontend/src/router/__tests__/
• 后端：backend/src/test/java/com/example/resourceplatform/service/impl/ResourceServiceImplTest.java

Agent 变更后可自动执行的验证命令：

# 前端
cd frontend && npx vitest run
# 后端（Windows PowerShell，需先设置 JAVA_HOME）
$env:JAVA_HOME = "D:\Program Files\Java\jdk-17"; cd backend; mvn test

关键约定

• Java 包路径: com.example.resourceplatform
• 后端源码: backend/src/main/java/com/example/resourceplatform/
  • controller/ — REST 接口层
  • service/ — 业务逻辑层
  • mapper/ — MyBatis-Plus Mapper 层
  • entity/ — 实体类
  • dto/ — 数据传输对象 / 视图对象
  • config/ — 配置类（Security、MyBatis-Plus）
  • security/ — JWT 与认证相关
  • common/ — 通用枚举、异常处理、分页
  • task/ — 定时任务
• 前端 API 层: frontend/src/api/ — 按模块拆分的接口调用
• 前端路由: frontend/src/router/index.js
• 前端状态管理: frontend/src/store/
• 前端页面: frontend/src/views/
• 前端布局: frontend/src/layout/
• 前端公共组件: frontend/src/components/
• SQL 脚本: sql/schema.sql（建表）、sql/migration_*.sql（增量迁移）