hera/AGENTS.md

Hera Backend Agent Guide

本文件适用于本仓库全部目录。Codex 修改代码前必须先阅读本文件，并遵循阿里巴巴《Java 开发手册》的命名、分层、异常处理和数据库规范。

技术基线

• Java 8，Spring Boot 2.7.x，MyBatis 2.3.x，MySQL 8.x。
• 构建工具为 Maven，编码统一使用 UTF-8。
• 不得擅自升级 Java、Spring Boot 或数据库大版本。
• 优先复用现有包结构、公共响应、异常和鉴权组件，避免引入功能重复的依赖。

修改流程

1. 修改前先检查 git status，保留用户已有的未提交改动。
2. 阅读需求涉及的 Controller、Service、Mapper、实体和 SQL，不凭字段名猜测数据库结构。
3. 数据库结构以 src/main/resources/schema.sql 和用户提供的最新 SQL 为准。
4. 改动保持最小范围，不做与需求无关的格式化或重构。
5. 完成后至少执行编译、git diff --check 和受影响功能验证。

Java 编码规范

• 类名使用 UpperCamelCase，方法、参数和变量使用 lowerCamelCase，常量使用 UPPER_SNAKE_CASE。
• Mapper 接口统一以 Mapper 结尾，Service 和 Controller 分别以 Service、Controller 结尾。
• 包名全部小写；按 controller/service/mapper/entity 职责分层，禁止跨层绕过 Service 直接访问 Mapper。
• 方法职责保持单一。复杂条件先拆分为有业务含义的方法，避免深层嵌套。
• 禁止无含义的魔法值；有业务含义的状态值应提取为常量或枚举。
• 字符串比较使用常量调用 equals，包装类型比较使用 equals，不得依赖 ==。
• 返回集合时优先返回空集合而不是 null。
• 捕获异常后必须处理、转换或记录，禁止空 catch；不得把数据库或系统内部异常原文直接返回前端。
• ThreadLocal 必须在请求结束时执行 remove()。
• 日期时间使用 java.time API，不新增 Date/Calendar 业务代码。
• 不写无意义注释；实体类、实体字段和公共 API 必须使用 /** ... */ Javadoc 说明业务含义。

Spring 与接口规范

• Controller 只负责参数接收、鉴权上下文和响应包装，业务逻辑放在 Service。
• 写操作需要事务时在 Service 层使用 @Transactional。
• 接口统一返回 ApiResponse<T>，业务错误统一抛出 BusinessException。
• 新增 /api/** 接口默认需要 JWT；公开接口必须显式加入白名单并说明原因。
• 请求参数必须设置合理的长度、范围和分页上限，不信任客户端传入的用户 ID 或状态值。
• 密码、密钥、身份证信息等敏感字段不得出现在日志或接口响应中。

MyBatis 规范

• Mapper 接口只声明方法并保留 @Mapper；业务 SQL 统一写在 src/main/resources/mapper/*.xml。
• XML 文件名与 Mapper 接口名一致，namespace 必须是 Mapper 接口的完整类名。
• 多参数方法必须使用 @Param 明确命名。
• 查询必须显式列出字段，禁止使用 SELECT *。
• 数据库字段使用 snake_case，Java 属性使用 lowerCamelCase；依赖 MyBatis 驼峰映射或显式 resultMap。
• 新增记录需要回填主键时使用 useGeneratedKeys="true" keyProperty="id"。
• 更新和删除必须带明确的主键或业务条件；禁止无条件全表更新、删除。
• 分页参数必须在 Service 层限制范围；当前单页最大值为 100。
• 唯一约束和外键冲突转换为可理解的业务响应，不向客户端暴露 SQL。

数据库规范

• 表名、字段名使用小写 snake_case；主键统一命名为 id。
• 表和重要字段必须有业务注释；时间字段统一使用 created_at、updated_at。
• 线上可重复执行的初始化脚本使用 CREATE TABLE IF NOT EXISTS，禁止在应用启动脚本中使用 DROP TABLE。
• 修改表结构时考虑已有数据兼容性；不得通过删除重建表来完成普通字段变更。
• 账号密码只保存安全哈希；真实姓名、身份证号等敏感信息按字段约定加密或哈希后存储。

验证命令

本机无全局 Maven 时，使用 IntelliJ 自带 Maven 和已安装的 JDK 8：

env JAVA_HOME='/Library/Java/JavaVirtualMachines/jdk1.8.0_251.jdk/Contents/Home' \
  '/Applications/IntelliJ IDEA.app/Contents/plugins/maven/lib/maven3/bin/mvn' test

涉及数据库 Mapper 时，还应在可用的测试数据库上至少验证对应的查询和写入链路；写入的临时数据必须在验证结束后清理。