1. Tổng quan

1.1 Yêu cầu được Giải quyết

1.2 Xác thực

Tất cả endpoint yêu cầu xác thực qua:

• Bearer Token — Authorization: Bearer <token>
• Cookie API Key — apiKeyCookie

Ngoài ra, quyền truy cập tệp tin được kiểm tra theo quyền sở hữu hoặc thành viên tổ chức (RBAC).

1.3 Tóm tắt Endpoint

2. Định dạng Phản hồi

2.1 Phản hồi Thành công

{
  "success": true,
  "data": { ... },
  "message": "Thao tác hoàn tất thành công"
}

2.2 Phản hồi Phân trang

{
  "success": true,
  "data": {
    "files": [ ... ],
    "total": 42,
    "page": 1,
    "limit": 20
  }
}

2.3 Phản hồi Lỗi

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Loại tệp tin không hợp lệ cho danh mục RESUME"
  }
}

3. Schema

3.1 Tệp tin

3.2 Phản hồi URL Presigned

4. Endpoint Tệp tin

4.1 Tải lên Tệp tin (Local Filesystem)

POST /files/upload FR-001

Tải lên tệp tin qua multipart/form-data. Server lưu tệp tin vào local filesystem và tạo bản ghi metadata.

Yêu cầu: Content-Type: multipart/form-data

Quy tắc Xác thực:

Phản hồi 200:

{
  "success": true,
  "data": {
    "id": "file-uuid-123",
    "original_name": "my-resume.pdf",
    "file_path": "user-123/RESUME/a1b2c3d4-resume.pdf",
    "mime_type": "application/pdf",
    "file_size": 524288,
    "category": "RESUME",
    "status": "ACTIVE"
  }
}

4.2 Tải lên Hàng loạt

POST /files/batch FR-011

Tải lên nhiều tệp tin trong một yêu cầu duy nhất (multipart/form-data).

Yêu cầu: Content-Type: multipart/form-data

Phản hồi 200:

{
  "success": true,
  "data": {
    "uploads": [
      { "id": "uuid-1", "original_name": "resume.pdf", "file_path": "..." },
      { "id": "uuid-2", "original_name": "avatar.jpg", "file_path": "..." }
    ],
    "errors": []
  }
}

4.3 Tải xuống Tệp tin

GET /files/:id/download FR-002

Tải xuống tệp tin từ local filesystem. Kiểm tra quyền truy cập trước khi trả về nội dung.

Tham số Đường dẫn:

Phản hồi 200: File stream (Content-Type: application/octet-stream)

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="my-resume.pdf"
Content-Length: 524288

<binary file data>

Lỗi 403 — Từ chối truy cập:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Bạn không có quyền truy cập tệp tin này"
  }
}

Lỗi 404 — Không tìm thấy tệp tin:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Không tìm thấy tệp tin"
  }
}

4.5 Liệt kê Tệp tin

GET /files FR-003

Liệt kê tệp tin với lọc tùy chọn theo người dùng, nhà tuyển dụng và danh mục. Hỗ trợ phân trang.

Tham số Truy vấn:

Ví dụ Yêu cầu:

GET /files?category=RESUME&page=1&limit=10

Phản hồi 200:

{
  "success": true,
  "data": {
    "files": [
      {
        "id": "file-uuid-123",
        "employer_id": "acme-corp-uuid",
        "user_id": "user-uuid-456",
        "original_name": "my-resume.pdf",
        "file_path": "user-123/RESUME/a1b2c3d4-resume.pdf",
        "file_path": "user-123/RESUME/a1b2c3d4-resume.pdf",
        "mime_type": "application/pdf",
        "file_size": 524288,
        "category": "RESUME",
        "is_public": false,
        "status": "ACTIVE",
        "created_at": "2026-08-17T10:45:00Z",
        "updated_at": "2026-08-17T10:45:00Z"
      }
    ],
    "total": 42,
    "page": 1,
    "limit": 10
  }
}

4.6 Tìm kiếm Tệp tin

GET /files/search FR-009

Tìm kiếm toàn văn trên tên và metadata tệp tin/thư mục.

Tham số Truy vấn:

Phản hồi 200:

{
  "success": true,
  "data": {
    "files": [ ... ],
    "total": 15,
    "page": 1,
    "limit": 20
  }
}

4.7 Tạo Thư mục

POST /files/folders FR-008

Tạo thư mục mới trong cấu trúc thư mục được ủy quyền.

Yêu cầu:

{
  "name": "My Documents",
  "parent_folder_id": "folder-uuid-123"
}

Phản hồi 200:

{
  "success": true,
  "data": {
    "id": "folder-uuid-456",
    "name": "My Documents",
    "parent_folder_id": "folder-uuid-123",
    "type": "FOLDER",
    "created_at": "2026-08-17T10:45:00Z"
  }
}

4.8 Đổi tên Tệp tin/Thư mục

PATCH /files/:id FR-010

Đổi tên tệp tin hoặc thư mục. Xử lý tên trùng lặp bằng cách thêm hậu tố số.

Yêu cầu:

{
  "name": "New Document Name"
}

Phản hồi 200:

{
  "success": true,
  "data": {
    "id": "file-uuid-123",
    "original_name": "New Document Name",
    "updated_at": "2026-08-17T10:50:00Z"
  }
}

4.9 Sao chép Tệp tin

POST /files/:id/copy FR-012

Sao chép tệp tin đến thư mục đích. Tạo bản ghi mới với cùng file vật lý.

Yêu cầu:

{
  "destination_folder_id": "folder-uuid-789"
}

Phản hồi 200:

{
  "success": true,
  "data": {
    "id": "file-uuid-new",
    "original_name": "document.pdf",
    "parent_folder_id": "folder-uuid-789",
    "file_path": "same-as-original",
    "created_at": "2026-08-17T10:55:00Z"
  }
}

4.10 Di chuyển Tệp tin

POST /files/:id/move FR-013

Di chuyển tệp tin đến thư mục đích. Cập nhật parent_folder_id.

Yêu cầu:

{
  "destination_folder_id": "folder-uuid-789"
}

Phản hồi 200:

{
  "success": true,
  "data": {
    "id": "file-uuid-123",
    "original_name": "document.pdf",
    "parent_folder_id": "folder-uuid-789",
    "updated_at": "2026-08-17T11:00:00Z"
  }
}

4.11 Xóa Tệp tin/Thư mục

DELETE /files/:id FR-004

Xóa mềm tệp tin hoặc thư mục. Đối với thư mục, đánh dấu đệ quy tất cả các mục con là DELETED.

Phản hồi 200:

{
  "success": true,
  "message": "Tệp tin/thư mục đã được xóa thành công"
}

4.12 Quản lý Quyền

GET /files/:id/permissions FR-014

Lấy tất cả quyền cho tệp tin hoặc thư mục.

Phản hồi 200:

{
  "success": true,
  "data": {
    "permissions": [
      { "id": "perm-uuid-1", "user_id": "user-uuid-1", "permission": "VIEW" },
      { "id": "perm-uuid-2", "role": "HR", "permission": "DOWNLOAD" },
      { "id": "perm-uuid-3", "org_id": "org-uuid-1", "permission": "EDIT" }
    ]
  }
}

PUT /files/:id/permissions FR-014

Cập nhật quyền cho tệp tin hoặc thư mục (chỉ admin).

Yêu cầu:

{
  "permissions": [
    { "user_id": "user-uuid-1", "permission": "VIEW" },
    { "role": "HR", "permission": "DOWNLOAD" },
    { "org_id": "org-uuid-1", "permission": "EDIT" }
  ]
}

Phản hồi 200:

{
  "success": true,
  "message": "Quyền đã được cập nhật thành công"
}

4.13 Quản lý Lưu trữ

GET /files/storage-usage FR-016

Lấy thống kê sử dụng lưu trữ cho người dùng hoặc tổ chức hiện tại.

Phản hồi 200:

{
  "success": true,
  "data": {
    "user": { "total_size": 52428800, "file_count": 25 },
    "organization": { "total_size": 524288000, "file_count": 250 }
  }
}

GET /files/quotas FR-017

Lấy cấu hình hạn ngạch lưu trữ (chỉ admin).

Phản hồi 200:

{
  "success": true,
  "data": {
    "quotas": [
      { "user_id": "user-uuid-1", "max_total_size": 104857600, "max_file_count": 100 },
      { "org_id": "org-uuid-1", "max_total_size": 1073741824, "max_file_count": 1000 }
    ]
  }
}

PUT /files/quotas FR-017

Cập nhật giới hạn hạn ngạch lưu trữ (chỉ admin).

Yêu cầu:

{
  "user_id": "user-uuid-1",
  "max_total_size": 209715200,
  "max_file_count": 200
}

GET /files/policies FR-018

Lấy chính sách lưu trữ theo danh mục (chỉ admin).

Phản hồi 200:

{
  "success": true,
  "data": {
    "policies": [
      {
        "category": "RESUME",
        "allowed_mime_types": ["application/pdf", "application/msword"],
        "max_file_size": 10485760,
        "retention_days": null,
        "encryption_enabled": false
      }
    ]
  }
}

PUT /files/policies FR-018

Cập nhật chính sách lưu trữ (chỉ admin).

Yêu cầu:

{
  "category": "RESUME",
  "allowed_mime_types": ["application/pdf", "application/msword", "application/vnd.openxmlformats-officedocument.wordprocessingml.document"],
  "max_file_size": 10485760,
  "retention_days": 365,
  "encryption_enabled": true
}

5. Mã Lỗi