Tổng Quan Dự Án: VinhPhat ERP
1. Dự án là gì?
Hệ thống quản lý vận hành nội bộ cho doanh nghiệp dệt may (B2B), kiến trúc mobile-first, số hóa toàn bộ quy trình: nhập sợi → dệt vải → nhuộm → tồn kho theo lô → đơn hàng → xuất hàng → thanh toán.
Dự án sử dụng hệ thống AI Agent với bộ quy tắc bắt buộc:
- AGENT.md — quy tắc vận hành AI toàn cục.
- .erp-rules.md — "Hiến pháp" 22 quy tắc kỹ thuật (bảo vệ DB, cấm sửa nghiệp vụ nhạy cảm).
- AI_WORKFLOW.md — quy trình 5 bước có trạm gác (Approval Gates).
- AI_CHECKLIST.md — biên bản nghiệm thu.
Nội dung cần đặc biệt lưu ý: Hệ thống AI Agent vận hành dựa trên bộ quy tắc nghiêm ngặt, trong đó ".erp-rules.md" đóng vai trò "Hiến pháp" bảo vệ Database và cấm tự ý sửa đổi các nghiệp vụ nhạy cảm.
2. Tech Stack
| Layer | Công nghệ |
|---|---|
| Frontend | React 18 + TypeScript + Vite 8 (SPA, mobile-first) |
| State/Query | TanStack Query + React Hook Form + Zod |
| UI | Tailwind CSS 4, Radix UI, shadcn-style (cva, tailwind-merge), Framer Motion, Recharts |
| Backend | Hono (Node.js) + Drizzle ORM — tại server/ |
| Database | Supabase (PostgreSQL) — Auth, RLS, Realtime — 351 migrations |
| AI/Phụ trợ | Anthropic SDK (AI audit), Python service (server/python/ cho vision/extraction), web-push (notifications) |
| Testing | Vitest (unit) + Playwright (e2e + visual regression) + fast-check |
3. Cấu trúc thư mục
VinhPhatERP_v3/ ├── src/ # Frontend (~1.594 file TS/TSX) │ ├── app/ # App shell: layouts, providers, router, registry │ ├── features/ # ⭐ 40+ module nghiệp vụ (core của dự án) │ │ └── orders/ # Pattern tiêu biểu: │ │ ├── components/ # UI components │ │ ├── hooks/ # Custom hooks │ │ ├── __tests__/ # Tests │ │ ├── orders.module.ts / constants / utils │ │ └── OrderList/OrderForm/OrderDetail.tsx │ ├── shared/ # Component/hook/util dùng chung │ ├── services/ # Adapter Supabase, offline queue (db-guard) │ └── ... ├── server/ # Hono API server │ └── src/routes/ # customers, orders, suppliers, yarn-receipts, │ # notifications, webhooks │ └── python/ # Python service (vision, extraction) ├── supabase/migrations/ # SQL migrations (351 files — không sửa file đã push) ├── docs/ # Tài liệu: ARCHITECTURE, module-map, coding-rules... ├── e2e/ # Playwright tests └── scripts/ # Tool hỗ trợ (audit, check, migration...)
4. 40+ Feature Modules — 5 nhóm nghiệp vụ chính
| Nhóm | Modules |
|---|---|
| Kinh doanh (CRM) | customers, quotations, contracts, orders, order-kanban, customer-portal |
| Mua hàng | suppliers, procurement, yarn-catalog, yarn-receipts, weaving-invoices |
| Sản xuất | bom, work-orders, looms (máy dệt), raw-fabric, dyeing-orders (nhuộm), finished-fabric, operations, color-catalog, fabric-catalog |
| Kho & Giao nhận | inventory, shipments, shipping-rates, driver-portal |
| Tài chính | payments, costing, recurring-transactions |
| Hệ thống | auth, employees, settings, reports, dashboard, notifications, chat, media, supplier-portal |
5. Luồng dữ liệu nghiệp vụ chính
Luồng dữ liệu được thiết kế theo docs/module-map.md:
Khách hàng → Báo giá → Hợp đồng → Đơn hàng
↓
Lệnh Sản xuất (gán Máy dệt) → Kho Vải Mộc → Lệnh Nhuộm → Vải Thành Phẩm
↓
Xuất kho/Giao hàng → (trigger tự trừ tồn kho khi "shipped")
↓
Thu/Chi & Công Nợ (khi "delivered" đủ số lượng → Order tự chuyển "completed")
Các trigger tự động quan trọng:
- work_orders = completed → tự tạo cuộn mộc thành phẩm.
- shipments = shipped → tự trừ tồn kho.
- shipments = delivered (đủ SL) → tự hoàn thành đơn hàng.
- Phiếu thu xác nhận → tự giảm công nợ khách.
6. Quy ước & Lệnh quan trọng
- Path alias: @ → ./src
- Lệnh dev: npm run dev (frontend) · npm run dev:all (cả server)
- Kiểm tra: npm run check = lint + lint:css + typecheck
- DB: db:new → db:push → db:reload → db:status
- Kiểm tra sau thay đổi:
- Frontend: test → typecheck → lint → build
- Server: typecheck:server → build:server
- Guard: Insert/Upsert phải qua src/lib/db-guard.ts
Cảnh báo rủi ro: Nghiêm cấm sửa file migration đã push, tự chạy db:push mà không xác nhận, và tự ý đổi schema/logic nghiệp vụ. Mọi thao tác Insert/Upsert bắt buộc phải đi qua db-guard.ts để đảm bảo an toàn dữ liệu.
Tags:
VinhPhatERP