Product Requirements Document (PRD)

Narayanganj Distribution Hub — Field Sales & Warehouse Management System

Table of Contents

1. Product Vision & Problem Statement

2. Goals & Anti-Goals

3. User Personas

4. System Architecture Overview

5. Module Specifications

• 5.1 Outlet & Market Mapping

• 5.2 Route Planning & Beat Management

• 5.3 SO Field Sales App

• 5.4 Target Setting & Performance

• 5.5 Warehouse Management

• 5.6 Procurement & Vendor Management

• 5.7 Dispatch & VLS Management

• 5.8 DSR Delivery App

• 5.9 Cash & Accounts

• 5.10 Admin Panel & Reporting

1. Data Model

2. API Design Principles

3. Integration Specifications

4. Non-Functional Requirements

5. Go-Live Readiness Gate

6. KPI Thresholds & Alert Configuration

7. Enum Values Reference

8. Open Questions

1. Product Vision & Problem Statement

1.1 What the System Is

The Narayanganj Distribution Hub System is a purpose-built field sales and warehouse management platform for an FMCG distribution hub operating across Narayanganj Town, Bandor, and Munshiganj. It is composed of two mobile applications (SO Field App and DSR Delivery App, both Android) and a web-based management portal used by warehouse, accounts, sales management, procurement, and executive stakeholders.

1.2 The Problem Being Solved

Today, the hub operates on a combination of paper forms, WhatsApp messages, verbal instructions, and manual spreadsheets. This creates five compounding failure modes:

1. Invisible field activity: There is no real-time record of SO visits, outlet orders, or strike rates. Management discovers problems days later, not hours.

2. Stock opacity: Stock moves in and out of the warehouse without a single authoritative record. Shortages are discovered at loading time, not the night before.

3. Cash leakage: Cash collected by DSRs is reconciled manually. Discrepancies are common and resolved informally, with no audit trail.

4. Procurement delays: The SCM Manager has no systematic view of stock levels, leading to either over-stocking (cash locked in inventory) or stockouts (lost revenue).

5. No accountability baseline: Because nothing is formally recorded, it is impossible to hold any individual accountable for any measurable outcome.

1.3 Core Principle

If it is not in the system, it did not happen.

Every order, every visit, every delivery, every cash collection, every stock movement, and every exception must be recorded digitally, in real time, by the person responsible for the activity.

1.4 What Success Looks Like

At the end of Day 1, the Business Head can open a single dashboard screen and see: how many outlets each SO visited, the total order value submitted, what stock left the warehouse, how much cash each DSR collected, and whether any discrepancy exists. No phone calls required.

2. Goals & Anti-Goals

2.1 Goals

2.2 Anti-Goals (Explicit Out-of-Scope)

3. User Personas

3.1 Sales Officer (SO)

Role: Sales Officer (Field App User) Count: 6 SOs active in Phase 1

Primary Job-to-Be-Done: Visit 75 P1 outlets daily across an assigned geographic block, take orders, and submit them digitally via the app before the 8:00 PM cut-off.

Pain Points the System Solves:

• Currently carries a paper route card and calls in orders verbally — orders are lost, misheard, or delayed.

• Has no visibility into whether their target is achievable; discovers miss at month-end.

• Cannot see outlet outstanding balance before visiting, leading to awkward collection conversations.

• Incentive calculation is done manually at month-end by the manager; SOs distrust the numbers.

Key Success Metric: Strike rate >70%; order value vs daily target visible in real time; incentive tier progression visible in app.

3.2 Delivery Sales Representative (DSR)

Role: DSR (Delivery App User) Count: Variable; at least 1 per active vehicle/route

Primary Job-to-Be-Done: Load vehicle per VLS, deliver stock to outlets in sequence, collect cash per invoice, and return to warehouse by 6:00 PM with correct cash, signed challans, and unsold stock.

Pain Points the System Solves:

• Currently receives handwritten VLS; loads from memory; quantities are disputed at return.

• Has no formal record of cash collected per outlet during the day; does mental arithmetic at day-end.

• Is blamed for shortages with no evidence trail.

• Arrival and departure times are not formally tracked; no accountability for late starts.

Key Success Metric: Day-end reconciliation variance = 0; departure by 8:30 AM 100% of days; zero disputed cash at day-end.

3.3 WH Manager

Role: WH Manager (Web App User) Count: 1 (currently Warehouse In-Charge position, noted as vacant; will be filled before go-live)

Primary Job-to-Be-Done: Manage all physical stock movements — receive inbound goods, generate VLS each night, oversee DSR loading, reconcile returns at day-end, and submit stock and cash reports by 7:00 PM.

Pain Points the System Solves:

• Currently maintains a manual stock register that is always at least one day behind.

• Generates VLS by hand each night from paper orders; prone to errors.

• Has no formal mechanism to record vehicle condition checks or DSR arrival times.

• Day-end reconciliation is time-consuming; discrepancies are resolved informally.

Key Success Metric: Opening stock report auto-generated at 7:00 AM; VLS generated in <5 minutes after order cut-off; day-end reconciliation closed by 7:00 PM daily.

3.4 SCM Manager

Role: SCM Manager (Web App User) Count: 1

Primary Job-to-Be-Done: Monitor stock levels, raise RFQs for uncontracted SKUs, issue approved POs to vendors by Monday 10:00 AM, and receive the weekly stock position report from the WH Manager every Sunday.

Pain Points the System Solves:

• Currently receives stock data via WhatsApp messages from the WH Manager; data is informal and often incomplete.

• Has no system to track vendor RFQ responses or PO acknowledgement status.

• Cannot see which SKUs are approaching the 30-day max stock cap or below minimum cover thresholds.

Key Success Metric: 100% of POs issued to vendors by Monday 10:00 AM; 0 RFQ responses missed past 48-hour deadline; stock position report received every Sunday before 7:00 PM.

3.5 Sales Head

Role: Sales Head / Supervisor (Web App User) Count: 1 (Regional Manager, Mr. Shahariyar)

Primary Job-to-Be-Done: Oversee daily SO performance across all 6 routes; classify outlets; approve route changes; validate monthly targets; review weekly strike rates and coverage metrics.

Pain Points the System Solves:

• Currently receives SO performance data as verbal reports or end-of-day WhatsApp summaries.

• Cannot identify underperforming SOs until the week or month has passed.

• Route changes are made informally, with no audit trail.

Key Success Metric: Monday morning SO performance review takes <15 minutes using dashboard; zero route changes made without system approval trail.

3.6 Business Head

Role: Business Head (Web App User — executive oversight) Count: 1 (Head of P.S & A.S, Mr. Imtiaj)

Primary Job-to-Be-Done: Receive the daily operations summary by 7:00 PM; approve high-value actions (POs, target revisions, vendor registrations, Debit Note resolutions); sign off on monthly P&L; execute the Go-Live Readiness Gate before Day 1.

Pain Points the System Solves:

• Currently has no single view of hub performance; must call multiple people to understand daily status.

• Cannot track whether incentive thresholds are being met or whether cash reconciliation is clean.

• No formal mechanism to approve or reject financial decisions with audit trail.

Key Success Metric: Daily operations summary received by 7:00 PM; all approval actions completed within system (zero off-system approvals).

3.7 Accounts

Role: Accounts (Web App User) Count: 1–2 (Head Office accounts team)

Primary Job-to-Be-Done: Process daily cash receipts from WH Manager, generate invoices, manage supplier payables per credit terms, and submit daily/weekly/monthly financial reports.

Pain Points the System Solves:

• Currently receives cash summary via phone or paper; re-enters data into spreadsheets.

• Has no automated mechanism to check whether an open Debit Note exists before processing a vendor payment.

• Monthly P&L takes multiple days to compile due to manual data collection.

Key Success Metric: Daily financial summary submitted by 7:00 PM without manual data collection; zero vendor payments processed with open Debit Notes.

3.8 App Admin

Role: App Admin (Web App User — system administration) Count: 1 (dedicated technical admin)

Primary Job-to-Be-Done: Load and maintain all master data (outlet master, SKU master, route plans, user accounts, promotional schemes, targets); perform daily backup verification; manage role assignments; execute the Go-Live Readiness data load.

Pain Points the System Solves:

• No system currently; all setup done in spreadsheets.

• No audit trail for master data changes.

• No automated backup or integrity check mechanism.

Key Success Metric: All 8 Go-Live Readiness items verified before Day 1; 100% of master data edits logged with full audit trail; zero unauthorized data changes.

4. System Architecture Overview

4.1 Three-Tier Structure

┌─────────────────────────────────────────────────────────────────┐ │ CLIENT LAYER │ │ │ │ ┌─────────────────────────┐ ┌──────────────────────────────┐ │ │ │ SO Field Sales App │ │ DSR Delivery App │ │ │ │ (Android — Offline │ │ (Android — Offline First) │ │ │ │ First) │ │ │ │ │ └─────────────────────────┘ └──────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Web Application (React / SPA) │ │ │ │ WH Manager | Accounts | Sales Head | Business Head │ │ │ │ SCM Manager | App Admin │ │ │ └─────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ HTTPS / REST ┌─────────────────────────────────────────────────────────────────┐ │ BACKEND API LAYER │ │ │ │ ┌────────────┐ ┌─────────────┐ ┌──────────────┐ │ │ │ Auth │ │ Business │ │ Notification │ │ │ │ Service │ │ Logic API │ │ Service │ │ │ │ (JWT/RBAC) │ │ (REST) │ │ (FCM/SMS) │ │ │ └────────────┘ └─────────────┘ └──────────────┘ │ │ │ │ ┌────────────┐ ┌─────────────┐ ┌──────────────┐ │ │ │ Sync │ │ Report │ │ File/Media │ │ │ │ Engine │ │ Engine │ │ Service │ │ │ │ (Offline) │ │ │ │ (Photos) │ │ │ └────────────┘ └─────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ ┌─────────────────────────────────────────────────────────────────┐ │ DATA LAYER │ │ │ │ ┌─────────────────────────┐ ┌──────────────────────────────┐ │ │ │ Primary Relational DB │ │ Object/File Storage │ │ │ │ (PostgreSQL) │ │ (Photos, Documents) │ │ │ └─────────────────────────┘ └──────────────────────────────┘ │ │ │ │ ┌─────────────────────────┐ ┌──────────────────────────────┐ │ │ │ Local SQLite DB │ │ Push Queue │ │ │ │ (Mobile Offline Store)│ │ (Notifications) │ │ │ └─────────────────────────┘ └──────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘

4.2 Key Architectural Principles

Offline-First Mobile Architecture: Both the SO Field App and DSR Delivery App must function fully offline. The apps maintain a local SQLite database that is the source of truth for all in-progress field operations. Connectivity to the server is treated as a bonus, not a requirement, for core field workflows.

Conflict Resolution Strategy:

• Mobile writes are append-only (new visit logs, new orders, new delivery logs).

• Server-side writes are the source of truth for master data (outlet master, SKU master, route plans, targets).

• On reconnect, the mobile app pushes all locally queued events to the server in chronological order.

• Conflicts (e.g., outlet master updated while SO was offline) are resolved by accepting the server version and notifying the mobile user of any changes.

Data Sync Strategy:

• Master data (outlets, SKUs, routes, targets) syncs at app launch and every 30 minutes when connected.

• Transactional data (visit logs, orders, delivery logs, cash entries) queues locally and pushes on every available connection window.

• Sync status is displayed in the mobile app header: "Synced 3 min ago" / "Offline — 5 records pending sync".

Security:

• All API endpoints require JWT Bearer token authentication.

• RBAC enforced at the API layer — each endpoint validates the caller's role before returning data.

• SO tokens are scoped to their assigned route only; any attempt to access another SO's data returns 403.

• All data in transit: TLS 1.2 minimum.

• Sensitive data at rest (credentials, bank details): AES-256 encrypted.

5. Module Specifications

5.1 Outlet & Market Mapping Module

Module Purpose: Maintain the authoritative master record of every retail outlet in the distribution universe, including GPS location, classification, and SO assignment.

User Stories

Acceptance Criteria

1. The "Register Outlet" screen on the SO app auto-populates GPS coordinates from the device; the SO cannot proceed without GPS lock.

2. On submission of a new outlet, the system checks for any existing outlet within a 50-metre radius; if found, it displays the existing outlet name and address and requires the SO to confirm "This is a different outlet" before saving.

3. Mandatory fields — outlet name, owner name, address, zone, outlet type, contact number, drop size tier — must all be populated before the registration form can be submitted; the system highlights missing fields.

4. Only the App Admin can edit an existing outlet record; every edit is logged with: editor user ID, timestamp, field changed, old value, new value.

5. The Sales Head can change any outlet's priority tier (P1/P2) from the web portal; the change takes effect for the next beat day's route generation.

6. The system enforces a maximum of 2,700 outlets in P1 status; if this cap is reached, the Sales Head must demote a P1 outlet before promoting a new one.

7. Bulk CSV import validates all rows before processing; import fails on any row with a missing mandatory field; a validation error report is returned to the App Admin listing all failed rows with reasons.

8. The system automatically generates a weekly flag report every Monday morning listing all P1 outlets with zero recorded visits in the last 3 consecutive weeks; this report is sent to the Sales Head via dashboard notification.

Business Rules Enforced

• OM-03: Duplicate detection radius = 50 metres (configurable by App Admin).

• OM-08: P1 cap = 2,700; P2 cap = 2,700.

• OM-09: 3-week no-visit flag for P1 outlets.

Edge Cases & Error States

• GPS unavailable: App prompts SO to enable location services; manual coordinate entry is not allowed (prevents spoofing).

• Offline registration: Outlet is saved locally with sync_status = pending; uploaded on next connection. Duplicate check is performed against locally cached outlet list; server re-validates on sync.

• CSV import with duplicate outlets: System compares by GPS proximity; flags potential duplicates in the validation report for App Admin to resolve manually.

5.2 Route Planning & Beat Management Module

Module Purpose: Define and maintain the structured weekly beat schedule assigning each P1 outlet to a specific SO and day of week, following the geographic blocking principle.

User Stories

Acceptance Criteria

1. The beat schedule only allows assignment to Sat, Sun, Mon, Tue, Wed, or Thurs; Friday cannot be assigned as a beat day for any outlet.

2. Each outlet can be assigned to exactly one SO and one beat day; the system rejects any attempt to assign an outlet that is already assigned.

3. Each SO's route for any beat day must have exactly 75 P1 outlets to be considered complete; the system displays a completion indicator (e.g., "45/75 outlets assigned") as the Sales Head builds the route.

4. The route map view renders all outlets on a geographic map (Google Maps / OpenStreetMap integration), colour-coded by SO, allowing the Sales Head to visually verify blocking principle compliance.

5. Route lock is enforced for a minimum of 4 weeks from go-live; any attempt to edit a locked route by the App Admin without a prior Sales Head approval record results in a system error ("Route is locked — approval required").

6. Route change approval workflow: Sales Head submits a change request in system (with reason) → App Admin receives notification → App Admin applies change → before/after state logged permanently.

7. Each SO's route includes a P2 backup pool of up to 10 outlets per beat day; P2 outlets are distinct from the P1 list and from each other.

8. When a SO activates a P2 outlet, they must select a reason code from the configured list; the system records: outlet ID, reason code, SO user ID, timestamp.

9. The system calculates estimated route duration based on outlet count and average inter-outlet travel time (sourced from route map clustering); if estimated duration exceeds 10 hours (8:00 AM to 6:00 PM), the system flags the route as infeasible and prevents lock until resolved.

Business Rules Enforced

• RP-03: One outlet, one SO — no sharing.

• RP-04: 4-week route lock.

• RP-10: Blocking principle — contiguous outlets per SO per beat day.

• RP-11: Sat–Thurs beat schedule; Friday excluded.

• RP-12: Route must complete within 8:00 AM–6:00 PM window.

Edge Cases & Error States

• Route has fewer than 75 P1 outlets: System allows save in draft state; Sales Head cannot lock until 75 outlets are assigned.

• SO changed mid-route-lock-period: Sales Head must submit change request; existing outlet assignments for the departing SO must be manually re-assigned; system generates a task list for Sales Head.

• P2 pool exhausted: If all 10 P2 outlets are activated or unavailable in a single day, SO receives in-app notification; remaining unvisited P1 outlets are flagged for next cycle.

5.3 SO Field Sales App Module

Module Purpose: Enable Sales Officers to execute their daily beat route — GPS check-in, order taking, visit logging, and real-time performance tracking — on their Android device, fully offline-capable.

User Stories

Acceptance Criteria

1. On app launch, the SO sees today's beat route: ordered list of outlets, daily visit target (75), daily order value target (calculated from SO monthly target ÷ working days), and number of P2 backups available.

2. GPS check-in is the first mandatory action at each outlet; the "Enter Order" and "Log Visit" buttons are greyed out until a valid GPS check-in is recorded.

3. GPS check-in is valid if the device GPS coordinate is within 100 metres (configurable) of the outlet's registered GPS pin; if outside 100 metres, the system shows a warning with the measured distance and requires the SO to confirm they are at the correct outlet (override logged for audit).

4. Before order entry, the system displays: outlet name, owner name, outstanding balance (BDT), last order date, and today's outlet-level target (SO target ÷ active outlet count on route).

5. If the outlet has an outstanding balance > 0, order entry is blocked; a message reads: "This outlet has an unpaid balance of BDT [X]. Please collect payment before placing a new order."

6. The order entry screen shows the full active SKU list; the SO selects SKUs and quantities; approved promotional schemes are auto-applied and displayed as line items.

7. The SO cannot enter a price or discount that exceeds the approved SKU master price; the price field is read-only, pre-populated from SKU master.

8. Order cut-off is 8:00 PM; at 8:00 PM, the system auto-closes order entry; any in-progress order that has not been submitted is saved as a draft locally and flagged as "Not Submitted — After Cut-Off".

9. Visit outcome must be selected before navigating to the next outlet: Order Placed / Closed / Owner Absent / Refused / Competitor Only.

10. Running dashboard updates in real time: (a) Memos visited / 75 target, (b) Order value BDT vs daily target BDT, (c) Strike rate %, (d) Incentive tier progress bar showing current accrual vs Test / 1st Step / BEP thresholds.

11. All data entered while offline is stored in local SQLite; on reconnection, the app automatically pushes queued records; sync status is visible in the app header.

12. The SO app only loads data for their assigned route; attempting to access any other SO's outlet data returns an error screen.

Business Rules Enforced

• SA-04: Own route only.

• SA-05/SA-06: GPS check-in mandatory; radius = 100m.

• SA-08: Outstanding balance blocks order entry.

• SA-14: 8:00 PM order cut-off is system-enforced.

• SA-15/SA-16: Price ceiling enforced; promotions auto-applied.

• BR-01: No credit field — all orders are cash-on-delivery.

• TS-09: Outlet-level target displayed at check-in.

Edge Cases & Error States

• SO GPS signal weak in dense urban area: App displays "Low GPS accuracy" warning; SO can retry GPS lock or accept with documented override.

• SKU not in master: SO cannot enter a free-text SKU; they must select from the approved list. If an outlet requests an unlisted SKU, SO can log it as a "competitor observation" or "new SKU request" using the notes field.

• Outlet GPS pin is incorrect: SO can flag the outlet GPS location as incorrect from the check-in screen; App Admin is notified for correction; the visit is logged with the flag.

5.4 Target Setting & Performance Module

Module Purpose: Configure monthly revenue targets and incentive thresholds at WH and SO levels; track daily performance against targets; trigger performance alerts.

User Stories

Acceptance Criteria

1. The monthly target configuration workflow: Business Head enters WH-level target → system calculates per-SO target using formula: (WH target ÷ 6, adjusted by route potential based on weighted average drop size of outlets on each SO's route) → Sales Head sees proposed targets and validates → Sales Head confirms "Meets BDT 3.5 Cr floor" (system blocks confirmation if calculated total < BDT 3.5 Cr) → Business Head approves and locks.

2. The target calculation uses: weighted average drop size × 2,700 P1 outlets × visit frequency; the system shows this calculation workings to the Sales Head for review.

3. Targets must be loaded into the app by the 1st of each month; the App Admin receives a reminder notification 5 days before month-end.

4. Weekly milestone targets are auto-generated as monthly target ÷ 4; displayed in the Sales Head dashboard.

5. Every Monday morning, the system sends an automated alert to the Sales Head listing any SO whose actual revenue for the previous week is below 80% of their weekly milestone target.

6. Mid-month target revision is system-locked; the Business Head must initiate a revision request; the system logs the request with reason, old target, proposed new target, and approval timestamp.

7. Incentive tier thresholds (Test: BDT 750/SO, 1st Step: BDT 17,500/SO, BEP: BDT 27,500/SO) are configured once per month and visible to each SO in the app as a progress bar.

8. The outlet-level target is calculated and displayed dynamically: SO monthly target ÷ number of active outlets on that SO's route; updated if outlet count changes mid-month.

9. Performance metrics tracked and displayed per SO: Memos/day, Strike Rate %, LPC, EC %, Order Value/Memo, SKU Distribution %.

Business Rules Enforced

• TS-02: Targets loaded by 1st of month.

• TS-04: Mid-month revision requires Business Head approval.

• TS-07: Monday morning flag for SOs below 80% weekly target.

• TS-09: Outlet-level target visible at check-in.

• TS-10: Budget floor validation at BDT 3.5 Cr.

Edge Cases & Error States

• Target not loaded by 1st of month: SO app displays "Target not yet configured" message; App Admin receives escalation alert; target can be backdated with Business Head approval and the audit log records the backdating.

• Route changes mid-month: Outlet-level target recalculates automatically when outlet count changes; SO is notified of the revision.

5.5 Warehouse Management Module

Module Purpose: Manage all physical stock movements at the warehouse — inbound receiving (GRN), storage, FEFO/FIFO dispatch, shortage allocation, and weekly reporting to SCM Manager.

User Stories

Acceptance Criteria

1. GRN creation requires selection of an existing open PO; free-form GRN (without a matching PO) is system-blocked with error: "No open PO found for this vendor. Cannot receive goods."

2. During GRN, the WH Manager selects each SKU and enters: qty received, batch number, expiry date, and condition (Acceptable / Damaged / Near-Expiry). The system calculates days to expiry from delivery date; if < 60 days, the item is auto-flagged as "Reject — Expiry" and cannot be accepted into stock.

3. The GRN handover location must be recorded: "Receiving Bay" (default) or "Other" (requires a text note). This validates supplier compliance with the no-storage-zone-entry rule.

4. If any item is marked "Reject", the WH Manager must confirm "Same-day return to supplier confirmed" before the GRN can be submitted; upon submission, the system automatically generates a Debit Note with: GRN reference, vendor ID, rejected SKUs and quantities, total value, raised_by (WH Manager), raised_at (timestamp), status = Open.

5. Any discrepancy between PO quantity and received quantity (excluding rejections) is flagged to the SCM Manager with a photo attachment field; the WH Manager must attach a photo within 2 hours.

6. GRN must be digitally signed by the WH Manager before stock is accepted; signature timestamp is recorded.

7. Stock is accepted into inventory under FIFO principle; the system assigns the received batch to the back of the storage queue.

8. For dispatch, the system enforces FEFO: the soonest-expiring batch is always allocated first for outbound VLS.

9. Opening stock report is auto-generated at 7:00 AM daily; visible to WH Manager and Business Head; includes: SKU name, current quantity, stock cover days (at current consumption rate), cover category (Fast/Medium/Slow), and flag colour (Red = below minimum, Amber = approaching minimum, Green = OK).

10. Near-expiry alert fires automatically for any item within the configured threshold (default 30 days to expiry); notification sent to WH Manager and Business Head.

11. Shortage allocation: if total available quantity for a SKU < total ordered quantity across all routes, the system calculates: allocated_qty_per_route = available_qty × (route_ordered_qty / total_ordered_qty). Each route receives exactly its pro-rata share, rounded down to whole units. Remainder units (from rounding) are flagged for manual allocation by WH Manager.

12. The weekly stock position report is submitted to the SCM Manager by the WH Manager every Sunday by 7:00 PM; system generates the report automatically at 6:30 PM Sunday and prompts the WH Manager to review and submit; if not submitted by 7:00 PM, an escalation alert is sent to the Business Head.

Business Rules Enforced

• WH-01: GRN blocked without open PO.

• WH-04: Expiry < 60 days = auto-reject.

• WH-07/WH-11: FIFO inbound, FEFO outbound.

• WH-16 (clarified): Pro-rata shortage allocation.

• VM-13: Handover at receiving bay only.

• VM-14 / BR-15: Rejected goods → same-day return → auto Debit Note.

Edge Cases & Error States

• PO already fully received: System shows "This PO is closed" and blocks new GRN; WH Manager must raise a discrepancy report.

• Stock variance after weekly count: System generates variance report (expected vs counted); WH Manager must record reason for each variance > 1%; variance > 3% triggers Business Head notification.

• All stock for a SKU in near-expiry status: System flags for immediate dispatch priority; WH Manager and Sales Head are notified.

5.6 Procurement & Vendor Management Module

Module Purpose: Manage the full procurement lifecycle from vendor registration through RFQ, PO issuance, goods receipt, and vendor payment compliance, with the SCM Manager as the primary actor.

User Stories

Acceptance Criteria

1. Vendor registration form requires all mandatory fields: legal name, contact person, SKU list, DP per SKU, credit terms, lead time (days), margin/GPM %, exclusivity scope, contract expiry date, bank details. Business Head must approve the registration before any PO can be raised for that vendor.

2. RFQ workflow: SCM Manager creates RFQ specifying SKU(s), quantity, and delivery date → system records RFQ issue timestamp → system sends notification to tagged vendors → vendors' responses (price, availability, lead time) are logged against the RFQ record → system flags any vendor that has not responded within 48 hours of RFQ issue with a "Non-Responsive" status → SCM Manager reviews responses and marks their recommendation → Business Head approves → PO raised against winning vendor.

3. PO form requires: vendor selection (from registered vendor list only), SKU(s) with quantities and agreed DP, required delivery date, WH receiving address. System blocks PO creation if vendor is not registered and approved.

4. PO must be approved by Business Head before it is issued; approved POs issued to vendor by Monday 10:00 AM; system records issue timestamp.

5. On PO issue, vendor has 24 hours to acknowledge; system tracks acknowledgement timestamp; unacknowledged POs after 24 hours are flagged to SCM Manager.

6. Any amendment to a PO after it has been issued requires: Business Head approval, system record of the amendment (field changed, old value, new value), and a notification to the vendor.

7. 7-day contract expiry alert is sent to SCM Manager and Business Head as a dashboard notification and push notification.

8. For uncontracted SKUs, the RFQ process requires a minimum of 2 vendor quotes before SCM Manager can make a recommendation.

Business Rules Enforced

• VM-01/VM-03: Unregistered vendor blocks PO; Business Head must approve.

• VM-07: PO requires Business Head approval.

• VM-08: Monday 10:00 AM PO issuance cadence.

• VM-09: 24-hour vendor PO acknowledgement window.

• VM-12: 48-hour RFQ response window.

• VM-13: Receiving bay handover enforced at GRN.

• VM-14: Rejection → auto Debit Note.

• AC-17: Open Debit Note blocks vendor payment.

Edge Cases & Error States

• Only one vendor available for a SKU: System allows waiver of the 2-vendor RFQ minimum with Business Head approval; waiver is logged.

• Vendor fails to acknowledge PO within 24 hours: SCM Manager must follow up offline; the PO remains open until vendor acknowledges or SCM Manager marks "Manually Confirmed".

• Debit Note amount exceeds vendor outstanding payable: System logs the excess as a credit to be applied against next invoice; Business Head is notified.

5.7 Dispatch & VLS Management Module

Module Purpose: Generate and manage the Vehicle Stock Allocation Sheet (VLS) each night post-order-cut-off, oversee the picking and staging process, and control DSR loading and departure.

User Stories

Acceptance Criteria

1. At 8:00 PM, the system auto-closes order entry and generates a Delivery Order (DO) consolidating all submitted orders. The WH Manager accesses the DO and generates VLS; the VLS generation action is available from 8:00 PM onwards.

2. VLS document includes: DSR name, vehicle ID, route/beat area, outlet delivery sequence (ordered by geography), per-outlet SKU list (item name, qty ordered, qty to deliver), total qty per SKU on vehicle, and shortage flags (if pro-rata allocation has reduced any qty).

3. VLS is printed per vehicle (PDF generated by system); print action available to WH Manager only; target print completion time: before 9:00 PM.

4. Picking workflow: WH Manager assigns the VLS to the picking team → picking team stages goods → a designated checker (a different person from the picker, assigned by WH Manager in the system) verifies each line of the VLS against staged goods → checker clicks "Confirm All Lines Verified" in system → system records: checker user ID, verification timestamp → VLS status changes to "Staged — Pending Signature".

5. DSR signs the VLS digitally in the system (DSR user ID + timestamp); system blocks loading confirmation until DSR signature is recorded.

6. WH Manager counter-signs the VLS digitally (WH Manager user ID + timestamp); system blocks DSR departure until counter-sign is recorded.

7. DSR arrival time is logged by WH Manager at the start of morning operations; if arrival time > 7:00 AM, system flags the record as "Late Arrival" with the logged timestamp.

8. Vehicle condition check is recorded by WH Manager: fuel level (OK / Low), tyres (OK / Defective), lights (OK / Defective). If any item is "Defective", the system blocks vehicle clearance for departure and generates an alert to Sales Head.

9. DSR departure time is logged when WH Manager marks "Vehicle Departed"; if departure time > 8:30 AM, system flags "Late Departure" with timestamp; alert sent to Sales Head.

10. The VLS is printed in two copies: original travels with the DSR in the vehicle, copy retained by WH Manager; system records document custody status.

Business Rules Enforced

• BR-16: WH Manager VLS counter-sign required before DSR can depart.

• DS-01a: Checker verification before staging sealing.

• DS-24: 7:00 AM DSR arrival — late flagged.

• DS-25: Vehicle condition check before departure.

• DS-26: 8:30 AM departure deadline — late flagged.

Edge Cases & Error States

• No orders submitted for a route: VLS for that route has zero items; system alerts WH Manager and Sales Head; no VLS is generated for that DSR for the day.

• Shortage causes a route VLS to have zero qty for a SKU: That SKU is listed on the VLS as "0 — Shortage" for all affected outlets; outlet-level notes on the challan flag the shortage.

• DSR absent: WH Manager can mark DSR absent; VLS status is set to "Undelivered — DSR Absent"; Sales Head is notified immediately.

5.8 DSR Delivery App Module

Module Purpose: Enable DSRs to execute delivery routes — GPS check-in, outlet identity confirmation, delivery logging, cash collection per outlet, and day-end return processing — fully offline-capable.

User Stories

Acceptance Criteria

1. The DSR app shows today's delivery route from the VLS: ordered outlet list, per-outlet SKU list with quantities, total vehicle load summary, and any shortage flags from the VLS.

2. GPS check-in at each outlet is mandatory before the delivery logging screen is unlocked.

3. Before the unloading screen is activated, the app displays a mandatory Outlet Identity Confirmation step: outlet name, owner name, and address are shown; the DSR must tap "Confirm — This is [Outlet Name]" to proceed. If the DSR taps "Wrong Outlet", delivery is blocked and an alert is sent to the WH Manager.

4. If the outlet has an unpaid previous invoice, the delivery completion button is blocked; the screen shows: "Outstanding balance: BDT [X]. Collect payment before completing delivery."

5. DSR logs per outlet: items delivered (each SKU and qty delivered — may differ from VLS if outlet refuses partial items), cash collected (BDT), challan number. Any qty variance from VLS must include a reason code.

6. Challan is generated in the app at delivery completion: outlet name, items ordered, items delivered, unit price, total value, delivery date. The challan is printed/shown on a receipt printer or displayed as a PDF for outlet owner sign-off; the signed original is left with the outlet; DSR retains a copy reference in the app.

7. Cash must be logged per outlet immediately after each delivery; the app does not allow navigation to the next outlet until the current outlet's delivery is marked as complete (delivered or closed/absent with reason).

8. If an outlet is closed or the owner is absent, the DSR logs reason code; no goods are left at the outlet; the items are retained on the vehicle and returned to WH at day-end.

9. Day-end return workflow: DSR taps "Return to Warehouse"; WH Manager opens the day-end reconciliation screen; WH Manager confirms receipt of: (a) cash envelope with total cash amount, (b) all signed challan copies, (c) all unsold/returned stock. The system shows the expected values for each from the VLS. WH Manager must confirm all three before closing the reconciliation; if any component is missing, reconciliation cannot close.

10. The DSR return time is logged when WH Manager initiates the day-end reconciliation; return times after 6:00 PM are flagged as "Late Return".

Business Rules Enforced

• DS-06: GPS check-in mandatory.

• DS-08: Cash logged per outlet — not end-of-day.

• DS-09: Outstanding balance blocks delivery completion.

• DS-28: Outlet identity confirmation before unloading.

• DS-27: Original challan stays with outlet; DSR retains copy.

• BR-17: Cash + challans + unsold stock must all be submitted together.

• BR-16: Departure blocked until VLS counter-signed.

Edge Cases & Error States

• DSR app offline all day: All delivery logs, cash entries, and challan data queued locally in SQLite; uploaded in bulk on first connection; day-end reconciliation can proceed via WH Manager's paper VLS copy and physical count.

• Outlet GPS pin is far from actual outlet: DSR checks in with a GPS override (logs measured distance); WH Manager is notified; the outlet's GPS pin is flagged for correction.

• Returns from outlet: DSR can only accept a return with explicit SO or WH Manager approval logged in the system; return reason is documented; items are added to "Returns" section of day-end reconciliation.

5.9 Cash & Accounts Module

Module Purpose: Process all daily cash flows — invoice generation, cash receipt from DSRs, supplier payables management, Debit Note tracking, and financial reporting.

User Stories

Acceptance Criteria

1. Invoice is auto-generated when an SO order is confirmed (status = Submitted); invoice includes: outlet name, SO name, order date, SKUs with quantities, unit prices (from SKU master), applicable discounts (from promotional schemes), VAT/tax, and total BDT value. All retail invoices have payment_type = Cash; no credit field is present.

2. Invoice must be generated before goods leave the warehouse; system enforces this by requiring invoice issuance before the DSR's VLS can be marked "Ready for Departure".

3. Supplier payment schedule is auto-generated based on GRN date + vendor credit terms (e.g., GRN date + 30 days for a 30-day credit term). Accounts cannot process a payment before the scheduled date without Business Head approval.

4. Before processing any vendor payment, the system checks for open Debit Notes for that vendor. If any Debit Note with status = "Open" exists, the payment button is blocked with message: "Vendor payment blocked: open Debit Note [DN-XXXXX] of BDT [X] requires Business Head resolution."

5. Debit Note tracking dashboard: shows all Debit Notes with status (Open / Resolved / Credited), vendor name, value, age (days since raised), and linked GRN. Accounts can view; Business Head can resolve.

6. Cash Receipt Voucher is generated by the system after WH Manager confirms day-end reconciliation; signed digitally by DSR and WH Manager; stored against the reconciliation record.

7. Daily financial summary is auto-generated at 7:00 PM and sent to the Business Head's dashboard and as a push notification: total cash received (all DSRs), total invoices issued, total outstanding receivables, total supplier payments due this week, and any open discrepancies.

8. Outstanding receivable per outlet is maintained in real time; if an outlet's balance is > 0, all new order attempts for that outlet are blocked across the system (both SO app and system).

9. Monthly P&L summary is auto-generated by the system on the 5th working day of each month for the previous month; Accounts reviews and submits to Business Head.

10. Supplier invoice three-way match: Accounts can only process a supplier payment after confirming: (a) PO exists and is approved, (b) GRN is raised and signed, (c) supplier invoice matches PO price and GRN quantity. Any mismatch blocks payment.

Business Rules Enforced

• BR-01: No credit for retail outlets.

• BR-07: Supplier payment follows credit terms.

• BR-08: Segregation of duty (WH Manager handles stock; Accounts handles cash).

• AC-17: Open Debit Note blocks vendor payment.

• AC-10: Three-way match (PO + GRN + supplier invoice) before payment.

Edge Cases & Error States

• DSR cash collected > invoiced amount: Excess cash is logged as an overpayment against the outlet; Accounts is notified; credited against next invoice.

• Supplier invoice amount differs from PO agreed DP: System flags the discrepancy; Accounts must get SCM Manager and Business Head sign-off before processing the payment at the invoiced amount.

• Debit Note partially resolved: If vendor credits only part of the Debit Note value, Accounts logs the partial credit; remaining balance stays as Open; payment is still blocked for the remaining outstanding value.

5.10 Admin Panel & Reporting Module

Module Purpose: Provide master data management, role-based dashboards, governance controls, audit trail, and operational reporting across all modules.

User Stories

Acceptance Criteria

1. App Admin can create, edit, and deactivate records for: outlets, SKUs, users, routes, promotional schemes, and targets. All edits are logged with: user ID, timestamp, entity type, record ID, field changed, old value, new value. Audit logs cannot be deleted or edited.

2. Business Head dashboard displays, on a single screen: (a) Visit Tracker — today's SO visit count vs target, (b) Order Summary — total order value vs WH daily target, (c) Cash Summary — total expected cash vs total collected, (d) Stock Alert — count of SKUs in Red/Amber coverage status, (e) Discrepancy Alerts — open cash discrepancies count, (f) Debit Note Alerts — count of open Debit Notes, (g) DSR Punctuality — count of late arrivals and departures today.

3. All dashboards update at a maximum 5-minute refresh interval; Business Head and Sales Head can manually refresh.

4. Surprise count workflow: Business Head triggers a "Surprise Count" for stock and/or cash from the admin panel → WH Manager receives in-app notification with instructions → WH Manager completes the count and enters findings → any variance is logged against the routine weekly variance record for trend analysis.

5. Route change approval workflow: Sales Head submits a route change request (outlet, proposed change, reason) → App Admin receives notification → App Admin applies change after Sales Head approval is recorded → before/after state logged permanently.

6. System generates the following scheduled reports automatically:

• Daily: Opening stock report (7:00 AM), Cash summary (7:00 PM), Financial summary (7:00 PM).

• Weekly: Stock position report to SCM Manager (Sunday 7:00 PM), SO performance flag report (Monday 7:00 AM).

• Monthly: P&L summary (5th working day), Expense report, Stock valuation report.

1. The Go-Live Readiness Checklist is accessible to Business Head and App Admin from the Admin Panel; it shows real-time completion status for all 8 data categories; the "Sign-Off and Unlock Day 1" button is shown only to the Business Head and is active only when all 8 items are complete.

Business Rules Enforced

• AD-01/AD-02: Full audit trail; route change trail.

• AD-03: Automated backups; monthly integrity audit.

• AD-04: Paper fallback protocol.

• AD-05: Surprise count workflow.

Edge Cases & Error States

• App Admin accidentally deactivates a live SO user: System prompts confirmation; deactivated user cannot log in; all active routes remain in the system; Sales Head is notified immediately.

• Promotional scheme expired but still in system: System auto-deactivates promotions past their validity end date; any order submitted after expiry does not receive the promotion; the scheme is moved to "Archived" status.

6. Data Model

6.1 Entities and Fields

OUTLET

• outlet_id (PK, UUID)

• outlet_name (string, required)

• owner_name (string, required)

• address (string, required)

• zone (enum: Narayanganj Town / Bandor / Munshiganj)

• outlet_type (enum: Grocery / Pharmacy / General Trade / Kiosk)

• gps_lat (decimal, required)

• gps_lng (decimal, required)

• priority_tier (enum: P1 / P2)

• drop_size_tier (enum: Small / Medium / Large)

• estimated_drop_size_bdt (decimal)

• contact_number (string, required)

• so_assignment_id (FK → USER)

• beat_day (enum: Sat / Sun / Mon / Tue / Wed / Thurs)

• visit_frequency (enum: Weekly / Fortnightly)

• competitor_brands (text)

• status (enum: Active / Inactive / Permanently Closed)

• outstanding_balance_bdt (decimal, default 0)

• registration_date (date)

• created_by (FK → USER)

• last_modified_at (timestamp)

• last_modified_by (FK → USER)

USER

• user_id (PK, UUID)

• name (string, required)

• role (enum: SO / DSR / WH Manager / SCM Manager / Accounts / Sales Head / Business Head / App Admin)

• assigned_zone (enum: Narayanganj Town / Bandor / Munshiganj / All)

• login_credentials (hashed password + salt)

• status (Active / Inactive)

• created_at (timestamp)

• last_login_at (timestamp)

ROUTE

• route_id (PK, UUID)

• so_id (FK → USER, role = SO)

• beat_day (enum: Sat / Sun / Mon / Tue / Wed / Thurs)

• outlet_list (FK[] → OUTLET)

• p2_backup_pool (FK[] → OUTLET)

• effective_from_date (date)

• locked_until_date (date)

• change_log (JSON array: [{changed_at, changed_by, reason, before_state, after_state}])

SKU

• sku_id (PK, UUID)

• sku_code (string, unique, required)

• sku_name (string, required)

• category (enum: Cosmetics / Food / General)

• tp_bdt (decimal — Trade Price)

• mrp_bdt (decimal — Maximum Retail Price)

• unit_of_measure (string, e.g. PCS / BOX / KG)

• stock_cover_category (enum: Fast / Medium / Slow)

• is_active (boolean)

VENDOR

• vendor_id (PK, UUID)

• vendor_name (string, required)

• contact_person (string, required)

• sku_list (FK[] → SKU)

• dp_per_sku (JSON: {sku_id: dp_bdt})

• credit_terms (enum: CAD / 15-day / 30-day / Advance)

• lead_time_days (integer)

• margin_gpm_pct (decimal)

• exclusivity_scope (text)

• contract_expiry_date (date)

• bank_details (encrypted text)

• status (Active / Inactive / Pending Approval)

• approved_by (FK → USER)

• approved_at (timestamp)

PURCHASE_ORDER (PO)

• po_id (PK, UUID)

• vendor_id (FK → VENDOR)

• sku_list_qty (JSON: [{sku_id, qty_ordered, agreed_dp_bdt}])

• delivery_date (date)

• wh_address (string)

• status (enum: Draft / Approved / Issued / Acknowledged / Partially Received / Closed / Cancelled)

• created_by (FK → USER — SCM Manager)

• approved_by (FK → USER — Business Head)

• approved_at (timestamp)

• issued_at (timestamp)

• vendor_acknowledged_at (timestamp)

GRN (Goods Received Note)

• grn_id (PK, UUID)

• po_id (FK → PO)

• received_date (date)

• handover_location (enum: Receiving Bay / Other)

• handover_location_note (text, required if Other)

• items_received (JSON: [{sku_id, batch_number, expiry_date, qty_ordered, qty_received, condition}])

• items_rejected (JSON: [{sku_id, qty_rejected, rejection_reason}])

• discrepancy_photos (file references)

• discrepancy_notes (text)

• same_day_return_confirmed (boolean)

• wh_manager_sign_id (FK → USER)

• signed_at (timestamp)

• status (enum: Draft / Signed / Partial / Closed)

DEBIT_NOTE

• debit_note_id (PK, UUID)

• grn_id (FK → GRN)

• vendor_id (FK → VENDOR)

• items_rejected (JSON: [{sku_id, sku_name, qty_rejected, rejection_reason, unit_dp_bdt}])

• total_value_bdt (decimal)

• raised_by (FK → USER)

• raised_at (timestamp)

• status (enum: Open / Resolved / Credited)

• resolution_notes (text)

• resolved_by (FK → USER)

• resolved_at (timestamp)

STOCK_LEDGER

• ledger_id (PK, UUID)

• sku_id (FK → SKU)

• transaction_type (enum: GRN / Dispatch / Return / Adjustment / Rejected)

• quantity (integer — positive for inbound, negative for outbound)

• batch_number (string)

• expiry_date (date)

• reference_id (string — PO ID / DO ID / VLS ID / Adjustment reference)

• reference_type (enum: PO / DO / VLS / Adjustment)

• performed_by (FK → USER)

• timestamp (timestamp)

ORDER

• order_id (PK, UUID)

• outlet_id (FK → OUTLET)

• so_id (FK → USER)

• order_date (date)

• sku_list_qty (JSON: [{sku_id, qty, unit_price_bdt, discount_applied, promotion_id}])

• total_value_bdt (decimal)

• status (enum: Submitted / Processing / Dispatched / Delivered / Partially Delivered / Cancelled)

• submitted_at (timestamp — must be ≤ 8:00 PM cut-off)

• is_cutoff_compliant (boolean)

DELIVERY_ORDER (DO)

• do_id (PK, UUID)

• order_id (FK → ORDER)

• dsr_id (FK → USER)

• vehicle_id (string)

• route_id (FK → ROUTE)

• generated_at (timestamp)

VLS (Vehicle Stock Allocation Sheet)

• vls_id (PK, UUID)

• do_ids (FK[] → DELIVERY_ORDER)

• dsr_id (FK → USER)

• vehicle_id (string)

• outlet_sequence (JSON: ordered array of outlet_ids with per-outlet SKU/qty lists)

• shortage_flags (JSON: [{sku_id, ordered_qty, allocated_qty, shortage_pct}])

• checker_user_id (FK → USER)

• checker_confirmed_at (timestamp)

• dsr_signature (boolean)

• dsr_signed_at (timestamp)

• wh_manager_signature (boolean)

• wh_manager_signed_at (timestamp)

• status (enum: Generated / Staged / Checker Verified / DSR Signed / WH Countersigned / Departed / Returned / Reconciled)

• printed_at (timestamp)

DSR_ATTENDANCE_LOG

• log_id (PK, UUID)

• dsr_id (FK → USER)

• date (date)

• arrival_time (timestamp)

• arrival_status (enum: On Time / Late)

• vehicle_id (string)

• vehicle_check_fuel (enum: OK / Low)

• vehicle_check_tyres (enum: OK / Defective)

• vehicle_check_lights (enum: OK / Defective)

• vehicle_cleared_for_departure (boolean)

• departure_time (timestamp)

• departure_status (enum: On Time / Late)

• logged_by (FK → USER — WH Manager)

CHALLAN (Delivery Note)

• challan_id (PK, UUID)

• vls_id (FK → VLS)

• outlet_id (FK → OUTLET)

• dsr_id (FK → USER)

• delivery_date (date)

• items_ordered (JSON: [{sku_id, qty_ordered}])

• items_delivered (JSON: [{sku_id, qty_delivered, variance_reason}])

• cash_collected_bdt (decimal)

• outlet_identity_confirmed (boolean)

• outlet_identity_confirmed_at (timestamp)

• outlet_signature (boolean)

• outlet_signed_at (timestamp)

• delivery_outcome (enum: Delivered / Partially Delivered / Closed / Owner Absent / Refused / Wrong Outlet)

• delivery_timestamp (timestamp)

• challan_copy_with_dsr (boolean)

CASH_RECONCILIATION

• recon_id (PK, UUID)

• dsr_id (FK → USER)

• vls_id (FK → VLS)

• date (date)

• total_invoiced_bdt (decimal)

• total_cash_expected_bdt (decimal)

• total_cash_collected_bdt (decimal)

• unsold_stock_returned (JSON: [{sku_id, qty}])

• challans_submitted_count (integer)

• cash_envelope_confirmed (boolean)

• challans_confirmed (boolean)

• unsold_stock_confirmed (boolean)

• variance_bdt (decimal)

• variance_reason (text)

• so_verification_required (boolean)

• so_findings (text)

• management_resolution (text)

• status (enum: Pending / Complete / Discrepancy — Under Review / Resolved / Escalated)

• closed_by (FK → USER)

• closed_at (timestamp)

INVOICE

• invoice_id (PK, UUID)

• order_id (FK → ORDER)

• outlet_id (FK → OUTLET)

• items (JSON: [{sku_id, qty, unit_price_bdt, discount_bdt, vat_bdt, line_total_bdt}])

• subtotal_bdt (decimal)

• total_discount_bdt (decimal)

• total_vat_bdt (decimal)

• total_bdt (decimal)

• payment_type (constant: Cash)

• issued_at (timestamp)

• issued_by (FK → USER — Accounts)

VISIT_LOG

• visit_id (PK, UUID)

• so_id (FK → USER)

• outlet_id (FK → OUTLET)

• visit_date (date)

• gps_checkin_lat (decimal)

• gps_checkin_lng (decimal)

• gps_match_status (enum: Pass / Fail / Override)

• gps_distance_metres (decimal)

• visit_outcome (enum: Order Placed / Closed / Owner Absent / Refused / Competitor Only)

• p2_activation (boolean)

• p2_reason_code (enum: Closed / Owner Absent / Refusing / Permanently Shut)

• order_id (FK → ORDER, nullable — if visit outcome = Order Placed)

• checkin_timestamp (timestamp)

PROMOTIONAL_SCHEME

• scheme_id (PK, UUID)

• scheme_name (string)

• sku_id (FK → SKU)

• trigger_qty (integer — buy X)

• bonus_qty (integer — get Y)

• discount_pct (decimal — or flat discount)

• valid_from (date)

• valid_to (date)

• is_active (boolean)

• created_by (FK → USER)

6.2 Entity Relationships

ORDER →belongs to→ OUTLET ORDER →placed by→ USER (role: SO) ORDER →generates→ INVOICE ORDER →generates→ DELIVERY_ORDER DELIVERY_ORDER →assigned to→ USER (role: DSR) DELIVERY_ORDER →grouped into→ VLS VLS →signed by→ USER (role: DSR) VLS →counter-signed by→ USER (role: WH Manager) VLS →checker verified by→ USER (role: designated checker) VLS →generates→ CHALLAN (one per outlet) CHALLAN →belongs to→ OUTLET CHALLAN →references→ VLS CHALLAN →closes→ CASH_RECONCILIATION (aggregated) DSR_ATTENDANCE_LOG →belongs to→ USER (role: DSR) PURCHASE_ORDER →raised by→ USER (role: SCM Manager) PURCHASE_ORDER →approved by→ USER (role: Business Head) PURCHASE_ORDER →received as→ GRN GRN →belongs to→ PURCHASE_ORDER GRN →matched to→ VENDOR GRN →generates→ DEBIT_NOTE (on rejection) DEBIT_NOTE →against→ VENDOR DEBIT_NOTE →resolved by→ USER (role: Business Head) STOCK_LEDGER →references→ SKU STOCK_LEDGER →references→ PURCHASE_ORDER / VLS VISIT_LOG →belongs to→ USER (role: SO) VISIT_LOG →records visit to→ OUTLET OUTLET →assigned to→ USER (role: SO) OUTLET →belongs to→ ROUTE ROUTE →owned by→ USER (role: SO)

7. API Design Principles

7.1 REST Conventions

• All APIs follow RESTful conventions: resources as nouns, HTTP verbs for actions (GET, POST, PUT, PATCH, DELETE).

• Base URL pattern: https://api.dist-hub.example.com/v1/{resource}

• All responses: JSON format with envelope { "status": "success|error", "data": {...}, "message": "..." }.

• Pagination: cursor-based for large collections (visit logs, stock ledger); page-size default = 50, maximum = 500.

• Timestamps: ISO 8601 format (UTC). Client devices must handle timezone conversion to local BDT (UTC+6).

• Error codes: standard HTTP status codes (200, 201, 400, 401, 403, 404, 409, 422, 500) with machine-readable error codes in response body.

7.2 Authentication & Authorization

• All endpoints require a valid JWT Bearer token in the Authorization header.

• Token expiry: 12 hours for web app; 7 days for mobile app (with refresh token rotation).

• RBAC enforcement: each API endpoint declares the minimum required role; the auth middleware validates the caller's role before processing.

• SO data scoping: any endpoint that returns outlet, order, or visit data applies an automatic WHERE so_id = {caller.user_id} filter for users with role = SO; this is enforced at the API layer, not relying on client-side filtering.

• Rate limiting: 100 requests/minute per user; 500 requests/minute per IP.

7.3 Offline Sync Strategy for Mobile

• Mobile apps maintain a local SQLite database as the primary data store for field operations.

• Master data pull (server → device): Full sync at app launch; delta sync every 30 minutes when connected. Master data includes: outlet list, SKU master, route plan, active promotions, daily targets.

• Transaction push (device → server): All write operations (visit logs, orders, delivery logs, cash entries) are written locally first with sync_status = pending. A background sync worker pushes pending records to server at every available connection window. Server returns sync_id for each accepted record; device updates sync_status = synced.

• Conflict strategy: Master data conflicts: server wins. Transaction conflicts (duplicate visit log for same outlet/time): server rejects with 409; device logs are kept locally with sync_status = conflict; App Admin is notified.

• Sync status display: Mobile header shows: "Synced [X min ago]" / "Offline — [N] records pending".

7.4 Key API Resource Groups

8. Integration Specifications

9. Non-Functional Requirements

10. Go-Live Readiness Gate

10.1 Purpose

The Go-Live Readiness Gate is a formal system control that prevents Day 1 operations from commencing until the Business Head has verified that all foundational data is correctly loaded and configured. No SO leaves the warehouse on Day 1, and no DSR receives a VLS, until the Business Head executes the "Sign-Off and Unlock Day 1" action.

10.2 The 8-Item Checklist

10.3 System Sign-Off Process

1. App Admin completes data loading for each item and marks it as "Ready for Review" in the Go-Live Checklist screen.

2. The system automatically validates completeness for items 1–8 (e.g., counts outlets with missing fields, checks SKU prices are non-zero, verifies each SO has exactly 75 route outlets).

3. System shows a real-time completion status next to each item: a green checkmark if validation passes, a red X with item count if validation fails.

4. Once all 8 items show green checkmarks, the "Sign-Off and Unlock Day 1" button becomes active for the Business Head.

5. Business Head clicks the button; a confirmation modal shows: "You are signing off that all 8 data categories are complete and verified. Day 1 operations will be unlocked. This action cannot be undone." Business Head confirms.

6. System records: sign-off user ID, timestamp; sets system state go_live_unlocked = true.

7. From this moment, SOs can log in and access their routes; DSRs can log in; WH Manager can generate VLS for Day 1.

11. KPI Thresholds & Alert Configuration

12. Enum Values Reference

This section is the definitive reference for all dropdown/enum values used across the system. Engineering must implement exactly these values as the allowed set; no free-text alternatives are accepted for enum fields.

12.1 Outlet Types

Grocery Pharmacy General Trade Kiosk

12.2 Priority Tiers

P1 P2

12.3 Drop Size Tiers

Small (BDT 500 – 2,000) Medium (BDT 2,001 – 8,000) Large (BDT 8,001 and above)

12.4 Beat / Visit Days

Sat Sun Mon Tue Wed Thurs

Friday is excluded; Friday must not appear as an assignable beat day anywhere in the system.

12.5 Visit Outcomes (SO Visit Log)

Order Placed Closed Owner Absent Refused Competitor Only

12.6 P2 Activation Reason Codes

Closed Owner Absent Refusing Permanently Shut

12.7 Delivery Outcomes (DSR Challan)

Delivered Partially Delivered Closed Owner Absent Refused Wrong Outlet

12.8 Delivery Variance Reasons (Challan line item)

Outlet Refused Item Shortage — Pro-Rata Damaged in Transit Expiry Concern at Outlet Outlet Requested Reduction Other (requires text note)

12.9 PO Statuses

Draft Approved Issued Acknowledged Partially Received Closed Cancelled

12.10 GRN Item Conditions

Acceptable Damaged Near-Expiry Wrong Item Quantity Short

12.11 GRN Rejection Reasons

Expiry < 60 Days Damaged Packaging Quantity Mismatch Wrong SKU Delivered Non-Conforming Quality

12.12 GRN Handover Locations

Receiving Bay Other

12.13 Credit Terms (Vendor)

CAD (Cash Against Delivery) 15-Day 30-Day Advance

12.14 SKU Categories

Cosmetics Food General

12.15 Stock Cover Categories

Fast (minimum cover: 14 days) Medium (minimum cover: 10 days) Slow (minimum cover: 7 days)

12.16 Stock Ledger Transaction Types

GRN Dispatch Return Adjustment Rejected

12.17 Reconciliation Statuses

Pending Complete Discrepancy — Under Review Resolved Escalated

12.18 Debit Note Statuses

Open Resolved Credited

12.19 User Roles

SO DSR WH Manager SCM Manager Accounts Sales Head Business Head App Admin

12.20 Zones

Narayanganj Town Bandor Munshiganj All (for users with cross-zone access: Sales Head, Business Head, App Admin)

12.21 VLS Statuses

Generated Staged Checker Verified DSR Signed WH Countersigned Departed Returned Reconciled

12.22 Vehicle Condition Check Values

Fuel: OK | Low Tyres: OK | Defective Lights: OK | Defective

12.23 GPS Check-In Statuses

Pass (within configured radius) Fail (outside radius — blocked) Override (outside radius — SO confirmed with audit log)

12.24 Outlet Statuses

Active Inactive Permanently Closed

12.25 Order Statuses

Submitted Processing Dispatched Delivered Partially Delivered Cancelled

12.26 DSR Arrival / Departure Statuses

On Time Late

13. Open Questions

The following questions require explicit product and business decisions before engineering implementation can begin. Each question is listed with context and the implication if not resolved.

OQ-01: Who physically performs the checker role for VLS verification, and how is this managed in the system?

Context: Business Rule DS-01a requires that a "designated checker" — different from the picker — verifies staged goods against the VLS before sealing. The system must record the checker's user ID.

Decision needed: Is the checker a fixed role (a specific person per shift), or does the WH Manager designate a different person each day? If it varies daily, the WH Manager must assign the checker in the system before the picking session begins. If it is a fixed role, a permanent "Checker" user account must be created. This affects user role design and the permissions matrix.

Implication if unresolved: Engineering cannot build the checker assignment workflow correctly.

OQ-02: What is the exact mechanism for printing challans — does each DSR have a mobile printer, or is the challan a digital PDF shown to the outlet owner?

Context: Requirement DS-27 states the signed original challan must remain with the outlet. This implies a physical paper challan. However, no printer hardware has been specified.

Decision needed: (a) Will each DSR vehicle be equipped with a Bluetooth thermal printer for printing challans at the outlet? Or (b) will challans be digital — shown on DSR phone screen for outlet owner to "sign" via a touchscreen signature? Or (c) will challans be pre-printed at the warehouse against the VLS the night before?

Implication if unresolved: The DSR app architecture (specifically the challan generation flow) differs significantly depending on the answer. Option (a) requires Bluetooth printer SDK integration. Option (b) requires digital signature capture. Option (c) requires pre-print logic and a different reconciliation model.

OQ-03: What is the daily cash deposit process — is there a specific bank account, deposit time window, and authorization chain?

Context: AC-16 requires daily cash deposit to bank to be recorded and reconciled. Currently, the system captures this as a manual entry.

Decision needed: Who physically deposits cash (WH Manager, Accounts, or a runner)? What is the target deposit time? Is there a single bank account or multiple? Is there a minimum deposit amount that triggers a separate approval?

Implication if unresolved: The cash deposit workflow in the Accounts module cannot be finalized; the daily cash summary report structure depends on this.

OQ-04: How should the system handle a DSR who misses the 6:00 PM return deadline — what is the escalation protocol and what does the WH Manager do with the day's stock and cash if the DSR is unreachable?

Context: DS-19 requires WH Manager to record DSR return time. No formal protocol is defined for late or non-return.

Decision needed: Should the system auto-escalate to Sales Head and Business Head after a configurable late threshold (e.g., 30 minutes late)? Can the WH Manager close a DSR's day-end with "DSR Not Returned — Escalated" status? What happens to the stock and cash accounting when this state is triggered?

Implication if unresolved: The day-end reconciliation state machine cannot be fully defined; the WH Manager will have no clear system guidance in an emergency.

OQ-05: What is the exact formula and weighting used for per-SO target adjustment in TS-01 ("WH target ÷ 6, adjusted by route potential")?

Context: Monthly targets are distributed across 6 SOs, with an adjustment for "route potential." The BRD references this but does not define the formula precisely.

Decision needed: Is route potential based on: (a) weighted average drop size of outlets on the route, (b) historical order value per SO from prior months, (c) total P1 outlet count on the route, or (d) a combination? Who defines the weighting factor and can it change monthly?

Implication if unresolved: The target auto-calculation logic in TS-01 and TS-10 cannot be implemented; the system cannot generate SO-level targets from the WH-level target without this formula.

OQ-06: How should the system handle a situation where the SCM Manager role is unfilled or on leave — who acts as backup, and does the Business Head have temporary PO-raise access?

Context: The SCM Manager is now a first-class system role responsible for raising RFQs and POs. If this role is vacant (as noted, Warehouse In-Charge is currently vacant), there is a risk of procurement blockage.

Decision needed: Should the system support a "delegate" feature where Business Head can temporarily grant SCM Manager permissions to another user? Or should PO-raise access default to Business Head if no SCM Manager user is active?

Implication if unresolved: The system may block procurement if the SCM Manager account is not set up or the person is unavailable, with no formal bypass.

OQ-07: What is the policy for handling returns from outlets — specifically, what approval level is required (SO only, or WH Manager only, or either) and how quickly must a returned SKU be re-assessed before returning to sellable stock?

Context: DS-13 states returns require "manager/SO approval" but does not specify which manager or what the re-inspection process is for returned goods before they re-enter inventory.

Decision needed: (a) Can an SO approve a return from the field app, or must the WH Manager approve it at the warehouse? (b) Do returned goods go directly back to stock or to the "Return Product Store" first for condition assessment? (c) If re-assessment finds the goods are not sellable, does a Debit Note apply to the outlet or is it a write-off?

Implication if unresolved: The returns workflow in both the DSR app and the WH module cannot be fully implemented; the STOCK_LEDGER transaction type for returns is ambiguous.

OQ-08: What is the system behaviour at the exact order cut-off moment (8:00 PM) for orders that are in progress but not yet submitted?

Context: SA-14 states the system auto-closes order entry at 8:00 PM. However, an SO may be mid-entry at 7:59 PM.

Decision needed: If an SO has started entering an order (SKUs selected, quantities entered) but has not tapped "Submit" by 8:00 PM: (a) should the system auto-submit the in-progress order as-is, (b) should it discard it and notify the SO, or (c) should it save the draft locally but mark it as "After Cut-Off — Not Submitted" for supervisor review? Each option has different implications for data integrity and SO fairness.

Implication if unresolved: The order cut-off logic in the SO app cannot be finalized; there is a risk of revenue loss or SO disputes if not explicitly decided.

Document Control: PRD Version 1.0 | May 2026 | Product Owner: Head of P.S & A.S Based on: BRD v1.1 — Narayanganj Distribution Hub Engineering decisions made against this PRD require written acknowledgement from the Product Owner. Open Questions in Section 13 must be resolved before sprint planning for affected modules begins.