📊 POS CSV Historical Transaction Importer

The real_rewards_importer module allows bulk ingestion of legacy and store POS transaction CSV files with automated deduplication and exact order mapping.

---

1. CSV File Schema

The POS importer expects standard comma-separated values matching the following columns:

Column Name	Expected Type	Description	Sample Value
order_id	String / Integer	Unique store transaction ID. Used directly as Odoo POS Order Name.	420025398
client_user_id	String	Storefront or cash register code where sale occurred.	STORE_POM_01
date_order	Datetime (ISO)	Transaction timestamp in UTC or standard local format.	2026-05-10 14:30:00
member_card	String	Scanned loyalty card number.	2000000012345
amount_total	Float	Gross receipt spend in PNG Kina.	45.95
points_awarded	Integer / Float	Calculated loyalty points (will be integer-truncated by backend).	45

---

2. Deduplication & Idempotency Engine

flowchart TD
    Row["Read CSV Transaction Row"] --> Check{"Does order_id exist in pos.order?"}
    Check -->|"Yes (Duplicate)"| Skip["⏭️ Skip Record & Log Warning"]
    Check -->|"No (New)"| LookupPartner{"Find Member by Card or UUID"}
    LookupPartner -->|"Found"| CreateOrder["Create pos.order with exact order_id"]
    CreateOrder --> Truncate["Truncate points: int(points_awarded)"]
    Truncate --> Ledger["Post entry to real.rewards.loyalty.ledger"]
    LookupPartner -->|"Not Found"| CreateAnon["Create Order with Unknown Loyalty Member Flag"]

---

3. Web Wizard Execution

1. Log into Odoo as an authorized operator.
2. Navigate to Point of Sale > Configuration > POS CSV Importer.
3. Attach the CSV file(s) to the file uploader.
4. Click Execute Import.
5. The system displays a progress dialog and generates an import summary log upon completion.