Tổng quan dự án

TÓM TẮT NHANH

BoxMe Forecast v10 là hệ thống dự báo nhu cầu đơn hàng + lập kế hoạch nhân sự cho các kho fulfillment thương mại điện tử tại Việt Nam. Hệ thống dự đoán volume đơn hàng hàng ngày ở cả cấp order-level lẫn SKU-level, sau đó chuyển đổi thành kế hoạch staffing tuân thủ Bộ luật Lao động 2019.

Vấn đề cần giải quyết

Các kho fulfillment e-commerce tại Việt Nam đối diện với:

Biến động nhu cầu cao — Double-day sales (2.2, 3.3, ..., 12.12) có thể tăng volume 5-10x
Quản lý ca làm phức tạp — 2-4 ca/ngày tùy loại ngày, tuân thủ luật lao động
SKU đa dạng — 13,000+ mã sản phẩm với complexity levels khác nhau
Nhiều kênh bán — Shopee, TikTokShop, Lazada, và các kênh khác co các calendar event riêng

Năng lực chính

Năng lực	Mô tả
Two-Level Forecasting	Order-level (per user/warehouse/product) + SKU-level (aggregated across channels)
Segmented ML Model	LightGBM classifier + segment-specific regressors với quantile predictions
E-commerce Calendar	Lịch nghỉ lễ VN, ngày lương (15/25), double-day (2.2–12.12), mega sales
5-Layer Workforce Planner	Forecast → Work Hours → Shifts → Staff Allocation → Capacity/Backlog/Cost
AutoML Self-Improvement	LLM-driven hyperparameter tuning với auto-backtest + rollback tự động
Walk-Forward Backtesting	Configurable train/test windows, breakdown theo SKU type, event tier, DOW
Multi-language	Tiếng Việt, Tiếng Anh, Tiếng Thái

Technology Stack

Frontend:  React 19 + TypeScript + Vite 6 + Recharts + TanStack Query
           Deploy: Cloudflare Pages

Backend:   Python 3.11 + FastAPI + LightGBM + scikit-learn + pandas + NumPy
           Deploy: Railway (FastAPI) + GitHub Actions (cron)

Database:  Supabase PostgreSQL (hosted)
           12+ ML-specific tables + RLS security

CI/CD:     GitHub Actions → Cloudflare Pages (frontend)
           GitHub Actions → Railway (backend)

Cấu trúc dự án (Top-Level)

workforce_planner/
├── src/                        # Frontend React (TypeScript)
│   ├── pages/                  # 33 trang UI
│   ├── components/             # UI Components + ShiftPlan
│   ├── services/modules/       # 5 module nhóm: forecast, workforce, data, config, analytics
│   ├── contexts/               # AuthContext + WarehouseContext
│   ├── hooks/                  # useQueries, useFormAutoSave, useNavigationGuard
│   ├── lib/                    # supabase client + queryClient
│   ├── locales/                # en.ts, vi.ts, th.ts
│   └── types.ts                # 300 dòng type definitions
│
├── forecast_engine/            # Backend Python ML
│   ├── main.py                 # FastAPI entry point (13 routers)
│   └── src/
│       ├── api/                # 15 route files RESTful
│       ├── core/               # 29 module core (model, features, pipeline, backtester...)
│       ├── automl/             # AutoML: orchestrator, self_improver, llm_provider, tuner
│       ├── data/               # repository, schemas, supabase_client
│       └── utils/              # Utilities
│
├── scripts/                    # Data import, seed, evaluate, verify
├── __tests__/                  # Frontend tests (14 categories, 509+ tests)
├── tests/                      # Python backend tests
├── docs/                       # Technical docs (9 chapters)
├── .github/workflows/          # CI/CD workflows
└── docs-site/                  # VitePress documentation (BẠN ĐANG ĐỌC)

Thống kê codebase

Metric	Giá trị
Frontend (TS/TSX)	~249 files
Backend (Python)	~258 files
Tổng source files	~507+ files
33 trang UI	Dashboard, Forecast, Workforce, Analytics, BSIN, Customer...
Frontend tests	509+ tests, 14 categories
i18n locales	3 ngôn ngữ (EN, VI, TH)
Database tables	12+ bảng ML pipeline
API routes	13 routers, 50+ endpoints

Tài liệu liên quan

Kiến trúc hệ thống — Sơ đồ kiến trúc tổng thể
ML Engine — Chi tiết mô hình dự báo
Workforce Planner — Kiến trúc 5 lớp lập kế hoạch nhân sự
Deploy Guide — Hướng dẫn triển khai

Tổng quan dự án ​

Vấn đề cần giải quyết ​

Năng lực chính ​

Technology Stack ​

Cấu trúc dự án (Top-Level) ​

Thống kê codebase ​