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
| Route | Auth | Mô tả |
|---|---|---|
POST /api/v1/resumes | Đăng nhập, vai trò: SUPER ADMIN, HR | Tạ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, HR | Danh 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, HR | Chi 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, HR | Cậ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, HR | Xóa mềm nhiều hồ sơ |
DELETE /api/v1/resumes/:id | Đăng nhập, vai trò: SUPER ADMIN, HR | Xó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 ADMIN | Thố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, HR | Chấm điểm lại hồ sơ bằng hàng đợi (quản trị viên hoặc HR) |
Nộp hồ sơ
| Đường | Route | Giới hạn | Phản hồi |
|---|---|---|---|
| CV trực tuyến | POST /resumes/cv-online | 10 lần mỗi 5 phút | Kết quả chấm điểm ngay |
| Tải file | POST /resumes/upload-cv | 20 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ò
HRchỉ thấy và sửa hồ sơ cócompanyIdtrùng công ty của mình; ngược lại403.GET /resumes/:id/analysischo 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ấynotes.HRchư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-uservàmy-resumeslàPOSTdù chỉ đọc dữ liệu, không nhận body, và trả200.PATCH /resumes/:idđổistatusmà không kiểm tra thứ tự chuyển; mỗi lần đổi thêm một phần tử vàohistoriesvà 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:
createtrong resumes.controller.ts - Mã thành công: 201,
message= "Resume created successfully"
Body: CreateUserCvDto (create-resume.dto.ts)
| Field | Kiểu | Bắt buộc | Validation | Ví dụ |
|---|---|---|---|---|
url | string | Có | IsNotEmpty | 'https://example.com/resume.pdf' |
companyId | mongoose.Schema.Types.ObjectId | Không | IsNotEmpty, IsMongoId | '507f1f77bcf86cd799439011' |
jobId | mongoose.Schema.Types.ObjectId | Không | IsNotEmpty, 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:
findAlltrong resumes.controller.ts - Mã thành công: 200,
message= "Resumes have been retrieved successfully"
Query
| Tên | Bắt buộc | Mô tả | Ví dụ |
|---|---|---|---|
page | Không | Trang, bắt đầu từ 1 | |
limit | Không | Số 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:
findOnetrong resumes.controller.ts - Mã thành công: 200,
message= "Resume has been retrieved successfully"
Path params
| Tên | Kiểu | Mô tả |
|---|---|---|
id | string |
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:
updatetrong resumes.controller.ts - Mã thành công: 200,
message= "Resume updated status successfully"
Path params
| Tên | Kiểu | Mô tả |
|---|---|---|
id | string |
Body: UpdateResumeDto (update-resume.dto.ts)
| Field | Kiểu | Bắt buộc | Validation | Ví dụ |
|---|---|---|---|---|
status | string | Không | IsNotEmpty, IsEnum(EResumeStatus), IsString | EResumeStatus.PENDING |
parsedData | ParsedDataDto | Không | ValidateNested | — |
aiAnalysis | AIAnalysisDto | Không | ValidateNested | — |
priority | string | Không | IsEnum(EResumePriority) | — |
adminNotes | string | Không | IsString | — |
hrNotes | string | Không | IsString | — |
isParsed | boolean | Không | IsBoolean | — |
isAnalyzed | boolean | Không | IsBoolean | — |
parseError | string | Không | IsString | — |
analysisError | string | Không | IsString | — |
Kiểu lồng ParsedDataDto
| Field | Kiểu | Bắt buộc | Validation | Ví dụ |
|---|---|---|---|---|
fullName | string | Không | IsString | — |
email | string | Không | IsEmail | — |
phone | string | Không | IsString | — |
skills | string[] | Không | IsArray, IsString | — |
normalizedSkills | string[] | Không | IsArray, IsString | — |
unmappedSkills | string[] | Không | IsArray, IsString | — |
experience | ParsedExperienceDto[] | Không | IsArray, ValidateNested | — |
education | ParsedEducationDto[] | Không | IsArray, ValidateNested | — |
summary | string | Không | IsString | — |
yearsOfExperience | number | Không | IsNumber | — |
Kiểu lồng AIAnalysisDto
| Field | Kiểu | Bắt buộc | Validation | Ví dụ |
|---|---|---|---|---|
matchingScore | number | Không | IsNumber, Min(0), Max(100) | — |
skillsMatch | SkillMatchDto[] | Không | IsArray, ValidateNested | — |
strengths | string[] | Không | IsArray, IsString | — |
weaknesses | string[] | Không | IsArray, IsString | — |
summary | string | Không | IsString | — |
recommendation | string | Không | IsString | — |
analyzedAt | Date | Không | IsDate | — |
DELETE /api/v1/resumes/bulk
Xóa mềm nhiều hồ sơ
- Auth: Đăng nhập, vai trò: SUPER ADMIN, HR
- Handler:
bulkRemovetrong resumes.controller.ts - Mã thành công: 200,
message= "Bulk delete resumes"
Body: BulkDeleteDto (bulk-delete.dto.ts)
| Field | Kiểu | Bắt buộc | Validation | Ví dụ |
|---|---|---|---|---|
ids | string[] | 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:
removetrong resumes.controller.ts - Mã thành công: 200,
message= "Resume deleted successfully"
Path params
| Tên | Kiểu | Mô tả |
|---|---|---|
id | string |
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:
getResumeByUsertrong 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:
getResumeOfMetrong 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:
submitCvOnlinetrong 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)
| Field | Kiểu | Bắt buộc | Validation | Ví dụ |
|---|---|---|---|---|
jobId | string | Có | 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:
uploadCVtrong 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)
| Field | Kiểu | Bắt buộc | Validation | Ví dụ |
|---|---|---|---|---|
jobId | string | Có | 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:
getAnalysistrong resumes.controller.ts - Mã thành công: 200,
message= "Analysis results retrieved successfully"
Path params
| Tên | Kiểu | Mô tả |
|---|---|---|
id | string |
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:
getQueueStatstrong 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:
reparseCVtrong resumes.controller.ts - Mã thành công: 201,
message= "Re-parsing queued successfully"
Path params
| Tên | Kiểu | Mô tả |
|---|---|---|
id | string |
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:
reanalyzeCVtrong resumes.controller.ts - Mã thành công: 202,
message= "Re-analysis queued successfully"
Path params
| Tên | Kiểu | Mô tả |
|---|---|---|
id | string |