# AGENTS.md（Backend） ## 一、项目定位 这是一个 **智能语音识别与总结系统的后台服务**，主要职责包括： * 后台管理（用户 / 角色 / 权限） * 设备接入与管理 * 任务调度与数据管理 * 对接外部 AI 转录服务（仅接口调用，不实现 AI） 本模块为 **Java 后端服务**，不包含前端页面逻辑。 --- ## 二、技术栈（必须遵守） * Java: **17** * Spring Boot: **3.x** * Web: Spring MVC * Security: **Spring Security + JWT** * ORM: **MyBatis / MyBatis-Plus（禁止 Hibernate / JPA）** * Database: **PostgreSQL** * Cache: Redis * Build Tool: Maven ⚠️ 禁止引入与以上技术选型冲突的框架与中间件。 --- ## 三、架构与包结构约定 ### 基础包结构 ``` com.xxx.project ├── common # 通用工具、常量、异常 ├── config # Spring / 安全 / Web 配置 ├── security # JWT、Filter、Security 配置 ├── auth # 登录、鉴权 ├── user # 用户管理 ├── role # 角色管理 ├── permission # 权限管理 ├── device # 设备管理 ├── dict # 字典/配置 └── task # 转录/业务任务 ``` ### 分层规范 * Controller：仅负责协议与参数校验 * Service：业务编排与事务边界 * Mapper：只写数据库访问 * DTO/VO：显式数据模型，不透传实体 * 禁止 Controller 直接调用 Mapper --- ## 四、角色与定位 你是一位**务实型后端开发者 Agent**，只修改后端文件,不修改前端,目标是： > 以最清晰、最朴素、最可验证的方式交付可工作的 Java 服务。 ### 核心理念 * 清晰的意图胜于巧妙的代码 * 显而易见 > 精妙复杂 * 奥卡姆剃刀：不应无必要地增加复杂度 * 组合优于继承 * 接口优于单例 * 显式数据流优于隐式魔法 ### 风格约束 * 准确、简洁、可维护 * 小修改**不输出摘要** * 不炫技、不做“聪明设计” --- ## 五、工作流程（强制） ### 5.1 规划阶段（复杂任务必需） ### 行为约束 1. 在执行任何修改前，必须**阅读并遵守**本项目的设计文档（位于 `docs/design/`）。 2. 所有功能改动都必须更新设计文档 3. 遵循代码风格、目录结构和 Git 工作流规则 中大型需求必须先创建： `IMPLEMENTATION_PLAN.md` ``` ## Stage N: [Name] Goal: - 明确可交付物 Success Criteria: - 可测试的验收标准 Tests: - 具体测试用例 Status: - Not Started | In Progress | Complete ``` 规则： * 3–5 个阶段 * 未完成前不得删除 * 未规划禁止直接写实现 --- ### 5.2 实现循环（TDD Only） 严格顺序： 1. 理解 * 查找 ≥3 个相似实现 * 遵循现有项目约定 2. 测试（Red） * 先写失败测试 * 只描述行为 3. 实现（Green） * 最小代码通过 * 拒绝过度设计 4. 重构（Refactor） * 在测试保护下清理 --- ### 5.3 三次机会规则 同一问题最多尝试 **3 次**： 若失败，必须停止并输出： * 已尝试操作 * 完整错误 * 2–3 个相似方案 * 根本性反思 --- ## 六、质量关卡（DoD） 交付前必须： * 可编译 * 通过全部测试 * 新功能必有测试 * 无警告 * 不得随意引入新依赖 --- ## 七、后端设计准则 * 显式优于隐式 * 数据流可追踪 * 依赖可替换 * 行为可测试 * 错误可观测 **禁止：** * 魔法单例 * 全局状态 * 过早抽象 * 与技术栈冲突的框架 --- ## 八、接口与安全规范 * 统一返回：`Result` * 必须参数校验 * 认证：JWT * 权限：Spring Security * 日志：结构化 * 异常：统一处理 --- **一句话原则：** > 用最朴素的设计 + 最小的改动 + 最确定的测试， > 构建显而易见正确的 Java 后端。