项目 on XEDCZQ的博客

Ai面试项目：knowledgebase模块

Fri, 15 May 2026 21:55:13 +0800

Knowledgebase 知识库模块设计与实现

这篇笔记记录我在 interview-guide 项目中对 Knowledgebase 模块的实现。目标是把“文档上传、向量化、RAG 查询、会话关联”打通成一个可持续迭代的知识服务能力。

模块能力概览

文档管理：支持上传、下载、删除、分类、关键字检索与统计。
向量化能力：基于 pgvector 存储向量，使用异步任务进行切片与入库。
RAG 问答：支持非流式与流式（SSE）多知识库检索问答。
会话协同：删除知识库时自动清理关联会话引用，降低数据不一致风险。

状态转换

图1：KnowledgeBase 主状态机

flowchart TD
A["调用 POST /api/knowledgebase/upload 上传文件"] --> B["文件校验 + 类型检测 + 去重检查"]

B --> C{"是否重复文件(fileHash已存在)"}
C -->|是| D["返回已有知识库记录\nduplicate=true\n不触发向量化"]
C -->|否| E["解析文本内容 + 上传文件到存储"]

E --> F["保存 KnowledgeBaseEntity\n初始 vectorStatus=PENDING"]
F --> G["发送向量化任务到 Redis Stream"]

G --> H["VectorizeStreamConsumer 消费任务"]
H --> I["markProcessing\nvectorStatus=PROCESSING"]

I --> J["vectorizeAndStore\n切分文档并写入 pgvector"]
J --> K{"向量化是否成功"}

K -->|是| L["markCompleted\nvectorStatus=COMPLETED\nvectorError=null"]
K -->|否| M{"retryCount < 3 ?"}
M -->|是| N["任务重新入队(retry+1)"]
N --> H
M -->|否| O["markFailed\nvectorStatus=FAILED\n写入vectorError"]

P["调用 POST /api/knowledgebase/{id}/revectorize"] --> Q["状态重置为 PENDING\n清空vectorError"]
Q --> G

R["调用 DELETE /api/knowledgebase/{id} 删除知识库"] --> S["移除RAG会话关联"]
S --> T["删除向量数据(尽力) + 删除存储文件(尽力)"]
T --> U["删除知识库DB记录\n生命周期结束"]

图2：分片上传知识库流程

flowchart TD
A["上传知识库成功"] --> B["保存知识库记录 vectorStatus=PENDING"]
B --> C["发送向量化任务到 Redis Stream"]
C --> D["VectorizeStreamConsumer 启动并轮询"]
D --> E["读取一条消息 kbId + content + retryCount"]
E --> F["更新状态 PROCESSING"]
F --> G["执行 vectorizeAndStore"]

G --> H["删除该 kbId 的旧向量"]
H --> I["文本分块 TokenTextSplitter"]
I --> J["给每个分块打 metadata kb_id"]
J --> K["分批调用 vectorStore.add 写入向量库"]

K --> L["更新状态 COMPLETED"]
L --> M["ACK 消息"]

G --> N{"处理异常"}
N -->|是| O{"retryCount < 3"}
O -->|是| P["retryCount+1 重新入队"]
P --> M
O -->|否| Q["更新状态 FAILED 并记录错误"]
Q --> M

关键接口设计

`GET /api/knowledgebase/list` 获取知识库列表（状态过滤 + 排序）

调用链：

Result.success(listService.listKnowledgeBases(status, sortBy));
knowledgeBaseRepository.findByVectorStatusOrderByUploadedAtDesc(vectorStatus);
knowledgeBaseRepository.findAllByOrderByUploadedAtDesc();
entities = sortEntities(entities, sortBy);

`GET /api/knowledgebase/{id}` 获取知识库详情

调用链：

listService.getKnowledgeBase(id);
knowledgeBaseRepository.findById(id);

`DELETE /api/knowledgebase/{id}` 删除知识库

核心流程：

deleteService.deleteKnowledgeBase(id);
knowledgeBaseRepository.findById(id);
sessionRepository.findByKnowledgeBaseIds(List.of(id));
vectorService.deleteByKnowledgeBaseId(id);
storageService.deleteKnowledgeBase(kb.getStorageKey());
knowledgeBaseRepository.deleteById(id);

说明：

先清理 RAG 会话关联，再删除向量与对象存储文件，最后删除数据库记录。
向量删除和对象存储删除失败仅 warn，不阻断主删除流程。

`POST /api/knowledgebase/query` 非流式问答（多知识库）

限流：

GLOBAL/IP 各 10

调用链：

queryService.queryKnowledgeBase(request);
answerQuestion(...);
countService.updateQuestionCounts(...);
vectorService.similaritySearch(...);

处理要点：

入参 knowledgeBaseIds 与 question 必填。
无命中返回固定文案“未检索到信息”。
有命中则拼接 context，构建提示词后调用默认 ChatClient 生成答案。
返回 QueryResponse(answer, primaryKbId, kbNamesStr)。

`POST /api/knowledgebase/query/stream` 流式问答（SSE，多知识库）

限流：

GLOBAL/IP 各 5

调用链：

queryService.answerQuestionStream(kbIds, question);
countService.updateQuestionCounts(...);
vectorService.similaritySearch(...);
chatClient.prompt().stream().content();
normalizeStreamOutput(...);

处理要点：

返回类型为 Flux<String>（text/event-stream）。
空输入或无检索命中时返回固定降级文本流。
流内异常与外层异常都做统一降级输出。

`GET /api/knowledgebase/categories` 获取所有分类名

调用链：

listService.getAllCategories();

Result<List<String>>

`GET /api/knowledgebase/category/{category}` 按分类获取知识库列表

调用链：

listService.listByCategory(category);

Result<List<KnowledgeBaseListItemDTO>>

`GET /api/knowledgebase/uncategorized` 获取未分类知识库列表

调用链：

listService.listByCategory(category);

说明：

当前实现沿用分类查询路径，通过特定分类值区分未分类集合。

`PUT /api/knowledgebase/{id}/category` 更新知识库分类

调用链：

listService.updateCategory(id, body.get("category"));

处理要点：

先按 id 查记录，不存在抛业务异常。
存在则更新 category 字段并保存。

`POST /api/knowledgebase/upload` 上传知识库文件（multipart）

参数：

file（必填）
name（可选）
category（可选）

限流：

GLOBAL/IP 各 3

调用链：

uploadService.uploadKnowledgeBase(file, name, category);
findByFileHash(fileHash);

处理流程：

校验文件非空、大小（最大 50MB）。
按 MIME + 扩展名白名单校验类型（PDF/DOCX/DOC/TXT/MD）。
计算 SHA-256 并做去重。
解析正文，空文本直接失败。
上传原文件到 RustFS（S3 兼容），生成 fileKey/fileUrl。
落库 KnowledgeBaseEntity，初始向量状态 PENDING。
投递异步向量化任务到 Redis Stream（knowledgebase:vectorize:stream）。
返回 knowledgeBase + storage + duplicate=false。

`GET /api/knowledgebase/{id}/download` 下载原始知识库文件

调用链：

listService.getEntityForDownload(id);
listService.downloadFile(id);

ResponseEntity<byte[]>（包含 Content-Disposition 与 Content-Type）

`GET /api/knowledgebase/search?keyword=...` 关键字搜索知识库

调用链：

listService.search(keyword);

`GET /api/knowledgebase/stats` 获取知识库统计信息

调用链：

listService.getStatistics();

KnowledgeBaseStatsDTO

`POST /api/knowledgebase/{id}/revectorize` 手动重新向量化

限流：

GLOBAL/IP 各 2

调用链：

uploadService.revectorize(id);

处理流程：

按 id 查知识库，不存在抛异常。
从对象存储下载原文件并重新解析文本。
解析失败或空文本直接失败。
更新向量状态为 PENDING。
投递向量化任务到 Redis Stream。
立即返回成功，前端轮询状态。

异步向量化处理流程（核心实现）

// 1) 删除旧向量
deleteByKnowledgeBaseId(knowledgeBaseId);

// 2) 文本切片（默认无重叠）
List<Document> chunks = textSplitter.apply(List.of(new Document(content)));

// 3) 写入 metadata（kb_id）
chunks.forEach(chunk -> chunk.getMetadata().put("kb_id", knowledgeBaseId.toString()));

// 4) 分批向量化写入（DashScope batch <= 10）
for (int i = 0; i < batchCount; i++) {
 int start = i * MAX_BATCH_SIZE;
 int end = Math.min(start + MAX_BATCH_SIZE, totalChunks);
 List<Document> batch = chunks.subList(start, end);
 vectorStore.add(batch);
}

小结

Knowledgebase 模块的核心是把“文件资产管理”和“检索增强问答”打通。对我来说，真正有价值的不只是上传成功，而是文档能够稳定进入向量化链路，并最终在问答场景里提供可复用、可追踪的知识支持。

Ai面试项目：voice interview模块

Thu, 14 May 2026 22:34:43 +0800

VoiceInterview 语音面试模块设计与实现

这篇笔记记录我在 interview-guide 项目中对 VoiceInterview 模块的实现。核心目标是让语音面试具备“实时交互 + 可恢复会话 + 可追踪评估”的完整体验。

模块能力概览

实时语音对话：基于 WebSocket + 千问3语音模型（ASR/TTS/LLM 统一 API Key）。
流式体验优化：句子级并发 TTS，边生成边合成边播放，首包延迟约 200ms。
服务端 VAD：自动断句，提供实时字幕（含中间结果）。
回声防护：支持手动提交机制，避免 AI 播报被误录入。
会话连续性：支持暂停/恢复与多轮上下文记忆，超时可自动暂停。
监控埋点：通过 Micrometer 采集 TTS/ASR 延迟、会话时长等指标。

状态转换

flowchart TD
A["创建会话
POST /api/voice-interview/sessions"] --> B["IN_PROGRESS"]

B --> C{"会话中事件"}
C -- "暂停/超时" --> D["PAUSED"]
D -- "恢复" --> B

C -- "结束面试" --> E["COMPLETED"]
E --> F["evaluateStatus = PENDING"]
F --> G["evaluateStatus = PROCESSING"]

G --> H{"评估结果"}
H -- "成功" --> I["EVALUATED
evaluateStatus = COMPLETED"]
H -- "失败" --> J["evaluateStatus = FAILED"]

B --> K["DELETE /api/voice-interview/sessions/{id}"]
D --> K
E --> K
I --> K
J --> K

关键接口设计

`POST /api/voice-interview/sessions` 创建语音面试会话

Controller 入口：

VoiceInterviewController.createSession(@Valid @RequestBody CreateSessionRequest request)

核心调用链：

voiceInterviewService.createSession(request);

实现要点：

兜底 skillId（未传则使用默认技能）。
兜底 llmProvider（空值走默认 provider）。
组装 VoiceInterviewSessionEntity（阶段开关、难度、简历 ID、JD 文本、计划时长等）。
默认 userId = "default"。
设置初始阶段（intro/tech/project/hr 中第一个启用阶段）。
持久化到数据库 voice_interview_sessions，并写入 Redis（带 TTL）。
返回 SessionResponseDTO（会话 ID、状态、阶段、配置等）。

`GET /api/voice-interview/sessions/{sessionId}` 根据会话 ID 获取详情

Controller 调用：

voiceInterviewService.getSessionDTO(sessionId);

实现要点：

先查 Redis 缓存，未命中再查数据库。
查到后组装 SessionResponseDTO。
查不到返回统一错误：Session not found: {sessionId}。

`POST /api/voice-interview/sessions/{sessionId}/end` 结束会话并触发异步评估

Controller 调用：

voiceInterviewService.endSession(sessionId.toString());

结束与评估逻辑：

session.setEndTime(now);
session.setCurrentPhase(COMPLETED);
session.setStatus(COMPLETED);
session.setEvaluateStatus(PENDING);
sessionRepository.save(session);
voiceEvaluateStreamProducer.sendEvaluateTask(sessionId);
redisService.streamAdd(streamKey(), buildMessage(payload), AsyncTaskStreamConstants.STREAM_MAX_LEN);

说明：

接口立即返回 Result.success()，不阻塞等待评估结果。
前端通过 GET /api/voice-interview/sessions/{sessionId}/evaluation 轮询评估状态。

`PUT /api/voice-interview/sessions/{sessionId}/pause` 暂停会话

核心调用：

voiceInterviewService.pauseSession(sessionId.toString(), reason);

实现要点：

仅 IN_PROGRESS 状态允许暂停。
更新状态为 PAUSED，记录原因并刷新 updatedAt。
同步持久化数据库与 Redis 缓存。

`PUT /api/voice-interview/sessions/{sessionId}/resume` 恢复会话

核心调用：

voiceInterviewService.resumeSession(sessionId.toString());

实现要点：

仅 PAUSED 状态允许恢复。
恢复后状态改为 IN_PROGRESS，不重置题目进度与阶段。
保存数据库并同步 Redis，返回最新 SessionResponseDTO。

`GET /api/voice-interview/sessions` 获取会话列表（按 userId/status 可过滤）

调用链：

voiceInterviewService.getAllSessions(userId, status);
sessionRepository.findByUserIdAndStatusOrderByUpdatedAtDesc(userId, statusEnum);

Result<List<SessionMetaDTO>>

`DELETE /api/voice-interview/sessions/{sessionId}` 删除语音面试会话

调用链：

voiceInterviewService.deleteSession(sessionId);

实现要点：

校验会话存在性。
删除会话与关联数据（消息/评估等）。
清理 Redis 缓存。

`GET /api/voice-interview/sessions/{sessionId}/messages` 获取对话历史

调用链：

voiceInterviewService.getConversationHistoryDTO(sessionId);

Result<List<VoiceInterviewMessageDTO>>

`GET /api/voice-interview/sessions/{sessionId}/evaluation` 获取异步评估状态与结果

实现要点：

先校验会话存在（不存在抛 VOICE_SESSION_NOT_FOUND）。
读取 evaluateStatus、evaluateError。
若状态为 COMPLETED，再读取评估详情：

evaluationService.getEvaluation(sessionId);

返回 VoiceEvaluationStatusDTO（包含状态，完成时附评估结果）。

`POST /api/voice-interview/sessions/{sessionId}/evaluation` 手动触发异步评估

处理逻辑：

voiceInterviewService.getSession(sessionId);
evaluationService.getEvaluation(sessionId);
voiceInterviewService.triggerEvaluation(sessionId);

规则：

若已 COMPLETED：直接返回已有评估结果。
若为 PENDING/PROCESSING：返回当前状态，不重复触发。
其他可触发状态：入队评估任务，立即返回 PENDING，前端继续轮询。

小结

VoiceInterview 模块的关键不是“把语音跑通”，而是把实时链路和会话生命周期稳定地串起来。对我来说，只有在创建、暂停、恢复、结束、评估这一整条链都能可靠协同时，语音面试才是真正可持续迭代的产品能力。

Ai简历分析：interview schedule模块

Thu, 14 May 2026 17:10:42 +0800

InterviewSchedule 面试安排模块设计与实现

这篇笔记记录我在 interview-guide 项目中对 InterviewSchedule 模块的实现思路。目标是把“邀约解析、记录管理、状态维护、提醒协同”整合成一条稳定可维护的链路。

模块能力概览

邀请解析：规则引擎 + AI 双通道，支持飞书/腾讯会议/Zoom 文本格式，自动提取公司、岗位、时间、会议链接。
日历管理：支持日/周/月视图、拖拽调整与列表视图协同。
状态维护：支持手动标记与定时任务自动过期。
提醒机制：支持可配置提醒，降低漏面试风险。

状态转换

flowchart TD
A["调用 POST /api/interview-schedule/parse 解析邀约文本"] --> B{"规则解析是否成功"}
B -->|是| C["返回 ParseResponse\nparseMethod = rule"]
B -->|否| D["调用 LLM 解析"]
D --> E{"AI 解析是否成功"}
E -->|是| F["返回 ParseResponse\nparseMethod = ai"]
E -->|否| G["返回解析失败\nsuccess = false"]

H["调用 POST /api/interview-schedule 创建记录"] --> I["create(): 强制 status = PENDING"]
I --> J["写入 DB\n状态: PENDING"]

J --> K["调用 GET /api/interview-schedule 或 /{id} 查询记录"]

J --> L["调用 PUT /api/interview-schedule/{id} 更新基础信息"]
L --> M["仅更新公司/岗位/时间等字段\n不改 status"]
M --> J

J --> N["调用 PATCH|PUT /api/interview-schedule/{id}/status?status=..."]
N --> O["updateStatus(): entity.setStatus(status)"]

O --> P{"目标状态"}
P -->|COMPLETED| Q["状态 -> COMPLETED"]
P -->|CANCELLED| R["状态 -> CANCELLED"]
P -->|RESCHEDULED| S["状态 -> RESCHEDULED"]
P -->|PENDING| T["状态 -> PENDING"]

Q --> U["记录继续可被状态接口改写"]
R --> U
S --> U
T --> U
U --> N

J --> V["定时任务 ScheduleStatusUpdater\n每小时执行一次"]
V --> W{"是否满足\nstatus=PENDING 且 interviewTime < now"}
W -->|是| X["批量更新为 CANCELLED"]
W -->|否| Y["不变"]

X --> R
Y --> J

J --> Z["调用 DELETE /api/interview-schedule/{id}"]
Z --> AA["删除记录（生命周期结束）"]

关键接口设计

`POST /api/interview-schedule/parse` 解析面试邀约文本

核心逻辑：

parseService.parse(request.getRawText(), request.getSource());
tryRuleParsing(rawText, source);
parseWithAI(rawText, source);

规则解析优先处理飞书/腾讯/Zoom 结构化片段。
AI 解析作为补充通道，增强对非标准文本的适配能力。
在 AI 解析前做输入边界约束与注入防护。

`POST /api/interview-schedule` 创建面试记录

用途：

支持用户直接输入信息创建面试安排。

调用链：

scheduleService.create(request);

请求体（核心字段）：

public class CreateInterviewRequest {
 @NotBlank(message = "公司名称不能为空")
 private String companyName;

 @NotBlank(message = "岗位不能为空")
 private String position;

 @NotNull(message = "面试时间不能为空")
 @com.fasterxml.jackson.annotation.JsonFormat(pattern = "yyyy-MM-dd'T'HH:mm[:ss]")
 private java.time.LocalDateTime interviewTime;

 private String interviewType; // ONSITE, VIDEO, PHONE
 private String meetingLink;
 private Integer roundNumber = 1;
 private String interviewer;
 private String notes;
}

`GET /api/interview-schedule/{id}` 根据 ID 获取面试记录

处理流程：

Controller 接收 id
调用 scheduleService.getById(id)
Service 从 Repository 查询单条记录，不存在则抛业务异常
返回 Result<InterviewScheduleDTO>

调用链：

scheduleService.getById(id);

`GET /api/interview-schedule` 获取面试记录列表

处理流程：

Controller 接收可选筛选参数：status/start/end
调用 scheduleService.getAll(status, start, end)
Service 按条件查询并转换 DTO
返回 Result<List<InterviewScheduleDTO>>

调用链：

scheduleService.getAll(status, start, end);

`PUT /api/interview-schedule/{id}` 更新面试记录

处理流程：

Controller 接收 id + CreateInterviewRequest（@Valid 校验）
调用 scheduleService.update(id, request)
Service 查询旧记录，更新字段并保存
返回更新后的 Result<InterviewScheduleDTO>

调用链：

scheduleService.update(id, request);

`DELETE /api/interview-schedule/{id}` 删除面试记录

处理流程：

Controller 接收 id
调用 scheduleService.delete(id)
Service 查到后删除，不存在则抛异常
返回 Result<Void>

调用链：

scheduleService.delete(id);

`PATCH/PUT /api/interview-schedule/{id}/status` 更新面试状态

接口实现：

@RequestMapping(path = "/{id}/status", method = {RequestMethod.PATCH, RequestMethod.PUT})
public Result<InterviewScheduleDTO> updateStatus(
 @PathVariable Long id,
 @RequestParam InterviewStatus status
) {
 log.info("更新面试状态: ID={}, status={}", id, status);
 InterviewScheduleDTO dto = scheduleService.updateStatus(id, status);
 return Result.success(dto);
}

核心调用：

scheduleService.updateStatus(id, status);

小结

InterviewSchedule 模块的核心价值在于把“邀约文本理解”和“面试过程管理”连接起来。对我来说，这一层做好之后，前端日历交互、提醒策略和后续面试评估才能形成连续体验，避免信息散落在聊天记录和手工备忘里。

Ai简历分析：interview模块

Thu, 14 May 2026 15:00:53 +0800

Interview 模拟面试模块设计与实现

这篇笔记记录我在 interview-guide 项目里对 Interview 模块的实现思路、核心接口和评估链路。重点是把“出题、答题、评估、导出”做成一个完整闭环，并且保证文字面试与语音面试的评估逻辑保持一致。

模块能力概览

Skill 驱动出题：内置 10+ 面试方向（Java 后端、大厂专项、前端、Python、算法、系统设计、测开、AI Agent 等），每个方向由 SKILL.md 约束考察范围与难度分布。
历史题目去重：创建会话时优先排除历史会话中已问过的题，减少重复考察。
面试时长联动：总时长变更后，各阶段（自我介绍、技术考察、项目深挖、反问）按比例自动分配。
智能追问流：支持多轮追问配置（默认 1 条），模拟真实面试追问过程。
统一评估引擎：文字面试和语音面试复用同一套评估架构（分批评估 + 结构化输出 + 汇总 + 兜底）。
报告导出：支持异步生成并导出 PDF 面试报告。
面试中心：统一入口，支持继续面试、重新面试和历史面试查看。

核心状态流转

flowchart TD
A["调用 POST /api/interview/sessions 创建会话"] --> B{"是否有未完成会话\n且 forceCreate != true"}
B -->|是| C["返回已有会话"]
B -->|否| D["生成题目并保存会话"]

D --> E["会话状态: CREATED\n缓存 Redis + 落库 DB"]
C --> E

E --> F["调用 GET /api/interview/sessions/{sessionId}/question"]
F --> G{"当前状态是否 CREATED"}
G -->|是| H["切换为 IN_PROGRESS"]
G -->|否| I["保持原状态"]
H --> J["返回当前题"]
I --> J

J --> K["调用 POST /api/interview/sessions/{sessionId}/answers 提交答案"]
K --> L["保存答案"]
L --> M{"是否还有下一题"}
M -->|是| N["currentIndex + 1\n状态保持 IN_PROGRESS"]
M -->|否| O["状态切换为 COMPLETED"]

N --> F
O --> P["evaluateStatus 置为 PENDING"]
P --> Q["发送评估任务到 Redis Stream"]

R["调用 POST /api/interview/sessions/{sessionId}/complete 提前交卷"] --> O

Q --> S["评估消费者处理"]
S --> T["evaluateStatus = PROCESSING"]
T --> U{"评估是否成功"}
U -->|是| V["保存评估报告"]
V --> W["会话状态 = EVALUATED\nevaluateStatus = COMPLETED"]
U -->|否| X{"重试次数 < 3 ?"}
X -->|是| Q
X -->|否| Y["evaluateStatus = FAILED\n记录 evaluateError"]

Z["调用 DELETE /api/interview/sessions/{sessionId}"] --> AA["删除 DB 会话与答案"]
AA --> AB["会话结束"]

关键接口设计

`GET /api/interview/sessions` 列出面试会话

用途：

面试记录页展示，按创建时间倒序返回会话列表。

调用链：

persistenceService.findAll().stream();

`POST /api/interview/sessions` 创建面试会话

限流策略：

全局限流 + IP 限流（5 次）

核心逻辑：

sessionService.createSession(request);
persistenceService.getHistoricalQuestions(skillId, request.resumeId());
sessionRepository.findTop10ByResumeIdAndSkillIdOrderByCreatedAtDesc(...);
sessionRepository.findTop10BySkillIdOrderByCreatedAtDesc(...);
questionService.generateQuestionsBySkill(...);
sessionCache.saveSession(...);
persistenceService.saveSession(...);

`GET /api/interview/sessions/{sessionId}` 获取会话信息

核心逻辑：

sessionService.getSession(sessionId);
sessionCache.getSession(sessionId);
restoreSessionFromDatabase(sessionId);

`GET /api/interview/sessions/{sessionId}/question` 获取当前问题

核心逻辑：

sessionService.getCurrentQuestionResponse(sessionId);
getCurrentQuestion(sessionId);
getOrRestoreSession(sessionId);

当会话为 CREATED 状态时，按 currentIndex 返回当前题目。

`POST /api/interview/sessions/{sessionId}/answers` 提交答案并推进

限流策略：

全局限流（10 次）

核心逻辑：

sessionService.submitAnswer(request);

更新题目答案、会话状态、缓存与数据库。
如果是最后一题：

persistenceService.updateEvaluateStatus(sessionId, AsyncTaskStatus.PENDING, null);
evaluateStreamProducer.sendEvaluateTask(sessionId);

`POST /api/interview/sessions/{sessionId}/answers` 暂存答案（不推进）

核心逻辑：

sessionService.saveAnswer(request);

同步更新 Redis 与数据库。

`POST /api/interview/sessions/{sessionId}/complete` 提前交卷

核心逻辑：

sessionService.completeInterview(sessionId);
sessionCache.updateSessionStatus(sessionId, SessionStatus.COMPLETED);

持久化数据库状态。

evaluateStreamProducer.sendEvaluateTask(sessionId);

`GET /api/interview/sessions/unfinished/{resumeId}` 查找未完成会话

核心逻辑：

sessionService.findUnfinishedSessionOrThrow(resumeId);
findUnfinishedSession(resumeId);
sessionCache.findUnfinishedSessionId(resumeId);
persistenceService.findUnfinishedSession(resumeId);

`GET /api/interview/sessions/{sessionId}/report` 生成面试评估报告

核心逻辑：

sessionService.generateReport(sessionId);
evaluationService.evaluateInterview(...);
unifiedEvaluationService.evaluate(...);
evaluateInBatches(...);
summarizeBatchResults(...);
structuredOutputInvoker.invoke(...);
securedSystemPrompt = systemPromptWithFormat + ANTI_INJECTION_INSTRUCTION;

通过反注入指令降低用户输入污染模型行为的风险。

`GET /api/interview/sessions/{sessionId}/details` 获取面试详情

调用链：

historyService.getInterviewDetail(sessionId);
interviewPersistenceService.findBySessionId(sessionId);

`GET /api/interview/sessions/{sessionId}/export` 导出面试报告 PDF

调用链：

historyService.exportInterviewPdf(sessionId);
interviewPersistenceService.findBySessionId(sessionId);
pdfExportService.exportInterviewReport(session);

`DELETE /api/interview/sessions/{sessionId}` 删除面试会话

调用链：

persistenceService.deleteSessionBySessionId(sessionId);
sessionRepository.findBySessionId(sessionId);
sessionRepository.delete(session);

评估引擎实现要点

同一条评估链路兼容文字面试与语音面试，减少分叉实现成本。
分批评估后再汇总，兼顾长上下文稳定性与结构化输出质量。
引入反注入提示词拼接，降低恶意输入对评估结果的干扰。
异常场景通过统一调用器与兜底字段输出，避免报告直接失败。

小结

Interview 模块目前已经实现了从创建会话、动态出题、过程作答、异步评估到报告导出的完整流程。对我来说，这一模块最关键的价值是把“面试过程管理”和“评估结果生产”拆成可演进的两个层次，后续无论替换题库策略还是升级评估模型，整体改动都能保持可控。

Ai简历分析：resume模块

Thu, 14 May 2026 11:31:10 +0800

Resume 简历管理模块设计与实现

本文记录 interview-guide 项目中 Resume 模块的核心设计、接口职责、异步处理链路与当前问题。

模块能力概览

多格式解析：支持 PDF、DOCX、DOC、TXT、MD。
异步处理流：基于 Redis Stream 异步分析简历，支持进度状态跟踪。
稳定性保障：失败自动重试（最多 3 次）+ 基于文件哈希的重复检测。
报告导出：支持将 AI 分析结果导出为结构化 PDF 报告。

核心状态流转

flowchart TD
A["调用 /api/resumes/upload"] --> B["文件校验与类型校验"]
B --> C{"是否重复简历?"}

C -->|是| D["返回历史结果或当前状态 (duplicate=true)"]
C -->|否| E["解析文本 + 上传对象存储 + 保存 ResumeEntity"]

E --> F["设置 analyzeStatus = PENDING"]
F --> G["发送 Redis Stream 分析任务"]

G --> H{"任务是否成功入队?"}
H -->|否| I["置为 FAILED (任务入队失败)"]
H -->|是| J["消费者拉取任务"]

J --> K["置为 PROCESSING"]
K --> L["调用 ResumeGradingService 进行 AI 分析"]

L --> M{"本次处理是否异常?"}
M -->|否| N["保存分析结果"]
N --> O["置为 COMPLETED"]

M -->|是| P{"retryCount < 3 ?"}
P -->|是| Q["retryCount + 1，重新入队"]
Q --> J
P -->|否| R["置为 FAILED (最终失败)"]

S["手动重试 /api/resumes/{id}/reanalyze"] --> T["置为 PENDING 并重新入队"]
T --> J

关键接口设计

`/api/resumes/upload` 简历上传（异步分析）

限流策略：

全局限流：@RateLimit(dimension = RateLimit.Dimension.GLOBAL, count = 5)
IP 限流：@RateLimit(dimension = RateLimit.Dimension.IP, count = 5)

入口调用：

uploadService.uploadAndAnalyze(file);

处理流程：

文件基础校验

fileValidationService.validateFile(file, MAX_FILE_SIZE, "简历");

包含：判空、大小限制、日志记录。 2. 文件类型识别

String contentType = parseService.detectContentType(file);

支持：PDF、DOCX、DOC、TXT、MD。 3. 重复文件检测

persistenceService.findExistingResume(file);

内部流程：

String fileHash = fileHashService.calculateHash(file);
resumeRepository.findByFileHash(fileHash);

简历解析与文本清洗

parseService.parseResume(file);

Apache Tika 解析纯文本
textCleaningService.cleanText(content) 清理多余换行，减少 Token 消耗

文件存储（非结构化）

storageService.uploadResume(file);
storageService.getFileUrl(fileKey);

上传到 RustFS/MinIO，用于非结构化文件存储。 6. 元数据入库

persistenceService.saveResume(file, resumeText, fileKey, fileUrl);

投递异步分析任务

analyzeStreamProducer.sendAnalyzeTask(savedResume.getId(), resumeText);

使用 Redis Stream 作为消息队列 8. 返回上传响应
前端通过后续查询接口观察异步分析状态。

`/api/resumes` 获取简历列表

调用链：

historyService.getAllResumes();
resumePersistenceService.findAllResumes();

当前问题：

尚未区分用户数据，默认返回全量列表。

`/api/resumes/{id}/detail` 获取简历详情

调用链：

historyService.getResumeDetail(id);
resumePersistenceService.findById(id);
resumeRepository.findById(id);

`/api/resumes/{id}/export` 导出分析报告 PDF

调用链：

historyService.exportAnalysisPdf(id);
resumePersistenceService.findById(resumeId);
resumePersistenceService.getLatestAnalysisAsDTO(resumeId);
pdfExportService.exportResumeAnalysis(resume, analysisDTO);

`/api/resumes/{id}` 删除简历

调用链：

deleteService.deleteResume(id);
persistenceService.findById(id);
storageService.deleteResume(resume.getStorageKey());
interviewPersistenceService.deleteSessionsByResumeId(id);
persistenceService.deleteResume(id);

`/api/resumes/{id}/reanalyze` 重新分析

限流策略：

全局限流：@RateLimit(dimension = RateLimit.Dimension.GLOBAL, count = 2)
IP 限流：@RateLimit(dimension = RateLimit.Dimension.IP, count = 2)

调用链：

uploadService.reanalyze(id);
resumeRepository.findById(resumeId);
analyzeStreamProducer.sendAnalyzeTask(resumeId, resumeText);

并在处理中更新状态后保存。

`/api/resumes/health` 健康检查

return Result.success();

用于服务可用性探测。

稳定性设计点

异步解耦：上传与分析分离，削峰并提升接口响应速度。
自动重试：分析失败后最多重试 3 次，降低瞬时故障影响。
哈希去重：基于内容 SHA-256 快速识别重复简历，避免重复计算。

小结

Resume 模块目前已经具备上传、解析、异步分析、导出与删除的完整闭环。下一阶段重点是用户隔离与可观测性建设，确保在多人使用和高并发场景下依旧稳定可控。

项目 on XEDCZQ的博客

Ai面试项目：knowledgebase模块

Knowledgebase 知识库模块设计与实现

模块能力概览

状态转换

图1：KnowledgeBase 主状态机

图2：分片上传知识库流程

关键接口设计

GET /api/knowledgebase/list 获取知识库列表（状态过滤 + 排序）

GET /api/knowledgebase/{id} 获取知识库详情

DELETE /api/knowledgebase/{id} 删除知识库

POST /api/knowledgebase/query 非流式问答（多知识库）

POST /api/knowledgebase/query/stream 流式问答（SSE，多知识库）

GET /api/knowledgebase/categories 获取所有分类名

GET /api/knowledgebase/category/{category} 按分类获取知识库列表

GET /api/knowledgebase/uncategorized 获取未分类知识库列表

PUT /api/knowledgebase/{id}/category 更新知识库分类

POST /api/knowledgebase/upload 上传知识库文件（multipart）

GET /api/knowledgebase/{id}/download 下载原始知识库文件

GET /api/knowledgebase/search?keyword=... 关键字搜索知识库

GET /api/knowledgebase/stats 获取知识库统计信息

POST /api/knowledgebase/{id}/revectorize 手动重新向量化

异步向量化处理流程（核心实现）

小结

Ai面试项目：voice interview模块

VoiceInterview 语音面试模块设计与实现

模块能力概览

状态转换

关键接口设计

POST /api/voice-interview/sessions 创建语音面试会话

GET /api/voice-interview/sessions/{sessionId} 根据会话 ID 获取详情

POST /api/voice-interview/sessions/{sessionId}/end 结束会话并触发异步评估

PUT /api/voice-interview/sessions/{sessionId}/pause 暂停会话

PUT /api/voice-interview/sessions/{sessionId}/resume 恢复会话

GET /api/voice-interview/sessions 获取会话列表（按 userId/status 可过滤）

DELETE /api/voice-interview/sessions/{sessionId} 删除语音面试会话

GET /api/voice-interview/sessions/{sessionId}/messages 获取对话历史

GET /api/voice-interview/sessions/{sessionId}/evaluation 获取异步评估状态与结果

POST /api/voice-interview/sessions/{sessionId}/evaluation 手动触发异步评估

小结

Ai简历分析：interview schedule模块

InterviewSchedule 面试安排模块设计与实现

模块能力概览

状态转换

关键接口设计

POST /api/interview-schedule/parse 解析面试邀约文本

POST /api/interview-schedule 创建面试记录

GET /api/interview-schedule/{id} 根据 ID 获取面试记录

GET /api/interview-schedule 获取面试记录列表

PUT /api/interview-schedule/{id} 更新面试记录

DELETE /api/interview-schedule/{id} 删除面试记录

PATCH/PUT /api/interview-schedule/{id}/status 更新面试状态

小结

Ai简历分析：interview模块

Interview 模拟面试模块设计与实现

模块能力概览

核心状态流转

关键接口设计

GET /api/interview/sessions 列出面试会话

POST /api/interview/sessions 创建面试会话

GET /api/interview/sessions/{sessionId} 获取会话信息

GET /api/interview/sessions/{sessionId}/question 获取当前问题

POST /api/interview/sessions/{sessionId}/answers 提交答案并推进

POST /api/interview/sessions/{sessionId}/answers 暂存答案（不推进）

POST /api/interview/sessions/{sessionId}/complete 提前交卷

GET /api/interview/sessions/unfinished/{resumeId} 查找未完成会话

GET /api/interview/sessions/{sessionId}/report 生成面试评估报告

GET /api/interview/sessions/{sessionId}/details 获取面试详情

GET /api/interview/sessions/{sessionId}/export 导出面试报告 PDF

DELETE /api/interview/sessions/{sessionId} 删除面试会话

评估引擎实现要点

小结

Ai简历分析：resume模块

Resume 简历管理模块设计与实现

模块能力概览

核心状态流转

关键接口设计

/api/resumes/upload 简历上传（异步分析）

/api/resumes 获取简历列表

/api/resumes/{id}/detail 获取简历详情

`GET /api/knowledgebase/list` 获取知识库列表（状态过滤 + 排序）

`GET /api/knowledgebase/{id}` 获取知识库详情

`DELETE /api/knowledgebase/{id}` 删除知识库

`POST /api/knowledgebase/query` 非流式问答（多知识库）

`POST /api/knowledgebase/query/stream` 流式问答（SSE，多知识库）

`GET /api/knowledgebase/categories` 获取所有分类名

`GET /api/knowledgebase/category/{category}` 按分类获取知识库列表

`GET /api/knowledgebase/uncategorized` 获取未分类知识库列表

`PUT /api/knowledgebase/{id}/category` 更新知识库分类

`POST /api/knowledgebase/upload` 上传知识库文件（multipart）

`GET /api/knowledgebase/{id}/download` 下载原始知识库文件

`GET /api/knowledgebase/search?keyword=...` 关键字搜索知识库

`GET /api/knowledgebase/stats` 获取知识库统计信息

`POST /api/knowledgebase/{id}/revectorize` 手动重新向量化

`POST /api/voice-interview/sessions` 创建语音面试会话

`GET /api/voice-interview/sessions/{sessionId}` 根据会话 ID 获取详情

`POST /api/voice-interview/sessions/{sessionId}/end` 结束会话并触发异步评估

`PUT /api/voice-interview/sessions/{sessionId}/pause` 暂停会话

`PUT /api/voice-interview/sessions/{sessionId}/resume` 恢复会话

`GET /api/voice-interview/sessions` 获取会话列表（按 userId/status 可过滤）

`DELETE /api/voice-interview/sessions/{sessionId}` 删除语音面试会话

`GET /api/voice-interview/sessions/{sessionId}/messages` 获取对话历史

`GET /api/voice-interview/sessions/{sessionId}/evaluation` 获取异步评估状态与结果

`POST /api/voice-interview/sessions/{sessionId}/evaluation` 手动触发异步评估

`POST /api/interview-schedule/parse` 解析面试邀约文本

`POST /api/interview-schedule` 创建面试记录

`GET /api/interview-schedule/{id}` 根据 ID 获取面试记录

`GET /api/interview-schedule` 获取面试记录列表

`PUT /api/interview-schedule/{id}` 更新面试记录

`DELETE /api/interview-schedule/{id}` 删除面试记录

`PATCH/PUT /api/interview-schedule/{id}/status` 更新面试状态

`GET /api/interview/sessions` 列出面试会话

`POST /api/interview/sessions` 创建面试会话

`GET /api/interview/sessions/{sessionId}` 获取会话信息

`GET /api/interview/sessions/{sessionId}/question` 获取当前问题

`POST /api/interview/sessions/{sessionId}/answers` 提交答案并推进

`POST /api/interview/sessions/{sessionId}/answers` 暂存答案（不推进）

`POST /api/interview/sessions/{sessionId}/complete` 提前交卷

`GET /api/interview/sessions/unfinished/{resumeId}` 查找未完成会话

`GET /api/interview/sessions/{sessionId}/report` 生成面试评估报告

`GET /api/interview/sessions/{sessionId}/details` 获取面试详情

`GET /api/interview/sessions/{sessionId}/export` 导出面试报告 PDF

`DELETE /api/interview/sessions/{sessionId}` 删除面试会话

`/api/resumes/upload` 简历上传（异步分析）

`/api/resumes` 获取简历列表

`/api/resumes/{id}/detail` 获取简历详情

`/api/resumes/{id}/export` 导出分析报告 PDF

`/api/resumes/{id}` 删除简历

`/api/resumes/{id}/reanalyze` 重新分析

`/api/resumes/health` 健康检查