backend/AGENTS.md

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 是默认激活的。

常用命令

# 开发模式启动（使用 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 为准