training/AGENTS.md

# 项目规则

## 项目背景

这是一个前后端分离的培训项目。

## 技术栈

- 前端：React 18、TypeScript、Vite
- 后端：Spring Boot 3.4.5、Java 21、MyBatis-Plus
- 数据库：MySQL 8
- 缓存：Redis

## 工作规则

- 所有文件使用 UTF-8 编码，避免中文乱码。
- 修改代码前，先阅读项目结构和相关文件。
- 修改前说明将影响哪些文件。
- 修改后给出启动命令和测试步骤。
- 不要把所有功能堆在一个页面或一个文件中。
- 建表或修改表结构时，补充完整的中文注释。
- 涉及删除文件、删除数据或清空数据库时，必须先二次确认，并提供操作日志和回滚说明。

## 环境

- 使用 `.env.example` 作为环境配置参考。
- 不要将密码、令牌或其他敏感信息写入代码、日志或提交内容。

## 前端规则

- 遵循现有组件、路由、状态管理和样式规范。
- 保持组件职责清晰，避免创建过大的组件。
- 修改用户界面时验证桌面端和移动端布局。

## 后端规则

- 代码须符合阿里巴巴Java开发规范、springboot框架规范、其他使用到的框架、中间件规范。
- 代码须简洁明了，不能冗杂。
- 能通用的代码最好通用。

## API 规范

- 接口路径使用版本前缀，例如 `/api/v1/`、`/api/v2/`；新增不兼容变更时升级主版本。
- 接口命名使用“动词 + 名词”表达操作和资源，例如 `POST /api/v1/users`。
- 接口成功响应统一使用以下结构：

    ```json
    {
        "code": 200,
        "message": "success",
        "data": {}
    }
    ```

- 错误码集中定义并保持全局唯一；不要在业务代码中散落硬编码错误码和错误信息。
- 分页接口统一使用 `page`、`pageSize` 请求参数，并在响应中提供 `total` 总条数；分页数据放在 `data` 中。
- 需要认证的接口通过 `Authorization: Bearer <token>` 传递凭证。
- JSON 请求和响应使用 `Content-Type: application/json`，并根据实际内容设置 `Accept` 请求头。
- 新增接口时同步明确 HTTP 方法、路径、请求头、请求参数、响应结构、错误码和版本归属。

## 数据库规则

- 表名使用大写，多个单词之间使用下划线连接，例如 `USER_PROFILE`。
- 新建或修改表结构后，将最终建表语句保存到 `sql/<表名>.sql`。
- SQL 中为表和字段补充清晰的中文注释。
- 数据库写操作前先确认目标、范围、影响行数和回滚方式。

## 输出规范

- 使用标准代码格式。
- 完成时说明：修改了哪些文件、每个文件的变化、验证方法、是否涉及 SQL，以及风险和回滚方式。

## 通用约束

### 语言规范（不可变）

- 文档和代码注释必须使用中文。
- 变量名、函数名、类名和其他代码标识符仍使用英文，并遵循对应语言的命名规范。

### 可观测性与兜底

- 任务必须具备完整链路：任务 ID、关联引用和关键日志。
- 失败时必须提供明确的兜底提示，并支持合理的重试机制。
- 日志不得记录密码、令牌或其他敏感信息。

### 占位元素

- 图标或图片资源尚未确定时，使用占位 `div` 并添加 `TODO` 注释。
- 禁止使用临时 SVG、临时占位图服务或未授权的外部图片作为占位元素。
- 占位元素必须明确标记最终资源的替换位置。