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

API Users

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

Nhóm route quản trị (POST, danh sách, xem, sửa, khóa, xóa) chỉ cho SUPER ADMIN. Nhóm save-job, follow-company dành cho người dùng đã đăng nhập tự quản lý dữ liệu của mình.

Danh sách route​

RouteAuthMô tả
POST /api/v1/usersĐăng nhập, vai trò: SUPER ADMINTạo người dùng với vai trò tùy chọn (quản trị viên), có thể gắn công ty cho HR
GET /api/v1/usersĐăng nhập, vai trò: SUPER ADMINLiệt kê người dùng có phân trang, lọc và sắp xếp (quản trị viên)
PATCH /api/v1/users/:idĐăng nhập, vai trò: SUPER ADMINCập nhật thông tin người dùng (quản trị viên)
POST /api/v1/users/save-jobĐăng nhập (mọi vai trò)Lưu một tin tuyển dụng vào danh sách của mình
DELETE /api/v1/users/save-jobĐăng nhập (mọi vai trò)Bỏ lưu một tin tuyển dụng
GET /api/v1/users/saved-jobsĐăng nhập (mọi vai trò)Xem danh sách tin đã lưu
POST /api/v1/users/follow-companyĐăng nhập (mọi vai trò)Theo dõi một công ty
DELETE /api/v1/users/follow-companyĐăng nhập (mọi vai trò)Bỏ theo dõi một công ty
GET /api/v1/users/following-companiesĐăng nhập (mọi vai trò)Xem danh sách công ty đang theo dõi
GET /api/v1/users/:idĐăng nhập, vai trò: SUPER ADMINXem một người dùng theo ID (quản trị viên)
PATCH /api/v1/users/:id/lockĐăng nhập, vai trò: SUPER ADMINKhóa tài khoản và vô hiệu mọi phiên (quản trị viên)
PATCH /api/v1/users/:id/unlockĐăng nhập, vai trò: SUPER ADMINMở khóa tài khoản (quản trị viên)
DELETE /api/v1/users/bulkĐăng nhập, vai trò: SUPER ADMINXóa mềm nhiều người dùng (quản trị viên)
DELETE /api/v1/users/:idĐăng nhập, vai trò: SUPER ADMINXóa mềm một người dùng (quản trị viên)

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

GET /users đọc bộ lọc bằng api-query-params và lọc qua allowlist trường và toán tử (users.service.ts), xem api-overview. Các trường lọc theo văn bản gồm name, email, company.name.

Quy tắc​

  • Khóa: không tự khóa mình; không khóa tài khoản đã khóa; khóa xong vô hiệu mọi phiên (users).
  • Mật khẩu của người dùng được băm bằng bcryptjs; response không được kỳ vọng chứa mật khẩu, nhưng việc loại field password khỏi response của GET /users chưa được kiểm tra. Trạng thái: Chưa xác minh.

Chi tiết từng route​

POST /api/v1/users​

Tạo người dùng với vai trò tùy chọn (quản trị viên), có thể gắn công ty cho HR

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

Body: CreateUserDto (create-user.dto.ts)

FieldKiểuBắt buộcValidationVí dụ
namestringCóIsNotEmpty, IsString, MaxLength(100)'Test'
emailstringCóIsEmail, IsNotEmpty'user@example.com'
passwordstringCóIsNotEmpty'123456'
avatarstringKhôngIsString, MaxLength(500)'https://example.com/avatar.jpg'
companyCompanyDtoKhôngIsNotEmptyObject, IsObject, ValidateNested—
roleERoleCóIsNotEmpty, IsEnum(ERole)ERole.HR

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/users​

Liệt kê người dùng có phân trang, lọc và sắp xếp (quản trị viên)

  • Auth: Đăng nhập, vai trò: SUPER ADMIN
  • Handler: findAll trong users.controller.ts
  • Mã thành công: 200, message = "Get list users"

Query

TênBắt buộcMô tảVí dụ
pageKhôngPage number (default: 1)'1'
limitKhôngNumber of items per page (default: 10)'10'
(toàn bộ query string)—Đọc bằng api-query-params: hỗ trợ lọc và sắp xếp (xem api-overview)

PATCH /api/v1/users/:id​

Cập nhật thông tin người dùng (quản trị viên)

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

Path params

TênKiểuMô tả
idstring

Body: UpdateUserDto (update-user.dto.ts)

Kế thừa OmitType(CreateUserDto, ['password'] as const).

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

POST /api/v1/users/save-job​

Lưu một tin tuyển dụng vào danh sách của mình

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: saveJob trong users.controller.ts
  • Mã thành công: HttpStatus.OK, message = "Job saved successfully"

Body: SaveJobDto (save-job.dto.ts)

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

DELETE /api/v1/users/save-job​

Bỏ lưu một tin tuyển dụng

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: unsaveJob trong users.controller.ts
  • Mã thành công: HttpStatus.OK, message = "Job unsaved successfully"

Body: SaveJobDto (save-job.dto.ts)

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

GET /api/v1/users/saved-jobs​

Xem danh sách tin đã lưu

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: getSavedJobs trong users.controller.ts
  • Mã thành công: 200, message = "Get saved jobs successfully"

Query

TênBắt buộcMô tảVí dụ
pageKhôngPage number (default: 1)1
limitKhôngNumber of items per page (default: 10)10

POST /api/v1/users/follow-company​

Theo dõi một công ty

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: followCompany trong users.controller.ts
  • Mã thành công: HttpStatus.OK, message = "Company followed successfully"

Body: FollowCompanyDto (follow-company.dto.ts)

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

DELETE /api/v1/users/follow-company​

Bỏ theo dõi một công ty

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: unfollowCompany trong users.controller.ts
  • Mã thành công: HttpStatus.OK, message = "Company unfollowed successfully"

Body: FollowCompanyDto (follow-company.dto.ts)

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

GET /api/v1/users/following-companies​

Xem danh sách công ty đang theo dõi

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: getFollowingCompanies trong users.controller.ts
  • Mã thành công: 200, message = "Get following companies successfully"

GET /api/v1/users/:id​

Xem một người dùng theo ID (quản trị viên)

  • Auth: Đăng nhập, vai trò: SUPER ADMIN
  • Handler: findOne trong users.controller.ts
  • Mã thành công: 200, message = "Get user by id"

Path params

TênKiểuMô tả
idstring

PATCH /api/v1/users/:id/lock​

Khóa tài khoản và vô hiệu mọi phiên (quản trị viên)

  • Auth: Đăng nhập, vai trò: SUPER ADMIN
  • Handler: lockUser trong users.controller.ts
  • Mã thành công: 200, message = "User account locked successfully"

Path params

TênKiểuMô tả
idstring

Body: LockUserDto (lock-user.dto.ts)

FieldKiểuBắt buộcValidationVí dụ
reasonstringKhôngIsString, MaxLength(500)'Violated community guidelines'

PATCH /api/v1/users/:id/unlock​

Mở khóa tài khoản (quản trị viên)

  • Auth: Đăng nhập, vai trò: SUPER ADMIN
  • Handler: unlockUser trong users.controller.ts
  • Mã thành công: 200, message = "User account unlocked successfully"

Path params

TênKiểuMô tả
idstring

DELETE /api/v1/users/bulk​

Xóa mềm nhiều người dùng (quản trị viên)

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

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

Xóa mềm một người dùng (quản trị viên)

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

Path params

TênKiểuMô tả
idstring