Add md file features in region, route, store, fleet, pricing, procurement, SFA, promotions, returns, finance, reporting, notifications, integration, and mobile capabilities

2026-08-19 15:18:31 +05:30
parent 45f374133f
commit d2390e7b12
25 changed files with 1565 additions and 88 deletions
@@ -0,0 +1,68 @@
+# 16 — Sales Force Automation (SFA) / CRM
+
+**Status**: Not Started
+**Depends On**: 12 — Store Management
+
+---
+
+## Goal
+
+Covers the lead/interaction half of
+[mainPlan.md §10](./mainPlan.md#10-sales-force-automation-sfa--crm):
+`logCustomerInteraction`, `createLead`, `convertLeadToStore`. Performance/incentive functions
+(`trackTargetVsAchievement`, `calculateIncentive`) are already scoped in
+[08_sales_agent_controls.md](./08_sales_agent_controls.md) — not repeated here.
+
+---
+
+## Background / Context
+
+There is no `Lead` entity or interaction log anywhere in the schema today — new outlet onboarding
+currently goes straight to `POST /api/stores` with no pre-qualification step.
+
+---
+
+## Data Model Changes
+
+### Lead
+
+`ProspectName`, `ContactInfo`, `Notes`, `Status` (`New`, `Qualified`, `Converted`, `Rejected`),
+`AssignedToUserId`.
+
+### Customer Interaction
+
+`StoreId` (nullable — can be logged against a `Lead` instead), `LeadId` (nullable), `UserId`,
+`Notes`, `CreatedAt`.
+
+---
+
+## API Endpoints
+
+| Function reference | Endpoint intent |
+|---|---|
+| `logCustomerInteraction(storeId, notes)` | `POST /api/stores/{id}/interactions` |
+| `createLead(prospectData)` | `POST /api/leads` |
+| `convertLeadToStore(leadId)` | `POST /api/leads/{id}/convert` — creates a `Store` via the existing `POST /api/stores` path internally |
+
+---
+
+## Business Rules
+
+- `convertLeadToStore` reuses `createStore` (§4, [12_store_management.md](./12_store_management.md))
+  rather than duplicating store-creation logic — a `Lead` conversion is not a separate creation
+  path.
+- Exactly one of `StoreId`/`LeadId` must be set on a `Customer Interaction` row, never both, never
+  neither.
+
+---
+
+## Open Questions
+
+- Does a `Lead` need its own scope/authorization model (region/route), or does it inherit the
+  creating user's scope with no further restriction until converted?
+
+---
+
+## Implementation Notes
+
+> Fill this section in during planning discussion before writing any code.