Mushroom & Vegetable Delivery Management System

A comprehensive delivery management system for small produce delivery businesses with support for SMS order intake, route optimization, billing, and Cantonese voice input.

✅ Test Results

All 5 core test scenarios PASSED:

✓ Scenario 1: Product and customer setup with pricing overrides
✓ Scenario 2: SMS order processing with Cantonese/English parsing
✓ Scenario 3: Order creation with custom pricing
✓ Scenario 4: Delivery adjustments
✓ Scenario 5: Billing statement generation and payment tracking

Features Implemented

Backend (Node.js + SQLite)

✅ Customer management with addresses and billing cycles
✅ Product catalog with cost/price tracking
✅ Customer-specific pricing overrides
✅ SMS/voicemail message parsing (Cantonese + English)
✅ Order management with line items
✅ Delivery route planning and optimization
✅ Billing statement generation
✅ Payment tracking (cash, cheque, e-transfer)
✅ Reporting (daily summary, period summary, top customers, product performance)
✅ Price history tracking

API Endpoints

Customers

GET /api/customers - List all customers
GET /api/customers/:id - Get customer by ID
GET /api/customers/phone/:phone - Get customer by phone
POST /api/customers - Create new customer
PUT /api/customers/:id - Update customer
DELETE /api/customers/:id - Delete customer
GET /api/customers/:id/pricing - Get pricing overrides
POST /api/customers/:id/pricing - Set pricing override

Products

GET /api/products - List all products (query: common_only=true)
GET /api/products/:id - Get product by ID
POST /api/products - Create new product
PUT /api/products/:id - Update product
POST /api/products/bulk-update-price - Bulk update prices
GET /api/products/:id/price-history - Get price history
GET /api/products/:id/cost-history - Get cost history

Orders

GET /api/orders - List orders (query: delivery_date, customer_id, status)
GET /api/orders/:id - Get order by ID
POST /api/orders - Create new order
PUT /api/orders/line-items/:line_item_id - Update line item (delivery adjustments)
POST /api/orders/:id/deliver - Mark order as delivered
DELETE /api/orders/:id - Delete order

Messages (SMS/Voicemail)

GET /api/messages - List messages (query: status)
POST /api/messages/receive-sms - Receive SMS webhook
POST /api/messages/:message_id/convert-to-order - Convert message to order
PUT /api/messages/:message_id/status - Update message status

Routes

GET /api/routes - List routes (query: delivery_date)
GET /api/routes/workers - List delivery workers
POST /api/routes/workers - Create worker
POST /api/routes/optimize - Optimize routes
GET /api/routes/:route_id - Get route details
PUT /api/routes/:route_id/status - Update route status

Billing

GET /api/billing/statements - List statements (query: customer_id, payment_status)
POST /api/billing/statements/generate - Generate statement
GET /api/billing/statements/:statement_id - Get statement details
PUT /api/billing/statements/:statement_id/send - Mark as sent
POST /api/billing/payments - Record payment
GET /api/billing/payments/customer/:customer_id - Get customer payments
GET /api/billing/outstanding - Get outstanding balances

Reports

GET /api/reports/daily-summary - Daily sales summary (query: date)
GET /api/reports/period-summary - Period summary (query: start_date, end_date)
GET /api/reports/top-customers - Top customers (query: start_date, end_date, limit)
GET /api/reports/product-performance - Product performance (query: start_date, end_date)

Installation & Setup

Prerequisites

Node.js (v16 or higher)
npm

Backend Setup

Navigate to backend directory:

cd D:\StandardTrading\delivery-system\backend

Install dependencies:

npm install

Initialize database:

npm run init-db

Run tests to verify setup:

npm test

Start the server:

npm start

The API will be available at http://localhost:3000

Environment Configuration

Copy .env.example to .env and configure:

PORT=3000
NODE_ENV=development

# Twilio (for SMS integration - optional for now)
TWILIO_ACCOUNT_SID=your_account_sid
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_PHONE_NUMBER=your_phone_number

# Google Maps API (for route optimization - optional for now)
GOOGLE_MAPS_API_KEY=your_api_key

Database Schema

The system uses SQLite with the following main tables:

customers - Customer information with addresses
products - Product catalog with costs and prices
customer_pricing - Customer-specific price overrides
orders - Orders with delivery dates
order_line_items - Individual items in orders
delivery_workers - Delivery personnel
delivery_routes - Optimized delivery routes
message_inbox - SMS/voicemail inbox
billing_statements - Billing statements per customer
payments - Payment records

Usage Examples

1. Add a Customer

curl -X POST http://localhost:3000/api/customers \
  -H "Content-Type: application/json" \
  -d '{
    "name_english": "Mr. Chan",
    "name_cantonese": "陳先生",
    "phone_primary": "416-555-0001",
    "address_street": "123 Main St",
    "address_city": "Toronto",
    "billing_cycle": "monthly"
  }'

2. Add a Product

curl -X POST http://localhost:3000/api/products \
  -H "Content-Type: application/json" \
  -d '{
    "name_english": "Large Eggs",
    "name_cantonese": "大雞蛋",
    "category": "eggs",
    "is_common_item": true,
    "current_base_cost": 3.50,
    "default_price": 5.00,
    "unit": "dozen"
  }'

3. Set Custom Pricing for VIP Customer

curl -X POST http://localhost:3000/api/customers/{customer_id}/pricing \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "{product_id}",
    "custom_price": 4.50,
    "notes": "VIP discount"
  }'

4. Simulate SMS Order

curl -X POST http://localhost:3000/api/messages/receive-sms \
  -H "Content-Type: application/json" \
  -d '{
    "from": "416-555-0001",
    "body": "明天要兩打大雞蛋，一公斤大菇"
  }'

5. Create Manual Order

curl -X POST http://localhost:3000/api/orders \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "{customer_id}",
    "delivery_date": "2026-01-14",
    "order_source": "manual-entry",
    "line_items": [
      {
        "product_id": "{product_id}",
        "quantity": 2
      }
    ]
  }'

6. Generate Daily Summary Report

curl http://localhost:3000/api/reports/daily-summary?date=2026-01-13

SMS Message Parser

The system includes a smart parser for Cantonese and English SMS messages:

Supported patterns:

"明天要兩打大雞蛋，一公斤大菇" → 2 dozen Large Eggs, 1 kg Large Mushroom
"tmr need 3 dozen 大雞蛋" → 3 dozen Large Eggs
"要蛋" → Flagged for manual review (ambiguous)

Confidence scoring:

High (>85%): Auto-creates order
Medium (60-85%): Flags for quick review
Low (<60%): Requires manual parsing

Next Steps (Not Yet Implemented)

Frontend Web Application

React-based dashboard
Mobile-responsive design
Voice input using Web Speech API
Customer/product management UI
Order entry grid interface
Route planning map view
Billing statement generation UI

Mobile PWA

Offline-capable delivery app
GPS navigation integration
Digital signature capture
Real-time order adjustments
Photo capture for notes

Integrations

Twilio SMS webhook (currently simulated)
Google Maps API for route optimization
Email service for billing statements
Voicemail transcription service

Additional Features

Multi-user authentication
Role-based permissions
Customer portal for self-ordering
Automated SMS confirmations
Inventory forecasting
Excel export for reports

File Structure

delivery-system/
├── backend/
│   ├── routes/
│   │   ├── customers.js      # Customer management
│   │   ├── products.js       # Product management
│   │   ├── orders.js         # Order management
│   │   ├── messages.js       # SMS/voicemail handling
│   │   ├── routes.js         # Delivery route planning
│   │   ├── billing.js        # Billing & payments
│   │   └── reports.js        # Reporting endpoints
│   ├── utils/
│   │   └── message-parser.js # SMS parsing logic
│   ├── database.js           # Database wrapper
│   ├── init-database.js      # Schema initialization
│   ├── server.js             # Express server
│   ├── test-scenarios.js     # Automated tests
│   ├── package.json
│   └── .env.example
├── frontend/                 # (To be implemented)
├── docs/
└── README.md

Support

For issues or questions, contact the development team.

License

Proprietary - For internal use only

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
backend		backend
frontend		frontend
FRONTEND_GUIDE.md		FRONTEND_GUIDE.md
MOBILE_VOICE_INPUT.md		MOBILE_VOICE_INPUT.md
PRODUCT_LIST.md		PRODUCT_LIST.md
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
START_HERE.md		START_HERE.md
start-servers.bat		start-servers.bat

heiwang/standardTradingInput

Folders and files

Latest commit

History

Repository files navigation