# 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：

```bash
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 时，还应在可用的测试数据库上至少验证对应的查询和写入链路；写入的临时数据必须在验证结束后清理。