Appeals & Surcharges

Appeal Workflow

Seller/AM có thể khiếu nại (appeal) điểm SOS khi tin rằng kết quả không chính xác do lỗi hệ thống, sự kiện bất khả kháng, hoặc lý do hợp lệ khác.

Quy trình 2 cấp review

1. AM tạo appeal (status: pending)
   ├── seller_code, period, component, reason, evidence
   └── Deadline tự động: +5 ngày

2. Ops Head review (PATCH /appeals/:id/review-ops)
   ├── decision: approve / reject
   └── status → under_review

3. AM Head review (PATCH /appeals/:id/review-am)  ← Final Decision
   ├── decision: approve / partial / reject
   ├── Có thể kèm score_adjustment
   └── status → approved / partially_approved / rejected

4. Nếu approved + có score_adjustment:
   ├── Tự động update seller_sos_period_score
   └── status score → recalculated

5. Webhook dispatch: seller.appeal_decided

Appeal Statuses

Status	Description
pending	Mới tạo, chưa review
under_review	Ops Head đã review, chờ AM Head
approved	AM Head approved hoàn toàn
partially_approved	AM Head approved một phần
rejected	AM Head reject
expired	Quá deadline chưa review

Appeal Reason Types

Type	Description
system_sync_error	Lỗi đồng bộ hệ thống (OMS/WMS/Helpdesk)
force_majeure	Sự kiện bất khả kháng (thiên tai, dịch bệnh)
marketplace_algorithm_change	Thay đổi thuật toán sàn TMĐT
other	Lý do khác

Score Adjustment

Khi AM Head approve, có thể kèm score_adjustment để sửa điểm:

{
  "decision": "approve",
  "score_adjustment": {
    "o_score_raw_after": 90,
    "o_score_weighted_after": 18.0,
    "total_sos_after": 87.5
  }
}

Hệ thống sẽ update các field có suffix _after vào seller_sos_period_score, bỏ suffix _after để map đúng column name. Score status chuyển thành recalculated.

---

Surcharges

Phụ phí (surcharge) được áp dụng cho Seller khi vi phạm các ngưỡng SOS hoặc điều kiện kinh doanh.

Surcharge Types

Type	Trigger	Impact
planning_overload	Seller không submit forecast / vượt capacity	Phí phụ trội
payment_block	Thanh toán quá hạn nghiêm trọng	Block đơn hàng + webhook
aging_storage_multiplier	Tồn kho aging > ngưỡng	Phí lưu kho tăng

Tạo Surcharge

POST /api/surcharges
Content-Type: application/json

{
  "seller_code": "SEL001",
  "period": "2026-02",
  "surcharge_type": "payment_block",
  "amount": 0,
  "trigger_details": {
    "reason": "Payment overdue > 20 days",
    "worst_days_late": 25
  }
}

Auto webhook events:

• seller.surcharge_created — luôn dispatch
• seller.order_blocked — chỉ khi surcharge_type = 'payment_block'

Surcharge Statuses

Status	Description
pending	Mới tạo, chưa áp dụng
applied	Đã áp dụng vào invoice
waived	Được miễn/hủy

Enforcement Check

WMS/OMS gọi API enforcement để kiểm tra seller có bị block không:

GET /api/sos/sellers/SEL001/enforcement

{
  "seller_code": "SEL001",
  "is_blocked": true,
  "active_surcharges": [
    {
      "type": "payment_block",
      "amount": 0,
      "period": "2026-02",
      "reason": "Payment overdue > 20 days"
    }
  ]
}

Use case: WMS kiểm tra trước khi accept đơn mới từ seller. Nếu is_blocked = true → reject đơn và thông báo seller thanh toán.

---

Configuration

Surcharge Config

Cấu hình ngưỡng trigger surcharge qua POST /api/config/surcharge:

{
  "surcharge_type": "planning_overload",
  "trigger_condition": "{ \"no_forecast_for_major_campaign\": true }",
  "action": "{ \"surcharge_amount_pct\": 5, \"notify_am\": true }",
  "description": "Phụ phí khi không submit forecast cho campaign lớn",
  "effective_from": "2026-01-01"
}

AM Bonus/Penalty Config

AM nhận thưởng/phạt dựa trên SOS delta trung bình của portfolio:

{
  "sos_delta_min": 5,
  "sos_delta_max": 10,
  "bonus_or_penalty_amount": 2000000,
  "currency": "VND",
  "description": "Thưởng cho AM có portfolio cải thiện 5-10 điểm SOS",
  "effective_from": "2026-01-01"
}