# TrustLens Returns & Refund Implementation Roadmap

Bu sənəd TrustLens-in hazırkı Returns/Refund sisteminin mərhələli şəkildə daha doğru, etibarlı və kommersiya baxımından güclü müdafiə sisteminə çevrilməsi üçün implementasiya planıdır.

Əsas prinsip: yeni scoring və PRO avtomatlaşdırmaları əlavə edilməzdən əvvəl refund məlumatının doğruluğu və bütün sistemlərdə eyni məna daşıması təmin edilməlidir.

## İcra statusu — 24 avqust 2026

- Phase 0: tamamlandı — canonical classifier, full-refund tolerance və eligible-order status qaydası vahidləşdirildi.
- Phase 1: tamamlandı — refund ledger, unikal idempotency, order lock, ledger əsaslı customer aggregate-ləri, downstream replay guard və GDPR inteqrasiyası əlavə edildi.
- Phase 2: tamamlandı — create/update/delete lifecycle reconciliation, Historical Sync backfill/parity, synthetic/live event dedup, legacy meta keçidi, category aggregate rebuild və restart-safe migration əlavə edildi.
- Phase 3: tamamlandı — ledger əsaslı vahid refund metrics service, action/distinct-order ayrımı, weighted store rate, customer-average rate, cohort/rolling analizləri, reporting/REST uyğunluğu və currency-safe məbləğlər əlavə edildi.
- Phase 4: tamamlandı — 30/90/365/lifetime risk profili, sample-size confidence, merchant baseline, purchase/refund ratio, delivery və item evidence, timing/reason/coupon/linked-account konteksti və plain-language score səbəbləri əlavə edildi.
- Phase 5: tamamlandı — Categories-in ayrıca penalty-si ləğv edildi, merchant-configurable category/SKU Product Risk multiplier-i Returns score-a inteqrasiya olundu, durable product facts, unattributed bucket, deleted-product fallback və kommersiya profili əlavə edildi.
- Phase 6: tamamlandı — canonical RefundContext, refund-only rule field-ləri, replay-safe action routing, refund webhook payload-u və inspector context log-u əlavə edildi; işləməyən reviews_before_refund sahəsi UI/validator-dan çıxarıldı.
- Phase 7: tamamlandı — pre-refund risk preview, beş səviyyəli qərar mühərriki, RMA/approval/inspection state machine, universal refund gate, evidence, duplicate tracking, SLA inbox, linked-open-order context, Profit-at-Risk və append-only audit trail əlavə edildi.
- Phase 8: tamamlandı — immutable legacy snapshot, shadow parity, izahlı mismatch telemetry, restart-safe migration checkpoint-ləri, guarded ledger cutover, admin reconciliation report-u və təhlükəsiz rollback əlavə edildi.
- Növbəti paket: production release müşahidəsi və real mağaza parity təsdiqi.

## Phase 0 — Domen qaydalarının müəyyənləşdirilməsi

### Məqsəd

`refund`, `return`, `full refund`, `partial refund` və `eligible order` anlayışları üçün vahid qayda yaratmaq.

### İşlər

- Financial refund ilə physical product return anlayışlarını ayırmaq.
- Refund classification siyahısını müəyyənləşdirmək:
  - `customer_return`
  - `pre_fulfillment_cancellation`
  - `merchant_error`
  - `shipping_failure`
  - `price_adjustment`
  - `goodwill`
  - `fraud_prevention`
  - `suspected_abuse`
  - `duplicate_payment`
  - `unknown`
- Full refund üçün vahid tolerance qaydası müəyyənləşdirmək.
- Return-rate denominator-a daxil olan order statuslarını müəyyənləşdirmək.
- Order-based, item-based və value-based return rate terminlərini ayırmaq.
- Bütün qaydaları reusable domain service-də toplamaq.

### Qəbul meyarları

- Live processing və Historical Sync eyni classifier-dən istifadə edə bilir.
- Eyni order bütün kod yollarında eyni full/partial nəticəsi alır.
- Financial refund avtomatik olaraq fiziki return/abuse kimi qəbul edilmir.

---

## Phase 1 — Refund Ledger və məlumat doğruluğu

### Məqsəd

Hər refund-u unikal, audit edilə bilən və idempotent qeyd kimi saxlamaq.

### İşlər

- Yeni `trustlens_refunds` cədvəli yaratmaq.
- Minimum sahələri əlavə etmək:
  - source və external refund ID
  - WooCommerce refund ID
  - order ID və customer email hash
  - amount və currency
  - order total və cumulative refunded amount
  - refund ratio
  - full/partial status
  - classification və reason
  - itemized status və item count
  - days since order
  - created, updated və deleted tarixləri
- `(source, external_refund_id)` üçün unique index yaratmaq.
- Eyni refund event-i təkrar gəldikdə ikinci dəfə tətbiq edilməməsini təmin etmək.
- Concurrent refund request-lər üçün atomik insert/reconcile axını yaratmaq.
- Customer aggregate-lərini ledger-dən hesablamaq.
- Event log-a refund ledger ID əlavə etmək.

### Qəbul meyarları

- Eyni `refund_id` iki dəfə işləndikdə məbləğ və counter dəyişmir.
- Eyni order bir neçə hissədə refund olunduqda `total_refunds` bir dəfə artır.
- Partial refund sonradan full olduqda bucket-lər düzgün dəyişir.
- Concurrent refund-lar double-count yaratmır.

---

## Phase 2 — Refund lifecycle və Historical Sync parity

### Məqsəd

Refund yaradılması, dəyişdirilməsi, silinməsi və historical import üçün eyni nəticəni təmin etmək.

### İşlər

- `woocommerce_order_refunded` hadisəsini ledger-ə yönləndirmək.
- `woocommerce_update_order_refund` hadisəsini reconcile etmək.
- `woocommerce_refund_deleted` hadisəsində refund-u reversed/deleted kimi qeyd etmək.
- Refund dəyişdirildikdə customer və category aggregate-lərini yenidən hesablamaq.
- Historical Sync-i refund ledger-i dolduracaq şəkildə refaktor etmək.
- Historical Sync-də cumulative refund classification istifadə etmək.
- Sync-dən əvvəl yaranmış live event-lərlə synthetic event duplicate-lərini önləmək.
- Köhnə `_trustlens_refund_counted`, `_trustlens_refund_was_full` və category meta-larından təhlükəsiz keçid hazırlamaq.
- Mövcud customer refund statistikaları üçün one-time reconciliation migration yaratmaq.
- Live Orders və Historical Sync-də eyni eligible-order status qaydasını istifadə etmək.

### Qəbul meyarları

- Sync-dən əvvəl və sonra customer refund statistikaları dəyişmir.
- Sync edilmiş order-a yeni partial refund əlavə edilməsi `total_refunds`-ı ikinci dəfə artırmır.
- Refund silindikdə məbləğ, counter, classification və score düzəlir.
- 40 + 60 partial refund həm live, həm sync nəticəsində eyni full-refund vəziyyəti yaradır.

---

## Phase 3 — Analytics, notification və reporting düzəlişləri

### Məqsəd

Merchant-ə göstərilən bütün return/refund metriklərinin eyni və aydın semantikaya malik olması.

### İşlər

- Repeat Refunder Alert-də `COUNT(DISTINCT order_id)` istifadə etmək.
- Refund action count və refunded-order count metriklərini ayırmaq.
- Mövcud “Return Rate Trend” qrafikini aşağıdakı metriklərə bölmək:
  - refund activity count/value
  - rolling distinct-order return rate
  - order-cohort return rate
- Store return rate üçün weighted formula tətbiq etmək:
  - `SUM(refunded_orders) / SUM(eligible_orders)`
- Customer-average return rate ilə store-weighted return rate-i ayrı göstərmək.
- Dashboard, Customer Detail, REST API və Scheduled Reports adlarını/formulalarını uyğunlaşdırmaq.
- Refund məbləğini refund/order currency-si ilə göstərmək.
- Multi-currency mağazalarda məbləğləri base currency-yə normalize etmək.
- Historical və live event-lərin report-larda duplicate sayılmamasını təmin etmək.

### Qəbul meyarları

- Bir order üç partial refund alsa, repeat-refunder order count-da bir dəfə görünür.
- Dashboard və customer detail eyni return-rate tərifindən istifadə edir.
- Store-wide rate kiçik sifariş tarixçəli müştərilər tərəfindən süni şəkildə şişmir.
- Multi-currency refund məbləğləri yanlış store currency ilə göstərilmir.

---

## Phase 4 — Return-aware scoring engine

### Məqsəd

Sadə lifetime refund counter-larından kontekstli və izah edilə bilən return-abuse scoring-ə keçmək.

### İşlər

- Aşağıdakı rolling window-ları əlavə etmək:
  - son 30 gün
  - son 90 gün
  - son 365 gün
  - lifetime
- Scoring-ə aşağıdakı siqnalları əlavə etmək:
  - distinct refunded-order frequency
  - refund value / purchased value ratio
  - refund amount / current order total ratio
  - median days-to-refund
  - return-window sonuna yaxın müraciətlər
  - təkrarlanan refund reason-lar
  - fulfillment və delivery statusu
  - item refund və shipping-only refund fərqi
  - linked-account refund patternləri
  - coupon/store-credit ilə əlaqəli refund davranışı
- `full refund = wardrobing` qaydasını ləğv edib delivery və return evidence tələb etmək.
- Minimum-order cliff əvəzinə confidence-weighted scoring tətbiq etmək.
- Hard-coded 1000/2000 refund məbləği penalty-lərini ləğv etmək.
- Məbləğ riskini merchant baseline, currency, margin və purchase value ilə müqayisə etmək.
- Positive clean-history bonusunun Orders və account-age bonusları ilə double-count edilməsini azaltmaq.

### Qəbul meyarları

- Pre-fulfillment cancellation müştəriyə avtomatik wardrobing penalty vermir.
- Eyni return rate müxtəlif sample size-larda eyni confidence ilə qiymətləndirilmir.
- Refund səbəbi və fulfillment statusu score izahında görünür.
- Bütün score səbəbləri merchant üçün plain-language formatında göstərilir.

---

## Phase 5 — Category-Aware modulunun Product Risk Intelligence-ə çevrilməsi

**Status: tamamlandı — 24 avqust 2026**

### Məqsəd

Eyni refund davranışını həm Returns, həm Categories modulunda iki dəfə cəzalandırmamaq.

### İşlər

- Category penalty-ni ayrıca score contribution olmaqdan çıxarmaq.
- Category/Product riskini Returns penalty-si üçün multiplier etmək.
- Hard-coded ingilis category slug-larını default qərar mənbəyi kimi ləğv etmək.
- Merchant üçün category risk settings UI yaratmaq.
- SKU/product səviyyəsində risk profili əlavə etmək:
  - return rate
  - refund value
  - chargeback rate
  - resale value
  - serial-number requirement
  - digital/physical status
  - margin və COGS
- Itemized olmayan refund-lar üçün “unattributed refund” bucket-i yaratmaq.
- Məhsulu silinmiş order/refund item-ları üçün fallback məlumat saxlamaq.

### Qəbul meyarları

- Eyni refund əsas davranış üçün iki müstəqil maksimum penalty yaratmır.
- Lokal və custom category slug-ları merchant tərəfindən konfiqurasiya edilə bilir.
- Product risk multiplier score izahında ayrıca göstərilir.

### İcra nəticəsi

- `trustlens_product_facts` proyeksiyası order item, SKU, product/category snapshot, refund value/quantity, virtual/downloadable, COGS, margin, resale və serial requirement məlumatını saxlayır.
- `order_item_id = 0` item-siz məbləğləri neytral “unattributed refund” bucket-ində saxlayır.
- Məhsul silindikdən sonra əvvəlki SKU/category və kommersiya snapshot-u rebuild zamanı qorunur.
- Store-wide product profili return/refund və chargeback rate-lərini hesablayır.
- Merchant-in real WooCommerce category-ləri Modules UI-da 0.50×–2.00× aralığında konfiqurasiya olunur; hard-coded ingilis slug default-ları yoxdur.
- Product risk yalnız Returns-in confidence-weighted raw penalty-sini dəyişir və ayrıca explanation kimi görünür; Categories modulu həmişə 0 score qaytarır.
- Phase 5 verification: 230 unit test / 364 assertion və 186 integration test / 467 assertion uğurla keçdi.

---

## Phase 6 — Refund-specific Automation Context

**Status: tamamlandı — 24 avqust 2026**

### Məqsəd

Automation qaydalarının yalnız lifetime customer statistikası ilə deyil, cari refund-un öz məlumatları ilə işləməsi.

### İşlər

- `RefundContext` obyekti yaratmaq.
- Aşağıdakı automation field-lərini əlavə etmək:
  - refund amount
  - refund ratio
  - cumulative refunded amount
  - refund type/classification
  - refund reason
  - refund currency
  - full/partial transition
  - days since order
  - item count
  - itemized status
  - fulfillment/delivery status
  - processed-by user ID/role
- `refund_processed` trigger-inə RefundContext ötürmək.
- Duplicate refund delivery-də automation-un təkrar işləməsini önləmək.
- İşləməyən `reviews_before_refund` counter-ını implement etmək və ya UI/validator-dan çıxarmaq.
- Refund-specific webhook payload yaratmaq.

### Qəbul meyarları

- Merchant “refund ratio > 80% və order delivered” kimi rule yarada bilir.
- Eyni refund replay olunduqda action ikinci dəfə işləmir.
- Automation inspector cari refund məlumatını və rule nəticəsini göstərir.

### İcra nəticəsi

- `TrustLens_Refund_Context` canonical ledger və WooCommerce obyektindən amount, cumulative ratio/value, type/classification, reason/currency, transition, timing, itemization, fulfillment/delivery və processor identity/role məlumatını yaradır.
- `refund_processed` rule-ları 15 refund-only field ilə işləyir; refund field-i başqa trigger ilə save edilə bilmir və context yoxdursa fail-closed davranır.
- “refund ratio > 80% AND order delivered” qaydası runtime və integration testində təsdiqləndi.
- Ledger-in atomik `automation_processed_at` consumer claim-i eyni refund replay ediləndə ikinci action-u bloklayır.
- Automation log-larında `context_json` saxlanır; inspector status, refund məbləği, ratio, classification/type, transition, delivery state və reason göstərir.
- Automation webhook body-si normalized `refund_context` daşıyır və mövcud HMAC/retry axınını qoruyur.
- Reviewed ledger classification qorunur; etibarlı evidence olduqda customer return, duplicate payment və pre-fulfillment cancellation üçün konservativ inference tətbiq olunur.
- Heç vaxt işləməyən `reviews_before_refund` field-i saxta 0 siqnalı yaratmaması üçün UI, validator və evaluator-dan çıxarıldı; legacy DB sütunu təhlükəsiz upgrade üçün saxlanıldı.
- Phase 6 verification: 234 unit test / 375 assertion və 189 integration test / 484 assertion uğurla keçdi; Phase 6 targeted integration 3 test / 17 assertion-dır.

---

## Phase 7 — PRO Refund Defense Workflow

**Status: tamamlandı — 24 avqust 2026**

### Məqsəd

TrustLens-i refund baş verdikdən sonra xəbər verən sistemdən refund qərarını qoruyan sistemə çevirmək.

### İşlər

- WooCommerce order ekranında Refund Risk Preview yaratmaq.
- Tövsiyə olunan qərarlar əlavə etmək:
  - instant refund
  - refund after return received
  - manager approval required
  - warehouse inspection required
  - manual investigation required
- Refund manager approval workflow yaratmaq.
- Riskli refund üçün hold/release mexanizmi yaratmaq.
- Original-payment-method-only siyasəti əlavə etmək.
- RMA case və return statusları əlavə etmək.
- Warehouse inspection checklist yaratmaq.
- Foto, serial number və item-condition evidence əlavə etmək.
- Eyni tracking number-in təkrar istifadəsini aşkar etmək.
- Refund risk case inbox və SLA əlavə etmək.
- Linked fraud cluster-də digər açıq order-ləri göstərmək.
- Profit-at-Risk hesablaması əlavə etmək:
  - refund amount
  - COGS
  - shipping cost
  - restocking/recovery value
  - customer lifetime value

### Qəbul meyarları

- Merchant refund verməzdən əvvəl risk və səbəbləri görür.
- Trusted/VIP müştəri üçün aşağı friction workflow mümkündür.
- Riskli refund manager və ya inspection təsdiqi olmadan tamamlanmır.
- Bütün qərarlar audit log-da saxlanılır.

### İcra nəticəsi

- WooCommerce order edit ekranına explainable Refund Risk Preview əlavə edildi; risk score, səbəblər, tövsiyə, refund ratio və Profit-at-Risk refund verilməzdən əvvəl görünür.
- Deterministik qərar mühərriki `instant_refund`, `refund_after_return_received`, `manager_approval_required`, `warehouse_inspection_required` və `manual_investigation_required` nəticələrini qaytarır; Trusted/VIP seqmentlərinə aşağı-friction credit verir.
- `trustlens_refund_cases` və append-only `trustlens_refund_case_events` cədvəlləri RMA statusunu, SLA-nı, assignment/approval/release identity-sini, səbəbləri və bütün qərar hadisələrini saxlayır.
- `woocommerce_create_refund` universal gate-i riskli case `released` olmadan refund-u dayandırır, released məbləğindən artıq refund-u rədd edir və original-payment-method-only siyasətini qoruyur.
- Global enforcement safe rollout üçün default off-dur; merchant konkret order-də case açan kimi həmin order dərhal qorunan rejimə keçir. PRO General Settings-dən qlobal rejim və 1–720 saat SLA aktivləşdirilə bilir.
- Warehouse checklist item/SKU match, condition və contents yoxlamalarını tələb edir; foto attachment ID-ləri, serial number və item condition evidence kimi saxlanır.
- Tracking number normallaşdırılmış HMAC ilə müqayisə edilir; başqa case-də təkrar istifadəsi investigation statusu və release blocker yaradır.
- Refund Cases inbox açıq case-ləri SLA deadline-a görə sıralayır və overdue işləri vurğulayır.
- Güclü linked-account cluster-ində processing/pending/on-hold order-lər cari order panelində göstərilir.
- Profit-at-Risk refund amount, COGS, shipping, recovery/resale value və Trusted/VIP CLV exposure komponentlərini ayrıca göstərir.
- Phase 7 verification: 239 unit test / 386 assertion və 193 integration test / 498 assertion uğurla keçdi; Phase 7 targeted testləri 9 test / 25 assertion-dır.

---

## Phase 8 — Test, migration və təhlükəsiz rollout

**Status: tamamlandı — 24 avqust 2026**

### Məqsəd

Yeni refund sistemini mövcud mağaza məlumatlarını pozmadan production-a çıxarmaq.

### Test ssenariləri

- Eyni refund ID-nin iki dəfə işlənməsi.
- Eyni anda yaradılan iki partial refund.
- Partial → full keçidi.
- Refund update və deletion.
- Historical Sync → yeni partial refund.
- Live data → Historical Sync → dəyişməyən nəticə.
- 40 + 60 cumulative full-refund parity.
- Zero-total və order total-dan artıq refund edge-case-ləri.
- Shipping-only və tax-only refund.
- Itemized olmayan manual refund.
- Deleted product və variation refund-u.
- Multi-currency refund.
- Guest customer və dəyişdirilmiş billing email.
- Duplicate live/synthetic event qoruması.
- Category aggregate parity.
- Automation replay protection.
- Refund notification distinct-order counting.

### Rollout planı

- Ledger-i əvvəlcə shadow mode-da doldurmaq.
- Köhnə və yeni hesablamaları admin-only müqayisə panelində göstərmək.
- Mismatch telemetry və reconciliation report yaratmaq.
- Migration-u batch-lərlə Action Scheduler üzərindən işlətmək.
- Migration tamamlanmadan köhnə aggregate-ləri silməmək.
- Ledger nəticələri stabil olduqdan sonra read path-i yeni sistemə keçirmək.
- Lazım olduqda təhlükəsiz rollback üçün köhnə sütunları bir release dövrü saxlamaq.

### Qəbul meyarları

- Mövcud mağaza məlumatları itmir.
- Migration restart və retry zamanı idempotent qalır.
- Köhnə və yeni aggregate-lər arasındakı fərqlər izah edilə bilir.
- Unit və integration suite tam keçir.
- Production read path yalnız shadow comparison uğurlu olduqdan sonra dəyişir.

### İcra nəticəsi

- `trustlens_refund_reconciliation` immutable legacy snapshot-ları və ledger müqayisə nəticələrini saxlayır; mismatch-lər `explained`, `unexplained` və `match` kimi təsnif edilir.
- Action Scheduler migration state-i page checkpoint, completed-page siyahısı, retry sayı və processed-order sayını saxlayır; köhnə/stale job progress-i iki dəfə artırmır.
- Upgrade backfill-i açıq `shadow` rejiminə keçir, mövcud read path-i legacy snapshot üzərində saxlayır və yalnız migration tamamlanıb unexplained mismatch sıfır olduqda ledger cutover-a icazə verir.
- Admin-only Data Settings paneli migration progress-i, parity xülasəsini, reconciliation sətirlərini, manual compare, guarded cutover və rollback əməliyyatlarını göstərir.
- GDPR erase axını reconciliation snapshot-larını, refund case-lərini və onların audit event-lərini də silir.
- Phase 8 targeted verification: 9 test / 25 assertion; tam regression: 243 unit test / 394 assertion və 198 integration test / 515 assertion uğurla keçdi.

### Post-implementation sistem auditi — 24 avqust 2026

- Plugin runtime versiyası header və DB schema versiyası ilə uyğunlaşdırıldı (`1.3.16`).
- Refund create/update/delete lifecycle-i WooCommerce admin, legacy/CPT, REST v3 və REST v4 yollarında ledger və product/category projection-larına bağlandı.
- Shadow rollout-da işlənməmiş müştərilərin itməsi, live-write snapshot race-i, pending comparison cutover-u və migration page-skip boşluğu bağlandı.
- Refund sahibinin billing email-i dəyişdikdə həm köhnə, həm yeni customer aggregate və category projection-ları yenidən qurulur.
- Ledger yazı xətaları migration/backfill/live reconcile axınlarında bounded retry və terminal logging ilə idarə olunur.
- Refund Defense risk siqnalının mənfi trust-score-dan müsbət risk balına çevrilməsi düzəldildi; bağlanmış case-lə enforcement bypass aradan qaldırıldı.
- Case yaratma və tracking-number yoxlaması advisory lock-larla race-safe edildi; immutable serial tələbi, real image evidence və item-condition validation əlavə olundu.
- SLA müqayisəsi UTC-safe edildi, admin nəticə bildirişləri işlək hala gətirildi, case və append-only audit event-ləri GDPR export-a daxil edildi.
- Təkrarlanan delivery-evidence implementasiyası çıxarıldı və vahid canonical helper-a bağlandı; scheduler uninstall cleanup siyahısı yeni reconcile job-ları ilə tamamlandı.
- Final verification: 246 unit test / 401 assertion və 208 integration test / 537 assertion — cəmi 454 test / 938 assertion uğurla keçdi. Dəyişdirilən PHP fayllarının syntax yoxlaması və `git diff --check` təmizdir.

---

## Tövsiyə olunan release bölgüsü

### Release A — Data Integrity

- Phase 0
- Phase 1
- Phase 2
- Phase 8-in ledger və migration testləri

### Release B — Accurate Intelligence

- Phase 3
- Phase 4
- Phase 5
- Analytics və scoring regression testləri

### Release C — Refund Automation Pro

- Phase 6
- Refund-specific webhook və notification-lar
- Automation replay protection

### Release D — Refund Defense Pro

- Phase 7
- RMA, approval və inspection workflow
- Profit-at-Risk və case management

## Birinci implementasiya paketi

İlk sprint/release üçün tövsiyə olunan minimum paket:

1. Canonical refund classifier.
2. `trustlens_refunds` ledger cədvəli.
3. Unique refund idempotency.
4. Live refund ingest.
5. Historical Sync ledger backfill.
6. Refund update/delete reconciliation.
7. Customer aggregate rebuild.
8. Duplicate və parity integration testləri.

Bu paket tamamlanmadan scoring, AI recommendation və refund approval workflow-a keçmək tövsiyə edilmir.
