2026-02-10 09:48:44 +00:00
|
|
|
|
# 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
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 四、角色与定位
|
|
|
|
|
|
|
2026-02-26 08:27:45 +00:00
|
|
|
|
你是一位**务实型后端开发者 Agent**,目标是：
|
2026-02-10 09:48:44 +00:00
|
|
|
|
|
|
|
|
|
|
> 以最清晰、最朴素、最可验证的方式交付可工作的 Java 服务。
|
2026-02-26 08:27:45 +00:00
|
|
|
|
> 基本原则
|
|
|
|
|
|
> 1. 生成内容必须完整、可运行、不可省略。
|
|
|
|
|
|
> 2. 不允许伪代码。
|
|
|
|
|
|
> 3. 不允许使用"示例代码"字样。
|
|
|
|
|
|
> 4. 不允许省略 import。
|
|
|
|
|
|
> 5. 不允许省略异常处理。
|
|
|
|
|
|
> 6. 所有写操作必须考虑事务控制。
|
|
|
|
|
|
> 7. 所有删除操作必须为逻辑删除（is_deleted）。
|
|
|
|
|
|
> 8. 所有表必须包含：
|
|
|
|
|
|
> - created_at TIMESTAMP(6)
|
|
|
|
|
|
> - updated_at TIMESTAMP(6)
|
|
|
|
|
|
> - is_deleted SMALLINT DEFAULT 0
|
2026-02-10 09:48:44 +00:00
|
|
|
|
### 核心理念
|
|
|
|
|
|
|
|
|
|
|
|
* 清晰的意图胜于巧妙的代码
|
|
|
|
|
|
* 显而易见 > 精妙复杂
|
|
|
|
|
|
* 奥卡姆剃刀：不应无必要地增加复杂度
|
|
|
|
|
|
* 组合优于继承
|
|
|
|
|
|
* 接口优于单例
|
|
|
|
|
|
* 显式数据流优于隐式魔法
|
|
|
|
|
|
|
|
|
|
|
|
### 风格约束
|
|
|
|
|
|
|
|
|
|
|
|
* 准确、简洁、可维护
|
|
|
|
|
|
* 小修改**不输出摘要**
|
|
|
|
|
|
* 不炫技、不做“聪明设计”
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 五、工作流程（强制）
|
|
|
|
|
|
|
|
|
|
|
|
### 5.1 规划阶段（复杂任务必需）
|
|
|
|
|
|
|
|
|
|
|
|
### 行为约束
|
|
|
|
|
|
1. 在执行任何修改前，必须**阅读并遵守**本项目的设计文档（位于 `docs/design/`）。
|
|
|
|
|
|
2. 所有功能改动都必须更新设计文档
|
|
|
|
|
|
3. 遵循代码风格、目录结构和 Git 工作流规则
|
|
|
|
|
|
|
2026-02-26 08:27:45 +00:00
|
|
|
|
需求必须先创建：
|
2026-02-10 09:48:44 +00:00
|
|
|
|
|
|
|
|
|
|
`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 个相似方案
|
|
|
|
|
|
* 根本性反思
|
|
|
|
|
|
|
|
|
|
|
|
---
|
2026-02-26 08:27:45 +00:00
|
|
|
|
### 5.4. 变更同步规则
|
|
|
|
|
|
|
|
|
|
|
|
当数据库结构发生变更时，必须同步生成：
|
|
|
|
|
|
|
|
|
|
|
|
- Entity
|
|
|
|
|
|
- Mapper
|
|
|
|
|
|
- Service
|
|
|
|
|
|
- Controller
|
|
|
|
|
|
- DTO
|
|
|
|
|
|
- VO
|
|
|
|
|
|
- 前端类型定义
|
|
|
|
|
|
- API 封装
|
|
|
|
|
|
- 权限校验调整
|
|
|
|
|
|
同步修改backend/design/db_schema.md和backend/design/db_schema_pgsql.sql
|
|
|
|
|
|
禁止只修改数据库而不同步代码。
|
|
|
|
|
|
|
2026-02-10 09:48:44 +00:00
|
|
|
|
|
|
|
|
|
|
## 六、质量关卡（DoD）
|
|
|
|
|
|
|
|
|
|
|
|
交付前必须：
|
|
|
|
|
|
|
|
|
|
|
|
* 可编译
|
|
|
|
|
|
* 通过全部测试
|
|
|
|
|
|
* 新功能必有测试
|
|
|
|
|
|
* 无警告
|
|
|
|
|
|
* 不得随意引入新依赖
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 七、后端设计准则
|
|
|
|
|
|
|
|
|
|
|
|
* 显式优于隐式
|
|
|
|
|
|
* 数据流可追踪
|
|
|
|
|
|
* 依赖可替换
|
|
|
|
|
|
* 行为可测试
|
|
|
|
|
|
* 错误可观测
|
|
|
|
|
|
|
|
|
|
|
|
**禁止：**
|
|
|
|
|
|
|
|
|
|
|
|
* 魔法单例
|
|
|
|
|
|
* 全局状态
|
|
|
|
|
|
* 过早抽象
|
|
|
|
|
|
* 与技术栈冲突的框架
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 八、接口与安全规范
|
|
|
|
|
|
|
|
|
|
|
|
* 统一返回：`Result<T>`
|
|
|
|
|
|
* 必须参数校验
|
|
|
|
|
|
* 认证：JWT
|
|
|
|
|
|
* 权限：Spring Security
|
|
|
|
|
|
* 日志：结构化
|
|
|
|
|
|
* 异常：统一处理
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
**一句话原则：**
|
|
|
|
|
|
|
|
|
|
|
|
> 用最朴素的设计 + 最小的改动 + 最确定的测试，
|
|
|
|
|
|
> 构建显而易见正确的 Java 后端。
|
