A1. The Marketplace in One Page

QuickBite is a hyperlocal food marketplace:

• The platform lists many restaurants (merchant warehouses) that serve defined zones.
• A customer sets an address → sees eligible restaurants → chooses Delivery, Pickup, or Dine-in → orders from one restaurant at a time (warehouse-scoped stock).
• Checkout is one page (tip + kitchen notes optional); payment via enabled methods (including optional wallet, all-or-nothing).
• Kitchen accepts and prepares; rider delivers and proves delivery (POD: photo and/or OTP).
• Platform keeps commission; merchants get payouts; riders get tips; marketing may add deals, cashback, referrals, wallet credit.
• One sentence: geo decides who can sell; warehouse decides what can be sold; order status decides who is working; commission decides who earns.

QuickBite storefront — the marketplace as the customer sees it

Money flow

Value-chain overview

Value-chain overview

A2. Personas

A3. How Money Moves

Customer pays (gross)

Food + delivery/pickup/dine-in fees + tax − discounts + rider tip (tip is rider economics, not kitchen food commission).

Credit Wallet must cover the full payable amount (no split tender with card).

Platform commission (take rate)

Merchant Commission calculates platform cut vs merchant owed:

Payout is a separate ops step from calculation. Refunds may not auto-reverse commission unless implemented.

Merchant commission settings (admin)

Promotions cost margin

Example (illustrative)

Food $20 + delivery $2 + tip $3 = $25 paid → ~15% food commission ≈ $3 platform → merchant ~$17 food → rider $3 tip. Exact ledgers to follow your rate tables.

Commission decision flow

Commission decision flow

Tip vs food revenue

Tip vs food revenue

A4. Journeys & Serving Types

Delivery journey: address → in-coverage restaurants → cart → OPC → track → POD. Pickup: serving type Pickup → pickup point → pay → collect (no rider POD). Mobile: same via Web API (JWT/NST); phone OTP needs Authentication; force-update per OS.

Geo & serving-type eligibility

Delivery coverage areas (admin) — zones that decide eligibility

Geo & serving-type eligibility

Merchant onboarding swimlane

Merchant onboarding swimlane

A5. Order Lifecycle (Kitchen + Rider)

Sales → Orders — where order statuses show up in admin

Auto-missed: clears stuck New (kitchen SLA).

Auto-cancel clears stale Pending/New. Tune minutes to real kitchen speed (e.g. 15–30 for QSR New; install defaults are 24h/48h).

Order state machine

Order state machine

A6. Business Rules & Daily Ops

Non‑negotiable rules

• One restaurant context per cart (warehouse-scoped inventory).
• Delivery visibility = coverage ∩ active warehouse ∩ delivery flags.
• Pickup may bypass delivery coverage when Allow Pickup.
• Wallet all-or-nothing.
• Tip ≠ kitchen commission.
• POD is a trusting policy (Photo / OTP / Both).
• Commission ≠ payout.
• Don't assume refund reverses commission.
• Merchants don't edit global take rates (typical ACL).
• Riders see only assigned orders.

Ops day

Healthy marketplace: zone always has ≥1 open restaurant; New→ Ready within SLA; high Complete; COD matches; merchants paid on schedule.

Merchant day

Active warehouse + stock → New→ Processing→ Ready → Pickup handoff or wait for rider → chat → own payout lines (not global rates).

A7. Admin vs Developer Ownership

Rule: Configure screen or warehouse form → admin. New behavior or invariant break → developer.

A8. Developer Domain Map & Invariants

Business asks → Start in

Hard Deps: Merchants Hub; Commission→ OM; Shop→ Promotions; Web Api last (Auth, Shop, OM, Menu, OPC). Soft: Promotions→ CreditWallet (must not crash if wallet is missing).

Invariants (do not break)

• Status Ids 10–50; Ready/In Route survives core Check Order Status (spec §6.8).
• No silent cross-warehouse cart merge.
• Don't "fix" empty Delivery lists by ignoring geo.
• OPC refreshes shipping/payment only for listed address fields.
• Buy Now ≠ Bypass cart (independent).
• No invented wallet split tender.
• Pickup hours display ≠ enforce unless you build enforcement.
• Document commission precedence; don't invent refund reverses.
• JWT/NST when enabled; OTP needs Authentication.
• Follow plugins/AGENTS.md.
• Multi-store overrides; no cross-store location leaks.
• GDPR: Purge Food Shop PII on customer delete (wallet, chat, favorites, location, subscribers, referrals).

B1. Product Positioning & Why QuickBite

Who buys it: city marketplace operators, multi-restaurant brands, white-label agencies, mobile teams needing API parity.

Why: hyperlocal primitives first-class; modular plugins; ops stack included; web + mobile one backend; nopCommerce ecosystem; Quick Bite Figma-aligned UX.

Tech: net9.0; Repository/linq2db; Fluent Migrator; SignalR; Lucene (+ optional Redis); Authentication for app OTP.

B2. Plugin Inventory & Features

A plugin Configure card (Mega menu) — every plugin follows this shape

Also needed: NopStation.Core; Authentication (app OTP); WidgetManager (mega menu). Shipping: live rates in Merchants (IShippingRateComputationMethod). FixedByWeightByTotal is review-only under plugins/code review/.

Feature Summary

• Discovery: coverage, cuisines/brands, favorites, reviews, Lucene, mega menu, quick view
• Checkout: OPC, tip/notes, Buy Now / bypass cart, pickup points, wallet
• Ops: status board, riders, POD, cash, auto-miss/cancel, SignalR, track order
• Commerce: commission, payouts, tips, affiliates, cashback, deals, tiers, shop widgets
• UX/mobile: Theme, chat, Web API, WebP/image resize

Plugin dependencies diagram

Plugin dependencies

B3. How Each Role Uses the Product

• Customer (web): location → /merchants → shop → OPC → track → optional wallet/deals/chat.
• Customer (app): appstart / JWT → same flows; respect force-update.
• Merchant: own warehouse/stock/orders/ribbons; not global rates.
• Rider: /deliveryman/orders → POD → cash → /deliveryman/tips → chat.
• Platform admin: install → maps/coverage/WH → OPC/OM → riders → Theme/Shop → optional commission/promos/Lucene/API → smoke tests.

B4. Architecture Diagrams

API prefixes: api/home, merchants, catalog, product, shoppingcart, checkout, order, customer, deal, chat.

System context / sequences

System context

Sequence — delivery order

Sequence — pickup order

Sequence — order lifecycle (customer / kitchen / rider / ops)

Real-time (SignalR)

Real-time (SignalR)

Security zones

Security zones

B5. Roles, Permissions, Limits

Customer roles — Merchants and DeliveryMan drive the permission model

Permission keys live in each plugin's *PermissionProvider (e.g., ManageWarehouses, ManageOrders, ManageNopStationMerchantCommissionConfiguration). NopChat has no dedicated PermissionProvider.

Unsupported / Do Not Promise

C1. Prerequisites & Install Order

Configuration → Local plugins — install starts here

Need: nopCommerce 4.90 admin; NopStation.Core; FoodShop packages; Maps key; working email; optional SMS, Redis, Authentication, WidgetManager.

Install via Configuration → Local plugins in this order:

After install: confirm ACL permissions; Theme sets store theme to FoodShop; sample assets seed on Install only (not Update).

Uninstall notes: localization/tasks removed; confirm table retention; OPC should clean auto tip/notes attributes; don't leave dependents if Merchants disabled.

C2. Day-Zero Go-Live

C3. Configure Merchants & Warehouses

Warehouse list — one warehouse per restaurant

Menu: NopStation → Warehouses → Configuration (/Admin/Warehouse/Configure). Also: Warehouses list, Delivery coverage, Delivery group, Cuisines, Brands, Review questions.

Install defaults to replace

EnableDefaultMerchant/Address true; sample NYC address; DistanceToAddNewAddress 100; discount filtering on; list grid 12,24,48. For multi-merchant production: often turn default merchant off; set real city center.

First save

• Google Maps API key (Places + Maps JS).
• Default merchant on/off + Default warehouse.
• Default address via Places/map.
• Dine-in %; keep discount filtering on; WebP ~80.
• Optional: Map custom address attributes (Customer settings → Address form fields).

Coverage

Delivery coverage areas — draw zones, then assign to a delivery group

States/cities/areas if required → Delivery coverage list → Delivery group → assign to warehouse (groups typically exclusive to one WH).

Warehouse fields (must-get-right)

Active, Name, lat/lng, address, AllowShipping + ShippingRate, AllowPickup + PickupFee, AllowDineIn + %, Serving option, Coverage group, pictures, SEO. Then map stock + cuisines/brands.

Common mistakes

• Invalid Maps key
• Attributes not mapped
• Inactive WH / no coverage
• AllowPickup off
• Default merchant on without DefaultWarehouse
• WebpQuality outside 1–100

C4. Configure OPC, Orders, Pickup

FoodShop OPC settings

OPC — NopStation → Foodshop OPC (/Admin/FoodshopOpc/Configure)

Install creates: Tip your rider (10/20/50/100, default 20) + Notes to Restaurant (max 500); OPC + bypass cart + panels + tip/notes UI on. Re-check attribute IDs after reinstall.

Minimum: Enable OPC; show editable cart; show attributes; tip + notes UI; discount/GC as needed. Tip is for delivery carts. Address field lists control when shipping/payment methods refresh — unlisted fields do not refresh.

Order Management — NopStation → Order management

Sales → Orders — the list the dashboard works from

Configure: /Admin/OrderStatusDashboard/Configure · Dashboard: …/Dashboard

Install defaults: auto-miss 1440m on; auto-cancel 2880m on; POD required; mode OTP only; OTP 4; email on; SMS off.

Production: choose Photo / OTP / Both; OTP 4–10; email and/or SMS (+ ActiveSMSPluginSystemName); tune SLA; enable location history cleanup in prod.

Delivery man: customer account → Delivery Man form (merchant, area, phone, KYC pics, Verified, Available) → /deliveryman/orders.

Daily board: New → Processing → Ready → assign rider → In Route → POD → Complete; COD → Cash Collection.

Pickup

No plugin Configure page. Warehouse AllowPickup (+ fee). Serving type Pickup → point appears only if AllowPickup. Hours may display without blocking checkout.

C5. Configure Commission, Promos, UX, Search, API

Promotions → Discounts

Merchant commission — Configure card

Commission — NopStation → Merchant commission

Configure card mainly: Enable plugin + Use commission rules. Rates on Rule/Category/Product screens. Enable Plugin defaults true; daily payout task registered. Rules mode with no published rules ⇒ commission 0. Tips need OPC tip UI; riders see /deliveryman/tips.

Theme — Themes → FoodShop

FoodShop theme settings

Theme = FoodShop; brand colors; phone/social; sticky/lazy; hide core homepage blocks if Shop widgets replace them; header shortcuts; footer boxes/logo/cards.

Shop — NopStation → Shop

Install: carousel/slider/tabs/campaign/CSS/ribbons on; flipbook off. Create slider + carousel/tab; ribbon caches (discount cache short); image resize 1920/768. CRUD: sliders, carousels, tabs, flipbooks, ribbons, subscribers.

Smart Mega Menu / Quick View / Chat

Mega menu settings

Mega menu on + hide default menu; picture size 300. Quick View: enable food-relevant sections; picture zoom needs Picture Zoom plugin. Chat: logo + weekday open flags.

Promotions & Wallet

Refer-and-earn, affiliate defaults, cashback, wallet transfer (only CreditWallet), tiers, banners/deals — promos cost margin. Activate payment method Credit Payment; show credit on checkout; max invoices; test full wallet pay only.

Lucene

FoodShop Lucene search settings

Writable Index Directory; fuzzy (distance 1) + contains; Exact boost highest; multi-instance + Redis only on farms; rebuild after catalog import.

Web API (last)

Strong secrets; Enable JWT (NST header); token lifetime; Show change base URL = Off in prod; home rails + theme colors; Android/iOS versions & force flags independent; GDPR delete account if needed. App OTP needs Authentication.

C6. Users, Verify, Troubleshoot

Merchant user: Customers → Merchants role → link warehouse. Rider: customer + Delivery Man Verified/Available. ACL: grant Administrators FoodShop manage permissions (warehouses, orders, commission, OPC, Shop, Promotions, Theme, WebApi, Lucene, etc.).

Verify

Delivery: in-coverage address → cart → OPC pay → New→ Ready→ rider→ POD→ Complete (+ commission). Pickup: Pickup serving → AllowPickup Point → Pay → merchant fulfill. Negatives: out of coverage; empty cart; low wallet; wrong OTP; other rider's order denied.

Sign-off checklist: Maps; ≥1 Active WH+stock+coverage; OPC tip/notes; POD; ≥1 rider; Theme/Shop; Lucene; optional wallet/API; multi-store if used.

Troubleshooting

Admin Menu Map

Configure URLs

D1. Settings Reference (All Plugins)

Each row: setting — admin hint / use. Suggested values noted where critical.

Merchants (MerchantSettings + discount admin fields)

OrderManagement (OrderStatusDashboardSettings)

Merchant Commission

Precedence (rules off): MerchantProduct → Product → max(MerchantCategory) → max(Category).

OPC (FoodshopOpcSettings)

Shop (ShopSettings)

EnableOCarousel / Slider / ProductTabs / FlipBook / ShopCampaign / ShopCustomCss; FlipbookDefaultPageSize; MerchantRibbon (+ dynamic, auto-sync, intervals/caches); MinimumReviewsToShowRating (default 3); EnableAutoImageResize; SliderDesktop/Mobile widths (1920/768).

Promotions (FoodShopPromotionsSettings)

Affiliate defaults (amount/%); ReferAndEarnEnabled + reward + max orders (0=unlimited); cashback HistoryPageSize / MinimumBalanceToDisplay / MinimumGiftcardAllowed; EnableCashBackToWalletTransfer + MinimalWalletTransferAmount; announcement/deal banner fields; Bronze→ Platinum thresholds and points rates.

NopChat / MegaMenu / QuickView

FoodShop NopChat configuration

Chat Logo + OpenOnMonday…Sunday. MegaMenu Enable + HideDefaultMenu + MenuItemPictureSize. QuickView toggles for related/also-purchased/zoom/descriptions/buttons/reviews/manufacturers/availability/delivery/specs/tags.

Theme (FoodShopSettings)

FoodShop theme settings

Color palette; Phone/Instagram/Pinterest; login box; lazy load; sticky header; hide review/buttons; CustomCss; footer contact/logo/cards; hide homepage bestsellers/categories/products; Header menu one/two; Footer description boxes 1–4.

WebApi (WebApiSettings)

EnableJwtSecurity; SecretKey/TokenKey/TokenSecret; CheckIat; TokenSecondsValid; home slider/featured/bestsellers/category/manufacturer rails; price text sizes; Android/iOS version + force + store URLs; Logo; ShowChangeBaseUrlPanel (off prod); theme/gradient colors; ProductBarcodeScanKeyId; AllowCustomersToDeleteAccount.

Lucene (FoodShopLuceneSearchSettings)

IndexDirectory; Fuzzy/Contains/Exact boosts + distances; MultiInstance + Redis*; Search Fields; Delimiters/regex; MaxSearchResults; SignalRKeepAliveMinutes.

CreditWallet

ShowAvailableCreditOnCheckoutPage; ShowInvoicesInCustomerWalletPage; MaxInvoicesToShowInCustomerWalletPage.

Pickup

No ISettings. Warehouse AllowPickup, PickupFee, address/geo/hours.

D2. Q&A

• Quick Bite vs FoodShop? Brand/Figma vs plugin suite.
• MVP plugins? Core + Merchants + OPC + OM + Theme (+ Pickup if needed).
• Multi-store? Yes — use overrides; isolate location/cart.
• No restaurants? Coverage, Active WH, location, serving type.
• Two restaurants in one cart? Not supported by design.
• Split wallet + card? No.
• Pickup hours block checkout? Not guaranteed.
• Missed vs Cancelled? Missed = New SLA fail; Cancelled = stopped/unpaid paths.
• Commission choice? Catalog precedence or UseCommissionRules.
• Cashback needs wallet? Only for transfer-to-wallet.
• API OTP fails? Needs Authentication plugin.
• Android force not iOS? Independent flags.
• Search on farm? Enable Lucene multi-instance + Redis.
• Customer delete? Purge FoodShop PII (verify per plugin).

D3. Glossary, Routes, Tables, Widgets

Glossary

Public Routes

Representative NS_* Tables

• Merchants: NS_MerchantWarehouse, coverage/group, cuisine/brand, reviews, favorites…
• OM: NS_DeliveryMan*, NS_OrderOtp, NS_DeliveryProof, cash…
• Commission: product/category/rule commissions, NS_MerchantOrderInfo, payouts, NS_RiderTip*…
• Shop / Promotions / Chat / MegaMenu / WebApi / Lucene / Wallet: see enterprise spec & migrations.
• OPC / Theme / QuickView / Pickup: mostly settings-driven.

Widget Zones (High Level)

Merchants (account/order/header/address); OM (account/order); OPC (product/footer); Shop (widgetZones.json, ribbons); Promotions (announcement body-start); Chat footer; MegaMenu via WidgetManager; Theme header/footer; Wallet checkout/account.

Schedule Tasks

OM auto miss/cancel + location cleanup; Merchants sync; Lucene rebuild; Commission payout (daily).

D4. Related Docs

Former split guides (redirect stubs only): quickbite_business_and_domain_guide.md, quickbite_hyperlocal_marketplace_product_publishing.md, quickbite_hyperlocal_marketplace_configuration_handbook.md.

E1. Capability Model & Maturity

Use this model in SOWs: sell L1+L2 for launch city; add L3/L4 by phase.

Capability maturity

E2. Deployment Topologies

Single-node (pilot / single city)

Single-node (pilot / single city)

Multi-node farm (enterprise)

Multi-node farm (enterprise)

Farm requirements: sticky sessions or SignalR backplane as per hosting; Lucene EnableMultiInstanceMode + Redis; durable IndexDirectory; shared secrets for WebApi JWT; store-scoped settings reviewed per node.

Environment Strategy

E3. Non-Functional Requirements (NFR)

Aligned with foodshop-specifications.md:

Performance targets

E4. Security & Trust Architecture

Threat controls

E5. GDPR / PII Map

On customer delete, verify purge or documented retention for:

WebApi AllowCustomersToDeleteAccount must align with Authentication consent flows.

GDPR delete

E6. Multi-Store Enterprise Pattern

Checklist: OPC/Theme/Chat/WebApi/Commission overrides reviewed per store; catalogs isolated; Maps key may be shared or per-store; WebApi theme colors per brand store.

Multi-store enterprise pattern

E7. KPIs & SLA Catalog (Ops)

Map timers: AutoMissed / AutoCancel minutes must match Accept-time KPI.

E8. RACI (Enterprise Roles)

R = Responsible, A = Accountable, C = Consulted, I = Informed.

E9. Release & Go-Live Gates

Mandatory before production

• Install order verified; Merchants hub healthy.
• Maps + ≥1 Active WH with stock + coverage.
• Delivery E2E with POD; Pickup E2E if offered.
• Rider isolation + admin ACL spot-check.
• Commission sample calc signed by finance (if L3).
• Lucene rebuild; WebApi JWT secrets not default; change-base-URL off.
• GDPR delete path tested on staging.
• Rollback plan: disable OPC flag / theme / payment method as emergency levers.
• Support runbook (§E10) published.
• P0 FS_TC_* Pass or Blocked+Bug ID in test report.

Normative test IDs and packs: docs/foodshop-specifications.md §§8–9.

Release gates

E10. Support Runbooks (Short)

Escalation: L1 Support (handbook Part C) → L2 Implementer (settings) → L3 Engineering (spec + AGENTS).

E11. Integration Landscape

Integration landscape

E12. Data & Domain ER (Conceptual)

Conceptual ER

E13. Wallet & Promotions Cashflow

Wallet & promotions cashflow

E14. Lucene Multi-Instance

Lucene multi-instance (Redis sync)

E15. Diagram Gallery Index

E16. Change Management

F1. Customer Playbook

Who You Are

You order food from nearby restaurants on the website or mobile app. You do not use the admin panel.

What You Can Do

Delivery Order (Step-by-Step)

Customer delivery order flow

1. Open the store → set your address / pin (must be in a delivery zone).
2. Choose serving type Delivery.
3. Open /merchants → pick a restaurant → add items (you order from one restaurant at a time).
4. Go to checkout → confirm address → choose payment → optional tip and notes to restaurant.
5. Place order → watch status (accepted → cooking → on the way).
6. When the rider arrives, share OTP or allow photo proof if the platform requires it.
7. Optional: favorite the restaurant, leave a review, check cashback.

Pickup Order

1. Choose Pickup.
2. Select a restaurant that allows pickup.
3. Checkout selects the restaurant as the pickup point.
4. Pay → go to the restaurant → collect (no rider).

Mobile App Notes

• App may require update (force-update).
• Sign-in may use phone OTP.
• Same flows as web via FoodShop API.

Customer FAQ

Training Checklist (Customer Success / UAT)

• Place Delivery order end-to-end
• Place Pickup order
• Tip appears on Delivery checkout
• Track Order updates
• Favorites add/remove
• Wallet pay (if enabled)
• Refer / cashback pages open (if enabled)

F2. Merchant / Kitchen Playbook

Who You Are

You run a restaurant (warehouse) on the marketplace. You use the admin site with the Merchants role — usually only at your restaurant.

What You Can Do (Typical)

Kitchen Board Flow

Kitchen board flow

1. Sign in to admin → Order status dashboard.
2. When New appears → accept → Processing while cooking.
3. Mark Ready when bag is packed.
4. Delivery: ensure a rider is assigned (you or dispatcher).
5. Pickup: give the order to the customer when they arrive.
6. Keep stock updated; wrong stock = customer complaints.
7. Answer chat if a customer asks about the order.
8. Check payout / commission lines for your orders (not global %).

Merchant FAQ

Training Checklist

• Login as merchant → see only own WH
• Update hours / AllowPickup
• Move a test order New → Ready
• Assign or see rider
• Update one product stock
• Open deal participation (if used)

F3. Rider Playbook

Who You Are

You are a delivery man. You use the public store (not full admin) after the platform links your customer account as a delivery man (Verified + Available).

Screens

Delivery Run (Step-by-Step)

Rider delivery run

1. Log in → set Available.
2. Open /deliveryman/orders — you only see your assignments.
3. Go to restaurant when order is Ready → pick up.
4. Navigate to customer; keep location sharing on if required.
5. Complete with photo and/or OTP (as configured). Wrong OTP = rejected.
6. Check /deliveryman/tips for tip history.
7. Use /deliveryman/chat if customer/merchant messages you.

Note: Recording COD cash into Cash collection is typically done by admin/merchant, not on the rider public menu.

Rider FAQ

Training Checklist

• Verified + Available
• Complete one OTP delivery
• Complete one photo delivery (if mode allows)
• Tips page loads
• Cannot open another rider's order

F4. Platform Admin / Dispatcher Playbook

Who You Are

You own the marketplace: zones, restaurants, settings, take rates, riders, SLA, theme, apps.

Daily Ops (Dispatcher)

• Morning: Maps OK, key WH Active, riders Available.
• Watch the Order status dashboard for new backlog.
• Assign riders when Ready.
• Chase Missed/Cancelled spikes → tune timers or staffing.
• Afternoon: COD Cash collection reconciles.
• Payday: commission / payout queues.

Setup (First Time)

Follow Part C (install → day-zero → Merchants → OPC → OM → Theme). Enterprise gates: Part E release checklist.

Admin FAQ

See Part D Q&A and Part C for troubleshooting.

Training Checklist

• Day-zero path complete
• Create WH + coverage + stock
• Create rider
• Delivery + Pickup smoke tests
• POD email OTP works
• ACL: merchant cannot open commission Configure

F5. Affiliate / Refer-and-Earn Playbook

Who You Are

You drive traffic and may earn affiliate / referral rewards.

Platform admin manages affiliates and commissions in FoodShop Promotions admin. Note: An /affiliatedorder/history route may exist in routing; confirm the Orders action is implemented in your build before promising order-history UI.

Affiliate FAQ

F6. Marketing Playbook

Who You Are

You run growth: banners, deals, cashback, refer program, homepage merchandising — without changing geo/take-rate engineering.

Remember: every promo costs margin — agree funding with finance (Part A money).

Training Checklist

• Publish one deal + banner
• Refer-and-earn amounts set
• Homepage slider live
• Cashback→wallet only if CreditWallet installed

F7. Developer Quick Start

Who You Are

You change FoodShop plugins safely under nopCommerce 4.90 / AGENTS standards.

• Read A8 invariants — do not break warehouse scope, coverage, status Ids, wallet split, soft deps.
• Map feature → plugin (A8 table).
• Follow plugins/AGENTS.md (no EF, thin controllers, FluentMigrator, permissions).
• Install order Part C; never reverse hard dependencies.
• Add/adjust FS_* cases in foodshop-specifications.md; evidence in test report.
• Unit: dotnet test …FoodShop.Tests · E2E: Playwright project.
• UI changes: QuickBite Figma + Figma MCP.
• Farm search: Lucene multi-instance + Redis (Part E).

Developer workflow — feature request to release gate

F8. Support Playbook

Who You Are

You help customers, merchants, and riders. You change settings only with admin rights; you escalate code bugs to engineering.

Severity table: Part E10. Config deep-dive: Part C.

Support Training Checklist

• Reproduce customer "no restaurants" with map
• Know Missed vs Cancelled
• Know tip ≠ merchant payout
• Escalate Sev-1 using E10

F9. Persona → Document Map (Quick)

F10. Cross-Persona Communication Diagram

When chat is enabled, Customer ↔ Merchant ↔ Rider ↔ Admin can message on open weekdays (customer widget) or /deliveryman/chat (rider).

Cross-persona communication

G1. Visual Training (Figma + Staging)

Design Mockups (Customer UX)

Trainers: open Figma for browse → cart → checkout; side-by-side with Part F. UI QA: Figma MCP + FS_UI_*.

Live Staging (Admin + Public Not in Mockup)

Source: https://foodshop.nop-station.site/. Optional capture folder: docs/_staging_screenshots/ (add images yourself — do not embed in this doc). Regenerate helper: plugins/src/Tests/NopStation.Plugin.FoodShop.E2E/scripts/capture-staging-screenshots.mjs.

Public Storefront — Capture Checklist

Auth-gated (need customer/rider session): /wallet/details, /cashback/history, /refer-and-earn, /deliveryman/orders (07–11).

Admin (Not in Figma) — Capture Checklist

Notes from Staging

• Staging login is multi-step (Email → Continue → Password → Continue); /Admin/Login is not used (404 theme page).
• FoodShop admin menus live under Nop Station → Plugins.
• Order Status Dashboard cards: New / In Progress / Delivered / Missed.
• OPC shows Enable rider tip UI + Enable notes to restaurant UI.
• Sample merchant shop: warehouse-1-new-york (Burger Express) — catalog may still include demo non-food SKUs.

G2. Email / SMS Message Templates

FoodShop-Installed Email Templates (Order Management)

Admin path: Configuration → Email accounts (SMTP) · Content management → Message templates → search Dashboard.Order.

SMS OTP

• Not a nopCommerce message template — sent via Active SMS plugin (ActiveSMSPluginSystemName) when Send OTP via SMS is on.
• Requires customer/order phone.
• Test: place Delivery order → trigger OTP → check SMS gateway logs.

Other Notifications

Ops checklist: SMTP works → both Dashboard templates Active → OTP email received → (optional) SMS plugin configured.

G3. Mobile API Samples (JWT / NST)

When Enable JWT security is on, protected APIs expect header NST = JWT string signed with TokenSecret, containing claim NST_KEY = configured TokenKey. Optional iat claim validated against TokenSecondsValid when Check Iat is on.

Generate a Sample NST Token (Node Example)

// npm i jsonwebtoken
const jwt = require('jsonwebtoken');
const tokenSecret = process.env.FOODSHOP_TOKEN_SECRET; // WebApi TokenSecret
const tokenKey   = process.env.FOODSHOP_TOKEN_KEY;     // WebApi TokenKey
const nst = jwt.sign(
  { NST_KEY: tokenKey, iat: Math.floor(Date.now() / 1000) },
  tokenSecret,
  { algorithm: 'HS256' } // match JwtHelper used by the plugin
);
console.log(nst);

(Confirm algorithm with your JwtHelper implementation if HS256 fails.)

Sample Calls

POST /api/appstart HTTP/1.1
Host: your-store.example
Content-Type: application/json
NST: {paste-jwt-here}
DeviceId: {stable-device-guid}

{
  "Data": {
    "AppVersion": "1.0.0",
    "SubscriptionId": ""
  }
}

GET /api/merchants HTTP/1.1
Host: your-store.example
NST: {paste-jwt-here}
DeviceId: {stable-device-guid}

# Bash sketch (set env vars first)
curl -s -X POST "https://your-store.example/api/appstart" \
  -H "Content-Type: application/json" \
  -H "NST: $NST" \
  -H "DeviceId: $DEVICE_ID" \
  -d '{"Data":{"AppVersion":"1.0.0"}}'

Common failures: 401 → missing/invalid NST, wrong TokenKey/Secret, expired iat, or JWT security on while client sends none. Phone OTP endpoints need Authentication plugin.

Prefixes: api/appstart, api/home, api/merchants, api/catalog, api/product, api/shoppingcart, api/checkout, api/order, api/customer, api/deal, api/chat, …

G4. i18n / Second-Language Checklist

NFR-11 in Part E: second language switches UI strings — verify with FS_I18N_* in the enterprise spec.

G5. Backup / Disaster Recovery (DR)

What to Back Up

RPO / RTO Guidance (Tune with IT)

Restore Drill (Quarterly)

1. Restore DB to staging.
2. Point staging appsettings at restored DB.
3. Rebuild Lucene index.
4. Smoke: /merchants, OPC, one Delivery order, API appstart.
5. Record time-to-green as actual RTO.

Failover Levers (No Full Restore)

• Disable OPC → emergency fallback to core checkout (degraded UX).
• Disable payment method / wallet.
• Force-update mobile to known-good build.
• Scale out web nodes; enable Lucene Redis sync if search skew.

Failover / recovery sequence

G6. Commercial SOW / Packaging Annex

Use Part E capability levels in proposals (illustrative packaging — not a price list):

SOW must-state exclusions (from Part B limits): no split wallet tender; pickup hours not hard-enforced by default; commission reverse-on-refund not assumed; FixedByWeight shipping package review-only.

Acceptance: Part E9 gates + Part F training checklists signed by customer UAT lead.

G7. Document Changelog

Complete guide v2.3 — Parts A–G. Spec/test catalogs remain in docs/foodshop-specifications.md.