Tổng quan
Một dự án phần mềm được tổ chức như một chiếc tủ hồ sơ: mỗi ngăn chứa đúng loại tài liệu của nó. Khi cần tìm hay sửa bất cứ thứ gì, bạn biết ngay phải mở ngăn nào. ProjectOS chia toàn bộ source code thành hai nhóm lớn:Dùng chung (Shared)
Các thành phần được dùng ở nhiều nơi trong dự án — ví dụ: thanh điều hướng, nút bấm, hàm định dạng ngày tháng.
Theo chức năng (Modules)
Mỗi tính năng lớn có thư mục riêng — ví dụ: Tasks, Risks, Team, Budget. Chúng hoạt động độc lập với nhau.
Sơ đồ thư mục tổng quan
Hãy hình dung cấu trúc dự án như một toà nhà văn phòng:Tầng 1 — Giao diện người dùng (src/app/)
Chứa tất cả các trang web mà người dùng nhìn thấy và tương tác.
Mỗi tính năng (Tasks, Risks, Team…) có một thư mục trang riêng.
Tầng 2 — Kho dùng chung (src/components/, src/hooks/, src/lib/...)
Chứa các thành phần tái sử dụng — nút bấm, ô nhập liệu, biểu đồ, hàm tiện ích.
Bất kỳ tính năng nào cũng có thể dùng chúng.
Tầng 3 — Kho theo tính năng (src/modules/)
Mỗi tính năng lớn có “kho riêng” chứa các thành phần, logic và dữ liệu chỉ dùng cho tính năng đó.
Các thư mục dùng chung
Giao diện (components/)
Thư mục này chứa các “viên gạch” xây dựng nên giao diện, được chia thành 4 nhóm:| Nhóm | Nội dung | Ví dụ |
|---|---|---|
| common/ | Khung chính của ứng dụng | Thanh menu bên, header, footer |
| ui/ | Các ô, nút, hộp thoại cơ bản | Nút bấm, ô nhập liệu, bảng dữ liệu |
| data-display/ | Hiển thị số liệu và trạng thái | Thẻ thống kê, thanh tiến độ, nhãn trạng thái |
| forms/ | Các ô nhập liệu nâng cao | Chọn ngày, dropdown lựa chọn |
Thư viện tiện ích (lib/)
Chứa các hàm dùng đi dùng lại nhiều lần, ví dụ:- Chuyển đổi định dạng ngày tháng
- Hiển thị số tiền đúng định dạng
- Xử lý thông báo lỗi từ Firebase
- Kiểm tra dữ liệu hợp lệ trước khi lưu
Hàm nhỏ (utils/)
Tương tựlib/ nhưng dành cho các hàm đơn giản hơn:
- Ghép class CSS
- Định dạng văn bản
- Các giá trị mặc định (phân trang, giới hạn hiển thị…)
Dữ liệu thời gian thực (hooks/)
Đây là nơi chứa các “cầu nối” giữa giao diện và Firebase. Khi dữ liệu trên Firebase thay đổi, giao diện tự động cập nhật mà không cần tải lại trang.Hãy hình dung hooks như các màn hình hiển thị số liệu trực tiếp — số liệu thay đổi ở nguồn thì màn hình cập nhật ngay lập tức.
Kiểu dữ liệu (types/)
Định nghĩa “khuôn mẫu” của từng loại dữ liệu. Ví dụ, một Task phải có: tiêu đề, trạng thái, mức ưu tiên, người phụ trách, ngày hết hạn. TypeScript sẽ báo lỗi ngay nếu code thiếu hoặc sai kiểu.Giá trị cố định (constants/)
Chứa các danh sách giá trị không đổi trong suốt dự án:- Danh sách trạng thái:
todo,in_progress,done,blocked - Danh sách mức ưu tiên:
low,medium,high,critical - Danh sách vai trò:
admin,manager,developer
Cấu hình (config/)
Chứa các thông số cài đặt cho ứng dụng — tên site, đường dẫn API, các tính năng bật/tắt.Các module theo tính năng
Mỗi tính năng lớn có cấu trúc bên trong giống nhau:Tasks — Quản lý công việc
Tasks — Quản lý công việc
Tất cả màn hình và logic liên quan đến việc tạo, gán, theo dõi, và cập nhật công việc.Các trang bao gồm:
- Danh sách tất cả tasks
- Chi tiết từng task
- Tạo mới / chỉnh sửa task
- Thẻ hiển thị task (TaskCard)
- Danh sách tasks dạng bảng hoặc Kanban (TaskList)
- Form điền thông tin task (TaskForm)
- Bộ lọc và tìm kiếm (TaskFilters)
Risks — Quản lý rủi ro
Risks — Quản lý rủi ro
Theo dõi các rủi ro tiềm ẩn trong dự án và kế hoạch xử lý.Các trang bao gồm:
- Danh sách rủi ro (Risk Register)
- Chi tiết và kế hoạch giảm thiểu từng rủi ro
- Ma trận xác suất vs mức độ ảnh hưởng (Risk Heatmap)
Team — Quản lý nhân sự
Team — Quản lý nhân sự
Danh sách thành viên, vai trò, và khối lượng công việc.Các trang bao gồm:
- Danh sách thành viên team
- Trang cá nhân từng người
- Biểu đồ khối lượng công việc (Workload)
- Quản lý vai trò và quyền hạn
Budget — Quản lý ngân sách
Budget — Quản lý ngân sách
Theo dõi chi phí thực tế so với ngân sách kế hoạch.Các trang bao gồm:
- Tổng quan ngân sách
- Danh sách chi phí đã phát sinh
- Báo cáo chi tiêu
Documents, Meetings, Reports
Documents, Meetings, Reports
Ba module bổ sung với cấu trúc tương tự — mỗi module đều có trang danh sách, trang chi tiết, và các thành phần hiển thị riêng.
Kết nối Firebase
Vì ProjectOS lưu toàn bộ dữ liệu trên Google Firebase, có một số thư mục đặc biệt:| Thư mục | Chức năng |
|---|---|
| firebase/ | Cài đặt kết nối tới Firebase (giống như nhập địa chỉ và mật khẩu văn phòng) |
| context/ | Lưu thông tin người dùng đang đăng nhập để mọi trang đều dùng được |
| store/ | Lưu trạng thái giao diện — ví dụ: menu đang mở hay đóng |
| providers/ | “Bao bọc” toàn bộ ứng dụng để Firebase và context hoạt động đúng |
| services/ | Các hàm thao tác dữ liệu: thêm, sửa, xóa, lắng nghe thay đổi từ Firestore |
Cấu trúc dữ liệu Firebase của ProjectOS được mô tả chi tiết trong trang Firestore và tổ chức Data.
Bảo mật dữ liệu
Firebase Security Rules là “bộ quy tắc bảo vệ” dữ liệu — quy định ai được phép đọc và ghi dữ liệu nào.| Loại dữ liệu | Ai được đọc | Ai được sửa/xóa |
|---|---|---|
| Hồ sơ cá nhân (users/) | Chính chủ | Chính chủ |
| Công việc (tasks/) | Thành viên dự án | Người tạo |
| Rủi ro (risks/) | Người đăng nhập | Người tạo |
| Dự án (projects/) | Thành viên được mời | Admin dự án |
| Thông báo | Chính chủ | Chính chủ |
Quy tắc đặt tên
Để cả team hiểu ngay file làm gì chỉ nhìn vào tên:| Loại | Quy tắc | Ví dụ |
|---|---|---|
| Giao diện (Component) | Chữ hoa đầu mỗi từ | TaskCard, UserProfile |
| Hooks (cầu nối dữ liệu) | Bắt đầu bằng use | useTasks, useAuth |
| Hàm tiện ích | Chữ thường, liền | formatDate, calculateDays |
| Kiểu dữ liệu | Chữ hoa đầu mỗi từ | Task, User, Project |
| Hằng số | Chữ HOA, gạch dưới | MAX_TASKS, DEFAULT_PAGE_SIZE |
| File service | Thêm .service.ts | tasks.service.ts |
Quy tắc quan trọng
Checklist khởi động dự án
Tạo cấu trúc thư mục
Tạo đủ các thư mục theo sơ đồ tổng quan:
app/, components/, modules/, firebase/, services/…