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,74 @@
+# 12 — Store Management (Beyond CRUD)
+
+**Status**: Not Started
+**Depends On**: 00 — Existing Gap Fixes
+
+---
+
+## Goal
+
+Store CRUD already exists (`Features/Store`). This step covers everything in
+[mainPlan.md §4](./mainPlan.md#4-store-outlet-management) that isn't
+plain CRUD: KYC, credit, segmentation, and dashboarding.
+
+---
+
+## Background / Context
+
+`Store` currently has no credit limit, outstanding balance, segment, or KYC fields — flagged as
+gap #8 in [00_existing_gaps.md](./00_existing_gaps.md).
+
+---
+
+## Data Model Changes
+
+### Store — New Fields
+
+`CreditLimit` (decimal), `OutstandingBalance` (decimal, derived/cached from Finance ledger once
+[19_finance_accounting.md](./19_finance_accounting.md) exists), `Segment` (string), `KycStatus`
+(`Pending`, `Verified`, `Rejected`).
+
+### KYC Document
+
+`StoreId`, `DocumentType`, `FileReference`, `UploadedAt` — file storage mechanism TBD (out of scope
+for this step's data model, just the record).
+
+---
+
+## API Endpoints
+
+| Function reference | Endpoint intent |
+|---|---|
+| `createStore(storeData, kycDocs)` | Extends existing `POST /api/stores` with doc upload |
+| `verifyStoreKyc(storeId)` | `PUT /api/stores/{id}/kyc/verify` |
+| `updateStoreCreditLimit(storeId, newLimit, approverId)` | `PUT /api/stores/{id}/credit-limit` |
+| `getStoreOutstandingBalance(storeId)` | `GET /api/stores/{id}/outstanding-balance` |
+| `classifyStore(storeId, segment)` | `PUT /api/stores/{id}/segment` |
+| `deactivateStore(storeId, reason)` | Extends existing `DELETE /api/stores/{id}` with a reason field |
+| `getStoreVisitHistory(storeId)` | `GET /api/stores/{id}/visit-history` — reads from [11_route_sales_management.md](./11_route_sales_management.md) |
+| `checkStoreSchemeEligibility(storeId, schemeId)` | `GET /api/stores/{id}/schemes/{schemeId}/eligibility` — depends on [17_promotions_schemes.md](./17_promotions_schemes.md) |
+| `getStoreSalesDashboard(storeId, period)` | `GET /api/stores/{id}/dashboard?period=...` |
+
+---
+
+## Business Rules
+
+- `updateStoreCreditLimit` requires an approver at Supervisor level or above.
+- A store with `KycStatus != Verified` should not be able to place orders above a configurable
+  threshold (or at all) — confirm exact rule with the user before implementing.
+- `deactivateStore` blocks new orders against it, matching the existing `IsActive` soft-delete
+  filter already used in `OrderService`.
+
+---
+
+## Open Questions
+
+- Is `OutstandingBalance` a cached/denormalized field updated on invoice/payment events, or always
+  computed live from Finance records?
+- What document types are required for KYC, and is file storage local, blob, or third-party?
+
+---
+
+## Implementation Notes
+
+> Fill this section in during planning discussion before writing any code.