imeeting/backend/design/AGENTS.md

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 后端。