Codebase Analysis

Quick Reference — Một trang tóm tắt toàn bộ project sau khi scan.

Hạng mục	Giá trị
Tên	Boxme Workforce Planner v2 (WFP MVP)
Stack chính	React 18 + TypeScript + Vite + Tailwind + Supabase
State / Data	Zustand · TanStack Query · React Hook Form + Zod
UI primitives	Radix UI · lucide-react · Recharts
Test	Vitest (unit) · Playwright (E2E)
Routing	React Router v6
Deploy	Cloudflare Pages (prototype HTML) · Supabase (DB+Auth)
Ngôn ngữ giao diện	Tiếng Việt

1. Cấu trúc thư mục

/Volumes/Data/Boxme/workforce/
├── index.html + js/              # Prototype HTML (deployed Cloudflare Pages)
├── wfp-v2/                       # MVP React app (production target)
│   ├── src/
│   │   ├── domain/               # Pure types (Zod schemas, entity contracts)
│   │   ├── engine/               # Pure compute (forecast, WLU) — KHÔNG side-effect
│   │   │   ├── forecast/         # historical-aggregator, generator
│   │   │   ├── wlu/              # calculator
│   │   │   └── cutoff.ts
│   │   ├── services/             # I/O layer (Supabase, xlsx, audit, review…)
│   │   ├── hooks/                # React Query hooks
│   │   ├── components/           # UI: layout, primitives, charts, review
│   │   ├── pages/                # Routes (planner/* admin/*)
│   │   ├── lib/                  # auth, scope, mock-store, env
│   │   └── router.tsx
│   ├── supabase/migrations/      # SQL schema
│   └── scripts/seed/             # Demo data seeders
├── architecture/                 # Contract docs (parallel-safety, TDD, boundaries)
├── openspec/changes/wfp-mvp/     # Active MVP plan (7 phase · 63 task)
├── HUONG-DAN-VAN-HANH.md         # Tài liệu vận hành non-tech hiện có
└── docs/                         # ← tài liệu mới (bạn đang đọc)

2. Module / Feature map

Module	File chính	Trách nhiệm
Auth	`src/lib/auth.tsx`, `pages/Login.tsx`	Supabase auth, role guard
Scope	`src/lib/scope.tsx`	Lưu warehouse + role hiện hành
Historical import	`services/historicalImportService.ts`, `services/xlsxParser.ts`, `pages/admin/HistoryImport.tsx`	Nhập 90 ngày đơn lịch sử (CSV/Excel/manual)
Adjustment intake	`services/adjustmentService.ts`, `pages/planner/SubmitAdjustment.tsx`	KAM gửi điều chỉnh forecast
Forecast engine	`engine/forecast/*`, `services/forecastService.ts`	Tính `baseline × monthly × event`
WLU calculator	`engine/wlu/calculator.ts`	Quy đổi đơn → workload minutes → headcount
Review & approve	`services/reviewService.ts`, `pages/planner/ForecastReview.tsx`, `components/review/*`	Pipeline `NEW → SEEN → ACCEPTED/REJECTED`
Reports	`services/reportService.ts`, `pages/planner/ForecastWarehouse.tsx`, `CustomerDetail.tsx`	Báo cáo theo kho + khách
Config	`services/configService.ts`, `pages/admin/{Config,NormsConfig,SeasonsConfig}.tsx`	Tham số mùa, sự kiện, UPH
Audit log	`services/auditService.ts`, `components/review/AuditTimeline.tsx`	Insert-only audit trail

3. Entry points & Routes

Route	Trang	Vai trò truy cập
`/login`	Đăng nhập	Public
`/`	Trang chủ	Tất cả
`/planner/forecast`	Tổng quan dự báo	Planner, OPS, Admin, Auditor
`/planner/forecast/review`	Phê duyệt yêu cầu KAM	Planner, OPS, Admin
`/planner/forecast/customer` · `/:id`	Forecast theo khách	Planner, OPS, Admin, Auditor
`/planner/forecast/warehouse`	Báo cáo kho	Planner, OPS, Admin, Auditor, WH Manager
`/planner/override-import`	Gửi điều chỉnh (KAM)	KAM, Planner
`/admin/history-import`	Nhập dữ liệu lịch sử	Admin, OPS
`/admin/warehouses`	Quản lý kho	Admin
`/admin/config` · `/dinhmuc` · `/thamso`	Cấu hình tham số	Admin

4. Forecast formula (cốt lõi)

forecast_qty(day) = round( baseline_avg(customer, warehouse, event_type)
                         × monthly_multiplier[month_of(day)]
                         × event_multiplier[event_type_of(day)] )

WLU/đơn (minutes)  = 60 / UPH_eff
UPH_eff            = harmonic_mean(UPH[group, pk_type], weight = product_mix)
total_workload_min = WLU × forecast_qty
headcount          = ceil(total_workload_min / shift_minutes)   # default 480

Tham chiếu: src/engine/forecast/generator.ts, src/engine/wlu/calculator.ts

5. Database (Supabase)

10 bảng chính, mọi bảng có RLS, có created_at/updated_at/created_by
audit_log insert-only (revoke UPDATE/DELETE ở RLS)
Index chuẩn trên (warehouse_id, customer_id, date)
Schema chi tiết: xem Database

6. Dependencies (chọn lọc)

Nhóm	Package	Vì sao
Data	`@supabase/supabase-js`, `@tanstack/react-query`	DB + cache
Form	`react-hook-form`, `zod`, `@hookform/resolvers`	Form + validation
UI	`@radix-ui/*`, `lucide-react`, `recharts`	Primitives & charts
Files	`xlsx`	Import Excel/CSV
State	`zustand`	Lightweight stores

7. Test coverage (hiện trạng)

Unit (Vitest): tập trung engine/forecast/* và engine/wlu/calculator.ts (pure functions)
E2E (Playwright): playwright.config.ts — placeholder cho smoke flow
Gate: npm run typecheck && npm test && npm run build PHẢI pass trước khi merge

8. Trạng thái MVP

7 phase · 63 task — xem openspec/changes/wfp-mvp/. Critical path 4 agent song song ~25 ngày làm việc.

9. Risks & gaps đã thấy

WLU calculator có một số function body còn rỗng (stub) — cần verify đã implement đủ cho MVP
Chưa có doc deployment cho phần React app (chỉ prototype HTML đang trên CF Pages)
audit_log cần test RLS revoke chặt chẽ
Demo seed snapshot phụ thuộc scripts/seed/demo-snapshot.ts — cần luôn cập nhật khi schema đổi

Xem tiếp Architecture · Database · Hướng dẫn kiểm thử MVP

Codebase Analysis ​

1. Cấu trúc thư mục ​

2. Module / Feature map ​

3. Entry points & Routes ​

4. Forecast formula (cốt lõi) ​

5. Database (Supabase) ​

6. Dependencies (chọn lọc) ​

7. Test coverage (hiện trạng) ​

8. Trạng thái MVP ​

9. Risks & gaps đã thấy ​

Codebase Analysis

1. Cấu trúc thư mục

2. Module / Feature map

3. Entry points & Routes

4. Forecast formula (cốt lõi)

5. Database (Supabase)

6. Dependencies (chọn lọc)

7. Test coverage (hiện trạng)

8. Trạng thái MVP

9. Risks & gaps đã thấy