Project on XEDCZQ Blog

AI Resume Analysis: Knowledgebase Module

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

Knowledgebase Module Design and Implementation

This note records how I implemented the Knowledgebase module in the interview-guide project. The goal is to connect document upload, vectorization, RAG query, and session association into a sustainable knowledge service workflow.

Module Capability Overview

Document management: supports upload, download, deletion, categorization, keyword search, and statistics.
Vectorization capability: stores vectors with pgvector, and processes chunking/storage through async tasks.
RAG Q&A: supports both non-streaming and streaming (SSE) multi-knowledgebase query.
Session coordination: automatically removes associated session references when deleting a knowledgebase to reduce inconsistency risk.

State Transitions

Diagram 1: KnowledgeBase Main State Machine

flowchart TD
A["Call POST /api/knowledgebase/upload to upload file"] --> B["File validation + type detection + dedup check"]

B --> C{"Is file duplicated (fileHash exists)?"}
C -->|Yes| D["Return existing knowledgebase record\nduplicate=true\nno vectorization triggered"]
C -->|No| E["Parse text content + upload file to storage"]

E --> F["Save KnowledgeBaseEntity\ninitial vectorStatus=PENDING"]
F --> G["Send vectorization task to Redis Stream"]

G --> H["VectorizeStreamConsumer consumes task"]
H --> I["markProcessing\nvectorStatus=PROCESSING"]

I --> J["vectorizeAndStore\nchunk text and write to pgvector"]
J --> K{"Did vectorization succeed?"}

K -->|Yes| L["markCompleted\nvectorStatus=COMPLETED\nvectorError=null"]
K -->|No| M{"retryCount < 3 ?"}
M -->|Yes| N["Requeue task (retry+1)"]
N --> H
M -->|No| O["markFailed\nvectorStatus=FAILED\nwrite vectorError"]

P["Call POST /api/knowledgebase/{id}/revectorize"] --> Q["Reset status to PENDING\nclear vectorError"]
Q --> G

R["Call DELETE /api/knowledgebase/{id} to delete knowledgebase"] --> S["Remove RAG session associations"]
S --> T["Delete vector data (best effort) + delete storage file (best effort)"]
T --> U["Delete knowledgebase DB record\nlifecycle ends"]

Diagram 2: Chunked Knowledgebase Vectorization Flow

flowchart TD
A["Knowledgebase upload succeeds"] --> B["Save knowledgebase record vectorStatus=PENDING"]
B --> C["Send vectorization task to Redis Stream"]
C --> D["VectorizeStreamConsumer starts polling"]
D --> E["Read one message: kbId + content + retryCount"]
E --> F["Set status to PROCESSING"]
F --> G["Execute vectorizeAndStore"]

G --> H["Delete old vectors for this kbId"]
H --> I["Text chunking via TokenTextSplitter"]
I --> J["Add metadata kb_id to each chunk"]
J --> K["Batch call vectorStore.add to write vectors"]

K --> L["Set status to COMPLETED"]
L --> M["ACK message"]

G --> N{"Processing exception?"}
N -->|Yes| O{"retryCount < 3"}
O -->|Yes| P["retryCount+1 and requeue"]
P --> M
O -->|No| Q["Set status to FAILED and record error"]
Q --> M

Key API Design

`GET /api/knowledgebase/list` Get Knowledgebase List (Status Filter + Sorting)

Call chain:

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

`GET /api/knowledgebase/{id}` Get Knowledgebase Detail

Call chain:

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

`DELETE /api/knowledgebase/{id}` Delete Knowledgebase

Core flow:

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

Notes:

Removes RAG session associations first, then deletes vectors/storage files, then DB record.
Vector/storage deletion failures are logged as warn and do not block the main delete flow.

`POST /api/knowledgebase/query` Non-Streaming Q&A (Multi-Knowledgebase)

Rate limits:

GLOBAL/IP: 10 each

Call chain:

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

Processing highlights:

knowledgeBaseIds and question are required.
If no hit, returns fixed fallback text: “No information retrieved”.
If hit exists, builds context + prompts and calls default ChatClient for answer generation.
Returns QueryResponse(answer, primaryKbId, kbNamesStr).

`POST /api/knowledgebase/query/stream` Streaming Q&A (SSE, Multi-Knowledgebase)

Rate limits:

GLOBAL/IP: 5 each

Call chain:

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

Processing highlights:

Returns Flux<String> (text/event-stream).
Empty input or no hit returns fallback text stream directly.
Both stream-time and outer exceptions are downgraded to safe fallback output.

`GET /api/knowledgebase/categories` Get All Category Names

Call chain:

listService.getAllCategories();

Return:

Result<List<String>>

`GET /api/knowledgebase/category/{category}` Get Knowledgebase List by Category

Call chain:

listService.listByCategory(category);

Return:

Result<List<KnowledgeBaseListItemDTO>>

`GET /api/knowledgebase/uncategorized` Get Uncategorized Knowledgebase List

Call chain:

listService.listByCategory(category);

Notes:

Current implementation reuses category-query path and distinguishes uncategorized by specific category value.

`PUT /api/knowledgebase/{id}/category` Update Knowledgebase Category

Call chain:

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

Processing highlights:

Queries by id first and throws business exception if not found.
Updates category and persists record when found.

`POST /api/knowledgebase/upload` Upload Knowledgebase File (multipart)

Parameters:

file (required)
name (optional)
category (optional)

Rate limits:

GLOBAL/IP: 3 each

Call chain:

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

Processing flow:

Validate file presence and size (max 50MB).
Validate type by MIME + extension whitelist (PDF/DOCX/DOC/TXT/MD).
Compute SHA-256 for dedup check.
Parse text content; fail directly on empty text.
Upload file to RustFS (S3-compatible), generate fileKey/fileUrl.
Save KnowledgeBaseEntity with initial vector status PENDING.
Enqueue async vectorization task to Redis Stream (knowledgebase:vectorize:stream).
Return knowledgeBase + storage + duplicate=false.

`GET /api/knowledgebase/{id}/download` Download Original Knowledgebase File

Call chain:

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

Return:

ResponseEntity<byte[]> (with Content-Disposition and Content-Type)

`GET /api/knowledgebase/search?keyword=...` Keyword Search Knowledgebase

Call chain:

listService.search(keyword);

`GET /api/knowledgebase/stats` Get Knowledgebase Statistics

Call chain:

listService.getStatistics();

Return:

KnowledgeBaseStatsDTO

`POST /api/knowledgebase/{id}/revectorize` Manual Re-Vectorization

Rate limits:

GLOBAL/IP: 2 each

Call chain:

uploadService.revectorize(id);

Processing flow:

Query knowledgebase by id, throw exception if missing.
Download source file from object storage and re-parse text.
Fail directly if parsing fails or returns empty text.
Reset vector status to PENDING.
Enqueue vectorization task to Redis Stream.
Return success immediately; frontend polls status afterward.

Async Vectorization Processing Flow (Core Implementation)

// 1) Delete old vectors
deleteByKnowledgeBaseId(knowledgeBaseId);

// 2) Text chunking (default no overlap)
List<Document> chunks = textSplitter.apply(List.of(new Document(content)));

// 3) Add metadata (kb_id)
chunks.forEach(chunk -> chunk.getMetadata().put("kb_id", knowledgeBaseId.toString()));

// 4) Batch vector write (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);
}

Summary

The core value of the Knowledgebase module is connecting file asset management with retrieval-augmented Q&A. For me, the real value is not just successful upload, but making sure documents reliably enter the vectorization pipeline and finally provide reusable, traceable knowledge support in Q&A scenarios.

AI Resume Analysis: Voice Interview Module

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

VoiceInterview Module Design and Implementation

This note records how I implemented the VoiceInterview module in the interview-guide project. The core goal is to make voice interviews deliver a complete experience of real-time interaction, resumable sessions, and traceable evaluation.

Module Capability Overview

Real-time voice interaction: built on WebSocket + Qwen3 Voice Model (shared API key for ASR/TTS/LLM).
Streaming experience optimization: sentence-level concurrent TTS, generation/synthesis/playback in parallel, first-packet latency around 200ms.
Server-side VAD: automatic segmentation with real-time subtitles (including intermediate results).
Echo protection: supports manual submission to avoid AI playback being captured as user input.
Session continuity: supports pause/resume and multi-turn context memory, with auto-pause on timeout.
Observability metrics: Micrometer metrics for TTS/ASR latency, session duration, etc.

State Transitions

flowchart TD
A["Create Session
POST /api/voice-interview/sessions"] --> B["IN_PROGRESS"]

B --> C{"Session Events"}
C -- "Pause / Timeout" --> D["PAUSED"]
D -- "Resume" --> B

C -- "End Interview" --> E["COMPLETED"]
E --> F["evaluateStatus = PENDING"]
F --> G["evaluateStatus = PROCESSING"]

G --> H{"Evaluation Result"}
H -- "Success" --> I["EVALUATED
evaluateStatus = COMPLETED"]
H -- "Failure" --> J["evaluateStatus = FAILED"]

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

Key API Design

`POST /api/voice-interview/sessions` Create Voice Interview Session

Controller entry:

VoiceInterviewController.createSession(@Valid @RequestBody CreateSessionRequest request)

Core call chain:

voiceInterviewService.createSession(request);

Implementation highlights:

Fallback skillId (use default skill when missing).
Fallback llmProvider (use default provider when empty).
Build VoiceInterviewSessionEntity (phase switches, difficulty, resume ID, JD text, planned duration, etc.).
Default userId = "default".
Set initial phase (the first enabled one in intro/tech/project/hr).
Persist to voice_interview_sessions and cache in Redis (with TTL).
Return SessionResponseDTO (session ID, status, phase, config, etc.).

`GET /api/voice-interview/sessions/{sessionId}` Get Session Detail by ID

Controller call:

voiceInterviewService.getSessionDTO(sessionId);

Implementation highlights:

Read Redis first, then DB fallback.
Build SessionResponseDTO when found.
Return unified error when not found: Session not found: {sessionId}.

`POST /api/voice-interview/sessions/{sessionId}/end` End Session and Trigger Async Evaluation

Controller call:

voiceInterviewService.endSession(sessionId.toString());

End + evaluation logic:

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);

Notes:

API returns Result.success() immediately without waiting for evaluation completion.
Frontend polls GET /api/voice-interview/sessions/{sessionId}/evaluation for progress.

`PUT /api/voice-interview/sessions/{sessionId}/pause` Pause Session

Core call:

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

Implementation highlights:

Only IN_PROGRESS sessions can be paused.
Set status to PAUSED, record reason, update updatedAt.
Persist DB and sync Redis cache.

`PUT /api/voice-interview/sessions/{sessionId}/resume` Resume Session

Core call:

voiceInterviewService.resumeSession(sessionId.toString());

Implementation highlights:

Only PAUSED sessions can be resumed.
After resume, status becomes IN_PROGRESS without resetting phase/progress.
Persist DB, sync Redis, and return latest SessionResponseDTO.

`GET /api/voice-interview/sessions` Get Session List (Filter by userId/status)

Call chain:

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

Return:

Result<List<SessionMetaDTO>>

`DELETE /api/voice-interview/sessions/{sessionId}` Delete Voice Interview Session

Call chain:

voiceInterviewService.deleteSession(sessionId);

Implementation highlights:

Validate session existence.
Delete session and related data (messages/evaluation, depending on repository implementation).
Clear Redis cache.

`GET /api/voice-interview/sessions/{sessionId}/messages` Get Conversation History

Call chain:

voiceInterviewService.getConversationHistoryDTO(sessionId);

Return:

Result<List<VoiceInterviewMessageDTO>>

`GET /api/voice-interview/sessions/{sessionId}/evaluation` Get Async Evaluation Status and Result

Implementation highlights:

Validate session first (throw VOICE_SESSION_NOT_FOUND if missing).
Read evaluateStatus and evaluateError.
If status is COMPLETED, load evaluation details:

evaluationService.getEvaluation(sessionId);

Return VoiceEvaluationStatusDTO (includes status and result when completed).

`POST /api/voice-interview/sessions/{sessionId}/evaluation` Manually Trigger Async Evaluation

Processing logic:

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

Rules:

If already COMPLETED: return existing evaluation result directly.
If PENDING/PROCESSING: return current status without duplicate triggering.
For other triggerable states: enqueue evaluation task and return PENDING, then frontend continues polling.

Summary

The key value of the VoiceInterview module is not just making voice interaction work, but making the entire real-time pipeline and session lifecycle robustly connected. For me, only when the full chain (create, pause, resume, end, evaluate) works reliably can voice interviews become a truly evolvable product capability.

AI Resume Analysis: Interview Schedule Module

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

InterviewSchedule Module Design and Implementation

This note records how I implemented the InterviewSchedule module in the interview-guide project. The goal is to integrate invitation parsing, record management, status maintenance, and reminder coordination into one stable and maintainable workflow.

Module Capability Overview

Invitation parsing: dual-channel parsing with rule engine + AI, supports Feishu/Tencent Meeting/Zoom text formats, automatically extracts company, role, interview time, and meeting link.
Calendar management: supports day/week/month view, drag-and-drop adjustment, and list view collaboration.
Status maintenance: supports manual status updates and scheduled auto-expiration.
Reminder mechanism: supports configurable reminders to reduce missed interviews.

State Transitions

flowchart TD
A["Call POST /api/interview-schedule/parse to parse invitation text"] --> B{"Did rule parsing succeed?"}
B -->|Yes| C["Return ParseResponse\nparseMethod = rule"]
B -->|No| D["Call LLM parsing"]
D --> E{"Did AI parsing succeed?"}
E -->|Yes| F["Return ParseResponse\nparseMethod = ai"]
E -->|No| G["Return parse failure\nsuccess = false"]

H["Call POST /api/interview-schedule to create record"] --> I["create(): force status = PENDING"]
I --> J["Write to DB\nstatus: PENDING"]

J --> K["Call GET /api/interview-schedule or /{id} to query record"]

J --> L["Call PUT /api/interview-schedule/{id} to update base info"]
L --> M["Only update company/role/time fields\nwithout changing status"]
M --> J

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

O --> P{"Target status"}
P -->|COMPLETED| Q["Status -> COMPLETED"]
P -->|CANCELLED| R["Status -> CANCELLED"]
P -->|RESCHEDULED| S["Status -> RESCHEDULED"]
P -->|PENDING| T["Status -> PENDING"]

Q --> U["Record can still be rewritten via status API"]
R --> U
S --> U
T --> U
U --> N

J --> V["Scheduled task ScheduleStatusUpdater\nruns every hour"]
V --> W{"Condition met?\nstatus=PENDING and interviewTime < now"}
W -->|Yes| X["Batch update to CANCELLED"]
W -->|No| Y["No change"]

X --> R
Y --> J

J --> Z["Call DELETE /api/interview-schedule/{id}"]
Z --> AA["Delete record (lifecycle ends)"]

Key API Design

`POST /api/interview-schedule/parse` Parse Interview Invitation Text

Core logic:

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

Rule parsing handles structured patterns from Feishu/Tencent/Zoom first.
AI parsing acts as a fallback channel for non-standard text.
Input boundary constraints and prompt-injection protection are applied before AI parsing.

`POST /api/interview-schedule` Create Interview Record

Purpose:

Allows users to directly create an interview schedule record from manual input.

Call chain:

scheduleService.create(request);

Request body (core fields):

public class CreateInterviewRequest {
 @NotBlank(message = "Company name cannot be empty")
 private String companyName;

 @NotBlank(message = "Position cannot be empty")
 private String position;

 @NotNull(message = "Interview time cannot be empty")
 @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}` Get Interview Record by ID

Processing flow:

Controller receives id
Calls scheduleService.getById(id)
Service queries repository for one record and throws business exception if not found
Returns Result<InterviewScheduleDTO>

Call chain:

scheduleService.getById(id);

`GET /api/interview-schedule` Get Interview Record List

Processing flow:

Controller accepts optional filters: status/start/end
Calls scheduleService.getAll(status, start, end)
Service queries by conditions and converts to DTO
Returns Result<List<InterviewScheduleDTO>>

Call chain:

scheduleService.getAll(status, start, end);

`PUT /api/interview-schedule/{id}` Update Interview Record

Processing flow:

Controller receives id + CreateInterviewRequest (with @Valid validation)
Calls scheduleService.update(id, request)
Service loads existing record, updates fields, and saves
Returns updated Result<InterviewScheduleDTO>

Call chain:

scheduleService.update(id, request);

`DELETE /api/interview-schedule/{id}` Delete Interview Record

Processing flow:

Controller receives id
Calls scheduleService.delete(id)
Service deletes when found, throws exception when missing
Returns Result<Void>

Call chain:

scheduleService.delete(id);

`PATCH/PUT /api/interview-schedule/{id}/status` Update Interview Status

API implementation:

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

Core call:

scheduleService.updateStatus(id, status);

Summary

The core value of the InterviewSchedule module is connecting invitation understanding with interview process management. For me, this layer is what enables frontend calendar interaction, reminder strategy, and downstream interview evaluation to form a continuous user experience, instead of scattering information across chats and manual notes.

AI Resume Analysis: Interview Module

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

Interview Mock Interview Module Design and Implementation

This note records how I implemented the Interview module in the interview-guide project, including the core APIs and evaluation pipeline. The main goal is to build a complete closed loop for question generation, answering, evaluation, and report export, while keeping text interviews and voice interviews aligned under the same evaluation logic.

Module Capability Overview

Skill-driven question generation: supports 10+ interview tracks (Java backend, major-company tracks, frontend, Python, algorithms, system design, test development, AI Agent, etc.). Each track is defined by SKILL.md for scope and difficulty distribution.
Historical question deduplication: previously asked questions in historical sessions are excluded during session creation to reduce repeated assessment.
Interview stage duration linkage: after total duration changes, each stage (self-introduction, technical assessment, project deep-dive, reverse Q&A) is auto-allocated by ratio.
Intelligent follow-up flow: supports multi-round follow-up configuration (default: 1 round) to simulate realistic interview interactions.
Unified evaluation engine: text and voice interviews share the same evaluation architecture (batch evaluation + structured output + summarization + fallback).
Report export: supports asynchronous generation and export of PDF interview reports.
Interview center: unified entry for continue/restart/history operations.

Core State Flow

flowchart TD
A["Call POST /api/interview/sessions to create session"] --> B{"Any unfinished session\nand forceCreate != true?"}
B -->|Yes| C["Return existing session"]
B -->|No| D["Generate questions and save session"]

D --> E["Session state: CREATED\nCache in Redis + persist in DB"]
C --> E

E --> F["Call GET /api/interview/sessions/{sessionId}/question"]
F --> G{"Is current state CREATED?"}
G -->|Yes| H["Switch to IN_PROGRESS"]
G -->|No| I["Keep current state"]
H --> J["Return current question"]
I --> J

J --> K["Call POST /api/interview/sessions/{sessionId}/answers to submit answer"]
K --> L["Save answer"]
L --> M{"Any next question?"}
M -->|Yes| N["currentIndex + 1\nState remains IN_PROGRESS"]
M -->|No| O["Switch state to COMPLETED"]

N --> F
O --> P["Set evaluateStatus to PENDING"]
P --> Q["Send evaluation task to Redis Stream"]

R["Call POST /api/interview/sessions/{sessionId}/complete for early submit"] --> O

Q --> S["Evaluation consumer processes task"]
S --> T["evaluateStatus = PROCESSING"]
T --> U{"Evaluation successful?"}
U -->|Yes| V["Save evaluation report"]
V --> W["Session state = EVALUATED\nevaluateStatus = COMPLETED"]
U -->|No| X{"Retry count < 3 ?"}
X -->|Yes| Q
X -->|No| Y["evaluateStatus = FAILED\nRecord evaluateError"]

Z["Call DELETE /api/interview/sessions/{sessionId}"] --> AA["Delete DB session and answers"]
AA --> AB["Session ended"]

Key API Design

`GET /api/interview/sessions` List Interview Sessions

Purpose:

Used by the interview history page, returns session list in reverse creation order.

Call chain:

persistenceService.findAll().stream();

`POST /api/interview/sessions` Create Interview Session

Rate limiting:

Global limit + IP limit (5)

Core logic:

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

`GET /api/interview/sessions/{sessionId}` Get Session Info

Core logic:

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

`GET /api/interview/sessions/{sessionId}/question` Get Current Question

Core logic:

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

If session is in CREATED state, return question by currentIndex.

`POST /api/interview/sessions/{sessionId}/answers` Submit Answer and Move Forward

Rate limiting:

Global limit (10)

Core logic:

sessionService.submitAnswer(request);

Updates answer, session state, cache, and DB.
If this is the last question:

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

`POST /api/interview/sessions/{sessionId}/answers` Save Draft Answer (No Progress)

Core logic:

sessionService.saveAnswer(request);

Syncs both Redis and DB.

`POST /api/interview/sessions/{sessionId}/complete` Early Submit

Core logic:

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

Persists DB status.

evaluateStreamProducer.sendEvaluateTask(sessionId);

`GET /api/interview/sessions/unfinished/{resumeId}` Find Unfinished Session

Core logic:

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

`GET /api/interview/sessions/{sessionId}/report` Generate Interview Evaluation Report

Core logic:

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

Uses anti-injection instruction to reduce prompt contamination risk from user input.

`GET /api/interview/sessions/{sessionId}/details` Get Interview Detail

Call chain:

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

`GET /api/interview/sessions/{sessionId}/export` Export Interview Report as PDF

Call chain:

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

`DELETE /api/interview/sessions/{sessionId}` Delete Interview Session

Call chain:

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

Evaluation Engine Implementation Highlights

A single evaluation pipeline supports both text and voice interviews, reducing branch complexity.
Batch-first then summarize strategy balances long-context stability and structured output quality.
Anti-injection prompt composition is applied to reduce malicious-input interference.
In failure scenarios, unified invoker + fallback fields avoid hard report failures.

Summary

The Interview module now covers the full workflow from session creation, dynamic question generation, answer progression, asynchronous evaluation, to report export. For me, the key value is separating interview process management from evaluation result production into two evolvable layers, so future changes to question strategy or model upgrades can stay controlled.

AI Resume Analysis: Resume Module

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

Resume Module Design and Implementation

This note records the core design, API responsibilities, async processing pipeline, and practical considerations of the Resume module in the interview-guide project.

Module Capabilities

Multi-format parsing: supports PDF, DOCX, DOC, TXT, and MD.
Async processing: uses Redis Stream for asynchronous resume analysis with status tracking.
Stability: built-in auto-retry on analysis failure (up to 3 times) + duplicate detection based on file hash.
Report export: supports one-click export of AI analysis results as a structured PDF report.

Core Status Flow

flowchart TD
A["Call /api/resumes/upload"] --> B["Validate file and type"]
B --> C{"Is duplicate resume?"}

C -->|Yes| D["Return historical result or status (duplicate=true)"]
C -->|No| E["Parse text + upload object storage + save ResumeEntity"]

E --> F["Set analyzeStatus = PENDING"]
F --> G["Send Redis Stream analyze task"]

G --> H{"Task queued successfully?"}
H -->|No| I["Set FAILED (queue failed)"]
H -->|Yes| J["Consumer pulls task"]

J --> K["Set PROCESSING"]
K --> L["Call ResumeGradingService for AI analysis"]

L --> M{"Any exception in this round?"}
M -->|No| N["Save analysis result"]
N --> O["Set COMPLETED"]

M -->|Yes| P{"retryCount < 3 ?"}
P -->|Yes| Q["retryCount + 1, requeue task"]
Q --> J
P -->|No| R["Set FAILED (final failure)"]

S["Manual retry /api/resumes/{id}/reanalyze"] --> T["Set PENDING and requeue"]
T --> J

Key API Design

`/api/resumes/upload` Upload Resume (Async Analysis)

Rate limit strategy:

Global limit: @RateLimit(dimension = RateLimit.Dimension.GLOBAL, count = 5)
IP limit: @RateLimit(dimension = RateLimit.Dimension.IP, count = 5)

Entry call:

uploadService.uploadAndAnalyze(file);

Processing flow:

Basic file validation

fileValidationService.validateFile(file, MAX_FILE_SIZE, "Resume");

Includes: null check, file size limit, and logging. 2. File type detection

String contentType = parseService.detectContentType(file);

Supports: PDF, DOCX, DOC, TXT, MD. 3. Duplicate file detection

persistenceService.findExistingResume(file);

Internal flow:

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

Resume parsing and text cleaning

parseService.parseResume(file);

Parse to plain text using Apache Tika
textCleaningService.cleanText(content) to reduce excessive line breaks and token usage

File storage (unstructured data)

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

Uploads to RustFS/MinIO for unstructured file storage. 6. Metadata persistence

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

Send async analysis task

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

Uses Redis Stream as the message queue 8. Return upload response
Frontend checks subsequent APIs for async processing status.

`/api/resumes` Get Resume List

Call chain:

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

Current issue:

User-level isolation is not implemented yet, so it currently returns the full list.

`/api/resumes/{id}/detail` Get Resume Detail

Call chain:

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

`/api/resumes/{id}/export` Export Analysis Report as PDF

Call chain:

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

`/api/resumes/{id}` Delete Resume

Call chain:

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

`/api/resumes/{id}/reanalyze` Reanalyze Resume

Rate limit strategy:

Global limit: @RateLimit(dimension = RateLimit.Dimension.GLOBAL, count = 2)
IP limit: @RateLimit(dimension = RateLimit.Dimension.IP, count = 2)

Call chain:

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

Then update and persist status in the processing step.

`/api/resumes/health` Health Check

return Result.success();

For service liveness checks.

Stability Design Points

Async decoupling: upload and analysis are separated to improve responsiveness.
Auto-retry: failed analysis retries up to 3 times to reduce transient failures.
Hash-based dedup: SHA-256 content hash avoids repeated analysis of identical files.

Summary

The Resume module already forms a complete loop: upload, parse, async analyze, export, and delete. The current implementation is stable enough for iterative feature expansion and production hardening.

Project on XEDCZQ Blog

AI Resume Analysis: Knowledgebase Module

Knowledgebase Module Design and Implementation

Module Capability Overview

State Transitions

Diagram 1: KnowledgeBase Main State Machine

Diagram 2: Chunked Knowledgebase Vectorization Flow

Key API Design

GET /api/knowledgebase/list Get Knowledgebase List (Status Filter + Sorting)

GET /api/knowledgebase/{id} Get Knowledgebase Detail

DELETE /api/knowledgebase/{id} Delete Knowledgebase

POST /api/knowledgebase/query Non-Streaming Q&A (Multi-Knowledgebase)

POST /api/knowledgebase/query/stream Streaming Q&A (SSE, Multi-Knowledgebase)

GET /api/knowledgebase/categories Get All Category Names

GET /api/knowledgebase/category/{category} Get Knowledgebase List by Category

GET /api/knowledgebase/uncategorized Get Uncategorized Knowledgebase List

PUT /api/knowledgebase/{id}/category Update Knowledgebase Category

POST /api/knowledgebase/upload Upload Knowledgebase File (multipart)

GET /api/knowledgebase/{id}/download Download Original Knowledgebase File

GET /api/knowledgebase/search?keyword=... Keyword Search Knowledgebase

GET /api/knowledgebase/stats Get Knowledgebase Statistics

POST /api/knowledgebase/{id}/revectorize Manual Re-Vectorization

Async Vectorization Processing Flow (Core Implementation)

Summary

AI Resume Analysis: Voice Interview Module

VoiceInterview Module Design and Implementation

Module Capability Overview

State Transitions

Key API Design

POST /api/voice-interview/sessions Create Voice Interview Session

GET /api/voice-interview/sessions/{sessionId} Get Session Detail by ID

POST /api/voice-interview/sessions/{sessionId}/end End Session and Trigger Async Evaluation

PUT /api/voice-interview/sessions/{sessionId}/pause Pause Session

PUT /api/voice-interview/sessions/{sessionId}/resume Resume Session

GET /api/voice-interview/sessions Get Session List (Filter by userId/status)

DELETE /api/voice-interview/sessions/{sessionId} Delete Voice Interview Session

GET /api/voice-interview/sessions/{sessionId}/messages Get Conversation History

GET /api/voice-interview/sessions/{sessionId}/evaluation Get Async Evaluation Status and Result

POST /api/voice-interview/sessions/{sessionId}/evaluation Manually Trigger Async Evaluation

Summary

AI Resume Analysis: Interview Schedule Module

InterviewSchedule Module Design and Implementation

Module Capability Overview

State Transitions

Key API Design

POST /api/interview-schedule/parse Parse Interview Invitation Text

POST /api/interview-schedule Create Interview Record

GET /api/interview-schedule/{id} Get Interview Record by ID

GET /api/interview-schedule Get Interview Record List

PUT /api/interview-schedule/{id} Update Interview Record

DELETE /api/interview-schedule/{id} Delete Interview Record

PATCH/PUT /api/interview-schedule/{id}/status Update Interview Status

Summary

AI Resume Analysis: Interview Module

Interview Mock Interview Module Design and Implementation

Module Capability Overview

Core State Flow

Key API Design

GET /api/interview/sessions List Interview Sessions

POST /api/interview/sessions Create Interview Session

GET /api/interview/sessions/{sessionId} Get Session Info

GET /api/interview/sessions/{sessionId}/question Get Current Question

POST /api/interview/sessions/{sessionId}/answers Submit Answer and Move Forward

POST /api/interview/sessions/{sessionId}/answers Save Draft Answer (No Progress)

POST /api/interview/sessions/{sessionId}/complete Early Submit

GET /api/interview/sessions/unfinished/{resumeId} Find Unfinished Session

GET /api/interview/sessions/{sessionId}/report Generate Interview Evaluation Report

GET /api/interview/sessions/{sessionId}/details Get Interview Detail

GET /api/interview/sessions/{sessionId}/export Export Interview Report as PDF

DELETE /api/interview/sessions/{sessionId} Delete Interview Session

Evaluation Engine Implementation Highlights

Summary

AI Resume Analysis: Resume Module

Resume Module Design and Implementation

Module Capabilities

Core Status Flow

Key API Design

/api/resumes/upload Upload Resume (Async Analysis)

/api/resumes Get Resume List

/api/resumes/{id}/detail Get Resume Detail

`GET /api/knowledgebase/list` Get Knowledgebase List (Status Filter + Sorting)

`GET /api/knowledgebase/{id}` Get Knowledgebase Detail

`DELETE /api/knowledgebase/{id}` Delete Knowledgebase

`POST /api/knowledgebase/query` Non-Streaming Q&A (Multi-Knowledgebase)

`POST /api/knowledgebase/query/stream` Streaming Q&A (SSE, Multi-Knowledgebase)

`GET /api/knowledgebase/categories` Get All Category Names

`GET /api/knowledgebase/category/{category}` Get Knowledgebase List by Category

`GET /api/knowledgebase/uncategorized` Get Uncategorized Knowledgebase List

`PUT /api/knowledgebase/{id}/category` Update Knowledgebase Category

`POST /api/knowledgebase/upload` Upload Knowledgebase File (multipart)

`GET /api/knowledgebase/{id}/download` Download Original Knowledgebase File

`GET /api/knowledgebase/search?keyword=...` Keyword Search Knowledgebase

`GET /api/knowledgebase/stats` Get Knowledgebase Statistics

`POST /api/knowledgebase/{id}/revectorize` Manual Re-Vectorization

`POST /api/voice-interview/sessions` Create Voice Interview Session

`GET /api/voice-interview/sessions/{sessionId}` Get Session Detail by ID

`POST /api/voice-interview/sessions/{sessionId}/end` End Session and Trigger Async Evaluation

`PUT /api/voice-interview/sessions/{sessionId}/pause` Pause Session

`PUT /api/voice-interview/sessions/{sessionId}/resume` Resume Session

`GET /api/voice-interview/sessions` Get Session List (Filter by userId/status)

`DELETE /api/voice-interview/sessions/{sessionId}` Delete Voice Interview Session

`GET /api/voice-interview/sessions/{sessionId}/messages` Get Conversation History

`GET /api/voice-interview/sessions/{sessionId}/evaluation` Get Async Evaluation Status and Result

`POST /api/voice-interview/sessions/{sessionId}/evaluation` Manually Trigger Async Evaluation

`POST /api/interview-schedule/parse` Parse Interview Invitation Text

`POST /api/interview-schedule` Create Interview Record

`GET /api/interview-schedule/{id}` Get Interview Record by ID

`GET /api/interview-schedule` Get Interview Record List

`PUT /api/interview-schedule/{id}` Update Interview Record

`DELETE /api/interview-schedule/{id}` Delete Interview Record

`PATCH/PUT /api/interview-schedule/{id}/status` Update Interview Status

`GET /api/interview/sessions` List Interview Sessions

`POST /api/interview/sessions` Create Interview Session

`GET /api/interview/sessions/{sessionId}` Get Session Info

`GET /api/interview/sessions/{sessionId}/question` Get Current Question

`POST /api/interview/sessions/{sessionId}/answers` Submit Answer and Move Forward

`POST /api/interview/sessions/{sessionId}/answers` Save Draft Answer (No Progress)

`POST /api/interview/sessions/{sessionId}/complete` Early Submit

`GET /api/interview/sessions/unfinished/{resumeId}` Find Unfinished Session

`GET /api/interview/sessions/{sessionId}/report` Generate Interview Evaluation Report

`GET /api/interview/sessions/{sessionId}/details` Get Interview Detail

`GET /api/interview/sessions/{sessionId}/export` Export Interview Report as PDF

`DELETE /api/interview/sessions/{sessionId}` Delete Interview Session

`/api/resumes/upload` Upload Resume (Async Analysis)

`/api/resumes` Get Resume List

`/api/resumes/{id}/detail` Get Resume Detail

`/api/resumes/{id}/export` Export Analysis Report as PDF

`/api/resumes/{id}` Delete Resume

`/api/resumes/{id}/reanalyze` Reanalyze Resume

`/api/resumes/health` Health Check