# 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.