fix(bills): bind validated customer and award eligible cashback on zero-balance settlement #1254

Summary

When settling a bill whose remaining balance is 0 (prepared.length === 0 in applyPaymentBatch, e.g. after a 100% bill discount or kitchen delivery override) via POST /api/bills/:id/payment or POST /api/bills/:id/payments with a newly selected customer_id, the validated customer is not persisted to bills.customer_id and loyalty cashback calculation receives null instead of the effective customer ID.

Verified Reproduction

On 08187174bfa47f08154e2b9b64cdb17b0ef2c459:

1. Create an order and generate an unpaid bill (customer_id: null), then apply a 100% discount (or partial payment followed by discount so balance = 0).
2. Settle the bill via POST /api/bills/:id/payment or POST /api/bills/:id/payments passing a valid customer_id.
3. Observe that payment_status becomes 'paid', but bill.customer_id in both the HTTP 200 response and the SQLite bills row remains null, loyaltyPointsEarned is 0 (even when bill.total > 0 from an earlier partial payment), and payment_idempotency caches the unlinked response.

Root Cause

In main/routes/bills.ts:

• preparePaymentBatch (lines 2911-2944) validates bodyCustomerId against bill.customer_id and orders.customer_id (enforcing customer_mismatch and customer_unavailable) and returns effectiveCustomerId.
• The positive-payment branch (prepared.length > 0, lines 3537-3542) executes if (!bill.customer_id && effectiveCustomerId) UPDATE bills SET customer_id = ?, updated_at = ? WHERE id = ? before reading freshBill and computing calculateCashback(db, bill, effectiveCustomerId).
• The zero-balance settlement branch (prepared.length === 0, lines 3393-3477) omits the UPDATE bills SET customer_id = ? statement, then reads freshBill.customer_id (null) at line 3422 and passes null to calculateCashback.

Expected Behavior & Chosen Design

In applyPaymentBatch (main/routes/bills.ts), within the if (prepared.length === 0) branch, persist effectiveCustomerId to bills.customer_id when !bill.customer_id && effectiveCustomerId before re-reading freshBill and invoking calculateCashback, matching the positive-payment branch.

Acceptance Criteria

• Settling a zero-remaining-balance bill with a newly selected valid customer_id via POST /api/bills/:id/payment or POST /api/bills/:id/payments updates bills.customer_id and returns the bound customer_id in the response.
• Eligible loyalty cashback on zero-remaining-balance settlement (when freshBill.total > 0) is calculated and credited once in loyalty_ledger under the bound customer.
• Idempotent replay via Idempotency-Key returns the cached response with the bound customer and does not duplicate loyalty awards.
• Conflicting customer (customer_mismatch) and non-existent customer (customer_unavailable) rejections remain enforced.

Required Regression Tests

• Single payment (POST /api/bills/:id/payment) zero-balance settlement with newly selected customer_id.
• Batch payment (POST /api/bills/:id/payments) zero-balance settlement with newly selected customer_id.
• Zero-balance settlement after partial payment + discount (total > 0, balance = 0) with newly selected customer_id awards loyalty cashback once.
• Idempotent replay and conflicting/missing customer rejection checks.

Related Historical Context & Considerations

• Related PRs / Issue: fix(main): gate exact-balance discount auto-settlement on kitchen delivery status #1211, fix(billing): remediate loyalty re-award and zero-balance idempotency #1249, Bill discount endpoint permits invalid order state changes and lacks audit logging #1176
• Financial & Data Integrity Considerations: Aligns zero-balance settlement customer attribution and single-award loyalty cashback with the standard payment path inside withTxn.