# RetailOS — Phase 03: CRM

**Status:** Draft for review · **Depends on:** Phase 02 (Shop Owner Panel) sign-off — CRM reads from Customer Purchase History which is generated by POS/Sales
**Duration estimate:** সপ্তাহ ৭–৮ (UI prototype scope)
**Goal:** RetailOS-কে সাধারণ POS থেকে আলাদা করে তোলার মূল মডিউল — এটাই RetailOS-এর USP (v1.5 Growth release-এর মূল অংশ)।

---

## 1. Deliverable Checklist (per roadmap chip list)

| # | Module | Description |
|---|---|---|
| 1 | Lead Management | New → Contacted → Interested → Confirmed → Delivered → Repeat Customer pipeline |
| 2 | Follow-up Calendar | Scheduled follow-ups per lead, overdue alerts |
| 3 | Notifications Engine | Central queue for Call/WhatsApp/SMS reminders (feeds multiple modules) |
| 4 | Customer Purchase History | Full timeline per customer, sourced from Sales (Phase 02) |
| 5 | Smart Consumption Prediction | Predicts when a customer will need to reorder a product |
| 6 | Loyalty Program | Points earned on sale, redeemable, plan-gated feature |

## 2. Lead Pipeline

**Stages:** `New → Contacted → Interested → Confirmed → Delivered → Repeat Customer`

- A lead can originate from: manual entry, Online Shop order (Phase 04, new customer), or promoted automatically from a Consumption Prediction reminder that got a positive response.
- Each stage transition is logged (who moved it, when) — pipeline reporting depends on this history, not just current stage.
- "Repeat Customer" is a terminal/recurring stage — once reached, the customer's future orders don't need to re-enter the pipeline from "New."

## 3. Follow-up Calendar

- Every lead can have one or more scheduled follow-ups (call, visit, message).
- Overdue follow-ups surface on the assigned staff member's dashboard — this is the mechanism that prevents leads from silently going cold.
- Calendar view groups by day; list view groups by lead — both needed since managers think in dates, staff think in leads.

## 4. Notifications Engine (shared infrastructure)

This is **not** CRM-only — it's the shared queue that Loyalty reminders, Consumption Prediction reminders, and Lead follow-ups all feed into, so channel logic (Call/WhatsApp/SMS) is written once.

- Queue entry: `{ customer_id, channel, message_template, trigger_source, scheduled_at, status }`
- `trigger_source` tags where the notification came from (consumption_prediction / follow_up / loyalty) — needed for reporting on which channel/source actually drives repeat sales.
- Respects the provider-abstraction pattern from Risk Register RSK-06 (WhatsApp/SMS API rate-limit or pricing risk) — channel provider is swappable without touching business logic.

## 5. Customer Purchase History

- Full chronological list of a customer's sales, returns, and due payments — this is the data source both Smart Consumption Prediction and Loyalty read from.
- Must load fast even for high-frequency customers (paginated, indexed by customer_id + date — flagged in Phase 00 §API Conventions pagination rule).

## 6. Smart Consumption Prediction

*(per existing Feature Spec — implemented here)*

- Prediction requires **minimum 3 purchase cycles** of history for a given customer+product pair; calculated from the **average interval** between those purchases.
- When the predicted "needs to reorder" date approaches, a reminder is pushed to the Notifications Engine queue.
- Prediction is explicitly framed as a **suggestion**, never an autonomous action — UI must show confidence/basis, and manual override always available (per Risk Register RSK-08 — wrong predictions damaging customer trust).
- A return/refund on a prediction-linked product does not retroactively delete the purchase-cycle data point, but should be excluded from future average-interval calculations.

## 7. Loyalty Program

*(per existing Feature Spec — implemented here)*

- Point accrual rule configurable per shop (e.g. X currency spent = 1 point).
- Points awarded automatically on sale completion; automatically reversed on return/refund.
- Redemption cannot exceed current balance — hard validation at redemption time (race-condition safe, since two simultaneous redemptions could otherwise both pass a stale balance check).
- **Plan-gated:** only available on Premium tier and above — UI must show locked/upsell state on lower tiers rather than hiding the feature entirely (drives upgrade interest).

## 8. Permission Notes (per Phase 00 matrix, CRM-specific)

| Action | Owner | Manager | Cashier |
|---|---|---|---|
| View/manage leads | Full | Full | Create + View own |
| Configure loyalty rules | Full | — | — |
| Redeem points | Full | Full | — |
| View consumption predictions | Full | Full | — |
| Send reminders | Full | Full | — |

---

## Deliverable Sign-off Checklist
- [ ] Lead pipeline stages + transition logging tested
- [ ] Follow-up Calendar (day view + lead view) tested, overdue alerts verified
- [ ] Notifications Engine queue built as shared service (not duplicated per feature)
- [ ] Customer Purchase History loads performantly with pagination
- [ ] Consumption Prediction tested against real multi-cycle purchase data, confidence/override UI verified
- [ ] Loyalty accrual + redemption + plan-gating tested, including return/refund point reversal

**Once every box above is checked, Phase 03 is Done — this completes the v1.5 Growth release's core feature set.**