Process Flows

Sơ đồ end-to-end của MVP. Mỗi diagram đều có text description kèm dưới — tiện cho AI/LLM đọc.

Flow 1 · Một ngày làm việc (Daily Operation)

sequenceDiagram
    actor KAM
    actor AM
    actor Planner
    actor WH as Warehouse Manager
    actor Aud as Auditor
    participant App as Workforce Planner
    participant DB as Supabase
    participant Eng as Forecast Engine

    KAM->>App: Upload adjustment (22:00 hôm trước)
    App->>DB: insert adjustment (state=NEW)
    Note over Eng,DB: 02:00 — Nightly job
    Eng->>DB: read 90 ngày historical + config
    Eng->>DB: write forecast_result (14 ngày tới)
    AM->>App: 08:30 — mark SEEN
    App->>DB: update state=SEEN + audit
    Planner->>App: 09:00 — duyệt / sửa
    App->>DB: update state=ACCEPTED + audited_qty + audit
    WH->>App: 14:00 — đọc báo cáo workload
    Aud->>App: 17:00 — truy vết quyết định

Text mô tả: KAM gửi adjustment đêm trước → engine chạy nightly lúc 02:00 dùng historical + config → AM xác nhận SEEN → Planner duyệt → WH đọc workload → Auditor truy vết.

---

Flow 2 · Adjustment Lifecycle (state machine)

stateDiagram-v2
    [*] --> NEW: KAM submits
    NEW --> SEEN: AM acknowledges
    NEW --> ACCEPTED: Planner direct approve
    NEW --> REJECTED: Planner rejects
    SEEN --> ACCEPTED: Planner approves
    SEEN --> REJECTED: Planner rejects
    ACCEPTED --> [*]: locked
    REJECTED --> [*]: locked
    note right of ACCEPTED
        ghi audit_log:
        actor, reason, Δ vs P85
    end note

Text mô tả: Adjustment đi từ NEW (KAM gửi) qua SEEN (AM xác nhận) đến ACCEPTED hoặc REJECTED bởi Planner. State ACCEPTED/REJECTED là terminal — không sửa được, chỉ có thể tạo adjustment mới.

---

Flow 3 · Forecast computation pipeline

flowchart TD
    A[Historical orders<br/>90 ngày] --> B[historical-aggregator]
    B --> |baseline_avg, P85, n| C[generator]
    D[monthly_multiplier<br/>config theo tháng] --> C
    E[event_multiplier<br/>NORMAL/MID/MEGA] --> C
    C --> |forecast_qty| F[forecast_result]
    F --> G[wlu/calculator]
    H[UPH config<br/>group × pk_type] --> G
    I[product_mix<br/>per customer] --> G
    G --> |WLU/đơn, total_minutes| J[Workload report]
    J --> K[Headcount = ceil min / 480]

Text mô tả: Pipeline tính forecast: lấy 90 ngày lịch sử → baseline → nhân monthly × event → ra forecast_qty. Từ forecast_qty × WLU (tính từ UPH × product_mix) → ra total_workload_minutes → chia ca 8h ra headcount.

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

---

Flow 4 · Review decision tree

flowchart TD
    Start([Adjustment ở state SEEN]) --> Q1{KAM qty vs P85?}
    Q1 -->|Δ ≤ 15%| A1[Auto-fit zone:<br/>duyệt nhanh, không cần note]
    Q1 -->|15% < Δ ≤ 30%| A2[Warn zone:<br/>cần note ngắn]
    Q1 -->|Δ > 30%| A3[Alert zone:<br/>note + citation lịch sử<br/>BẮT BUỘC]
    A1 --> Decide{Decision}
    A2 --> Decide
    A3 --> Decide
    Decide -->|Accept| ACC[ACCEPTED<br/>audited_qty = KAM qty]
    Decide -->|Modify| MOD[ACCEPTED<br/>audited_qty = Planner qty]
    Decide -->|Reject| REJ[REJECTED<br/>audited_qty = baseline]

Text mô tả: Planner ra quyết định dựa trên độ lệch Δ của số KAM gửi so với P85 baseline. ≤15% bấm duyệt nhanh; 15–30% phải note; >30% bắt buộc note + dẫn chứng lịch sử.

---

Flow 5 · Audit trail (insert-only)

flowchart LR
    A1[Action: state change] --> Log[(audit_log)]
    A2[Action: qty edit] --> Log
    A3[Action: config change] --> Log
    A4[Action: import] --> Log
    Log --> R1[Auditor query by<br/>warehouse + customer + date]
    Log --> R2[Timeline UI<br/>per adjustment]
    Note[/RLS: REVOKE UPDATE, DELETE/]
    Log -.- Note

Text mô tả: Mọi action có side-effect (state change, sửa qty, đổi config, import) đều ghi 1 dòng audit_log. Bảng được RLS revoke UPDATE/DELETE → chỉ INSERT.

---

Flow 6 · User journey theo persona

Bước	KAM	AM	Planner	WH Mgr	Auditor
1	Mở /planner/override-import	Inbox notification	Dashboard /planner/forecast	/planner/forecast/warehouse	Báo cáo tuần
2	Upload Excel hoặc nhập tay	Click vào yêu cầu	Filter Tier=KEY	Chọn kho × ngày	Tra adjustment ID
3	Verify preview	So với account của mình	So Δ vs P85	Đọc WLU theo PK type	Đọc timeline
4	Submit → toast OK	Mark SEEN	Approve/Reject + note	Export Excel	Cross-check raw orders
5	Theo dõi state	Done	Done	Lên ca	Đóng case

Tiếp: Architecture · SOP