2.6 KiB
2.6 KiB
21 — Notifications & Alerts
Status: Not Started Depends On: 02 — Stock Ledger, 12 — Store Management, 08 — Sales Agent Controls
Goal
Covers mainPlan.md §15 in full — a cross-cutting delivery mechanism (email/SMS/push) triggered by events other steps already produce.
Background / Context
No notification channel exists in this codebase today. This step is purely the delivery mechanism and trigger wiring; the underlying conditions it watches for are already defined elsewhere (reorder point in 02_stock_ledger.md, credit limit in 12_store_management.md, route deviation logic in 09_fraud_controls.md).
Data Model Changes
Notification
RecipientUserId, Type, Payload (JSON), Channel (Email, SMS, Push, InApp), SentAt,
ReadAt (nullable).
API Endpoints
| Function reference | Endpoint intent |
|---|---|
sendLowStockAlert(warehouseId, sku) |
Internal — triggered when a stock movement crosses the reorder point set in 02_stock_ledger.md |
sendCreditLimitBreachAlert(storeId) |
Internal — triggered on order/invoice creation when Store.OutstandingBalance exceeds Store.CreditLimit |
sendApprovalPendingNotification(approverId, requestId) |
Internal — triggered by submitOrderForApproval (08_sales_agent_controls.md) and return approval (18_returns_claims.md) |
sendRouteDeviationAlert(routeId, salesRepId) |
Internal — triggered from 09_fraud_controls.md's anomaly flag. The source data now exists (RouteVisitLog.IsDeviationFlagged, see 11_route_sales_management.md), but no anomaly flag or notification reads it yet. |
| — | GET /api/notifications — recipient's own notification inbox |
| — | PUT /api/notifications/{id}/read |
Business Rules
- Every
send*function in §15 is a trigger, not a user-facing endpoint — the only client-facing endpoints are inbox read/list. - Notification delivery failures (e.g. SMS provider down) must not roll back the business transaction that triggered them — fire-and-forget, logged separately.
Open Questions
- Which channels are actually needed at launch — in-app only, or SMS/email/push from day one? This significantly changes the infrastructure needed (third-party provider integration, see 22_integration_api.md).
Implementation Notes
Fill this section in during planning discussion before writing any code.