# 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）

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

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

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

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

```bash
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` 环境变量自定义端口。

### 前端

```bash
cd frontend
npm install
npm run dev
```

## 测试与验证

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

```bash
# 前端单元测试（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 变更后可自动执行的验证命令：**
```bash
# 前端
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`（增量迁移）