Skip to content

CMC7899/MPOS

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

124 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

TMG POS System

A comprehensive Point of Sale (POS) application with two main modules: POS Module for staff and Self-Checkout (SCO) Module for customers. Deployed on Cloudflare Pages with Thai localization and technology products.

🌐 Live Demo

Production URL (Cloudflare Pages)

πŸ”— https://tmgpos.pages.dev

Development Sandbox

πŸ”— https://3000-ib5zip5dd4151kpca3h9m-dfc00ec5.sandbox.novita.ai

Quick Start Links

Production URLs:

  1. SCO Self-Checkout: https://tmgpos.pages.dev/sco
  2. POS Login: https://tmgpos.pages.dev/pos/login
  3. POS Modern: https://tmgpos.pages.dev/pos/modern
  4. POS Home: https://tmgpos.pages.dev/pos/home
  5. Manager Dashboard: https://tmgpos.pages.dev/manager

✨ Features

Currently Implemented βœ…

βœ… Core Infrastructure

  • βœ… Hono + TypeScript + Cloudflare Pages architecture
  • βœ… Comprehensive D1 database schema (15 tables)
  • βœ… Mock data with 50+ products, users, members, discount rules
  • βœ… Responsive UI with TailwindCSS
  • βœ… Login system with role-based access
  • βœ… Session management with localStorage
  • βœ… PM2 process management

βœ… User Roles Supported

  • Customer - SCO self-service access
  • Cashier - Basic POS operations
  • Supervisor - Approval workflows with PIN
  • SCO Attendant - Self-checkout management
  • Store Manager - Full system access

βœ… POS Features Implemented

  • βœ… Home page - Module selection (POS vs SCO)

  • βœ… Login screen - Role-based authentication

  • βœ… POS Home/Sales Screen - Full cart management

    • Product search with barcode scanning simulation
    • Real-time product search and suggestions
    • Quick product grid for popular items
    • Cart item management (add, remove, update quantity)
    • Member attachment and detachment
    • Cart summary with subtotal, discounts, tax, total
    • Empty state handling
  • βœ… Member Lookup Modal - Complete implementation

    • Search by phone, member ID, or name
    • Display recent members with tier badges
    • Member card with points and tier information
    • Birthday detection and display
    • One-click member attachment
  • βœ… Discount Panel Modal - Three-tab interface

    • Line Discount Tab - Item-level discounts (% or fixed)
    • Bill Discount Tab - Order-level discounts with reasons
    • Preset Discounts Tab - Pre-configured discount options
    • Real-time preview of discount impact
    • Supervisor approval workflow for high discounts (>10% line, >5% bill)
  • βœ… Coupon Panel Modal - Full coupon management

    • Coupon code entry and validation
    • Available coupons display for members
    • Applied coupons management
    • Validation rules: min purchase, member-only, tier restrictions
    • Stackability checks
    • Real-time discount calculation
  • βœ… Payment Method Selection - Professional payment gateway

    • Order summary display
    • Four payment methods: Cash, Card/EDC, e-Wallet, Split Payment
    • Beautiful gradient card interface
  • βœ… Cash Payment Flow - Complete cash handling

    • Amount due display
    • Cash received input with keyboard support
    • Quick amount buttons ($5, $10, $20, $50, $100, Exact)
    • Automatic change calculation
    • Insufficient payment detection
    • Payment recording and receipt generation
  • βœ… EDC Card Payment Flow - Card terminal simulation

    • Amount display
    • Processing states (ready, processing, approved, declined)
    • Card type and last 4 digits capture
    • Authorization code and RRN (Reference Retrieval Number)
    • Retry on failure
    • Mock API integration
  • βœ… e-Wallet Payment Flow - Digital payment support

    • Provider selection (PayPal, Apple Pay, Google Pay, Venmo)
    • QR code display (mock)
    • Payment status polling
    • Transaction ID generation
    • Success confirmation with details
    • Auto-simulation for demo purposes
  • βœ… Receipt Generation - Professional receipt display

    • Store header with address and contact
    • Transaction details (receipt no, date, terminal, cashier)
    • Member information if attached
    • Itemized product list with quantities and prices
    • Subtotal, discounts, tax, total breakdown
    • Payment method details
    • Change calculation for cash payments
    • Points earned display for members
    • Print functionality (simulated)
  • βœ… Supervisor Approval Modal - Security workflow

    • Reason display for approval request
    • 4-digit PIN entry
    • Role validation (Cashier, Supervisor, Manager)
    • Real-time PIN verification via API
    • Approval/denial feedback
    • Used for: high discounts, voids, refunds, shift variance
  • βœ… Open Daily Shift - Shift management

    • Shift information display (store, terminal, cashier, date, time)
    • Starting cash float entry
    • Optional denomination breakdown (bills and coins)
    • Auto-calculation of denominations
    • Notes field for shift opening
    • Shift ID generation
    • Session storage management
  • βœ… Close Daily Shift - Cash reconciliation

    • Shift summary with duration
    • Sales summary (total transactions, sales by payment type)
    • Cash reconciliation (starting float + cash sales = expected cash)
    • Actual cash count entry
    • Variance calculation (overage/shortage)
    • Color-coded variance display (green=match, blue=over, red=short)
    • Supervisor approval for large variance (>$10)
    • Closing notes field
    • Shift closing report generation
  • βœ… Shift Closing Report - Detailed summary

    • Complete shift details
    • Sales breakdown by payment method
    • Cash reconciliation details
    • Variance reporting
    • Print functionality
    • Historical storage in localStorage

βœ… Advanced Discount Engine

  • βœ… Priority-based calculation - Higher priority discounts applied first
  • βœ… Stackable vs Non-stackable - Rule enforcement
  • βœ… Member pricing - Automatic member price application
  • βœ… Member tier discounts - Bronze/Silver/Gold/Platinum (0-10%)
  • βœ… Birthday discounts - Automatic detection and application (20% off)
  • βœ… Automatic discounts - Applied when conditions met
  • βœ… Manual discounts - Line-level or bill-level with reason tracking
  • βœ… Coupon support - With full validation logic and stacking rules
  • βœ… Discount breakdown - Detailed calculation steps for audit
  • βœ… Max discount caps - Configurable limits per rule

βœ… API Endpoints

  • βœ… POST /api/login - User authentication
  • βœ… GET /api/products - Product listing
  • βœ… GET /api/products/search - Product search
  • βœ… GET /api/members/search - Member lookup
  • βœ… POST /api/supervisor/validate - PIN validation
  • βœ… POST /api/payment/edc - Mock card payment processing
  • βœ… POST /api/payment/ewallet - QR code generation and webhook
  • βœ… POST /api/transactions - Save completed transactions
  • βœ… GET /api/discounts - Get active discount rules

βœ… Business Logic Modules

  • βœ… DiscountEngine (~660 lines) - Advanced discount calculation engine
  • βœ… CartManager - Complete cart state management with recalculation
  • βœ… ModalSystem - Reusable modal framework for all UI dialogs
  • βœ… ShiftManagement (~630 lines) - Open/close shift with cash reconciliation
  • βœ… TransactionManagement (~850 lines) - Void, return/refund, transaction history
  • βœ… ReportsSystem (~540 lines) - X-Report and Z-Report generation
  • βœ… Coupon validation with all business rules
  • βœ… Member savings calculation
  • βœ… Tax calculation (10% default)
  • βœ… Real-time cart recalculation on every change
  • βœ… Payment recording and transaction completion
  • βœ… Receipt generation with proper formatting
  • βœ… Transaction storage and retrieval from localStorage
  • βœ… Supervisor approval workflow integration

Features Implemented βœ…

βœ… Core POS Module: 100% COMPLETE!

All originally specified POS features have been implemented including:

  • βœ… Transaction void with supervisor approval
  • βœ… Return/refund processing with reason tracking
  • βœ… Transaction history viewer with filters
  • βœ… X-Report (current shift summary)
  • βœ… Z-Report (end of day with shift close)

βœ… SCO Module: 100% COMPLETE!

All self-checkout features have been fully implemented:

  • βœ… Customer self-service interface with barcode scanning
  • βœ… Manual barcode entry and quick scan demo buttons
  • βœ… Member card integration (scan card or manual lookup)
  • βœ… Automatic member pricing and tier discounts
  • βœ… Real-time cart management with add/remove items
  • βœ… Coupon entry and validation system
  • βœ… Digital payment integration screens:
    • Card Payment (tap/insert simulation)
    • Digital Wallet (Apple Pay, Google Pay, etc.)
    • QR Payment (scan to pay)
    • Cash Payment (call attendant)
  • βœ… Help/Attendant request system
  • βœ… Bagging area reminders
  • βœ… Complete payment flow with receipt
  • βœ… Transaction completion and storage

🚧 Store Manager Dashboard (Future Enhancement)

  • Discount rule management (CRUD operations)
  • Discount analytics and reporting
  • Threshold configuration UI
  • Usage audit logs viewer
  • Sales analytics dashboard

🚧 Optional Enhancements (Beyond Original Spec)

  • Delivery Later order management
  • Multi-language support
  • Offline mode with sync
  • Advanced inventory management

🎯 Key Achievements

Advanced Discount System ⭐

The implemented discount engine is production-ready with:

  • Multi-level application: Member pricing β†’ Automatic discounts β†’ Manual discounts β†’ Coupons
  • Smart stacking: Prevents non-stackable conflicts
  • Priority ordering: Higher priority rules evaluated first
  • Cap enforcement: Respects maximum discount limits
  • Calculation transparency: Full audit trail of applied discounts
  • Real-time updates: Instant recalculation on cart changes

Complete Transaction Workflow ⭐

End-to-end transaction processing:

  • Cart Management: Add/remove/update items with real-time calculations
  • Member Integration: Attach members for automatic pricing and tier discounts
  • Discount Application: Manual, automatic, and coupon-based discounts
  • Payment Processing: Cash, Card/EDC, e-Wallet with proper recording
  • Receipt Generation: Professional receipt with all transaction details
  • Shift Management: Open/close with cash reconciliation and variance detection

Modal System Architecture ⭐

Reusable modal framework with:

  • Member Lookup: Search and attach members with tier info
  • Discount Panel: Three-tab interface for all discount types
  • Coupon Panel: Validation and application with real-time feedback
  • Payment Methods: Professional payment gateway selection
  • Supervisor Approval: PIN-based approval workflow
  • Shift Management: Open/close with denomination breakdown

Business Logic Separation ⭐

Clean architecture with:

  • Frontend: Pure presentation in HTML/JS
  • Backend: Hono API routes
  • Business Logic: Standalone modules (DiscountEngine, CartManager, ModalSystem, ShiftManagement)
  • Data Layer: Ready for D1 database integration

Mock Data Quality ⭐

Realistic test data including:

  • 50+ products across 10 categories
  • 8 members with different tiers
  • 14 discount rules covering all types
  • Complete sample transaction history
  • Role-based user accounts

πŸ“Š Project Statistics

Code Metrics

  • Total Lines of Code: ~7,400+ lines (production code)
  • Frontend JavaScript: ~5,220+ lines
    • cart-engine.js: ~642 lines (discount engine + cart manager)
    • modals.js: ~1,766 lines (payment flows, coupons, discounts, receipts)
    • shift-management.js: ~628 lines (open/close shift)
    • transaction-management.js: ~845 lines (void, return/refund, history)
    • reports.js: ~547 lines (X-Report, Z-Report)
    • sco-modals.js: ~339 lines (SCO modals and interactions)
    • pos-home.html: ~544 lines (main POS interface)
    • sco-home.html: ~447 lines (SCO shopping interface)
    • sco-payment.html: ~458 lines (SCO payment screens)
  • Backend TypeScript: ~530 lines (Hono API routes)
  • Database Schema: ~457 lines SQL (15 tables)
  • Mock Data: ~212 lines SQL (seed data)

Feature Coverage

  • Implemented Screens: 25+ complete UIs

    • Home page (POS/SCO selection)
    • POS Login screen
    • POS Home/Sales screen with navigation menu
    • POS Member Lookup modal
    • POS Discount Panel modal (3 tabs)
    • POS Coupon Panel modal
    • POS Payment Method Selection
    • POS Cash Payment flow
    • POS EDC Card Payment flow
    • POS e-Wallet Payment flow
    • POS Receipt display
    • POS Open Daily Shift
    • POS Close Daily Shift with report
    • POS Supervisor Approval modal
    • POS Transaction Void
    • POS Return/Refund Processing
    • POS Transaction History Viewer
    • POS X-Report (Current Shift)
    • POS Z-Report (End of Day)
    • SCO Shopping/Scanning screen
    • SCO Member Card Scan modal
    • SCO Coupon Entry modal
    • SCO Help/Attendant Request modal
    • SCO Payment Selection screen
    • SCO Payment Processing screens (Card, Wallet, QR, Cash)
    • SCO Receipt and Success screen
  • API Endpoints: 10+ RESTful endpoints

  • Business Rules: 150+ validation and calculation rules

  • Database Tables: 15 normalized tables

  • Mock Products: 50+ items

  • Discount Rules: 14 pre-configured rules

  • User Roles: 5 distinct roles with permissions

  • Member Tiers: 4 tiers (Bronze, Silver, Gold, Platinum)

Testing & Demo Data

  • Test Users: 5 user accounts (Manager, Supervisor, 2 Cashiers, SCO Attendant)
  • Test Members: 8 members across all tiers
  • Test Coupons: 3 coupon codes (SAVE5, WELCOME10, GOLD20)
  • Test Products: 50+ products with barcodes and pricing
  • Sample Transactions: Complete transaction workflow testable

πŸ—„οΈ Database Schema

Tables Implemented

  1. users - User authentication and roles
  2. stores - Store information
  3. terminals - POS/SCO terminal management
  4. product_categories - Product categorization
  5. products - Product catalog (50+ sample products)
  6. member_tiers - Loyalty tier configuration
  7. members - Customer loyalty program
  8. discount_rules - Advanced discount system
  9. daily_sessions - Shift management
  10. transactions - Sales transactions
  11. transaction_lines - Line items
  12. transaction_discounts - Applied discounts
  13. payments - Payment records
  14. coupon_usage - Coupon tracking
  15. activity_logs - Audit trail

πŸš€ Getting Started

Prerequisites

  • Node.js 18+ (installed)
  • npm (installed)

Installation

# Clone and navigate
cd /home/user/webapp

# Install dependencies
npm install

# Build project
npm run build

Development

# Start development server
npm run dev:sandbox

# Or use PM2 (recommended for sandbox)
fuser -k 3000/tcp || true
pm2 start ecosystem.config.cjs

Demo Credentials

For POS Module

  • Store Manager: somchai / manager123 (Thai name: Somchai Promchan, PIN: 1234)
  • Supervisor: apinya / super123 (Thai name: Apinya Srisawat, PIN: 2345)
  • Cashier 1: nattapong / cash123 (Thai name: Nattapong Wongsakul)
  • Cashier 2: siriwan / cash123 (Thai name: Siriwan Chaiyakul)
  • SCO Attendant: thana / sco123 (Thai name: Thana Bunyarit, PIN: 3456)

Test Members

  • Gold Member: Pannee Rattanakorn - Phone: 555-1001 - Points: 1,250
  • Platinum Member: Chanya Thammasat - Phone: 555-1003 - Points: 5,800
  • Silver Member: Wichit Sukhsamran - Phone: 555-1002 - Points: 450

Test Coupons

  • SAVE5: $5 off on orders $25+
  • WELCOME10: 10% off for new members
  • GOLD20: 20% off for Gold members on $50+

How to Test

Testing POS Module

  1. Login: Go to /pos/login and login as cashier1 / cash123
  2. Open Shift: Enter starting float (e.g., $200) and confirm
  3. Add Products: Use search bar or click quick products (Coca-Cola, Pepsi, Milk, Chips)
  4. Attach Member: Click "Member Lookup", search by phone 555-1001 (Alice - Gold)
  5. Apply Discount: Click "Discounts", select "Line Discount" or "Bill Discount"
    • For discounts >10%, will require supervisor PIN: 2345
  6. Apply Coupon: Click "Coupon", enter code SAVE5 or WELCOME10
  7. Checkout: Click "Checkout", select payment method:
    • Cash: Enter amount tendered, calculate change
    • Card: Simulate card terminal processing
    • e-Wallet: Generate QR code or select wallet type
  8. Receipt: View and print receipt
  9. Void Transaction: Use navigation menu β†’ "Void Transaction"
  10. View History: Navigation menu β†’ "Transaction History"
  11. Reports: Generate X-Report (current shift) or Z-Report (end of day)
  12. Close Shift: Navigation menu β†’ "Close Daily Shift", review totals

Testing SCO Module

  1. Start Shopping: Go to /sco (no login required)
  2. Scan Items:
    • Enter barcode manually (e.g., 7890001 for Coca-Cola)
    • Or click quick scan buttons for demo products
  3. Member Card: Click "Scan Card" button
    • Quick demo: Click Gold Member (555-1001) to apply member pricing
    • Or enter phone/member number manually
  4. Apply Coupon: Click "Enter Coupon Code"
    • Enter SAVE5 or WELCOME10
    • Or click quick coupon buttons
  5. Request Help: Click "Need Help?" to simulate attendant request
  6. Checkout: Click "Pay Now" when ready
  7. Select Payment: Choose payment method:
    • Card Payment: Simulate tap/insert card
    • Digital Wallet: Apple Pay, Google Pay simulation
    • QR Payment: Scan QR code simulation (2-minute timer)
    • Cash Payment: Requests attendant assistance
  8. Complete: Process payment and view success screen with receipt
  9. Receipt Options: Print receipt or email receipt
  10. Start New Shopping: Click to begin new transaction or exit

πŸ“‚ Project Structure

webapp/
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ index.tsx              # Main Hono application entry
β”‚   └── renderer.tsx           # HTML renderer helper
β”œβ”€β”€ public/
β”‚   β”œβ”€β”€ pos-home.html          # POS Sales screen (600+ lines)
β”‚   └── static/
β”‚       β”œβ”€β”€ cart-engine.js     # Discount engine + Cart manager (660+ lines)
β”‚       β”œβ”€β”€ modals.js          # All modals and workflows (2,200+ lines)
β”‚       β”œβ”€β”€ shift-management.js # Open/Close shift (600+ lines)
β”‚       └── style.css          # Custom styles
β”œβ”€β”€ migrations/
β”‚   └── 0001_initial_schema.sql # Database schema (15 tables, 500+ lines)
β”œβ”€β”€ seed.sql                   # Mock data (700+ lines)
β”œβ”€β”€ dist/                      # Built files (generated by Vite)
β”‚   β”œβ”€β”€ _worker.js             # Compiled Hono worker
β”‚   └── _routes.json           # Cloudflare routing config
β”œβ”€β”€ ecosystem.config.cjs       # PM2 configuration
β”œβ”€β”€ package.json               # Dependencies and scripts
β”œβ”€β”€ wrangler.jsonc             # Cloudflare configuration
β”œβ”€β”€ tsconfig.json              # TypeScript configuration
β”œβ”€β”€ vite.config.ts             # Vite build configuration
└── README.md                  # This file

β”œβ”€β”€ ecosystem.config.cjs # PM2 configuration β”œβ”€β”€ package.json # Dependencies & scripts β”œβ”€β”€ wrangler.jsonc # Cloudflare configuration └── README.md # This file


## 🎯 Tech Stack

### Backend
- **Hono** - Lightweight web framework
- **Cloudflare Workers** - Edge runtime
- **Cloudflare D1** - SQLite database
- **TypeScript** - Type safety

### Frontend
- **TailwindCSS** - Utility-first CSS
- **Font Awesome** - Icons
- **Axios** - HTTP client
- **Vanilla JavaScript** - No framework overhead

### Development
- **Vite** - Build tool
- **Wrangler** - Cloudflare CLI
- **PM2** - Process manager
- **Git** - Version control

## πŸ“Š Data Models

### Products (Tech Products)
- **Electronics** - Cameras, Headsets, Keyboards, Mice
  - Logitech Webcam C920 - $79.99 (Barcode: 7890001)
  - Sony WH-1000XM4 Headset - $299.99 (Barcode: 7890002)
  - Keychron K2 Mechanical Keyboard - $89.99 (Barcode: 7890003)
  - Logitech MX Master 3 Mouse - $99.99 (Barcode: 7890004)

### Discount Rules
- **Automatic discounts** - Applied when conditions met
- **Member tier discounts** - 3-10% based on tier
- **Birthday specials** - 20% off on birthday
- **Coupons** - Code-based discounts
- **Manual discounts** - Staff-applied with approval
- **Promotional discounts** - Time-limited offers

### Payment Methods
- Cash (with change calculation)
- Card/EDC (with mock terminal simulation)
- **PromptPay QR** (Thailand's instant payment system)
- Split Payment (multiple methods)

## πŸ” Security Features

- Role-based access control (RBAC)
- PIN-based supervisor approval
- Session management
- Audit logging
- Approval workflows for high-value transactions

## πŸ“ˆ Recommended Next Steps

### Already Completed βœ…
1. βœ… **POS Home Screen** - Fully functional with cart management
2. βœ… **Discount Engine** - Complete with priority-based stacking
3. βœ… **Member Features** - Backend logic ready, needs UI modal
4. βœ… **API Endpoints** - All core endpoints implemented

### Still To-Do 🚧
1. **Payment Flow Screens**
   - Cash payment UI with change calculator
   - EDC payment UI with status display
   - e-Wallet payment UI with QR display
   - Split payment UI

2. **Member Lookup Modal**
   - Search interface
   - Member details display
   - Attach/detach actions

3. **Discount Panel UI**
   - Line discount form
   - Bill discount form
   - Preset discount selector

4. **Coupon Panel UI**
   - Coupon code input
   - Applied coupons list
   - Validation messages

5. **Open/Close Daily Shift**
   - Cash float entry
   - Denomination breakdown
   - Closing reconciliation

6. **Receipt Generation**
   - Receipt template
   - Print preview
   - Transaction details

7. **SCO Module**
   - Customer-facing interface
   - Self-scanning flow
   - Attendant override

8. **Supervisor Approval Modal**
   - PIN entry form
   - Approval reason display
   - Success/error handling
   - Analytics charts
   - Usage reports

## πŸ§ͺ Testing

```bash
# Test server is running
curl http://localhost:3000

# Check PM2 status
pm2 status

# View logs
pm2 logs pos-webapp --nostream

# Restart service
fuser -k 3000/tcp && pm2 restart pos-webapp

🌍 Deployment Status

πŸ“ Git Repository

# Current status
git status

# View commit history
git log --oneline

# Create new commit
git add .
git commit -m "Your message"

🀝 Contributing

This is a POC/demo project. The application demonstrates:

  • Modern POS architecture
  • Role-based workflows
  • Advanced discount logic
  • Multi-module design
  • Cloudflare edge deployment

πŸ“„ License

Demo/POC project for evaluation purposes.

πŸ”— Important Links


Last Updated: 2026-02-24 Status: βœ… Production Deployed Version: 1.0.0 (Production) Project: TMG POS System

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors