@miraiva_test/miravia-order-report 0.1.13

package/dist/reference.md

@@ -0,0 +1,409 @@
+# Reference · API Fields & Excel Column Mapping
+
+This Skill strictly follows PRD §Order Detail Export clauses. Each row = one **Miravia sub-order** (`order_item_id`).
+
+## Data Sources
+
+| API | Purpose | Client Method |
+|-----|---------|---------------|
+| `GET /orders/get` | Main order basic info (paginated) | `MiraviaClient.iter_orders()` |
+| `GET /orders/items/get` | Sub-order product / amount / logistics / cancellation info | `MiraviaClient.get_multi_order_items()` |
+| `GET /reverse/getreverseordersforseller` | Refund / reverse orders (joined by `order_item_id`) | `MiraviaClient.get_reverse_orders()` |
+
+### Main Order API `/orders/get` Parameters (strictly per official docs)
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `created_after` / `created_before` | String | One pair required (with `update_after/before`) | ISO 8601, e.g. `2026-05-19T00:00:00+08:00` |
+| `update_after` / `update_before` | String | Same as above | For incremental sync scenarios |
+| `status` | String | No | Single value: `unpaid / pending / repacked / packed / ready_to_ship / shipped / delivered / returned / canceled / failed / lost` |
+| `limit` | Number | No | Page size, max 100, default 100 |
+| `offset` | Number | No | Default 0; **`offset + limit ≤ 5000`** (server hard limit) |
+| `sort_by` / `sort_direction` | String | No | `created_at` / `updated_at`; `ASC` / `DESC` |
+| `marketplace` | String | No | Marketplace identifier |
+| `country` | String | No | Country |
+| `buyer_id` | String | No | Buyer ID |
+| `channel` | String | No | ★ Channel: `AE` / `Miravia` |
+| `ship_to` | String | No | ★ Ship-to country: `ES` / `PT` |
+| `buyer_ids` | String | No | ★ Batch buyer IDs |
+| `filter_unpaid` | Boolean | No | ★ Filter unpaid orders |
+| `filter_hold` | Boolean | No | ★ Filter orders in hold status |
+
+> ⚠️ **Known Pitfalls**:
+> 1. The official docs spell the parameter as `limt` (missing an `i`) — this is a **documentation typo**. The gateway actually accepts `limit` (consistent with Lazada/AE). Code uses `limit` uniformly; do not be misled by the docs.
+> 2. **`offset + limit ≤ 5000`** is a server hard limit; exceeding it returns an error. This Skill exits early in `MiraviaClient.iter_orders` when approaching the limit; if `countTotal > 5000`, callers must split time windows (e.g. by day/hour) and re-fetch.
+> 3. Response fields `data.countTotal` / `data.count` are Strings; use `int(...)` for conversion.
+
+### Forward Order `/orders/get` Full Response Fields
+
+> Below is the complete response field reference from API docs. ★ = fields newly used in v4 dashboard.
+
+#### Main Order Level (`data.orders[]`)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `order_id` | String | Main order ID |
+| `marketplace` | String | Marketplace identifier |
+| `created_at` | String | Order creation time (ISO 8601) |
+| `items_count` | Number | Number of items |
+| `payment_method` | String | Payment method |
+| `buyer_id` | String | Buyer ID |
+| `customer_first_name` | String | Buyer first name |
+| `customer_last_name` | String | Buyer last name |
+| `address_shipping` | Object | Shipping address (OpenAddressDTO) |
+| `warehouse_code` | String | Warehouse code |
+| `voucher_platform` | String | Platform voucher amount |
+| `order_type` | String | Order type |
+| `channel` | String | ★ Channel (AE/Miravia) |
+| `remarks` | String | Buyer remarks |
+| `delivery_info` | String | Delivery info |
+
+#### Sub-Order Level (`order_items[]` / `/orders/items/get`)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `order_item_id` | String | Sub-order ID |
+| `status` / `Status` | String | Sub-order status |
+| `updated_at` | String | Update time |
+| `product_id` | String | Product ID |
+| `name` | String | Product name |
+| `product_main_image` | String | Product main image URL |
+| `sku` | String | Platform SKU |
+| `shop_sku` | String | Seller SKU |
+| `quantity` | Number | Quantity |
+| `item_price` | String | Unit price |
+| `paid_price` | String | Paid amount |
+| `voucher_amount` | String | Total voucher amount |
+| `voucher_platform` | String | Platform discount |
+| `voucher_seller` | String | Seller discount |
+| `voucherSellerLPI` | String | ★ Seller LPI voucher |
+| `VoucherCode` | String | ★ Voucher code |
+| `voucherCodeSeller` | String | ★ Seller voucher code |
+| `shipping_amount` | String | Shipping amount |
+| `shippingFeeOriginal` | String | ★ Original shipping fee |
+| `shippingFeeDiscountSeller` | String | ★ Seller shipping discount |
+| `currency` | String | Currency |
+| `WalletCredits` | String | ★ Wallet credits deduction |
+| `TaxAmount` | String | ★ Tax amount |
+| `ShippingType` | String | ★ Shipping type |
+| `ShippingProviderType` | String | Logistics provider type |
+| `ShipmentProvider` | String | Logistics provider name |
+| `TrackingCode` | String | Tracking number |
+| `PackageId` | String | Package ID |
+| `IsDigital` | String | ★ Digital product flag (`1`/`0`) |
+| `isSOF` | String | ★ Seller-own-fulfillment flag (`1`/`0`) |
+| `isFBL` | String | ★ Fulfilled-by-Lazada/Miravia flag (`1`/`0`) |
+| `isReroute` | String | ★ Reroute flag (`1`/`0`) |
+| `CancelReturnInitiator` | String | Cancel/return initiator |
+| `Reason` | String | Cancellation reason |
+| `ReasonDetail` | String | Cancellation reason detail |
+| `refundAmount` | String | ★ Forward order refund amount |
+| `orderFlag` | String | ★ Order flag |
+| `channel` | String | ★ Sub-order channel (AE/Miravia) |
+| `shipTo` | String | ★ Ship-to country (ES/PT) |
+| `returnable` | Boolean | ★ Whether returnable |
+| `sellerRemarkText` | String | ★ Seller remarks |
+| `buyerRemarkText` | String | ★ Buyer remarks |
+| `Variation` | String | ★ Variation attributes (color, size, etc.) |
+
+#### Address Level (`OpenAddressDTO`, nested in `address_shipping`)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `FirstName` | String | Recipient first name |
+| `LastName` | String | Recipient last name |
+| `Phone` | String | Phone |
+| `Phone2` | String | Alternate phone |
+| `Address1` ~ `Address5` | String | Address lines 1-5 |
+| `CustomerEmail` | String | Email |
+| `City` | String | ★ City |
+| `PostCode` | String | Postal code |
+| `Country` | String | Country |
+
+---
+
+### Reverse Order API `/reverse/getreverseordersforseller` Parameters (complete, strictly per official docs)
+
+#### Common Parameters (same as all Open APIs)
+`app_key` / `timestamp` / `access_token` / `sign_method` / `sign` are required; `isv_channel` is optional. Injected uniformly by `MiraviaClient._common_params()` + `generate_sign()`; business logic need not handle these.
+
+#### Business Parameters (13 total)
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `page_size` | Number | **Yes** | Page size, default 10; this Skill defaults to 100 |
+| `page_no` | Number | **Yes** | Page number, starting from 1 |
+| `trade_order_id` | Number | No | **Filter by forward main order ID** — single-order reverse query entry |
+| `reverse_order_id` | Number | No | Filter by reverse order ID |
+| `reverse_tracking_number` | String | No | Filter by return tracking number, e.g. `TN23423` |
+| `trade_order_time_range_start_time_stamp` | Number | No | Main order creation start time, **millisecond timestamp** |
+| `trade_order_time_range_end_time_stamp`   | Number | No | Main order creation end time, **millisecond timestamp** |
+| `reverse_order_line_time_range_start_time_stamp` | Number | No | Reverse order line creation start time, **millisecond timestamp** |
+| `reverse_order_line_time_range_end_time_stamp`   | Number | No | Reverse order line creation end time, **millisecond timestamp** |
+| `reverse_status_list` | String[] | No | JSON array string, see "reverse_status enum" below |
+| `ofc_status_list` | String[] | No | JSON array string, return logistics status, see "ofc_status enum" below |
+| `dispute_in_progress` | Boolean | No | Whether dispute is in progress |
+| `marketplace` | String | No | Marketplace: `ae` / `miravia`, empty returns all |
+
+##### reverse_status Enum (used in both request filter and response fields)
+
+```
+REQUEST_INITIATE        Buyer initiated request
+REQUEST_REJECT          Request rejected
+REQUEST_CANCEL          Request cancelled
+CANCEL_SUCCESS          Cancellation succeeded
+REPLACE_PENDING         Replacement pending
+REPLACE_WAIT_AUDIT      Replacement awaiting audit
+REPLACE_SUCCESS         Replacement succeeded (note: official docs have typo: dREPLACE_SUCCESS)
+REFUND_PENDING          ★ Refund pending (key status to monitor)
+REFUND_AUTHORIZED       Refund authorized
+REFUND_SUCCESS          ★ Refund succeeded (key status to monitor)
+REFUND_REJECT           Refund rejected
+REQUEST_COMPLETE        Request completed
+SELLER_AGREE_RETURN     Seller agreed to return
+SELLER_REJECT_RETURN    Seller rejected return
+BUYER_RETURN_ITEM       ★ Buyer has returned item (key status to monitor)
+SELLER_AGREE_REFUND     Seller agreed to refund
+SELLER_REJECT_REFUND    Seller rejected refund
+CS_APPROVING            CS reviewing
+AGREE_CANCEL_ORDER      Agreed to cancel order
+REJECT_CANCEL_ORDER     Rejected cancel order
+```
+
+##### ofc_status Enum (OrderFulfillmentCenter / return logistics status)
+
+```
+RETURN_PICKUP_PENDING     Pending pickup
+RETURN_TPL_RECEIVED       ★ 3PL received, in transit to seller/warehouse
+RETURN_DELIVERED          ★ Delivered to seller/warehouse
+RETURN_STOCK_INBOUND      ★ Miravia warehouse inbound completed
+RETURN_QC_DONE            ★ Warehouse QC completed
+RETURN_LOGISTIC_CLOSURE   ★ Warehouse refund/reject decision made
+```
+
+##### request_type Enum (response field, reverse request type)
+
+```
+CANCEL          Cancellation
+RETURN          Return
+REPLACEMENT     Replacement
+ONLY_REFUND     Refund only
+```
+
+##### refund_payment_method Enum (response field, refund method)
+
+```
+CARD_APPLE_PAY / CARD_GOOGLE_PAY / DIRECTDEBIT_PAYPAL / MIXEDCARD
+NO_REFUND / ONLINE_BANKING_BIZUM / WALLET_PAYPAL_PAYLATER
+```
+
+##### shipping_type Enum (response field, return shipping method)
+
+```
+DEFAULT / PICK_UP / DROP_OFF / CUSTOMER_SEND
+```
+
+#### Two Correct Approaches for Single-Order Queries
+
+| Seller Need | Recommended Parameters |
+|-------------|----------------------|
+| Check refund/return full status for a specific order | `trade_order_id=<main_order_id>` + `page_size=100, page_no=1` (no time window needed) |
+| Known reverse order ID, query details | `reverse_order_id=<reverse_order_id>` |
+| Known return tracking number, reverse lookup order | `reverse_tracking_number=<TN...>` |
+| Batch refund rate diagnosis / Top refund SKUs | `trade_order_time_range_start_time_stamp/...end...` (milliseconds) + `reverse_status_list=[REFUND_SUCCESS,REFUND_PENDING,...]` |
+
+> ⚠️ **Historical Pitfalls** (retained as warning): The following parameters **do not exist** and will be silently ignored by the server (returning all data); do not use them:
+> - `start_create_time` / `end_create_time` (incorrect field names, and not millisecond timestamps)
+> - `status` (single value) and enums like `REQUESTING / REFUNDING / CLOSED / REJECTED`
+>
+> The server has a deep pagination limit around `page_no >= ~31` (offset > 3000).
+> This Skill uses `max_pages=30` in batch scenarios; if `total` exceeds the limit, split time windows and re-fetch.
+> **For single-order queries**, use `trade_order_id` for exact filtering — results are typically 1 to a few records, never hitting pagination limits.
+
+### Reverse Order `/reverse/getreverseordersforseller` Full Response Fields
+
+> Below is the complete response field reference from API docs. ★ = fields newly used in v4 dashboard.
+> ⚠️ The reverse sub-order `refundAmount` unit is **cents**; divide by 100 to convert to currency units.
+> ⚠️ `requestType` is at the **main order level**, not sub-order level; `_flatten()` must propagate it from main to sub-order level.
+
+#### Main Order Level (`data.items[]`, `OpenApiReverseOrderResponse`)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `reverseOrderId` | Number | Reverse order ID |
+| `tradeOrderId` | Number | Forward main order ID |
+| `requestType` | String | ★ Refund type: `CANCEL` / `RETURN` / `ONLY_REFUND` / `REPLACEMENT` |
+| `shippingType` | String | ★ Shipping method (see `shipping_type` enum) |
+| `rtm` | Boolean | ★ Whether seller warehouse |
+| `bizType` | String | ★ Business type |
+| `marketplace` | String | Marketplace identifier |
+| `shipFrom` | String | ★ Ship-from location |
+| `instantRefund` | Boolean | ★ Whether instant (small-amount) refund |
+| `reverseOrderLineDTOList` | Array | Reverse sub-order list |
+
+#### Sub-Order Level (`reverseOrderLineDTOList[]`, `OpenApiReverseOrderLineDTO`)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `reverseOrderLineId` | Number | Reverse sub-order ID |
+| `tradeOrderLineId` | Number | Forward sub-order ID (= `order_item_id`) |
+| `platformTradeOrderItemId` | Number | Platform sub-order ID |
+| `marketplace` | String | Marketplace identifier |
+| `reverseStatus` | String | Reverse status, see `reverse_status` enum |
+| `ofcStatus` | String | Return logistics status, see `ofc_status` enum |
+| `isDispute` | Boolean | Whether in dispute |
+| `isNeedRefund` | Boolean | Whether refund is needed |
+| `actions` | String | Available actions |
+| `refundAmount` | Number | Refund amount (**unit: cents**, divide by 100) |
+| `refundCurrency` | String | Refund currency |
+| `refundPaymentMethod` | String | ★ Refund payment method, see enum |
+| `itemUnitPrice` | Number | Item unit price |
+| `isFastRefund` | Boolean | Whether fast refund |
+| `isInstantRefund` | Boolean | Whether instant refund |
+| `isNotReceived` | Boolean | ★ Whether buyer has not received goods |
+| `reasonText` | String | Refund reason text |
+| `reasonCode` | String | ★ Refund reason code |
+| `dutyParty` | String | ★ Refund duty party: `SELLER` / `PLATFORM` / `LOGISTIC` / `pending` |
+| `whqcDecision` | String | ★ Warehouse QC decision |
+| `trackingNumber` | String | Return tracking number |
+| `returnShippingFee` | Number | ★ Return shipping fee |
+| `affordReturnShippingFee` | Boolean | ★ Whether seller bears return shipping |
+| `returnable` | Boolean | ★ Whether returnable |
+| `goodsStatus` | String | ★ Goods status |
+| `refundItemCounts` | Number | ★ Refund item count |
+| `returnOrderLineGmtCreate` | String | Reverse sub-order creation time |
+| `returnOrderLineGmtModified` | String | Reverse sub-order update time |
+| `tradeOrderGmtCreate` | String | Forward main order creation time |
+| `buyer` | Object | Buyer info (contains `userId`) |
+| `sellerSkuId` | String | ★ Seller SKU ID |
+| `platformSkuId` | String | ★ Platform SKU ID |
+| `eanNumber` | String | ★ EAN barcode |
+| `productDTO` | Object | ★ Product info {`id`, `sku`} |
+| `features` | Object | Extended features |
+
+---
+
+## Field Mapping
+
+> All column names are defined in `scripts/export_orders.py` constant `EXPORT_COLUMNS`.
+
+### Main Order Basic Info (from `/orders/get`)
+| Excel Column | API Field | Description |
+|--------------|-----------|-------------|
+| `order_id` | `order_id` | Main order ID |
+| `marketplace` | `marketplace` / `country` | Marketplace |
+| `created_at` | `created_at` | Order creation time |
+| `items_count` | `items_count` | Total items in order |
+| `payment_method` | `payment_method` | Payment method |
+| `buyer_id` | `customer_first_name` / `buyer_id` | Buyer identifier (masked) |
+| `ship_address` | `address_shipping` concatenated | Shipping address |
+| `ship_country` | `address_shipping.country` | Ship-to country |
+| `warehouse_code` | `warehouse_code` | Shipping warehouse |
+| `buyer_remark` | `remarks` | Buyer remarks |
+| `seller_remark` | `delivery_info` | Seller remarks |
+
+### Sub-Order Basic (from `/orders/items/get`)
+| Excel Column | API Field |
+|--------------|-----------|
+| `order_item_id` | `order_item_id` |
+| `item_status` | `status` |
+| `item_updated_at` | `updated_at` |
+
+### Products
+| Excel Column | API Field |
+|--------------|-----------|
+| `product_id` | `product_id` |
+| `product_name` | `name` |
+| `product_url` | `product_main_image` |
+| `sku` | `sku` |
+| `shop_sku` | `shop_sku` |
+| `quantity` | Fixed 1 (API returns one row per item) |
+| `unit_price` | `item_price` |
+
+### Amounts
+| Excel Column | API Field |
+|--------------|-----------|
+| `buyer_paid` | `paid_price` |
+| `discount_total` | `voucher_amount` |
+| `discount_platform` | `voucher_platform` |
+| `discount_seller` | `voucher_seller` |
+| `shipping_paid` | `shipping_amount` |
+| `shipping_disc_total` | `shipping_amount_voucher` |
+| `shipping_disc_platform` | `shipping_service_cost` |
+| `shipping_disc_seller` | `shipping_amount_seller` |
+| `currency` | `currency` |
+
+### Logistics
+| Excel Column | API Field |
+|--------------|-----------|
+| `shipment_type` | `shipment_type` |
+| `tracking_no` | `tracking_code` |
+| `package_id` | `package_id` |
+| `shipping_provider` | `shipping_provider_type` / `shipping_provider` |
+
+### Cancellation
+| Excel Column | Source |
+|--------------|--------|
+| `is_canceled` | `cancel_return_initiator` non-empty or `status in ('canceled','cancelled')` |
+| `cancel_initiator` | `cancel_return_initiator` |
+| `cancel_reason` | `reason` / `reason_detail` |
+
+### Refunds (from `/reverse/getreverseordersforseller`, joined by `trade_order_line_id == order_item_id`)
+| Excel Column | API Field |
+|--------------|-----------|
+| `refund_id` | `reverse_order_id` / `dispute_id` |
+| `refund_apply_at` | `reverse_order_lines[].return_order_line_gmt_create` / `trade_order_gmt_create` |
+| `refund_status` | `reverse_order_lines[].reverse_status` |
+| `refund_amount` | `reverse_order_lines[].refund_amount` |
+| `refund_reason` | `reverse_order_lines[].reason_text` |
+| `is_fast_refund` | `reverse_order_lines[].is_fast_refund` |
+| `is_instant_refund` | `reverse_order_lines[].is_instant_refund` |
+| `refund_tracking_no` | `reverse_order_lines[].tracking_number` |
+
+## HTML Report Fields
+
+### v4 Unified Dashboard (`templates/report_v4.html`)
+
+Data is injected via `window.DATA = {...}` JSON; frontend JS renders dynamically. 6 Tabs:
+
+| Tab | Key Metrics |
+|-----|-------------|
+| Overview | KPI cards (orders/GMV/refund rate/cancel rate), executive summary, country distribution |
+| Sales Performance | Daily trends, net revenue, AOV tiers, payment methods, seller discounts, shipping stats, order status |
+| Cancellations & Refunds | Cancel initiator, seller approval rate, cancel reasons, refund types, duty party, refund reasons, fast refund, refund SKUs |
+| Product Insights | Top SKUs, SKU matrix (volume × refund rate), category distribution, discount depth, FBM ratio, digital vs physical |
+| Buyers & Markets | Buyer KPIs, country detail table, city distribution, country sparklines, payment × country, anomalous buyers |
+| Logistics & Fulfillment | Logistics provider distribution, FBM comparison, delivery types |
+
+Frontend interactions: Time range filter (7d/15d/30d/all) + Platform switch (All/Miravia/M2A)
+
+## Signature Rules Quick Reference
+
+```
+api_path + key1 + value1 + key2 + value2 + ...   (keys sorted ascending, empty values filtered out, sign excluded)
+       ↓ HMAC-SHA256(secret)
+       ↓ .hexdigest().upper()
+=  sign
+```
+
+Implementation: `scripts/miravia_client.py::generate_sign`
+
+## Excel Text Format Specification
+
+The following columns contain long numeric string IDs and **must be written as text format** to avoid Excel displaying them in scientific notation or losing precision:
+
+```
+order_id, order_item_id, product_id, sku, shop_sku,
+package_id, tracking_no, refund_id, refund_tracking_no, buyer_id
+```
+
+Implementation: `scripts/export_orders.py::export_dataframe` uses `TEXT_ID_COLUMNS`, converting to pure strings + openpyxl `number_format='@'` as double insurance.
+
+## Error Handling Conventions
+
+| Error Code | Behavior |
+|------------|----------|
+| `IncompleteSignature` / `InvalidAccessToken` | Terminate; prompt user to re-authorize |
+| HTTP network errors | Auto-retry 3 times (exponential backoff, max 5s) |
+| `/reverse/...` failure | Soft failure, continue generating report without refund columns |
+| Sub-order count ≥ `--max-orders` | Exit code 2, suggest narrowing time range |

package/dist/requirements.txt

@@ -0,0 +1,6 @@
+# Miravia Order Report Dependencies
+requests>=2.28.0
+pandas>=1.5.0
+openpyxl>=3.0.10
+jinja2>=3.1.0
+cryptography>=41.0