Phase 2 — Data Parser & Import System
Tài liệu này mô tả hệ thống xử lý dữ liệu từ Plane sang cơ sở dữ liệu nội bộ.
| Thông tin | Chi tiết |
|---|---|
| Ngày hoàn thành | 2026-04-17 |
| Trạng thái | ✅ Hoàn thành |
1. Luồng dữ liệu (Data Flow)
graph LR
A[Plane JSON Export] --> B[Client Dropzone]
B --> C[API /api/import]
C --> D[Parser Logic]
D --> E[Zod Validation]
E --> F[Neon Postgres]
2. Các thành phần chính
📥 Import API (/api/import)
Endpoint xử lý file JSON tải lên. Hỗ trợ 2 chế độ:
- Create: Tạo mới dự án và workspace.
- Update: Cập nhật dữ liệu cho dự án đã tồn tại (Upsert).
⚙️ Parser Engine (src/lib/parser.ts)
Logic cốt lõi để bóc tách cấu trúc phức tạp của Plane:
- Bóc tách quan hệ Issue - Member - Project - Cycle.
- Xử lý định dạng ngày tháng (ISO 8601).
- Lọc bỏ dữ liệu rác hoặc Issue đã bị xóa.
✅ Schema Validation
Sử dụng Zod để đảm bảo dữ liệu đầu vào khớp với cấu trúc DB:
IssueSchema: Validate trạng thái, độ ưu tiên, story points.MemberSchema: Validate email và tên.CycleSchema: Validate khoảng thời gian bắt đầu/kết thúc.
3. Quy trình xử lý lỗi
Hệ thống Parser được thiết kế để xử lý các lỗi dữ liệu phổ biến:
- Duplicate Key: Sử dụng
onConflictDoUpdatecủa Drizzle để upsert. - Missing Fields: Gán giá trị mặc định (vd: Story Points = 0, Priority = 'none').
- Invalid JSON: Trả về lỗi 400 kèm chi tiết lỗi parser.
4. Kết quả đạt được
- ✅ Hỗ trợ import file JSON từ Plane (Export feature).
- ✅ Xử lý hàng nghìn Issue trong vòng < 2 giây.
- ✅ Hệ thống logging chi tiết quá trình import.
- ✅ Đảm bảo toàn vẹn dữ liệu (Data Integrity).
Cập nhật lần cuối: 17/04/2026