112 lines
3.7 KiB
Markdown
112 lines
3.7 KiB
Markdown
# AGENTS.md
|
||
|
||
> 本文件用于帮助后续 OpenCode 会话快速了解本仓库，避免常见错误。
|
||
|
||
## 项目概况
|
||
|
||
- **技术栈**：Java 17 + Spring Boot 3.3.2 + Spring Security 6 + MyBatis-Plus 3.5.7
|
||
- **构建工具**：Maven（单模块 POM）
|
||
- **应用入口**：`com.ichangzuo.iczApplication`
|
||
- **默认端口**：8989（dev/test）/ 9999（prod）
|
||
- **接口文档**：启动后访问 `http://localhost:8989/doc.html`（Knife4j）
|
||
|
||
## 运行环境依赖
|
||
|
||
- **MySQL**：数据库名 `music`，开发配置在 `application-dev.yml`
|
||
- **Redis**：端口 16378，开发环境密码 `CZwy168`
|
||
- **运行时 Profile**：
|
||
- `dev`（默认）：本地开发
|
||
- `test`：测试环境（数据库 `192.168.5.2`）
|
||
- `prod`：生产环境
|
||
|
||
> 注意：`application.yml` 中默认激活的是 `prod`，但 Maven 的 `dev` profile 是默认激活的。
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
# 开发模式启动（使用 dev profile）
|
||
mvn spring-boot:run -P dev
|
||
|
||
# 打包（默认 dev）
|
||
mvn clean package
|
||
|
||
# 测试环境打包
|
||
mvn clean package -P test
|
||
|
||
# 生产环境打包
|
||
mvn clean package -P prod
|
||
|
||
# 运行测试
|
||
mvn test
|
||
|
||
# 跳过测试打包
|
||
mvn clean package -DskipTests
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
src/main/java/com/ichangzuo/
|
||
iczApplication.java # 启动类（注意不是 YouLaiApplication）
|
||
common/ # 公共模块：注解、常量、枚举、异常、工具类
|
||
config/ # 自动装配配置（CORS、Redis、Security、Swagger 等）
|
||
core/ # 核心功能：切面（日志、防重提交）、过滤器、Security
|
||
module/ # 业务模块
|
||
auth/ # 认证模块
|
||
codegen/ # 代码生成器
|
||
file/ # 文件模块
|
||
mail/ # 邮件模块
|
||
sms/ # 短信模块
|
||
websocket/ # WebSocket 模块
|
||
system/ # 系统管理模块：用户、角色、菜单、部门、字典等
|
||
controller/
|
||
converter/ # MapStruct 转换器
|
||
event/ # 事件处理
|
||
handler/
|
||
listener/
|
||
model/ # bo, dto, entity, form, query, vo
|
||
mapper/
|
||
service/
|
||
```
|
||
|
||
## 关键配置与约定
|
||
|
||
### 数据库与 ORM
|
||
|
||
- **MyBatis-Plus**：
|
||
- 逻辑删除字段：`is_deleted`（删除=1，未删除=0）
|
||
- 主键 ID 类型：`none`
|
||
- 驼峰下划线自动转换已开启
|
||
- **数据源**：Druid 连接池
|
||
|
||
### 安全与认证
|
||
|
||
- 基于 Spring Security + JWT 的无状态认证
|
||
- JWT 密钥配置在 `application.yml` 的 `security.jwt.key`
|
||
- 部分接口在白名单中（如 `/api/v1/auth/**`、`/client/**` 等），无需认证
|
||
|
||
### 文件存储
|
||
|
||
- 支持 `minio` 和 `aliyun` 两种类型，通过 `oss.type` 切换
|
||
- 当前测试/生产环境使用 `minio`
|
||
|
||
### 缓存
|
||
|
||
- Spring Cache + Redis，但当前 `spring.cache.enabled=false`
|
||
|
||
### 定时任务
|
||
|
||
- 集成 XXL-JOB，但默认 `enabled: false`
|
||
|
||
### 支付
|
||
|
||
- 集成支付宝和微信支付，配置在 `pay.ali` 和 `pay.wx` 下
|
||
|
||
## 开发注意事项
|
||
|
||
1. **启动类名称**：实际启动类是 `iczApplication`，不是 README 中提到的 `YouLaiApplication.java`
|
||
2. **MapStruct**：项目使用 MapStruct 进行实体转换，配合 Lombok 使用，需确保 `lombok-mapstruct-binding` 依赖存在
|
||
3. **Undertow 替代 Tomcat**：`spring-boot-starter-tomcat` 被排除，使用 `spring-boot-starter-undertow`
|
||
4. **打包配置**：`spring-boot-maven-plugin` 配置了 `ZIP` layout，并排除了 Lombok
|
||
5. **Maven Profile 优先级**：`dev` profile 默认激活，但 Spring 的 `application.yml` 默认激活 `prod`。实际运行时以 Spring 的 `spring.profiles.active` 为准
|