backend-design

项目上下文与总原则

• 遵循本项目既有分层架构：controller → service 接口 → serviceImpl → mapper / entity / DTO / VO，以及 core 下的「门面 + 执行器 + 解析器/模板」模式（参考 AiCodeGeneratorFacade、CodeParserExecutor、CodeFileSaverExecutor）。
• 所有 Web 接口统一返回 BaseResponse<T>，优先通过 ResultUtils.success / ResultUtils.error 构建响应；需要自定义提示时可以使用 new BaseResponse<>(code, data, message)。
• 参数校验、业务前置校验、权限校验统一使用 ThrowUtils.throwIf(...) 搭配 ErrorCode / MyException，不要在 Controller 中随意使用 if (...) return 之类的早退返回。
• 依赖注入优先使用构造器注入 + Lombok：在 controller、serviceImpl 中使用 @RequiredArgsConstructor，同时配合 @Slf4j 打日志。
• 全局异常通过 GlobalExceptionHandler 兜底，业务代码中抛出 MyException 或通过 ThrowUtils.throwIf 抛出，不在控制层/服务层到处写 try-catch 吃掉异常。
• 统一使用 Hutool 工具类，如 StrUtil 做字符串判空，BeanUtil 做对象属性拷贝。
• 绝对不要修改前端目录：禁止改动 ai-generate-code-frontend/** 下的任何文件，仅操作 Java 后端、SQL、Maven、YAML 等后端相关内容。

统一响应与异常处理风格

• 所有对外接口（@RestController 下的方法）返回类型统一为 BaseResponse<T>：
  • 正常成功：return ResultUtils.success(data);
  • 需要自定义提示：return new BaseResponse<>(20000, data, "自定义提示");
  • 特殊业务分支可以按现有风格使用 new BaseResponse<>(code, data, message)，但保持与项目已有语义一致（例如管理员已存在等场景）。
• 参数 & 状态校验：
  • 统一使用 ThrowUtils.throwIf(condition, ErrorCode.PARAMS_ERROR, "具体错误信息");
  • 登录态校验：ThrowUtils.throwIf(user == null || user.getId() == null, ErrorCode.NOT_LOGIN_ERROR, "用户未登录或会话失效");
  • 资源不存在：ThrowUtils.throwIf(entity == null, ErrorCode.NOT_FOUND_ERROR, "xxx 不存在");
  • 权限不足：ThrowUtils.throwIf(!hasPermission, ErrorCode.NO_AUTH_ERROR, "无权限/只能操作自己的资源");
  • 通用系统错误：使用 ErrorCode.SYSTEM_ERROR 或 ErrorCode.OPERATION_ERROR，语义同项目现有代码。
• GlobalExceptionHandler 行为：
  • MyException：记录错误日志，包装为 ResultUtils.error(e.getCode(), e.getMessage());
  • 其他 RuntimeException：记录堆栈，包装为 ResultUtils.error(ErrorCode.SYSTEM_ERROR, "系统错误");
  • 编写新的异常/错误处理逻辑时，保持与此模式兼容，不破坏现有异常分层。

针对「修改」场景的行为规范

当用户指令中包含**「修改」**字样时，执行以下策略：

1. 最小修改原则
   • 只在必要的最小范围内修改代码，尽量局部变更，避免重排大段结构。
   • 保持方法签名、入参与返回类型不变，除非用户明确要求调整接口。
2. 保持现有风格与语义
   • 继续使用 ThrowUtils.throwIf 做参数与权限校验，沿用现有错误码与错误信息风格。
   • 控制器里依旧通过 ResultUtils.success 返回统一响应。
   • 日志继续采用当前格式：log.info("xxx, param={}", param); 或 log.error("xxx, appId={}, userId={}", appId, userId, e);
3. 保留原有实现思路
   • 若只做 Bug 修复或小优化，直接在原逻辑上微调即可。
   • 若必须大幅重构单个方法，也要优先采用「提取新私有方法 + 旧方法委托调用新方法」的方式，保持原方法作为入口存在，以便回滚。