Yếu tố thành công
| Tư duy quan trọng | Điều kiện cần: | Điều kiện đủ |
|---|---|---|
| thiếu --jsx | Có thời gian |
✅ Kiên nhẫn |
| thiếu --jsx | luôn mở termile npm run dev |
✅ Localhost phải chuẩn |
Quy trình trước khi commit
| Tư duy quan trọng | Bạn không cần: | Bạn cần: |
|---|---|---|
| code đúng ngay từ đầu |
code sai → hệ thống báo ngay → sửa ngay |
Quy trình trước khi commit
| Tình huống | Bạn không cần: | Ý nghĩa |
|---|---|---|
| Found 18 errors in 3 files. husky - pre-commit script failed (code 1) | TypeScript phát hiện lỗi → Husky chặn commit |
BẢO VỆ bạn khỏi commit code lỗi |
Quy trình trước khi commit
| stt | command | Ý nghĩa |
|---|---|---|
| Dùng trước khi commit | npm run typecheck |
BẢO VỆ bạn khỏi commit code lỗi |
| Dùng khi đang code | npx tsc --noEmit |
→ check nhanh, chỉ báo lỗi chứ không in lệnh |
| Dùng khi trước lệnh commit | git status |
→ Xem lại danh sách file sẽ commit để đảm bảo không có file "lạ" nào lọt vào: |
| Dùng khi trước lệnh commit | npm run lint |
→ kiểm tra chất lượng code (linter) |
| Dùng khi trước lệnh commit | npx eslint . --fix |
→ tự động sửa các lỗi format đơn giản |
| Dùng khi trước lệnh commit | npm run lint -- --fix |
→ tự động sửa các lỗi format đơn giản |
| Dùng khi trước lệnh commit | npm run build |
→ tự động sửa các lỗi format đơn giản |
Danh mục prompt
| 1 | 2 | 3/ | |
|---|---|---|---|
| Chia mini-task thật nhỏ, cẩn thận, an toàn. Sau mỗi lần modified cần chạy verify npm typecheck, npm run lint. Rule: không được ép kiểu as any, tuyệt đối không gây ra lỗi any, không được duplicate, gây lỗi duplicate, không được dùng emoji, không dùng relative import giữa các feature. Output: đảm bảo hiển thị đúng chuẩn "Premium" và responsive linh hoạt, không được phá vỡ Layout chung của hệ thống, có báo cáo. |
Có thời gian |
✅ Kiên nhẫn | |
| Audit | luôn mở termile npm run dev |
✅ Localhost phải chuẩn |
Code
| Tư duy quan trọng | Điều kiện cần: | Điều kiện đủ |
|---|---|---|
| Tab switcher | Tính năng thông minh (Smart Features) |
Tiêu chuẩn "Interactive Roll Grid" |
| Combobox | luôn mở termile npm run dev |
✅ Localhost phải chuẩn |
| Component | Mô tả |
|---|---|
| Icon | Icon wrapper (Lucide) |
| AdaptiveSheet | Bottom sheet / drawer adaptive |
| Badge | Label badge với variants |
| Combobox | Dropdown có search |
| ConfirmProvider / useConfirm | Dialog xác nhận (context-based) |
| DataTablePremium | Bảng dữ liệu nâng cao |
| DraftBanner | Banner thông báo trạng thái draft |
| EmptyState | UI khi không có dữ liệu |
| ErrorBoundary | Bắt lỗi React |
| FeatureScaffoldPage | Layout scaffold cho feature page |
| KpiCard | Card hiển thị chỉ số KPI |
| PagePlaceholder | Placeholder khi page chưa có nội dung |
| Pagination | Phân trang |
| Portal | Render ngoài DOM tree |
| QuickSupplierForm | Form tạo nhanh nhà cung cấp |
| SaveStatus | Hiển thị trạng thái lưu (auto-save) |
| TableSkeleton | Skeleton loading cho bảng |
| TabSwitcher | Tab switcher dùng chung |
Cấu trúc Shared Module trong Vĩnh Phát ERP
Dựa trên cấu trúc kiến trúc của dự án (Level 7 Architecture Extension) và việc kiểm tra thư mục gốc, codebase này không thiết kế theo mô hình monorepo thuần túy với thư mục packages/ chứa các npm packages riêng biệt. Thay vào đó, các "shared packages" (các module dùng chung) được phân chia theo Layer Architecture (kiến trúc phân tầng) nghiêm ngặt với sự hỗ trợ của eslint-plugin-boundaries để đảm bảo không vi phạm cross-feature import.
Dưới đây là danh sách chi tiết các "shared packages/modules" (Kho lưu trữ Logic và UI) được dùng chung cho toàn bộ các tính năng:
1. 🎨 UI Components Dùng Chung (src/shared/components/)
Gồm các thành phần giao diện tuân thủ chặt chẽ design guideline "Premium" và "Mobile-first" của dự án:
- Layout & Bảng dữ liệu:
DataTablePremium.tsx,KpiCardPremium.tsx,KpiCard.tsx,TabSwitcher.tsx,FeatureScaffoldPage.tsx - Forms & Modal:
AdaptiveSheet.tsx: Bottom sheet bắt buộc dành cho giao diện di động (thay thế Modal ở chính giữa).Combobox.tsx: Thành phần dropdown có tích hợp tìm kiếm (thay thế cho native select).ConfirmDialog.tsx: Dialog xác nhận cho các thao tác nguy hiểm.SearchInput.tsx,QuickSupplierForm.tsx
- Tương tác & Trạng thái:
Badge.tsx,DraftBanner.tsx,EmptyState.tsx,SaveStatus.tsx,TableSkeleton.tsx,PagePlaceholder.tsx - Thành phần khác:
AddButton.tsx,Icon.tsx(Wrapper cho hệ thống icon chuẩn Lucide-React),ErrorBoundary.tsx,Pagination.tsx,Portal.tsx,ViewToggle.tsx - Thư mục con:
roll-grid/(Thành phần quản lý lưới chọn mã cuộn vải)
2. 🧠 Logic & Hooks Dùng Chung (src/shared/hooks/)
Đóng gói các logic React (UI behavior, fetching dropdown list) để tránh việc viết lặp lại mã ở nhiều module:
- Tương tác & UX:
useKeyboardNavigation.ts,useEditableTableKeyboard.ts,useMediaQuery.ts,useTheme.ts,useStepper.ts,useConfirm.ts - Biểu mẫu & Lưu trữ (Forms):
useAutoSave.ts,useFormOptions.ts - Lấy danh sách chọn (Dropdown Options):
useActiveCustomers.ts,useColorOptions.ts,useEmployeeOptions.ts,useFabricCatalogOptions.ts,useShippingRateOptions.ts,useYarnCatalogOptions.ts - App Context & Settings:
useTenant.ts,useAuth.ts,useCompanySettings.ts
3. 🛠️ Utilities Dùng Chung (src/shared/utils/)
Các hàm tiện ích thuần tuý, thực hiện một chức năng cụ thể và không dính dáng đến vòng đời của React:
format.ts: Các tiện ích định dạng hiển thị cho ngày tháng (Date), tiền tệ (Currency), số lượng.export.ts: Các helper phục vụ việc xuất dữ liệu của hệ thống định dạng File Excel (qua thư viện ExcelJS), PDF, v.v.
4. 🗃️ Global Contexts (src/shared/context/)
Khu vực đảm nhiệm việc quản lý state phân cấp toàn cục (Global State):
TenantContext.tsx&tenant-context.ts: Cung cấp thông tin nhánh (Branch), hệ thống thuê bao hoặc cấu hình tổng đài tùy thuộc vào đối tượng Tenant hiện tại của người dùng.
5. 🧱 Lõi thư viện chuẩn (src/shared/lib/)
FeatureRegistry.ts: File cốt lõi định hình kiến trúc ứng dụng. Chịu trách nhiệm khởi tạo và đăng ký các Plug-in Tính năng (Feature modules) vào ứng dụng chính, tuân theo quy tắc hoàn hảo của Level 7 Plugin System Architecture.
6. 📄 Nguồn Chân Lý Dữ Liệu (src/shared/index.ts)
Là cánh cổng Public API định nghĩa toàn bộ mô hình dữ liệu chính xác nhất của hệ thống, giúp Backend và Frontend thống nhất một ngôn ngữ:
- Chứa các Domain Models phản ánh (mirror) hệ cơ sở dữ liệu: Profile, Customer, Order, Supplier, OrderItem, Payment, Shipment...
- Chứa các cấu trúc Enums: UserRole, OrderStatus, ActiveStatus, ShipmentStatus, InventoryItemType...
- Chứa API Envelope chuẩn: ApiResponse, PaginatedResponse, ApiError. Lớp này được dùng song song cho cả ứng dụng Frontend (
src/) và Server Backend (server/).
💡 Quy tắc "Đóng gói" cốt lõi: Toàn bộ code chức năng mới trong ứng dụng phải sinh ra ở src/features/[featureName]/ và tuyệt đối không được gọi chéo sang nhau (cross-feature relative imports). Nếu một logic cần dùng lớn hơn 1 tính năng, nó bắt buộc phải được quy hoạch về cấu trúc src/shared/ này.
Phân Tích Business Flow (Luồng Nghiệp Vụ) Trong Hệ Thống Vĩnh Phát ERP
Dựa trên kiến trúc các Feature Modules hiện hành trong codebase kết hợp với các định nghĩa chuẩn (Schemas & Type Enums), dưới đây là bản giao đồ Business Flow (Luồng nghiệp vụ kinh doanh) của hệ thống. Đây là một mô hình ứng dụng ERP điển hình cho ngành dệt nhuộm / sản xuất vải, tập trung vào chuỗi cung ứng khép kín từ nguyên liệu đến thành phẩm.
1. Luồng Quản Lý Dữ Liệu Nền Tảng (Master Data)
Mọi quy trình đều bắt đầu từ việc thiết lập các nhóm dữ liệu gốc dùng chung cốt lõi:
- Danh mục sản phẩm: Quản lý
yarn-catalog(Danh mục Sợi) vàfabric-catalog(Danh mục Vải). - Đối tác: Quản lý
customers(Khách hàng tiêu thụ) vàsuppliers(Nhà cung cấp sợi, gia công nhuộm). - Nội bộ: Quản lý
employees(Nhân sự) kết hợpsettings/shipping-rates(Cấu hình giá vận chuyển chung).
2. Luồng Bán Hàng Và Quản Lý Đơn (Sales & Order Flow)
Khu vực tương tác trực tiếp với khách hàng được quản lý theo một đường ống khép kín (Sales Pipeline):
- Cấp Báo giá: Khởi tạo
quotations(Báo giá) gửi khách hàng chốt giá và duyệt mẫu. - Tạo Đơn Hàng: Chuyển từ Báo giá thành công hoặc lập trực tiếp qua module
orders(Quản lý Đơn hàng). Tại đây hệ thống bắt đầu bóc tách chi tiết về số lượng từng loại vải, mã màu sắc và đơn giá cam kết. - Theo dõi Tiến độ: Trạng thái đơn được biểu diễn trực quan qua
order-kanbanvà moduleorder-progress. Vòng đời đi qua: Draft ➡️ Confirmed ➡️ In Progress ➡️ Completed.
3. Luồng Quản Trị Yếu Tố Đầu Vào (Procurement)
Để có nguyên liệu đáp ứng sản xuất cho Đơn hàng, bộ phận kho hoặc thu mua tiến hành:
- Nhập Sợi nguyên liệu: Sử dụng module
yarn-receipts(Phiếu nhập sợi) từ Nhà cung cấp. Tại bước này, khối lượng sợi vật lý được cập nhật tăng vào Tổng Tồn Kho (inventory).
4. Luồng Sản Xuất: Dệt & Nhuộm (Manufacturing/Production)
Đây là quy trình tạo ra chuỗi giá trị phức tạp nhất, được quản lý qua nhiều vòng vi tinh chỉnh (Warping ➡️ Weaving ➡️ Greige Check ➡️ Dyeing):
- Định mức vật tư (BOM): Khai báo
bom(Bill of Materials) để hệ thống tự tính: Dệt 1.000m vải A sẽ tiêu hao bao nhiêu tấn sợi mã B tương ứng. - Giai đoạn Dệt Mộc:
- Phát hành
work-orders(Lệnh dệt/Lệnh sản xuất) xuất sợi cho nhà máy dệt. - Ghi nhận
weaving-invoices(Chứng từ dệt) để tinh quyết thù lao nếu đối tác dệt là gia công ngoài. - Dệt xong, cuộn mộc được bắn Barcode nhập vào Module
raw-fabric(Kho Vải Mộc).
- Phát hành
- Giai đoạn Nhuộm & Hoàn tất (Thành phẩm):
- Phát hành
dyeing-orders(Lệnh nhuộm) xuất vải mộc mang sang nhà máy nhuộm. - Hoàn tất Nhuộm + Kiểm phẩm (Final Check), hàng được xác nhận và nhập thẳng vào Module
finished-fabric(Kho Thành Phẩm) bằng mã màu cuộn chi tiết.
- Phát hành
5. Luồng Giao Nhận & Fulfillment
Kho thành phẩm (finished-fabric) tiến hành đối chiếu với yêu cầu Đơn hàng gốc (orders) để trả kết quả cuối cùng cho Khách hàng:
- Tạo
shipments(Phiếu xuất / Giao hàng): Chèn module bắn mã vạch quét chọn thẳng các cuộn vải tồn trong kho lên xe giao khách hàng. - Quản lý trạng thái giao vận: Preparing ➡️ Shipped ➡️ Delivered (hoặc Returned nếu có lỗi). Kho hàng thành phẩm sẽ tự động trừ đi số tồn khi lệnh giao hàng hoàn tất.
6. Luồng Kế Toán Tài Chính (Finance)
Chịu trách nhiệm ghi nhận và cấn trừ các dòng tiền (CashFlow):
- Thanh toán:
paymentslưu trữ các lần giao dịch chuyển khoản / tiền mặt từ Khách hàng thanh toán cho Đơn hàng. - Công nợ đối tác: Hệ thống tự động tính toán dư nợ. Công nợ khách hàng (dòng tiền thu về trừ cho lượng hóa đơn xuất đi), cũng như công nợ Trả Nhà Cung Cấp Sợi / Đơn vị Gia Công thao tác thông qua module báo cáo khoản nợ (Debt).
7. Báo Cáo & Phân Tích Tổng Quan (Dashboard & Reports)
Giai đoạn chốt chặn cung cấp cái nhìn vĩ mô cho Cấp Quản Lý, tổng hợp toàn bộ dữ liệu từ 6 luồng trên qua Event Database Real-Time:
dashboard: Hiển thị nhanh các thông số KPI bằng Premium Cards.reports: Xoáy sâu vào các báo cáo chi tiết về Tài chính, Biến động Tồn kho, Hiệu suất Sản xuất Dệt/Nhuộm.inventory: Hệ thống sổ cái Tồn Kho để xem lịch sử Log và Balance biến động của phân hệ Khối Yarn / Raw Fabric / Finished Fabric độc lập.