Configuration Reference
Hệ thống SOS có 12 bảng cấu hình quản lý qua API CRUD chung. Tất cả config tables chia sẻ cùng pattern endpoint.
CRUD Pattern
Mỗi config type hỗ trợ 5 operations:
| Method | Path | Description |
|---|---|---|
GET | /api/config/<type> | List tất cả active records |
GET | /api/config/<type>/:id | Get by ID |
POST | /api/config/<type> | Tạo mới |
PUT | /api/config/<type>/:id | Cập nhật |
DELETE | /api/config/<type>/:id | Soft delete (is_active = 0) |
Tất cả config records tự động có: id, is_active, created_at, updated_at, created_by.
1. Score Weights — /api/config/score-weights
Trọng số cho 5 thành phần điểm SOS.
| Field | Required | Description |
|---|---|---|
score_component | ✅ | p_score / o_score / t_score / f_score / i_score |
weight_pct | ✅ | Phần trăm trọng số (tổng 5 components = 100%) |
max_points | ❌ | Điểm tối đa (default 100) |
effective_from | ✅ | Ngày hiệu lực |
effective_to | ❌ | Ngày hết hiệu lực |
// Example
{ "score_component": "p_score", "weight_pct": 25, "max_points": 100, "effective_from": "2026-01-01" }
2. Tiers — /api/config/tiers
Phân hạng seller theo tổng điểm SOS.
| Field | Required | Description |
|---|---|---|
tier_name | ✅ | Tên hạng (Platinum, Gold, Silver, Bronze, Warning) |
tier_order | ✅ | Thứ tự (1 = cao nhất) |
min_sos_score | ✅ | Điểm SOS tối thiểu |
max_sos_score | ✅ | Điểm SOS tối đa |
color_code | ❌ | Mã màu hex |
benefits | ❌ | Mô tả quyền lợi |
restrictions | ❌ | Mô tả hạn chế |
effective_from | ✅ | Ngày hiệu lực |
3. P-Score Config — /api/config/p-score
Cấu hình đánh giá Planning & Forecast.
| Field | Required | Description |
|---|---|---|
campaign_type | ✅ | major_campaign / mini_campaign |
required_lead_days | ✅ | Số ngày cần submit trước campaign |
on_time_points | ❌ | Điểm cho submit đúng hạn |
late_penalty_per_day | ❌ | Trừ điểm mỗi ngày trễ |
accuracy_base_points | ❌ | Điểm base accuracy |
accuracy_good_range_min | ❌ | % sai lệch tối thiểu (vẫn tốt) |
accuracy_good_range_max | ❌ | % sai lệch tối đa (vẫn tốt) |
accuracy_penalty_per_10pct | ❌ | Trừ điểm mỗi 10% lệch |
4. O-Score Config — /api/config/o-score
Cấu hình đánh giá Order Operations.
| Field | Required | Description |
|---|---|---|
effective_from | ✅ | Ngày hiệu lực |
max_delay_minutes | ❌ | Ngưỡng delay (mặc định 30 phút) |
acceptable_late_pct | ❌ | % trễ chấp nhận được (mặc định 3%) |
penalty_per_1pct_over | ❌ | Trừ điểm mỗi 1% vượt ngưỡng |
base_points | ❌ | Điểm khởi đầu (mặc định 100) |
5. T-Score Config — /api/config/t-score
Cấu hình đánh giá Ticket SLA (tiers theo thời gian phản hồi).
| Field | Required | Description |
|---|---|---|
tier_index | ✅ | Thứ tự tier (1 = tốt nhất) |
response_hours_min | ✅ | Giờ phản hồi tối thiểu |
response_hours_max | ❌ | Giờ phản hồi tối đa (NULL = không giới hạn) |
points | ✅ | Điểm cho tier này |
effective_from | ✅ | Ngày hiệu lực |
6. F-Score Config — /api/config/f-score
Cấu hình đánh giá Finance/Payment (tiers theo ngày trễ).
| Field | Required | Description |
|---|---|---|
tier_index | ✅ | Thứ tự tier |
days_late_min | ✅ | Ngày trễ tối thiểu |
days_late_max | ❌ | Ngày trễ tối đa (NULL = không giới hạn) |
points | ✅ | Điểm cho tier này |
effective_from | ✅ | Ngày hiệu lực |
7. I-Score Config — /api/config/i-score
Cấu hình đánh giá Inventory Health.
| Field | Required | Description |
|---|---|---|
effective_from | ✅ | Ngày hiệu lực |
aging_threshold_days | ❌ | Ngưỡng tồn kho aging (ngày) |
base_good_pct | ❌ | % aging tốt (mặc định 5%) |
penalty_per_5pct | ❌ | Trừ điểm mỗi 5% vượt |
base_points | ❌ | Điểm khởi đầu (mặc định 100) |
severe_aging_days | ❌ | Ngưỡng aging nghiêm trọng (180) |
severe_aging_pct_threshold | ❌ | % kích hoạt multiplier (30%) |
severe_storage_multiplier | ❌ | Hệ số nhân phạt (1.5) |
calculation_basis | ❌ | Cơ sở tính: cbm / qty / max |
8. Surcharge Config — /api/config/surcharge
Cấu hình luật trigger phụ phí.
| Field | Required | Description |
|---|---|---|
surcharge_type | ✅ | Loại phụ phí |
trigger_condition | ✅ | JSON điều kiện kích hoạt |
action | ✅ | JSON hành động khi trigger |
description | ❌ | Mô tả |
effective_from | ✅ | Ngày hiệu lực |
9. AM Bonus/Penalty — /api/config/am-bonus-penalty
Cấu hình thưởng/phạt cho Account Manager.
| Field | Required | Description |
|---|---|---|
sos_delta_min | ✅ | Delta SOS tối thiểu |
sos_delta_max | ❌ | Delta SOS tối đa |
bonus_or_penalty_amount | ✅ | Số tiền thưởng/phạt |
currency | ❌ | Đơn vị tiền tệ (mặc định VND) |
description | ❌ | Mô tả |
effective_from | ✅ | Ngày hiệu lực |
10. AM KPI Weight — /api/config/am-kpi-weight
Trọng số các thành phần KPI của AM.
| Field | Required | Description |
|---|---|---|
component | ✅ | Thành phần KPI (vd: avg_sos, revenue, growth) |
weight_pct | ✅ | Phần trăm trọng số |
effective_from | ✅ | Ngày hiệu lực |
11. Grace Period — /api/config/grace-period
Cấu hình ưu đãi cho seller mới.
| Field | Required | Description |
|---|---|---|
effective_from | ✅ | Ngày hiệu lực |
grace_period_months | ❌ | Số tháng grace period (mặc định 2) |
min_score_floor | ❌ | Điểm sàn tối thiểu (mặc định 70) |
min_orders_threshold | ❌ | Ngưỡng đơn hàng tối thiểu (mặc định 30) |
apply_to_components | ❌ | JSON components áp dụng |
12. Frappe Helpdesk — /api/config/helpdesk
Cấu hình tích hợp với Frappe Helpdesk.
| Field | Required | Description |
|---|---|---|
country_code | ✅ | Mã quốc gia |
helpdesk_url | ✅ | URL Helpdesk instance |
api_key | ✅ | API key xác thực |
api_secret | ✅ | API secret |
sync_method | ❌ | pull / push |
pull_cron | ❌ | Cron schedule cho pull |
seller_field_mapping | ❌ | JSON mapping field names |
business_hours_start | ❌ | Giờ bắt đầu tính SLA |
business_hours_end | ❌ | Giờ kết thúc tính SLA |
timezone | ❌ | Timezone (mặc định Asia/Ho_Chi_Minh) |