OpenIsle/backend/AGENTS.md

Backend 协作指引

1) 适用范围

• 作用于 backend/ 目录及其子目录。
• 若与根 AGENTS.md 冲突，以本文件为准（仅后端范围）。

2) 代码结构心智模型

• controller/：接口层（入参校验、权限边界、响应格式）。
• service/：业务编排与领域规则（核心逻辑放这里）。
• repository/：JPA 数据访问（基于实体与查询方法）。
• model/：实体模型与枚举。
• dto/ + mapper/：对外契约和映射转换。
• config/：安全、缓存、MQ、OpenAPI、初始化器等基础设施配置。
• search/：OpenSearch 索引与事件驱动同步。

3) 后端修改规则

• 控制器保持“薄”，复杂逻辑下沉到 service/。
• DTO 变更优先考虑兼容性，避免无版本的破坏性字段删除/改名。
• 新增接口时：
  • 补齐必要的鉴权规则（SecurityConfig）。
  • 补齐 OpenAPI 注解（@Operation、@ApiResponse 等）。
• 涉及缓存时，确认 CachingConfig 中缓存名、TTL 与失效策略一致。

4) 重点一致性检查

• 鉴权与公开接口：
  • src/main/java/com/openisle/config/SecurityConfig.java
• 搜索索引同步（实体字段/文案变更时）：
  • src/main/java/com/openisle/search/SearchDocumentFactory.java
  • src/main/java/com/openisle/search/SearchIndexEventPublisher.java
• 消息通知链路（评论/通知相关）：
  • src/main/java/com/openisle/config/RabbitMQConfig.java
  • src/main/java/com/openisle/config/ShardingStrategy.java
  • src/main/java/com/openisle/service/NotificationProducer.java
• 环境变量消费面：
  • src/main/resources/application.properties
  • 根目录 .env.example

5) 数据与事务注意事项

• 涉及多表写入时，明确事务边界，避免半成功状态。
• 避免在 Controller 直接操作 Repository。
• JPA 懒加载对象对外返回前应通过 DTO 映射，避免序列化副作用。

6) 测试与验证

• 首选全量：mvn test
• 变更集中时可先跑目标测试（示例）：
  • mvn -Dtest=PostControllerTest test
  • mvn -Dtest=SearchServiceTest test
• 涉及搜索/MQ 配置时，至少完成一次启动级验证或关键集成测试。

7) 输出要求

• 明确列出“接口/字段/权限/事件”是否发生变化。
• 若影响 mcp/ 或 docs/，在结果中显式提示需同步改动。