mica-admin CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

mica-admin 是基于 mica 工具集的低代码权限管理平台，使用 Maven、Spring Boot 4.1、Spring Security、MyBatis-Plus（后端）+ Vben Admin 5.x（前端）。

Maven multi-module 结构：

• mica-admin-server/ — Spring Boot 后端（Java 17+）
• mica-admin-web/ — 前端工程（Vite + Vue 3 + Naive UI）。这是 Vben Admin 5.x 的本地化版本，源码提取到 mica-admin-web/vben/，由 pnpm workspace 协议引用。完整前端说明见 mica-admin-web/CLAUDE.md。

构建命令

后端 (mica-admin-server)

从仓库根目录执行：

# 默认 dev profile，跳过前端构建
mvn package
# 生产构建：触发 pnpm install + pnpm build:prod，把 dist 打入 META-INF/resources
mvn clean package -Pprod -U -Dmaven.test.skip=true

# 单测
mvn test -Dtest=ClassName#methodName -DfailIfNoTests=false

# 本地启动
mvn spring-boot:run -Dspring-boot.run.profiles=dev

Maven profile 行为：

• dev（默认激活）：skipNpmBuild=true，不构建前端。
• prod：skipNpmBuild=false，通过 exec-maven-plugin 触发前端构建，并把 mica-admin-web/dist 复制到 META-INF/resources，与后端 jar 合并。

前端 (mica-admin-web)

cd mica-admin-web
pnpm install
pnpm dev               # Vite dev server，端口 5888，/api 代理到 http://localhost:8080
pnpm typecheck         # vue-tsc --noEmit --skipLibCheck
pnpm lint              # eslint --fix
pnpm build             # 类型检查 + 生产构建
pnpm build:prod        # 仅打包，跳过类型检查（Maven prod profile 调的就是这个）
pnpm build:analyze     # 构建并分析包体积

后端架构 (mica-admin-server)

主包：net.dreamlu.mica.admin，源码 src/main/java/：

• net.dreamlu.mica.admin.common — 公共常量（ApiCode、MicaAdminConstants）。
• net.dreamlu.mica.admin.framework — 框架核心：安全、MyBatis、AOP 日志、控制器基类、VO、工具类。
• net.dreamlu.mica.admin.project — 业务模块，目前主要是 project.system（用户/角色/菜单/部门/字典/文件存储/监控/日志/通知）。

关键框架细节

• 容器：Tomcat（Spring Boot 4.1 已移除 Undertow 适配），日志 Log4j2（非 Logback）。
• ORM：MyBatis-Plus 3.5 + Druid。实体扫描 net.dreamlu.mica.admin.**.entity；Mapper XML 位于 classpath:net/dreamlu/mica/admin/**/mapper/*Mapper.xml。
• 存储：MySQL（schema 见 docs/database/mysql.sql）+ Redis（localhost:6379）。
• 安全：Spring Security + JWT（HMAC，密钥在 mica.security.jwt-token.secret）+ RSA 公钥加密登录密码 + 算术图形验证码。配置见 framework.config.MicaAdminSecurityConfig。
  • 放行白名单在 application.yml 的 mica.security.permit-all 中。
  • 表单登录端点：POST /api/session（form-urlencoded）。
  • 注销端点：GET /api/logout。
  • 认证相关组件：framework.security.auth.*（SecAuthenticationProvider、SecAuthHandler、SecWebAuthDetailsSource、AuthUserArgumentResolver）。
  • JWT：framework.security.jwt.*（JwtTokenService、JwtTokenStore、JwtAuthenticationTokenFilter、JwtUser）。
• 基础类：framework.base.BaseModel（含 id/created_by/created_at/updated_by/updated_at 审计字段，由 framework.mybatis.MybatisPlusMetaObjectHandler 自动填充）和 framework.base.BaseController（统一响应封装）。
• 系统日志：@ApiLog 注解 + AOP 切面（framework.syslog.SysLogAspect）→ 事件 → SysLogListener 异步落库。
• API 文档：mica-openapi（Swagger/Knife4j），访问 /doc.html。
• 文件存储：dromara.x-file-storage（本地 + OSS 抽象），控制器 SysFileStorageController。