# 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.