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.