SRV-30 — V2 — Loyalty engine (points, levels, rewards, vouchers)
Points ledger, earning on delivery/payment, expiry job, reversals, level computation over a period, rewards catalogue, redemptions and vouchers usable at checkout.
| Field | Details |
|---|---|
| Task code | SRV-30 |
| Phase | P4 — V2 evolutions |
| Product scope | V2 |
| Status | Planned |
| Start | Sun 24 Jan 2027 |
| Due | Wed 27 Jan 2027 |
| Responsible | Anis — Full-stack developer |
| Co-responsible | — |
| Effort | 3 person-day(s) planned · 8 from scratch · size M |
| Area · app | Server · server |
| Depends on | SRV-29 |
| Unblocks | SRV-31 |
| Milestones | — |
Summary
Points ledger, earning on delivery/payment, expiry job, reversals, level computation over a period, rewards catalogue, redemptions and vouchers usable at checkout.
Description
Advanced loyalty is V2 (cahier §4.4, §4.6, §5.5, §14.2; LOY-01…LOY-05, PRC-03). This task implements the points ledger (LoyaltyAccount, LoyaltyTransaction with EARN, BONUS, REDEEM, EXPIRE, ADJUST, REVERSAL), earning on delivery or payment according to a setting, bonuses, the expiry job, reversals when an order is cancelled or a return is received (V1 returns emit the events), levels Bronze, Silver, Gold and VIP computed over a rolling period with client-validated thresholds, the rewards catalogue and redemptions, and vouchers usable at checkout through the cart engine. It also adds the V2 pricing layer of PRC-03 — per-reseller price agreements and level-based prices on top of the three customer-type prices (PriceList, PriceListItem). Out of scope: loyalty pages (DSH-21, WEB-20, mobile).
Subtasks
| # | Subtask | Owner |
|---|---|---|
| 1 | Ledger services with balance invariants and admin.loyalty.adjust (ADJUST with reason) | Anis |
| 2 | Earning rules (points per amount, earn on DELIVERED or on invoice PAID by setting) and bonuses | Anis |
| 3 | Expiry job (FIFO expiry after the configured period) and REVERSAL on order cancellation and return reception | Anis |
| 4 | Level computation job over the rolling period with thresholds and level-change notifications | Anis |
| 5 | Rewards catalogue (RewardType) with admin.rewards.crud, redemptions and admin.redemptions fulfilment | Anis |
| 6 | Vouchers generated by redemption and applied by the cart engine at checkout | Anis |
| 7 | PriceList / PriceListItem agreements and level-based adjustments in the price resolver (customer-type price → agreement → level → promotions) | Anis |
| 8 | Reseller endpoints loyalty.summary, transactions, rewards, redeem, redemptions | Anis |
Deliverables
- apps/server/src/modules/loyalty/{ledger,earning,levels,rewards,vouchers}.service.ts, jobs.ts, router.ts
- apps/server/src/modules/pricing/agreements.ts
- Prisma migration adding the V2 loyalty and price-agreement models
Acceptance criteria
- The balance always equals the sum of transactions; a cancelled order's points are reversed (LOY-02, LOY-05)
- Points expire per the configured period and appear as EXPIRE transactions (LOY-02)
- A reseller crossing the Gold threshold over the period moves to Gold and is notified (LOY-03)
- A voucher from a redemption reduces the cart total once and cannot be reused (LOY-04)
- A reseller with a price agreement gets the agreed price instead of their customer-type price, and promotions apply on top (PRC-03)
Requirements covered
| Requirement | Title | Release |
|---|---|---|
| LOY-01 | Points earned per order, credited after delivery or payment (setting), bonuses | V2 |
| LOY-02 | Points expiry, adjustments and reversal on cancellation or refund | V2 |
| LOY-03 | Levels Bronze, Silver, Gold, VIP over a period with client-validated thresholds | V2 |
| LOY-04 | Rewards catalogue (voucher, free delivery, discount, gift, early access) and redemption | V2 |
| LOY-05 | Traceable points history for the reseller and the back-office | V2 |
| PRC-03 | Per-reseller price agreements and level-based prices on top of the three customer-type prices | V2 |
API surface
| Endpoint group | Operations |
|---|---|
| Loyalty (V2) | 5 |
| Promotions & loyalty | 10 |
Test measures
- DB tests for ledger invariants under concurrent earn/redeem
- Job tests for expiry and levels with a fake clock
- Unit tests for the extended price resolution order
Risks
- Thresholds and earning rates not validated by HOCO — all values are settings and the ledger is replayable
KPI
- Delivered by Wed 27 Jan 2027 within 3 person-day(s).
- Every acceptance criterion above demonstrated before hand-off; linked requirements' acceptance criteria pass.
- Zero open critical defects, permission gaps or data-integrity regressions at sign-off.
Generated from content/plan/tasks.json by scripts/generate-team-tasks.mjs. Dates are computed by the scheduler (Sunday–Thursday weeks, holidays excluded) — change the plan, not this page.