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

API Jobs

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

Ai thấy tin nào​

GET /jobs và GET /jobs/:id công khai (@OptionalAuth), kết quả phụ thuộc người gọi:

Người gọiThấy
Khách hoặc NORMAL USERTin isActive, APPROVED, chưa quá endDate (hoặc không có endDate)
HR có công tyMọi tin của công ty mình, mọi trạng thái
SUPER ADMINTất cả

Danh sách được cache 60 giây trong Redis, tách theo phạm vi (public, super-admin, hr:<companyId>).

Danh sách route​

RouteAuthMô tả
POST /api/v1/jobsĐăng nhập, vai trò: SUPER ADMIN, HRTạo tin tuyển dụng, trạng thái duyệt mặc định PENDING (quản trị viên hoặc HR)
GET /api/v1/jobsTùy chọn (khách hoặc đã đăng nhập)Danh sách tin có phân trang, lọc, sắp xếp và tìm theo keyword. Kết quả phụ thuộc người gọi
GET /api/v1/jobs/:idTùy chọn (khách hoặc đã đăng nhập)Chi tiết một tin
PATCH /api/v1/jobs/:idĐăng nhập, vai trò: SUPER ADMIN, HRCập nhật tin. HR chỉ sửa tin công ty mình
DELETE /api/v1/jobs/bulkĐăng nhập, vai trò: SUPER ADMIN, HRXóa mềm nhiều tin
DELETE /api/v1/jobs/:idĐăng nhập, vai trò: SUPER ADMIN, HRXóa mềm một tin
PATCH /api/v1/jobs/:id/approveĐăng nhập, vai trò: SUPER ADMINDuyệt hoặc từ chối tin (quản trị viên)

Lọc, tìm kiếm và sắp xếp​

  • keyword tìm trên tên tin, kỹ năng và tên công ty.
  • Bộ lọc khác đọc từ query string bằng api-query-params, chỉ các trường: name, skills, location, locationCode, salary, quantity, level, formOfWork, isActive, approvalStatus, company._id, startDate, endDate, createdAt. Trường khác bị bỏ qua.
  • Sắp xếp chỉ theo các trường trong ALLOWED_SORT_FIELDS (ví dụ name, salary, createdAt, updatedAt, level, location), giá trị 1 hoặc -1.
  • skills được chuẩn hóa qua danh mục kỹ năng; giá trị không có trong danh mục làm yêu cầu bị 400.

Quy tắc ghi​

  • POST và PATCH: kỹ năng và địa điểm được chuẩn hóa; company._id quyết định snapshot công ty.
  • PATCH /jobs/:id/approve: chỉ SUPER ADMIN, đặt approvalStatus, approvalNote, approvedBy, approvedAt. Không kiểm tra trạng thái hiện tại, nhưng DTO chỉ nhận APPROVED hoặc REJECTED (không quay lại PENDING).
  • Tạo tin luôn đưa việc "tin mới" vào hàng đợi báo người theo dõi công ty, trước khi tin được duyệt (jobs).
  • approvalStatus không nằm trong CreateJobDto hay UpdateJobDto, nên không đặt được qua POST/PATCH; tin mới luôn PENDING.

Chi tiết từng route​

POST /api/v1/jobs​

Tạo tin tuyển dụng, trạng thái duyệt mặc định PENDING (quản trị viên hoặc HR)

  • Auth: Đăng nhập, vai trò: SUPER ADMIN, HR
  • Handler: create trong jobs.controller.ts
  • Mã thành công: 201, message = "Create a new job"

Body: CreateJobDto (create-job.dto.ts)

FieldKiểuBắt buộcValidationVí dụ
namestringCóIsNotEmpty, IsString, MaxLength(100)'Senior Backend Engineer'
skillsstring[]CóIsNotEmpty, IsArray, ArrayMinSize(1), IsString, MaxLength(100)['NestJS', 'MongoDB', 'TypeScript', 'Docker']
companyCompanyDtoCóIsNotEmptyObject, IsObject, ValidateNested—
locationCodestringKhôngIsString, MaxLength(100)'ha-noi'
locationstringKhôngIsString, MaxLength(200)'Hà Nội'
salarynumberCóIsNotEmpty, IsNumber, IsPositive25000000
quantitynumberCóIsNotEmpty, IsInt, Min(1), Max(1000)5
levelEJobLevelCóIsNotEmpty, IsEnum(EJobLevel), IsString, MaxLength(50)EJobLevel.SENIOR
formOfWorkstringCóIsNotEmpty, IsString, IsEnum(EJobFormOfWork)EJobFormOfWork.FULL_TIME
descriptionstringCóIsNotEmpty, IsString, MaxLength(5000)'We are looking for an experienced backend engineer to join …
startDateDateCóIsNotEmpty, IsDate'2025-11-01'
endDateDateCóIsNotEmpty, IsDate, IsAfter'2025-12-31'
isActivebooleanCóIsNotEmpty, IsBooleantrue

Kiểu lồng CompanyDto

FieldKiểuBắt buộcValidationVí dụ
_idstringKhôngIsNotEmpty, IsMongoId'507f1f77bcf86cd799439011'
namestringKhôngIsNotEmpty, IsString, MaxLength(100)'Tech Corp'
logostringKhôngIsString'logo.png'

GET /api/v1/jobs​

Danh sách tin có phân trang, lọc, sắp xếp và tìm theo keyword. Kết quả phụ thuộc người gọi

  • Auth: Tùy chọn (khách hoặc đã đăng nhập)
  • Handler: findAll trong jobs.controller.ts
  • Mã thành công: 200, message = "Get list jobs"

Query

TênBắt buộcMô tảVí dụ
pageKhôngPage number (starts from 1)1
limitKhôngNumber of items per page10
keywordKhôngSearch keyword — matches job title, skills, and company name'React'
(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/jobs/:id​

Chi tiết một tin

  • Auth: Tùy chọn (khách hoặc đã đăng nhập)
  • Handler: findOne trong jobs.controller.ts
  • Mã thành công: 200, message = "Get job by id"

Path params

TênKiểuMô tả
idstring

PATCH /api/v1/jobs/:id​

Cập nhật tin. HR chỉ sửa tin công ty mình

  • Auth: Đăng nhập, vai trò: SUPER ADMIN, HR
  • Handler: update trong jobs.controller.ts
  • Mã thành công: 200, message = "Update job by id"

Path params

TênKiểuMô tả
idstring

Body: UpdateJobDto (update-job.dto.ts)

Kế thừa PartialType(CreateJobDto).

DTO không khai báo field riêng.

DELETE /api/v1/jobs/bulk​

Xóa mềm nhiều tin

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

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/jobs/:id​

Xóa mềm một tin

  • Auth: Đăng nhập, vai trò: SUPER ADMIN, HR
  • Handler: remove trong jobs.controller.ts
  • Mã thành công: 200, message = "Delete job by id"

Path params

TênKiểuMô tả
idstring

PATCH /api/v1/jobs/:id/approve​

Duyệt hoặc từ chối tin (quản trị viên)

  • Auth: Đăng nhập, vai trò: SUPER ADMIN
  • Handler: approveJob trong jobs.controller.ts
  • Mã thành công: 200, message = "Job approval status updated"

Path params

TênKiểuMô tả
idstring

Body: ApproveJobDto (approve-job.dto.ts)

FieldKiểuBắt buộcValidationVí dụ
statusEJobApprovalStatusCóIsNotEmpty, IsEnum(ALLOWED_STATUSES)EJobApprovalStatus.APPROVED
approvalNotestringKhôngIsString, MaxLength(500)'Job description does not meet content guidelines.'