Data Flow

Quick Reference — dữ liệu đi từ trái sang phải, mỗi mũi tên = 1 service call + 1 audit row (nếu có side-effect).

1. End-to-end pipeline

flowchart LR
    subgraph Intake[Intake Layer]
      RAW[Raw orders<br/>CSV/Excel/manual]
      ADJ[KAM adjustments<br/>Excel/form]
    end

    subgraph Storage[Supabase]
      HO[historical_orders]
      FA[forecast_adjustments]
      CFG[config_values]
      FR[forecast_results]
      AL[audit_log]
    end

    subgraph Engine[Engine Layer]
      AGG[historical-aggregator]
      GEN[forecast/generator]
      WLU[wlu/calculator]
    end

    subgraph Output[Output / UI]
      OVR[Forecast Overview]
      REV[Review queue]
      WH[Warehouse report]
      CUS[Customer report]
    end

    RAW --> HO
    ADJ --> FA
    HO --> AGG
    AGG --> GEN
    CFG --> GEN
    GEN --> FR
    FR --> WLU
    CFG --> WLU
    WLU --> WH
    FR --> OVR
    FA --> REV
    REV --> FR
    FA -.audit.-> AL
    FR -.audit.-> AL
    CFG -.audit.-> AL

Text mô tả: Đầu vào gồm historical_orders (90 ngày) và forecast_adjustments (KAM gửi). Engine historical-aggregator → forecast/generator đọc lịch sử + config → ghi forecast_results. WLU calculator đọc forecast_results + config → output báo cáo workload. Mọi thay đổi state, qty, config đều ghi audit_log.

2. Bảng trạng thái dữ liệu

Giai đoạn	Bảng	Tần suất ghi	Ai ghi
Import lịch sử	historical_orders	hàng tuần / theo đợt	Admin / Ops
KAM gửi	forecast_adjustments	hàng ngày	KAM
Engine nightly	forecast_results	02:00 mỗi đêm	System (cron / RPC)
Planner duyệt	forecast_results.audited_qty + state	hàng ngày	Planner
Audit	audit_log	mỗi action	System (trigger / service)
Config change	config_values	thỉnh thoảng	Admin

3. Forecast nightly job

sequenceDiagram
    participant Cron as Cron 02:00
    participant Svc as forecastService
    participant Eng as engine/forecast
    participant DB as Supabase

    Cron->>Svc: trigger compute()
    Svc->>DB: read historical_orders (90d)
    Svc->>DB: read config_values (monthly, event)
    Svc->>DB: read customer_warehouse (active pairs)
    loop mỗi (kho, khách, ngày)
        Svc->>Eng: aggregate(historical) → baseline
        Svc->>Eng: generate(baseline, monthly, event) → forecast_qty
    end
    Svc->>DB: upsert forecast_results
    Svc->>DB: insert audit_log (action=NIGHTLY_COMPUTE)

4. Adjustment merge vào forecast_result

Khi Planner ACCEPTED 1 adjustment:

sequenceDiagram
    participant UI as ForecastReview
    participant Svc as reviewService
    participant DB

    UI->>Svc: accept(adjustment_id, audited_qty, note)
    Svc->>DB: update adjustment.state=ACCEPTED
    Svc->>DB: update forecast_result.audited_qty
    Svc->>DB: insert audit_log (action=STATE_CHANGE)
    Svc->>DB: insert audit_log (action=QTY_EDIT)
    DB-->>Svc: ok
    Svc-->>UI: toast success

5. Read paths (báo cáo)

Trang	Service	Query chính
/planner/forecast	forecastService.list()	forecast_results join customer, warehouse
/planner/forecast/review	reviewService.queue()	forecast_adjustments WHERE state IN (NEW,SEEN)
/planner/forecast/warehouse	reportService.byWarehouse()	aggregate forecast_results × wlu_config
/planner/forecast/customer/:id	reportService.byCustomer()	filter forecast_results by customer

6. Điểm ghi audit (tổng kết)

Action	Ai trigger	Ghi audit khi nào
IMPORT_HISTORICAL	Admin	service xử lý xong file
SUBMIT_ADJUSTMENT	KAM	sau insert thành công
STATE_CHANGE	AM / Planner	mỗi lần đổi state
QTY_EDIT	Planner	khi sửa audited_qty
CONFIG_CHANGE	Admin	sau update config_values
NIGHTLY_COMPUTE	System	đầu + cuối job

Tiếp: Deployment · API Reference