| name | mica-admin-backend |
| description | Use when adding, modifying or reviewing backend code in mica-admin-server (Spring Boot 4.1 + MyBatis-Plus + Spring Security). Covers the 6-file CRUD module recipe (entity/query/mapper/service/impl/controller), response conventions (success returns raw body, code=0 only on error), @ApiLog audit logging, @PreAuthorize permission codes, IPage pagination, Excel export, caching, and sys_menu seeding. |
mica-admin 后端开发
Spring Boot 4.1 + MyBatis-Plus 3.5 + Spring Security + JWT，主包 net.dreamlu.mica.admin。
分层与文件位置
业务代码一律落在 mica-admin-server/src/main/java/net/dreamlu/mica/admin/project/<module>/：
| 层 | 目录 | 命名 | 基类/父接口 |
|---|
| 实体 | entity/ | SysBanner | extends BaseModel |
| 查询条件 | pojo/ | BannerQuery | 纯 @Data POJO |
| Mapper | mapper/ | SysBannerMapper + 同名 .xml | BaseMapper<T> |
| 服务接口 | service/ | ISysBannerService | IService<T> |
| 服务实现 | service/impl/ | SysBannerServiceImpl | ServiceImpl<M, T> |
| 控制器 | controller/ | SysBannerController | extends BaseController |
框架层（framework/）只在需要扩展安全、AOP、序列化等横切能力时才改。
完整可复制模板见 references/crud-module.md。
硬性约定
响应格式 — 成功直接返回裸数据体（对象 / List / IPage），不要手工包 R.success()；写操作返回 void。失败由全局异常处理器包成 { code, msg }，且成功 code = 0（不是 200），前端拦截器按此适配，不要改。
审计字段 — BaseModel 已含 id/createdBy/createdAt/updatedBy/updatedAt，由 MybatisPlusMetaObjectHandler 自动填充。实体里不要重复声明，也不要手动 set。
分页 — 控制器直接把 Page<T> page 作为入参（Spring 自动绑定 ?current=&size=），返回 IPage<T>：
public IPage<SysBanner> list(Page<SysBanner> page, BannerQuery query) {
return bannerService.page(page, bannerService.getQueryWrapper(query));
}
查询条件构造 — 统一放在 service 的 getQueryWrapper(query)，用 LambdaQueryWrapper + 条件生效标志位，不要在控制器里拼 wrapper：
wrapper.like(StringUtil.isNotBlank(name), SysBanner::getName, name);
wrapper.eq(query.getEnabled() != null, SysBanner::getEnabled, query.getEnabled());
时间范围用 List<LocalDateTime> createTime，size() > 1 时 between。
业务异常 — 用 R.throwFail("存在用户岗位关系")，不要自己 throw new RuntimeException。
校验 — 控制器方法加 @Validated，类上加 @Validated 才能校验 @NotEmpty 等方法级参数。新增/修改共用实体时用 CreateGroup / UpdateGroup 分组（BaseModel.id 已按分组标注 @Null / @NotNull）。
删除 — 批量删除签名固定为 @NotEmpty @RequestBody Set<Long> ids，DELETE 方法。有关联关系的先校验再删（deleteIfUnusedByIds）。
缓存 — @Cacheable(value = "sys:post:user#10m", key = "#userId")，value 用 冒号分隔业务名#TTL 格式，TTL 由 mica 的 Redis cache 解析。
Excel 导出 — 控制器 @GetMapping("download") + @ResponseExcel(name = "岗位数据") 返回 List<T>；实体字段加 @ExcelProperty(value, index) + @ColumnWidth，枚举列用 converter = EnabledEnum.Converter.class，不导出的字段 @ExcelIgnore。
Mapper XML — 放在 src/main/resources/net/dreamlu/mica/admin/**/mapper/*Mapper.xml（与 Java 包路径镜像）。简单 CRUD 靠 MyBatis-Plus，无需写 XML。
权限码
格式 <模块>:<资源>:<动作>，动作用 list / query / add / edit / del / export。
@PreAuthorize("@sec.hasPermission('system:banner:list')")
⚠️ 用 :del，不要用 :remove。历史遗留的 SysPostController / SysNoticeController / SysMessageController 里写的是 :remove，但数据库 sys_menu 与前端按钮用的都是 :del——这几处是既存 bug，新代码一律对齐 :del，改动老模块时顺手核对 docs/database/mysql.sql。
放行接口写进 application.yml 的 mica.security.permit-all，不要在代码里关安全。
审计日志
写操作加 @ApiLog("新增轮播图")，AOP（framework.syslog.SysLogAspect）发事件 → SysLogListener 异步落库。查询接口不加。@Operation(summary = ...) 用于 Swagger，两者都要写。
新增模块 checklist
- 建表 SQL 写进
docs/database/mysql.sql。
- 可用
src/test/java/.../generator/MysqlAutoGenerator.java 生成骨架（改 strategyConfig.addInclude(...)，产物在 src/gen_code/，需手工搬进 project/）。
- 按上表补全 6 个文件。
- 在
docs/database/mysql.sql 追加 sys_menu 菜单行 + 5 条按钮权限行（模板见 references）。
mvn test -Dtest=XxxTest -DfailIfNoTests=false / mvn spring-boot:run -Dspring-boot.run.profiles=dev 验证。- 前端联调：前端接口类型是手写的（无 swagger 代码生成），改动实体字段后需同步
mica-admin-web/src/api/ 与 uniapp 的类型定义；/doc.html 可用于人工核对。
命令
mvn package
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
Java 用 Tab 缩进（.editorconfig），LF 行尾，文件末尾留换行。日志用 Log4j2，容器是 Tomcat（4.1 已移除 Undertow）。
