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

Data Model Changes

Store — New Fields

CreditLimit (decimal), OutstandingBalance (decimal, derived/cached from Finance ledger once 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
`checkStoreSchemeEligibility(storeId, schemeId)`	`GET /api/stores/{id}/schemes/{schemeId}/eligibility` — depends on 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.

2.7 KiB Raw Blame History