3.8 KiB
3.8 KiB
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 规划阶段（复杂任务必需）
行为约束
- 在执行任何修改前，必须阅读并遵守本项目的设计文档（位于
docs/design/）。 - 所有功能改动都必须更新设计文档
- 遵循代码风格、目录结构和 Git 工作流规则
中大型需求必须先创建：
IMPLEMENTATION_PLAN.md
## Stage N: [Name]
Goal:
- 明确可交付物
Success Criteria:
- 可测试的验收标准
Tests:
- 具体测试用例
Status:
- Not Started | In Progress | Complete
规则：
- 3–5 个阶段
- 未完成前不得删除
- 未规划禁止直接写实现
5.2 实现循环（TDD Only）
严格顺序：
-
理解
- 查找 ≥3 个相似实现
- 遵循现有项目约定
-
测试（Red）
- 先写失败测试
- 只描述行为
-
实现（Green）
- 最小代码通过
- 拒绝过度设计
-
重构（Refactor）
- 在测试保护下清理
5.3 三次机会规则
同一问题最多尝试 3 次：
若失败，必须停止并输出：
- 已尝试操作
- 完整错误
- 2–3 个相似方案
- 根本性反思
六、质量关卡（DoD）
交付前必须：
- 可编译
- 通过全部测试
- 新功能必有测试
- 无警告
- 不得随意引入新依赖
七、后端设计准则
- 显式优于隐式
- 数据流可追踪
- 依赖可替换
- 行为可测试
- 错误可观测
禁止：
- 魔法单例
- 全局状态
- 过早抽象
- 与技术栈冲突的框架
八、接口与安全规范
- 统一返回：
Result<T> - 必须参数校验
- 认证：JWT
- 权限：Spring Security
- 日志：结构化
- 异常：统一处理
一句话原则：
用最朴素的设计 + 最小的改动 + 最确定的测试， 构建显而易见正确的 Java 后端。