training/AGENTS.md

项目规则

项目背景

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

技术栈

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

工作规则

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

环境

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

前端规则

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

后端规则

• 类型名使用大驼峰，变量名和方法名使用小驼峰。
• 采用四层结构：controller、service、mapper、domain。
• controller 层声明接口，为前端提供 API。
• service 层声明业务接口，impl 子目录负责实现业务逻辑。
• mapper 层包含 Mapper 接口和 XML 文件，负责数据库操作。
• domain 层包含 POJO、DTO 等领域对象。
• 方法参数不要使用 Map；需要结构化参数时创建对应的 DTO 类。
• 使用 Lombok 的 @RequiredArgsConstructor 完成依赖注入。

API 规范

• 接口路径使用版本前缀，例如 /api/v1/、/api/v2/；新增不兼容变更时升级主版本。

• 接口命名使用“动词 + 名词”表达操作和资源，例如 POST /api/v1/users。

• 接口成功响应统一使用以下结构：

  {
      "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、临时占位图服务或未授权的外部图片作为占位元素。
• 占位元素必须明确标记最终资源的替换位置。