Imported from Godfrey-ngd/IntervAI (AGENTS.md). Install upstream with npx skills add Godfrey-ngd/IntervAI. Copyright stays with the author.

AI Interview Platform 编码规范

Spring Boot 4.0 + Java 21 + Spring AI + React 面试平台。写代码时必须遵守以下规则。

一、项目结构

单模块 Maven 项目，按功能分包：

interview.guide/
├── App.java                          # @SpringBootApplication + @EnableScheduling
│
├── common/                           # 通用基础能力
│   ├── annotation/                   #   @RateLimit（可重复注解，滑动窗口限流）
│   ├── aspect/                       #   RateLimitAspect（AOP + Redis Lua 限流）
│   ├── ai/                           #   StructuredOutputInvoker（结构化输出重试）
│   │                                 #   LlmProviderRegistry（多 LLM Provider 注册与缓存）
│   ├── async/                        #   AbstractStreamConsumer/Producer（Redis Stream 模板）
│   ├── config/                       #   配置类（CORS、S3、ObjectMapper、OpenAPI、LlmProvider）
│   ├── constant/                     #   CommonConstants、AsyncTaskStreamConstants
│   ├── exception/                    #   ErrorCode（10 个错误域 1xxx-10xxx）
│   │                                 #   BusinessException、RateLimitExceededException
│   ├── model/                        #   AsyncTaskStatus
│   └── result/                       #   Result<T>（统一响应包装）
│
├── infrastructure/                   # 技术基础设施
│   ├── export/                       #   PdfExportService（iText 8）
│   ├── file/                         #   文件解析（Tika）、存储（S3/RustFS）、校验、清洗
│   ├── mapper/                       #   MapStruct 映射器（Interview、Resume、KB、RagChat）
│   └── redis/                        #   RedisService、InterviewSessionCache
│
└── modules/                          # 业务模块（每个模块自包含 MVC 分层）
    ├── resume/                       #   简历管理：上传、解析、AI 评分、去重
    ├── interview/                    #   模拟面试：会话、AI 出题、答题评估、报告导出
    ├── knowledgebase/                #   知识库：文档上传、向量化（pgvector）、RAG 查询、聊天会话
    ├── interviewschedule/            #   面试日程：日历管理、AI 解析面试邀请
    └── voiceinterview/               #   语音面试：WebSocket 实时通话、ASR/TTS、多轮评估

技术栈：Spring Boot 4.0 / Java 21（虚拟线程）/ Spring AI 2.0 / JPA + PostgreSQL + pgvector / Redisson / Redis Stream / MapStruct / iText 8 / Apache Tika

前端：React 18 + TypeScript + Vite + TailwindCSS 4（frontend/ 目录）

二、分层架构

Controller → Service → Repository
                ↕
          Infrastructure（RedisService、FileStorageService、PdfExportService）

Controller 层

• 仅路由和委托，禁止业务逻辑
• RESTful 风格：/api/{module}/{action}
• 使用 @RateLimit 注解做限流（@Repeatable，每维度独立 count）
• 通过 @Valid + @RequestBody 校验请求

Service 层

• 业务逻辑编排，合理拆分大 Service（如 ResumeUploadService、ResumeParseService、ResumeGradingService）
• 使用 LlmProviderRegistry.getChatClientOrDefault(provider) 获取 ChatClient（支持多 Provider）
• 异步任务通过 Redis Stream（AbstractStreamProducer/Consumer 模板）
• 所有业务异常使用 BusinessException(ErrorCode.XXX, message)，禁止 RuntimeException

Repository 层

• Spring Data JPA，继承 JpaRepository
• 自定义查询用 @Query 或方法命名约定

三、JavaBean 后缀规则

• 不可变数据载体优先用 record（如 CreateInterviewRequest、QueryRequest）
• Entity 映射用 MapStruct（@Mapper(componentModel = "spring")）
• 简单场景可用 BeanUtils.copyProperties
• 禁止直接返回 Entity 给前端

四、异常与错误码

ErrorCode 分域规则

异常处理规则

• 抛出：throw new BusinessException(ErrorCode.XXX, "描述信息")
• 禁止 throw new RuntimeException(...) —— 必须用 BusinessException
• 全局异常处理器 GlobalExceptionHandler 统一返回 HTTP 200 + Result.error(code, message)
• catch (BusinessException e) { throw e; } 保留业务异常原样抛出

五、限流组件

// 每个 @RateLimit 对应一个维度，各自独立的 count/interval/timeUnit
@RateLimit(dimension = RateLimit.Dimension.GLOBAL, count = 10)
@RateLimit(dimension = RateLimit.Dimension.IP, count = 10)
public Result<QueryResponse> queryKnowledgeBase(...) { ... }

• 注解：@Repeatable，AOP 切面 RateLimitAspect 逐条执行单 key Lua 脚本
• Lua 脚本：resources/scripts/rate_limit_single.lua，滑动时间窗口
• Redis Key 设计：ratelimit:{ClassName:MethodName}:dimension（Hash Tag 分组）
• 维度：GLOBAL（全局限流）、IP（按 IP）、USER（按用户）

六、异步任务（Redis Stream）

使用 AbstractStreamProducer / AbstractStreamConsumer 模板：

// 生产者
public class VectorizeStreamProducer extends AbstractStreamProducer<KnowledgeBaseTask> { ... }

// 消费者
public class VectorizeStreamConsumer extends AbstractStreamConsumer<KnowledgeBaseTask> { ... }

• 三个管道：知识库向量化、简历分析、面试评估
• 常量定义在 AsyncTaskStreamConstants
• 消费者实现 processMessage() 方法
• 失败重试：最大 3 次，超过后标记 FAILED
• 实体删除：异步处理前校验实体是否存在，不存在直接 ACK 丢弃

七、AI 服务调用

LLM Provider

// 统一通过 Registry 获取，支持多 Provider 路由
ChatClient chatClient = llmProviderRegistry.getChatClientOrDefault(provider);

• 配置：app.ai.providers.{providerId}.baseUrl/apiKey/model
• 默认 Provider：app.ai.default-provider

结构化输出

// 使用 StructuredOutputInvoker 做重试包装
String result = structuredOutputInvoker.invokeStructuredOutput(prompt, ChatClient, outputConverter);

Prompt 模板

• 存放在 resources/prompts/，使用 StringTemplate（.st）格式
• 语音面试角色模板：prompts/voice-interview/*.st

八、格式与命名

• 2 空格缩进，列限制 100 字符
• 类名 UpperCamelCase，方法名 lowerCamelCase，常量 UPPER_SNAKE_CASE
• 禁止通配符导入
• 优先 record 作为不可变数据载体
• 使用现代 Java 特性：switch 表达式、pattern matching instanceof、text blocks
• 避免内联全限定类名（用 import 代替）

九、事务规则

• @Transactional 放 Service 层
• 禁止在事务方法内调用外部 API（LLM 调用、S3 上传等）
• 禁止同类内部调用 @Transactional 方法（AOP 代理不生效）
• 保持事务范围最小

十、日志规范

• 使用 SLF4J（@Slf4j）
• 结构化日志：log.info("Session created: sessionId={}, role={}", id, role)
• 异常作为最后一个参数：log.error("Evaluation failed: sessionId={}", id, e)
• 禁止 log.error("Error: {}", e.getMessage())（丢失堆栈）

十一、数据库

• PostgreSQL + pgvector（向量搜索，1024 维 COSINE）
• JPA 实体使用 @Data、@Builder、@NoArgsConstructor、@AllArgsConstructor
• ddl-auto 开发环境 update，生产环境 false（表结构由 JPA Entity 注解驱动，无需手动迁移）

十二、配置管理

• 配置文件：application.yml + .env（通过 spring.config.import）
• 敏感信息（API Key、数据库密码）放 .env，不入版本控制
• 业务配置用 @ConfigurationProperties（如 VoiceInterviewProperties、AppConfigProperties）
• 禁止 @Value 散落在 Service 中（集中到 Properties 类）

十三、测试

• JUnit 5 + Mockito + AssertJ
• @DisplayName 中文描述测试意图
• @Nested 按功能分组测试
• 集成测试用 H2 内存数据库（application-test.yml）
• 限流测试需要真实 Redis

速查：禁止清单