vitepress-template

Appearance

Refund and Return Processing ​

**Referenced Files in This Document** - [[after_sale_order.proto]](file/bi-basic/api/after-sale-order/v1/after-sale-order.proto) - [[AfterSaleOrder_API_Usage.md]](file/bi-basic/docs/aftersaleorder-api-usage.md) - [[after_sale_order.go (BO)]](file/bi-basic/internal/biz/bo/after-sale-order.go) - [[after_sale_order_test.go]](file/bi-basic/test/after-sale-order-test.go) - [[sql_order_view.go]](file/bi-analysis/internal/biz/sql-order-view.go) - [[sql_product_view.go]](file/bi-analysis/internal/biz/sql-product-view.go) - [[指标实现情况.md]](file/bi-analysis/docs/.md) - [[biz.go (Taobao Refunds)]](file/bi-api-leke/common/leke-helper/taobao/biz.go) - [[page.tsx (UI Refund List)]](file/ui-web/src/app/dashboard/basic/orders/after-sales/page.tsx)

Table of Contents ​

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction ​

This document describes the refund and return processing system across the refund data model, retrieval APIs, status tracking, amount and currency handling, order synchronization, reason categorization, customer communication triggers, audit trail maintenance, error handling, and integration with accounting systems for financial reconciliation. It focuses on the AfterSaleOrder domain, the display API for listing refunds, and the analytical views that compute refund metrics.

Project Structure ​

The refund and return system spans three major areas:

  • Data model and API surface for AfterSaleOrder
  • Business logic for refund display and filtering
  • Analytical views for refund metrics and reconciliation

Diagram sources

Section sources

Core Components ​

  • AfterSaleOrder data model defines refund records with composite primary keys, timestamps, quantities, reasons, amounts, offsets, buyer identifiers, and flags for full refund and trial orders.
  • Display API supports listing and filtering refunds with date ranges, shop, product, SKU, reason, flags, and payment time ranges.
  • Analytics views compute refund metrics by linking refund events to order data and categorizing by pre/post delivery and full/partial refund.

Section sources

Architecture Overview ​

The refund pipeline integrates external refund data (e.g., Taobao) into the AfterSaleOrder domain, which is then consumed by analytics views for reporting and reconciliation.

Diagram sources

Detailed Component Analysis ​

AfterSaleOrder Data Model and Fields ​

  • Composite primary key: order_id, shop_id, refund_id
  • Timestamps: refund_apply_time, refund_finish_time
  • Quantities and flags: quantity, is_full_refund, is_trial_order
  • Monetary fields: refund_amount, cost_offset, commission_offset
  • Descriptive fields: refund_type, refund_reason, after_sale_remark, buyer_uid
  • Display/business fields include product and SKU identifiers, platform, logistics, and payment time for correlation.

Diagram sources

Section sources

Refund Retrieval and Filtering via Display API ​

  • Endpoint: ListAfterSaleOrderDisplay
  • Filters supported:
    • Shop, order number, refund ID, refund type
    • Date ranges: refund application time and refund completion time
    • Flags: full refund, trial order, virtual order, net flag
    • Payment time range
    • Product/SKU identifiers
    • Refund reason (fuzzy match)
  • Pagination via limit and page
  • Response includes list, where conditions, totals, and summary metrics.

Diagram sources

Section sources

Refund Status Tracking ​

  • Refund lifecycle fields:
    • refund_apply_time: initiation
    • refund_finish_time: completion
  • Display fields include c_status and c_step_status for UI rendering.
  • External platform statuses (e.g., Taobao) map to internal representation during ingestion.

Diagram sources

Section sources

Refund Amount Calculation, Currency, and Tax Implications ​

  • Monetary fields:
    • refund_amount: total refund amount
    • cost_offset: cost offset
    • commission_offset: platform fee offset
  • Amounts are stored as floating-point doubles with two decimal precision.
  • Currency is implied by platform and stored as numeric values; no explicit currency field is present in the AfterSaleOrder model.
  • Tax implications are not modeled in the AfterSaleOrder schema; tax-related adjustments would require offsets or separate fields if needed.

Section sources

Integration with Order Synchronization for Correlation and Validation ​

  • AfterSaleOrder links to basic orders via order_id for correlation.
  • Analytics views join refund data with order data to compute metrics consistently.
  • The refund table lacks product ID directly; it is joined via order_id to extract product identifiers for aggregation.

Diagram sources

Section sources

Refund Reason Categorization and Customer Communication Triggers ​

  • refund_reason supports free-text reasons; fuzzy matching is available in filters.
  • c_type distinguishes refund categories such as BUYER_NOT_RECEIVED (pre-delivery) vs others (post-delivery).
  • c_remark_refund allows additional notes for customer communication.
  • UI page provides controls to filter by reason and date ranges for operational dashboards.

Section sources

Audit Trail Maintenance ​

  • Kafka message key recommended as order_id_refund_id to ensure idempotent upserts and partition locality.
  • Upsert semantics on composite primary key guarantee audit-safe updates without duplication.
  • Timestamps capture lifecycle events for auditability.

Section sources

Error Handling for Partial Refunds, Multiple Items, and Delays ​

  • Partial/full distinction: b_full_refund flag enables accurate aggregation of items and orders.
  • Virtual/trial flags support filtering for special categories.
  • Delays: refund_finish_time indicates completion; missing completion implies processing delay.
  • UI supports date-range selection for monitoring overdue refunds.

Section sources

Examples of Refund Processing Workflows ​

  • External platform refund ingestion:
    • Retrieve refunds via GetRefunds and OrderRefundsGet
    • Publish AfterSaleOrder messages to Kafka
    • Upsert into StarRocks table
  • Internal dashboard workflow:
    • Filter by shop, date ranges, reason, flags
    • Paginate and summarize refund metrics

Diagram sources

Section sources

Integration with Accounting Systems for Financial Reconciliation ​

  • Analytics views compute:
    • Total refund amount, pre/post delivery split, item counts, order counts, buyer counts
    • Cost and platform fee offsets derived from refund records
  • Metrics aligned with financial reconciliation:
    • d_refund, d_refund_pre, d_refund_after
    • i_refund_item, i_refund_ord, i_refund_byr
    • d_cost_goods_yoy, d_fee_platform_yoy

Diagram sources

Section sources

Dependency Analysis ​

  • API depends on BO for request/response shapes and filters.
  • Tests validate API behavior across multiple filter combinations.
  • Analytics views depend on refund and order tables for metric computation.
  • External integrations (Taobao) feed refund events into the system.

Diagram sources

Section sources

Performance Considerations ​

  • Prefer batch publishing for high-volume refund ingestion.
  • Use appropriate pagination (limit/page) and date-range filters to reduce payload sizes.
  • Ensure Kafka partitioning by order_id_refund_id to maintain upsert locality.
  • Monitor refund completion lag via refund_finish_time to detect processing delays.

Troubleshooting Guide ​

  • Validation failures: Ensure required fields (order_id, shop_id, refund_id) are present and formatted correctly.
  • Duplicate records: Verify unique Kafka message keys to prevent duplicates.
  • Missing product IDs: Confirm order_id linkage to retrieve product identifiers for analytics.
  • Excessive delays: Track refund_finish_time vs refund_apply_time to identify bottlenecks.

Section sources

Conclusion ​

The refund and return processing system centers on a robust AfterSaleOrder model, a flexible display API with rich filtering, and analytics views that enable financial reconciliation. By integrating external refund data, maintaining audit-safe upserts, and leveraging clear status and categorization fields, the system supports operational visibility, compliance, and accurate accounting.

Appendices ​

  • UI integration: The dashboard page demonstrates refund list retrieval and date-range filtering for operational monitoring.

Section sources