Viết Prompt cho Firestore (Next.js)

tasks                          ← công việc cần làm
  ├── {taskId}
  │   ├── title: string
  │   ├── description: string
  │   ├── status: "todo" | "in_progress" | "done" | "blocked"
  │   ├── priority: "low" | "medium" | "high" | "critical"
  │   ├── projectId: Reference → projects/{projectId}
  │   ├── assignee: Reference → users/{userId}
  │   ├── reporter: Reference → users/{userId}
  │   ├── tags: string[]
  │   ├── watchers: string[]
  │   ├── dependencies: string[]
  │   ├── isCompleted: boolean
  │   ├── isBlocked: boolean
  │   ├── isPinned: boolean
  │   ├── hasAttachments: boolean
  │   ├── estimatedHours: number
  │   ├── actualHours: number
  │   ├── percentComplete: number
  │   ├── storyPoints: number
  │   ├── dueDate: Timestamp
  │   ├── completedAt: Timestamp | null
  │   ├── createdAt: Timestamp
  │   └── updatedAt: Timestamp
  │
  └── {taskId}/comments        ← subcollection bình luận của task
      └── {commentId}
          ├── content: string
          ├── author: Reference → users/{userId}
          └── createdAt: Timestamp

projects                       ← dự án
  └── {projectId}
      ├── name: string
      ├── description: string
      ├── status: "active" | "archived" | "completed"
      ├── teamSize: number
      ├── createdAt: Timestamp
      └── updatedAt: Timestamp

users                          ← thành viên team
  └── {userId}
      ├── name: string
      ├── email: string
      ├── role: "admin" | "manager" | "developer" | "designer"
      ├── isActive: boolean
      ├── skills: string[]
      ├── createdAt: Timestamp
      └── updatedAt: Timestamp

# Các giá trị enum cho phép
task:
  status:   todo | in_progress | done | blocked
  priority: low | medium | high | critical

project:
  status: active | archived | completed

user:
  role: admin | manager | developer | designer

# Task — fields đầy đủ
task:
  id: text (tự sinh)
  title: text (bắt buộc)
  description: text (tùy chọn)
  status: text — todo | in_progress | done | blocked
  priority: text — low | medium | high | critical
  projectId: reference → projects/{id}
  assignee: reference → users/{id} (tùy chọn)
  reporter: reference → users/{id} (bắt buộc)
  tags: mảng văn bản
  watchers: mảng userId
  dependencies: mảng taskId
  isCompleted: boolean
  isBlocked: boolean
  isPinned: boolean
  hasAttachments: boolean
  estimatedHours: số
  actualHours: số
  percentComplete: số (0–100)
  storyPoints: số
  dueDate: timestamp (tùy chọn)
  completedAt: timestamp | null
  createdAt: timestamp
  updatedAt: timestamp

# Comment — subcollection của task
comment:
  id: text (tự sinh)
  content: text
  author: reference → users/{id}
  createdAt: timestamp

Thêm function để tạo task mới trong Firestore:
- File: lib/firebase/tasks.ts
- Collection: "tasks"
- Fields bắt buộc: title, projectId, reporter
- Fields tùy chọn: description, assignee, dueDate, priority, tags
- Giá trị mặc định:
  - status: "todo"
  - priority: "medium"
  - isCompleted: false, isBlocked: false, isPinned: false
  - estimatedHours: 0, actualHours: 0, percentComplete: 0
  - createdAt: server timestamp, updatedAt: server timestamp
- Validation:
  - title: bắt buộc, 3–200 ký tự
  - projectId: phải tồn tại trong collection "projects"
  - dueDate: nếu có, phải là ngày trong tương lai
  - priority: chỉ nhận "low" | "medium" | "high" | "critical"
- Return: { id: string, task: Task }
- Error handling: ValidationError cho input sai, ProjectNotFoundError cho projectId sai
- Không tạo API route, chỉ utility function

- Tên collection và subcollection (nếu có)
- Fields bắt buộc và tùy chọn
- Giá trị mặc định (nhất là với enum như status, priority)
- Quy tắc validation
- Các trường hợp lỗi và custom error types
- Kiểu dữ liệu trả về (return type)

Tạo function để lấy task theo ID:
- Collection: "tasks", Document ID: taskId
- Return: Task object với tất cả fields hoặc null nếu không tìm thấy
- Xử lý Firestore errors một cách thuần tuý
- Bao gồm TypeScript Task interface

Thêm function getTasksByProject:
- Collection: "tasks"
- Query: where("projectId", "==", projectId)
- Chỉ lấy tasks chưa bị archive: where("status", "!=", "blocked")
- Order by: dueDate ascending, priority descending
- Return: Task[]
- Bao gồm error handling cho network failures

Tạo function getTaskComments:
- Subcollection: tasks/{taskId}/comments
- Order by: createdAt ascending
- Return: Comment[]
- Bao gồm Comment interface với fields: id, content, author, createdAt

Tạo function updateTask:
- Nhận taskId và partial task data
- Chỉ cập nhật các fields được cung cấp (partial update, không xóa fields khác)
- Fields cho phép cập nhật: title, description, status, priority, assignee,
  dueDate, tags, estimatedHours, actualHours, percentComplete, isBlocked, isPinned
- Ngăn chặn cập nhật: createdAt, reporter, projectId
- Tự động:
  - Set updatedAt = server timestamp
  - Nếu status chuyển sang "done", set isCompleted = true và completedAt = server timestamp
  - Nếu percentComplete = 100, tự động set status = "done"
- Validate status: chỉ nhận "todo" | "in_progress" | "done" | "blocked"
- Xử lý lỗi document not found

- Liệt kê rõ fields nào được phép cập nhật
- Nêu rõ các fields bị khóa (không cho cập nhật)
- Mô tả lógic tự động (auto-set) nếu có
- Chỉ rõ enum field chỉ nhận những giá trị nào

Thêm function deleteTask:
- Soft delete: set status thành "archived" (không xoá khỏi Firestore)
- Ghi lại: updatedAt = server timestamp
- Không xoá subcollection comments (giữ lại lịch sử)
- Return: true nếu thành công, false nếu taskId không tồn tại
- Xử lý not found một cách đuồ đặt (không throw lỗi)

- Soft delete hay hard delete?
- Nếu soft delete: dùng field nào (đánh dấu `isDeleted` hay đổi `status`)?
- Có xóa subcollection liên quan không?
- Kiểu dữ liệu trả về khi document không tồn tại

Tạo function getTasksByStatus:
- Collection: "tasks"
- Filter: where("status", "==", status)
- status chỉ nhận: "todo" | "in_progress" | "done" | "blocked"
- Return: Task[]
- Order by: dueDate ascending
- Hỗ trợ phân trang (limit parameter, mặc định 20)

- Chỉ rõ enum field nhận giá trị nào
- Luôn kèm order by để kết quả nhất quán
- Thêm limit để tránh lấy quá nhiều dữ liệu

Thêm function searchTasks với nhiều điều kiện lọc:
- Collection: "tasks"
- Bộ lọc (tất cả tùy chọn):
  - projectId: exact match
  - assignee: exact match (userId)
  - status: exact match ("todo" | "in_progress" | "done" | "blocked")
  - priority: exact match ("low" | "medium" | "high" | "critical")
  - isBlocked: boolean
  - dueBefore: Timestamp range (dueDate <= dueBefore)
  - dueAfter: Timestamp range (dueDate >= dueAfter)
  - tags: array-contains
- Order by: dueDate ascending, updatedAt descending
- Return: Task[]
- Nếu không có bộ lọc, return tất cả tasks không phải "archived"

- Liệt kê rõ các field lọc cùng nhau (Firestore cần composite index)
- Chỉ rõ kiểu so sánh: exact match / range / array-contains
- Nêu cách xử lý khi không có filter nào

Cập nhật function searchTasks để hỗ trợ cursor-based pagination:
- Parameters: filters (như trên), pageSize (mặc định 20), lastDoc (DocumentSnapshot | null)
- Lần gọi đầu tiên: lastDoc = null (lấy trang đầu)
- Các trang tiếp theo: truyền lastDoc từ kết quả trước (dùng startAfter)
- Return: { tasks: Task[], lastDoc: DocumentSnapshot | null, hasMore: boolean }
- Order by: dueDate ascending

Cursor-based (khuyên dùng):
- Dùng DocumentSnapshot làm con trỏ
- Hoạt động tốt với dữ liệu thay đổi liên tục
- Không bị lệch khi thêm/xóa bản ghi mới

Offset-based (không nên dùng):
- Dùng limit/offset
- Dễ bị lệch trang khi có bản ghi mới

Thêm function searchTasksByTitle:
- Tìm kiếm query string trên field "title"
- Thực hiện dùng where("title", ">=", query) và where("title", "<=", query + "\uf8ff")
- Kết hợp client-side filter để loại kết quả không khớp
- Xử lý search string rỗng (return empty array)
- Return: Task[] với limit 30 kết quả đầu

Firestore không hỗ trợ full-text search:

- Client-side filtering → phù hợp dataset nhỏ (<500 bản ghi)
- Algolia / Typesense → phù hợp dataset lớn, cần search nâng cao
- Firebase Search Extension → tích hợp sẵn với Firestore

Tạo hook hooks/useTasks.ts:
- Export hook: useTasks(filters: TaskFilters)
- State: { tasks: Task[], loading: boolean, error: Error | null }
- Lấy dữ liệu từ API endpoint /api/tasks/search với filters làm query params
- Gọi lại khi filters thay đổi (useEffect với filters làm dependency)
- Return: { tasks, loading, error, refetch }
- Xử lý cleanup khi component unmount

Tạo hook hooks/useTaskMutation.ts:
- Export hook: useTaskMutation()
- Các hàm:
  - createTask(data: CreateTaskInput): Promise<Task>
  - updateTask(taskId: string, data: Partial<Task>): Promise<Task>
  - deleteTask(taskId: string): Promise<void>
- State: { loading: boolean, error: Error | null }
- Gọi API endpoints tương ứng
- Tự động reset error sau 5 giây
- Return: { createTask, updateTask, deleteTask, loading, error }

# Kiểu enum (giá trị cố định)
task:
  status:   todo | in_progress | done | blocked
  priority: low | medium | high | critical

project:
  status: active | archived | completed

user:
  role: admin | manager | developer | designer

# Mô tả cấu trúc task đầy đủ
task:
  id: text
  title: text (bắt buộc)
  description: text (tùy chọn)
  status: todo | in_progress | done | blocked
  priority: low | medium | high | critical
  projectId: id của project
  assignee: id của user (tùy chọn)
  reporter: id của user (bắt buộc)
  tags: danh sách text
  isCompleted: true | false
  isBlocked: true | false
  estimatedHours: số
  actualHours: số
  percentComplete: số (0–100)
  dueDate: timestamp
  completedAt: timestamp hoặc null
  createdAt: timestamp
  updatedAt: timestamp

# Sau đó yêu cầu thực hiện:
# createTask, getTask, updateTask, deleteTask, getTaskComments, addComment

Luôn định nghĩa interface trước khi yêu cầu viết các function CRUD.
Giúp Claude Code tạo code đúng kiểu dữ liệu và không cần đoán mò.

Cho function getTaskWithDetails:
- Throw các lỗi cụ thể:
  - TaskNotFoundError khi taskId không tồn tại
  - ValidationError cho taskId format không hợp lệ
  - FirestoreError cho lỗi network/permission
- Bao gồm thông báo lỗi kèm ngữ cảnh (ví dụ: taskId nào gây lỗi)

- Dùng custom error class thay vì throw Error chung
- Kèm thông tin ngữ cảnh trong error message
- Phân biệt rõ lỗi do input sai và lỗi network

Thêm validation cho createTask:
- title: bắt buộc, 3–200 ký tự
- projectId: bắt buộc, phải tồn tại trong collection "projects"
- dueDate: nếu có, phải là ngày trong tương lai
- priority: phải là "low" | "medium" | "high" | "critical"
- tags: mỗi tag tối đa 30 ký tự, tối đa 10 tags
- Return: { success: true, id: string } hoặc { success: false, errors: string[] }

- Liệt kê tất cả quy tắc và giải hạn
- Mô tả cách xử lý validation lỗi (throw hay return errors[])
- Enum field phải liệt kê đủ giá trị hợp lệ

Tạo function completeTask sử dụng Firestore transaction:
- Cập nhật task document:
  - status: "done"
  - isCompleted: true
  - completedAt: server timestamp
  - percentComplete: 100
- Cập nhật user stats trong collection "users":
  - Tăng completedTasksCount lên 1
  - Cập nhật lastActivityAt: server timestamp
- Dùng Firestore transaction để đảm bảo atomicity (cả 2 updates hoặc không cái nào)
- Return: task ID nếu thành công
- Tự động rollback nếu bất kỳ bước nào thất bại
- Throw TaskNotFoundError nếu taskId không hợp lệ

- Liệt kê rõ tất cả các bước trong transaction
- Nêu rõ điều kiện rollback
- Dùng transaction khi cần cập nhật đồng thời nhiều document

Thêm các Firestore function
Tạo CRUD cho tasks

Tạo function createTask cho collection "tasks" với:
- Kiểm tra title 3–200 ký tự
- Xác minh projectId tồn tại trong collection "projects"
- Giá trị mặc định: status = "todo", priority = "medium"

Tạo một hàm tìm kiếm

Tạo function tìm kiếm task theo:
- Tiêu đề (khớp một phần)
- Trạng thái: chỉ nhận "todo" | "in_progress" | "done" | "blocked"
- Người được giao (userId — đặt chính xác)
- Khoảng thời gian đến hạn (dueBefore, dueAfter)
Trả về kết quả có phân trang theo dueDate ascending

Xây dựng toàn bộ hệ thống quản lý công việc

Tạo function getOverdueTasks:
- Lọc tasks có dueDate < hiện tại VÀ status != "done"
- Sắp xếp theo dueDate tăng dần (quá hạn lâu nhất lên đầu)
- Hỗ trợ phân trang kiểu cursor-based
- Return: { tasks: Task[], lastDoc, hasMore }