Chuyển tới nội dung chính

API Resumes

Tiền tố /api/v1/resumes. Controller: resumes.controller.ts. Module: resumes. Collection: resumes.

Hai nhóm người dùng: ứng viên nộp và xem hồ sơ của mình (cv-online, upload-cv, by-user, my-resumes, :id/analysis), và HR hoặc quản trị viên xử lý hồ sơ (CRUD, reparse, reanalyze). queue/stats chỉ cho quản trị viên.

Danh sách route​

RouteAuthMô tả
POST /api/v1/resumesĐăng nhập, vai trò: SUPER ADMIN, HRTạo hồ sơ thủ công (quản trị viên hoặc HR)
GET /api/v1/resumesĐăng nhập, vai trò: SUPER ADMIN, HRDanh sách hồ sơ có phân trang. HR chỉ thấy hồ sơ công ty mình
GET /api/v1/resumes/:idĐăng nhập, vai trò: SUPER ADMIN, HRChi tiết một hồ sơ. HR chỉ xem hồ sơ công ty mình
PATCH /api/v1/resumes/:idĐăng nhập, vai trò: SUPER ADMIN, HRCập nhật hồ sơ. Đổi status ghi histories và gửi thông báo cho ứng viên
DELETE /api/v1/resumes/bulkĐăng nhập, vai trò: SUPER ADMIN, HRXóa mềm nhiều hồ sơ
DELETE /api/v1/resumes/:idĐăng nhập, vai trò: SUPER ADMIN, HRXóa mềm một hồ sơ
POST /api/v1/resumes/by-userĐăng nhập (mọi vai trò)Lấy các hồ sơ ứng tuyển của chính người gọi (dùng POST, không có body)
POST /api/v1/resumes/my-resumesĐăng nhập (mọi vai trò)Lấy danh sách URL file CV của chính người gọi (dùng POST, không có body)
POST /api/v1/resumes/cv-onlineĐăng nhập (mọi vai trò)Nộp hồ sơ bằng CV trực tuyến, chấm điểm ngay trong request
POST /api/v1/resumes/upload-cvĐăng nhập (mọi vai trò)Tải file CV và nộp hồ sơ. Việc đọc và phân tích đi qua hàng đợi
GET /api/v1/resumes/:id/analysisĐăng nhập (mọi vai trò)Xem kết quả đọc và phân tích CV (chủ hồ sơ, HR cùng công ty hoặc quản trị viên). Ứng viên không thấy notes
GET /api/v1/resumes/:id/fileĐăng nhập (mọi vai trò)Tải file CV (stream, không bọc envelope). Chủ hồ sơ, HR cùng công ty hoặc quản trị viên; sai quyền 403, thiếu file 404
GET /api/v1/resumes/queue/statsĐăng nhập, vai trò: SUPER ADMINThống kê hàng đợi xử lý hồ sơ (quản trị viên)
POST /api/v1/resumes/:id/reparseĐăng nhập, vai trò: SUPER ADMIN, HRĐọc lại file CV bằng hàng đợi (quản trị viên hoặc HR)
POST /api/v1/resumes/:id/reanalyzeĐăng nhập, vai trò: SUPER ADMIN, HRChấm điểm lại hồ sơ bằng hàng đợi (quản trị viên hoặc HR)

Nộp hồ sơ​

ĐườngRouteGiới hạnPhản hồi
CV trực tuyếnPOST /resumes/cv-online10 lần mỗi 5 phútKết quả chấm điểm ngay
Tải filePOST /resumes/upload-cv20 lần mỗi giờstatus: "processing", kèm jobs.parseJobId, estimatedTime: "30-60 seconds" (chuỗi trong code)

Nộp trùng (cùng ứng viên, cùng job, đơn cũ chưa xóa) trả 409 Conflict, kể cả khi hai request đến đồng thời (unique index userId + jobId). Upload bị từ chối thì file vừa tải lên bị xóa.

Chấm điểm được processor tự xếp hàng sau khi đọc CV xong; response chỉ có parseJobId.

upload-cv nhận multipart/form-data với file CV và jobId. Quy tắc nghiệp vụ (trùng đơn, CV bị tắt): resumes.

Phạm vi theo vai trò​

  • HR chỉ thấy và sửa hồ sơ có companyId trùng công ty của mình; ngược lại 403.
  • GET /resumes/:id/analysis cho chủ hồ sơ, HR cùng công ty và SUPER ADMIN; sai quyền trả 403. Chỉ HR và quản trị viên thấy notes.
  • HR chưa gắn công ty bị từ chối (403) ở mọi route hồ sơ.

Lọc và sắp xếp​

GET /resumes chỉ nhận bộ lọc trên status, priority, companyId, jobId, userId, isParsed, isAnalyzed, email, createdAt, updatedAt, aiAnalysis.matchingScore; toán tử trong giá trị giới hạn ở so sánh ($eq, $ne, $gt, $gte, $lt, $lte, $in, $nin); regex được coi là chuỗi con (đã escape). populate/fields từ client bị bỏ qua, server luôn populate companyId.name và jobId.name. Phạm vi công ty của HR được gán sau bước lọc.

Known Limitation​

  • by-user và my-resumes là POST dù chỉ đọc dữ liệu, không nhận body, và trả 200.
  • PATCH /resumes/:id đổi status mà không kiểm tra thứ tự chuyển; mỗi lần đổi thêm một phần tử vào histories và gửi thông báo cho ứng viên.
  • Điểm phù hợp chỉ ảnh hưởng priority; trạng thái tự động đã bị tắt trong processor (resumes (collection)).

Chi tiết từng route​

POST /api/v1/resumes​

Tạo hồ sơ thủ công (quản trị viên hoặc HR)

  • Auth: Đăng nhập, vai trò: SUPER ADMIN, HR
  • Handler: create trong resumes.controller.ts
  • Mã thành công: 201, message = "Resume created successfully"

Body: CreateUserCvDto (create-resume.dto.ts)

FieldKiểuBắt buộcValidationVí dụ
urlstringCóIsNotEmpty'https://example.com/resume.pdf'
companyIdmongoose.Schema.Types.ObjectIdKhôngIsNotEmpty, IsMongoId'507f1f77bcf86cd799439011'
jobIdmongoose.Schema.Types.ObjectIdKhôngIsNotEmpty, IsMongoId'507f1f77bcf86cd799439011'

GET /api/v1/resumes​

Danh sách hồ sơ có phân trang. HR chỉ thấy hồ sơ công ty mình

  • Auth: Đăng nhập, vai trò: SUPER ADMIN, HR
  • Handler: findAll trong resumes.controller.ts
  • Mã thành công: 200, message = "Resumes have been retrieved successfully"

Query

TênBắt buộcMô tảVí dụ
pageKhôngTrang, bắt đầu từ 1
limitKhôngSố mục mỗi trang, mặc định 10, tối đa 100
(toàn bộ query string)—Đọc bằng api-query-params: hỗ trợ lọc và sắp xếp (xem api-overview)

GET /api/v1/resumes/:id​

Chi tiết một hồ sơ. HR chỉ xem hồ sơ công ty mình

  • Auth: Đăng nhập, vai trò: SUPER ADMIN, HR
  • Handler: findOne trong resumes.controller.ts
  • Mã thành công: 200, message = "Resume has been retrieved successfully"

Path params

TênKiểuMô tả
idstring

PATCH /api/v1/resumes/:id​

Cập nhật hồ sơ. Đổi status ghi histories và gửi thông báo cho ứng viên

  • Auth: Đăng nhập, vai trò: SUPER ADMIN, HR
  • Handler: update trong resumes.controller.ts
  • Mã thành công: 200, message = "Resume updated status successfully"

Path params

TênKiểuMô tả
idstring

Body: UpdateResumeDto (update-resume.dto.ts)

FieldKiểuBắt buộcValidationVí dụ
statusstringKhôngIsNotEmpty, IsEnum(EResumeStatus), IsStringEResumeStatus.PENDING
parsedDataParsedDataDtoKhôngValidateNested—
aiAnalysisAIAnalysisDtoKhôngValidateNested—
prioritystringKhôngIsEnum(EResumePriority)—
adminNotesstringKhôngIsString—
hrNotesstringKhôngIsString—
isParsedbooleanKhôngIsBoolean—
isAnalyzedbooleanKhôngIsBoolean—
parseErrorstringKhôngIsString—
analysisErrorstringKhôngIsString—

Kiểu lồng ParsedDataDto

FieldKiểuBắt buộcValidationVí dụ
fullNamestringKhôngIsString—
emailstringKhôngIsEmail—
phonestringKhôngIsString—
skillsstring[]KhôngIsArray, IsString—
normalizedSkillsstring[]KhôngIsArray, IsString—
unmappedSkillsstring[]KhôngIsArray, IsString—
experienceParsedExperienceDto[]KhôngIsArray, ValidateNested—
educationParsedEducationDto[]KhôngIsArray, ValidateNested—
summarystringKhôngIsString—
yearsOfExperiencenumberKhôngIsNumber—

Kiểu lồng AIAnalysisDto

FieldKiểuBắt buộcValidationVí dụ
matchingScorenumberKhôngIsNumber, Min(0), Max(100)—
skillsMatchSkillMatchDto[]KhôngIsArray, ValidateNested—
strengthsstring[]KhôngIsArray, IsString—
weaknessesstring[]KhôngIsArray, IsString—
summarystringKhôngIsString—
recommendationstringKhôngIsString—
analyzedAtDateKhôngIsDate—

DELETE /api/v1/resumes/bulk​

Xóa mềm nhiều hồ sơ

  • Auth: Đăng nhập, vai trò: SUPER ADMIN, HR
  • Handler: bulkRemove trong resumes.controller.ts
  • Mã thành công: 200, message = "Bulk delete resumes"

Body: BulkDeleteDto (bulk-delete.dto.ts)

FieldKiểuBắt buộcValidationVí dụ
idsstring[]CóIsArray, ArrayMinSize(1), ArrayMaxSize(100), IsMongoId['507f1f77bcf86cd799439011', '507f1f77bcf86cd799439012']

DELETE /api/v1/resumes/:id​

Xóa mềm một hồ sơ

  • Auth: Đăng nhập, vai trò: SUPER ADMIN, HR
  • Handler: remove trong resumes.controller.ts
  • Mã thành công: 200, message = "Resume deleted successfully"

Path params

TênKiểuMô tả
idstring

POST /api/v1/resumes/by-user​

Lấy các hồ sơ ứng tuyển của chính người gọi (dùng POST, không có body)

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: getResumeByUser trong resumes.controller.ts
  • Mã thành công: 200, message = "Resume has been retrieved successfully"

POST /api/v1/resumes/my-resumes​

Lấy danh sách URL file CV của chính người gọi (dùng POST, không có body)

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: getResumeOfMe trong resumes.controller.ts
  • Mã thành công: 200, message = "Resume has been retrieved successfully"

POST /api/v1/resumes/cv-online​

Nộp hồ sơ bằng CV trực tuyến, chấm điểm ngay trong request

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: submitCvOnline trong resumes.controller.ts
  • Mã thành công: 201, message = "CV submitted successfully"
  • Giới hạn tốc độ: 10 lần mỗi 5 phút

Body: SubmitCvOnlineDto (submit-cv-online.dto.ts)

FieldKiểuBắt buộcValidationVí dụ
jobIdstringCóIsNotEmpty, IsMongoId'507f1f77bcf86cd799439011'

POST /api/v1/resumes/upload-cv​

Tải file CV và nộp hồ sơ. Việc đọc và phân tích đi qua hàng đợi

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: uploadCV trong resumes.controller.ts
  • Mã thành công: 201, message = "CV uploaded and queued for processing"
  • Giới hạn tốc độ: 20 lần mỗi 1 giờ

Body: UploadCvDto (upload-cv.dto.ts)

FieldKiểuBắt buộcValidationVí dụ
jobIdstringCóIsNotEmpty, IsMongoId'507f1f77bcf86cd799439011'

Upload: nhận file qua multipart/form-data (@UploadedFile).

GET /api/v1/resumes/:id/analysis​

Xem kết quả đọc và phân tích CV (chủ hồ sơ hoặc quản trị viên)

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: getAnalysis trong resumes.controller.ts
  • Mã thành công: 200, message = "Analysis results retrieved successfully"

Path params

TênKiểuMô tả
idstring

GET /api/v1/resumes/queue/stats​

Thống kê hàng đợi xử lý hồ sơ (quản trị viên)

  • Auth: Đăng nhập, vai trò: SUPER ADMIN
  • Handler: getQueueStats trong resumes.controller.ts
  • Mã thành công: 200, message = "Queue statistics retrieved"

POST /api/v1/resumes/:id/reparse​

Đọc lại file CV bằng hàng đợi (quản trị viên hoặc HR)

  • Auth: Đăng nhập, vai trò: SUPER ADMIN, HR
  • Handler: reparseCV trong resumes.controller.ts
  • Mã thành công: 201, message = "Re-parsing queued successfully"

Path params

TênKiểuMô tả
idstring

POST /api/v1/resumes/:id/reanalyze​

Chấm điểm lại hồ sơ bằng hàng đợi (quản trị viên hoặc HR)

  • Auth: Đăng nhập, vai trò: SUPER ADMIN, HR
  • Handler: reanalyzeCV trong resumes.controller.ts
  • Mã thành công: 202, message = "Re-analysis queued successfully"

Path params

TênKiểuMô tả
idstring