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