project initialization

docs/user-guides/modules/retail.md

@@ -0,0 +1,769 @@
+# Retail Module User Guide
+
+## Overview
+
+The Retail Module provides comprehensive solutions for Malaysian retail businesses, including inventory management, sales processing, customer relationship management, and Malaysian market-specific features like SST compliance and local payment methods.
+
+### Key Features
+
+- **Inventory Management**: Track stock levels, manage suppliers, automate reordering
+- **Sales Processing**: Complete POS functionality with Malaysian payment methods
+- **Customer Management**: Loyalty programs, customer insights, personalized marketing
+- **SST Compliance**: Automated SST calculation and reporting
+- **Multi-location**: Support for multiple store locations
+- **Reporting**: Comprehensive sales and inventory reports
+- **Mobile Access**: Full functionality on mobile devices
+
+## Getting Started
+
+### 1. Module Setup
+
+#### Initial Configuration
+
+1. Navigate to **Retail → Settings → General**
+2. Configure basic settings:
+   ```markdown
+   Required Settings:
+   - Store Name: Your business name
+   - Store Address: Malaysian address format
+   - Contact Information: Phone and email
+   - Business Hours: Operating hours
+   - Currency: Malaysian Ringgit (MYR)
+   - Timezone: Asia/Kuala Lumpur (UTC+8)
+   ```
+
+#### SST Configuration
+
+1. Navigate to **Retail → Settings → Tax**
+2. Configure SST settings:
+   ```markdown
+   SST Configuration:
+   - SST Registration Number: Your SST registration number
+   - Standard Rate: 6% (default)
+   - Exempt Categories: Configure tax-exempt products
+   - SST-Registered: Enable if you are SST-registered
+   - Include SST in Prices: Choose pricing strategy
+   ```
+
+#### Payment Methods
+
+1. Navigate to **Retail → Settings → Payment Methods**
+2. Enable Malaysian payment options:
+   ```markdown
+   Available Payment Methods:
+   - Cash: Cash payments
+   - Touch 'n Go: e-wallet payments
+   - GrabPay: e-wallet payments
+   - Credit Cards: Visa, Mastercard, Amex
+   - Debit Cards: Bank debit cards
+   - Online Banking: Maybank2U, CIMB Clicks, etc.
+   - E-wallets: Boost, ShopeePay, etc.
+   ```
+
+### 2. Product Setup
+
+#### Creating Product Categories
+
+1. Navigate to **Retail → Products → Categories**
+2. Create categories for your products:
+   ```markdown
+   Example Categories:
+   - Electronics
+   - Clothing & Apparel
+   - Food & Beverages
+   - Health & Beauty
+   - Home & Living
+   - Sports & Outdoors
+   ```
+
+#### Adding Products
+
+1. Navigate to **Retail → Products → Add Product**
+2. Enter product details:
+   ```markdown
+   Product Information:
+   - SKU: Unique stock keeping unit
+   - Product Name: Descriptive product name
+   - Category: Select appropriate category
+   - Description: Detailed product description
+   - Brand: Product brand
+   - Barcode: Product barcode (optional)
+   ```
+
+3. Configure pricing:
+   ```markdown
+   Pricing Information:
+   - Cost Price: Your cost price
+   - Selling Price: Retail price
+   - SST Rate: 6% or exempt
+   - Discount: Default discount percentage
+   - Promotion: Special pricing if applicable
+   ```
+
+4. Set inventory details:
+   ```markdown
+   Inventory Details:
+   - Current Stock: Current stock quantity
+   - Reorder Point: When to reorder
+   - Maximum Stock: Maximum stock level
+   - Location: Store location
+   - Supplier: Default supplier
+   ```
+
+## Inventory Management
+
+### 1. Stock Management
+
+#### Receiving Stock
+
+1. Navigate to **Retail → Inventory → Receive Stock**
+2. Select supplier and purchase order
+3. Enter received quantities:
+   ```markdown
+   Receiving Process:
+   - Select Supplier: Choose from supplier list
+   - PO Reference: Purchase order number
+   - Receive Date: Date of receipt
+   - Products: List of products received
+   - Quantities: Actual quantities received
+   - Condition: Note any damaged items
+   ```
+
+#### Stock Transfers
+
+1. Navigate to **Retail → Inventory → Stock Transfer**
+2. Configure transfer:
+   ```markdown
+   Transfer Details:
+   - From Location: Source store/location
+   - To Location: Destination store/location
+   - Products: Items to transfer
+   - Quantities: Transfer quantities
+   - Transfer Date: Date of transfer
+   - Reason: Purpose of transfer
+   ```
+
+#### Stock Adjustments
+
+1. Navigate to **Retail → Inventory → Stock Adjustment**
+2. Make adjustments:
+   ```markdown
+   Adjustment Types:
+   - Damage: Write off damaged stock
+   - Loss: Account for lost stock
+   - Found: Add found items
+   - Count Correction: Fix counting errors
+   - Expiry: Remove expired items
+   ```
+
+### 2. Supplier Management
+
+#### Adding Suppliers
+
+1. Navigate to **Retail → Suppliers → Add Supplier**
+2. Enter supplier information:
+   ```markdown
+   Supplier Details:
+   - Company Name: Supplier business name
+   - Contact Person: Primary contact
+   - Phone: Contact phone number
+   - Email: Contact email
+   - Address: Supplier address
+   - Payment Terms: Payment conditions
+   - Products: Products supplied
+   - Lead Time: Delivery time
+   ```
+
+#### Purchase Orders
+
+1. Navigate to **Retail → Purchasing → Create PO**
+2. Create purchase order:
+   ```markdown
+   PO Creation:
+   - Supplier: Select supplier
+   - Order Date: Order placement date
+   - Expected Delivery: Delivery date
+   - Products: Required items and quantities
+   - Prices: Agreed prices
+   - Terms: Payment and delivery terms
+   ```
+
+### 3. Inventory Reports
+
+#### Stock Status Report
+
+1. Navigate to **Retail → Reports → Inventory → Stock Status**
+2. Generate report with filters:
+   ```markdown
+   Available Filters:
+   - Product Category: Filter by category
+   - Stock Level: Low stock, normal, high stock
+   - Location: Specific store locations
+   - Supplier: Filter by supplier
+   - Date Range: Specific time period
+   ```
+
+#### Inventory Valuation
+
+1. Navigate to **Retail → Reports → Inventory → Valuation**
+2. View inventory value:
+   ```markdown
+   Valuation Methods:
+   - FIFO: First In, First Out
+   - LIFO: Last In, First Out
+   - Weighted Average: Average cost method
+   - Specific Cost: Track specific costs
+   ```
+
+## Sales Processing
+
+### 1. Point of Sale (POS)
+
+#### Sales Transaction
+
+1. Navigate to **Retail → POS → New Sale**
+2. Process sale:
+   ```markdown
+   Sales Process:
+   1. Add Products: Scan or select products
+   2. Enter Quantities: Specify quantities
+   3. Apply Discounts: Add customer discounts
+   4. Calculate Total: System calculates total with SST
+   5. Select Payment: Choose payment method
+   6. Process Payment: Complete payment
+   7. Generate Receipt: Print or email receipt
+   ```
+
+#### Payment Processing
+
+**Cash Payments**
+- Enter amount received
+- Calculate change
+- Complete transaction
+
+**E-wallet Payments**
+- Select e-wallet type (Touch 'n Go, GrabPay)
+- Generate QR code
+- Wait for customer payment
+- Confirm payment
+
+**Card Payments**
+- Insert/swipe card
+- Enter PIN if required
+- Process transaction
+- Get authorization
+
+**Online Banking**
+- Select bank
+- Generate payment reference
+- Customer completes online payment
+- Confirm payment received
+
+### 2. Sales Management
+
+#### Sales Orders
+
+1. Navigate to **Retail → Sales → Sales Orders**
+2. Create sales order:
+   ```markdown
+   Sales Order Details:
+   - Customer: Select customer
+   - Order Date: Order placement date
+   - Products: Items and quantities
+   - Prices: Agreed prices
+   - Discounts: Any applicable discounts
+   - Delivery: Delivery instructions
+   - Payment Terms: Payment conditions
+   ```
+
+#### Invoices
+
+1. Navigate to **Retail → Sales → Invoices**
+2. Generate SST-compliant invoice:
+   ```markdown
+   Invoice Requirements:
+   - Business Details: Your business information
+   - SST Registration: Your SST number
+   - Customer Details: Customer information
+   - Invoice Number: Unique invoice number
+   - Date: Invoice date
+   - Items: Products/services provided
+   - SST Amount: SST calculation
+   - Total Amount: Total including SST
+   - Payment Terms: Payment conditions
+   ```
+
+#### Returns and Refunds
+
+1. Navigate to **Retail → Sales → Returns**
+2. Process return:
+   ```markdown
+   Return Process:
+   - Original Invoice: Reference original sale
+   - Return Date: Date of return
+   - Products: Items being returned
+   - Reason: Return reason
+   - Condition: Item condition
+   - Refund Method: How to process refund
+   - Restock: Whether to restock item
+   ```
+
+### 3. Sales Reports
+
+#### Sales Summary
+
+1. Navigate to **Retail → Reports → Sales → Summary**
+2. View sales performance:
+   ```markdown
+   Sales Metrics:
+   - Total Sales: Gross sales amount
+   - Net Sales: Sales after returns
+   - SST Collected: Total SST amount
+   - Average Transaction: Average sale value
+   - Items Sold: Total units sold
+   - Top Products: Best-selling items
+   ```
+
+#### Sales by Category
+
+1. Navigate to **Retail → Reports → Sales → By Category**
+2. Analyze category performance:
+   ```markdown
+   Category Analysis:
+   - Category Sales: Sales by product category
+   - Category Profit: Profit by category
+   - Category Margin: Profit margin by category
+   - Category Growth: Growth trends by category
+   ```
+
+## Customer Management
+
+### 1. Customer Registration
+
+#### Adding Customers
+
+1. Navigate to **Retail → Customers → Add Customer**
+2. Enter customer information:
+   ```markdown
+   Customer Information:
+   - Personal Details:
+     • Full Name: Customer's full name
+     • IC Number: Malaysian IC (optional)
+     • Phone: Contact phone number
+     • Email: Email address
+     • Date of Birth: For age verification
+
+   - Address:
+     • Street Address: Complete address
+     • City: City or town
+     • State: Malaysian state
+     • Postal Code: Postcode
+     • Country: Malaysia (default)
+
+   - Preferences:
+     • Communication: Preferred contact method
+     • Language: Preferred language
+     • Interests: Product interests
+   ```
+
+#### Customer Groups
+
+1. Navigate to **Retail → Customers → Groups**
+2. Create customer segments:
+   ```markdown
+   Customer Groups:
+   - VIP Customers: High-value customers
+   - Regular Customers: Frequent shoppers
+   - New Customers: Recently acquired
+   - Wholesale: Business customers
+   - Senior Citizens: Age 60+ customers
+   - Students: Student customers
+   ```
+
+### 2. Loyalty Program
+
+#### Setting Up Loyalty Program
+
+1. Navigate to **Retail → Settings → Loyalty Program**
+2. Configure loyalty program:
+   ```markdown
+   Loyalty Configuration:
+   - Program Name: Name of your loyalty program
+   - Points per RM: Points earned per ringgit spent
+   - Redemption Rate: Points needed for rewards
+   - Tiers: Customer benefit tiers
+   - Expiry: Points expiration policy
+   - Benefits: Tier-specific benefits
+   ```
+
+#### Customer Tiers
+
+1. Navigate to **Retail → Settings → Loyalty Tiers**
+2. Define customer tiers:
+   ```markdown
+   Tier Structure:
+   - Bronze Tier: Entry level (0-500 points)
+     • 1 point per RM spent
+     • Birthday discount: 5%
+
+   - Silver Tier: Mid level (501-2000 points)
+     • 1.2 points per RM spent
+     • Birthday discount: 10%
+     • Early access to sales
+
+   - Gold Tier: High level (2001+ points)
+     • 1.5 points per RM spent
+     • Birthday discount: 15%
+     • Early access to sales
+     • Exclusive events
+   ```
+
+### 3. Customer Communication
+
+#### Email Marketing
+
+1. Navigate to **Retail → Marketing → Email Campaigns**
+2. Create email campaign:
+   ```markdown
+   Campaign Setup:
+   - Campaign Name: Descriptive campaign name
+   - Target Audience: Customer segments
+   - Email Template: Choose or create template
+   - Content: Campaign content
+   - Schedule: Send date and time
+   - Personalization: Dynamic content fields
+   ```
+
+#### SMS Marketing
+
+1. Navigate to **Retail → Marketing → SMS Campaigns**
+2. Create SMS campaign:
+   ```markdown
+   SMS Campaign:
+   - Message Content: SMS text (160 characters)
+   - Recipients: Target customer list
+   - Send Time: Scheduled send time
+   - Personalization: Customer name insertions
+   - Opt-out: Include opt-out instructions
+   ```
+
+## Malaysian Market Features
+
+### 1. SST Compliance
+
+#### SST Configuration
+
+1. Navigate to **Retail → Settings → SST**
+2. Configure SST settings:
+   ```markdown
+   SST Settings:
+   - SST Registration: Your SST registration number
+   - Tax Rates: Standard rate (6%) and exempt categories
+   - Tax-Inclusive Pricing: Whether prices include SST
+   - Invoice Requirements: SST-compliant invoicing
+   - Reporting: SST reporting and filing
+   - Audit Trail: Transaction history for audits
+   ```
+
+#### SST Reporting
+
+1. Navigate to **Retail → Reports → SST**
+2. Generate SST reports:
+   ```markdown
+   SST Reports:
+   - SST Summary: Total SST collected
+   - SST by Category: SST by product category
+   - SST Transactions: Detailed SST transactions
+   - SST Filing: Ready-to-file SST reports
+   - Exempt Sales: Sales exempt from SST
+   ```
+
+### 2. Malaysian Payment Methods
+
+#### E-wallet Integration
+
+1. Navigate to **Retail → Settings → Payment Methods**
+2. Configure e-wallets:
+   ```markdown
+   E-wallet Setup:
+   - Touch 'n Go: Business account setup
+   - GrabPay: Merchant configuration
+   - Boost: Merchant setup
+   - ShopeePay: Business account setup
+   - Transaction Fees: Configure fee structure
+   - Settlement: Bank settlement details
+   ```
+
+#### Online Banking
+
+1. Navigate to **Retail → Settings → Online Banking**
+2. Configure bank integrations:
+   ```markdown
+   Bank Integration:
+   - Maybank2U: Business banking setup
+   - CIMB Clicks: Merchant services
+   - RHB Now: Banking integration
+   - Hong Leong Connect: Payment processing
+   - Payment Gateway: Gateway configuration
+   ```
+
+### 3. Local Business Features
+
+#### Malaysian Address Format
+
+1. Navigate to **Retail → Settings → Address Format**
+2. Configure address format:
+   ```markdown
+   Malaysian Address Format:
+   - Street Address: Street number and name
+   - Taman/Area: Residential or commercial area
+   - Postcode: Malaysian postcode
+   - City: City or town
+   - State: Malaysian state
+   - Country: Malaysia (default)
+   ```
+
+#### Public Holidays
+
+1. Navigate to **Retail → Settings → Holidays**
+2. Configure holidays:
+   ```markdown
+   Malaysian Holidays:
+   - Federal Holidays: National holidays
+   - State Holidays: State-specific holidays
+   - Religious Holidays: Religious observances
+   - Special Events: Special business events
+   - Operating Hours: Holiday operating hours
+   ```
+
+## Reporting and Analytics
+
+### 1. Sales Analytics
+
+#### Sales Performance
+
+1. Navigate to **Retail → Analytics → Sales Performance**
+2. View sales metrics:
+   ```markdown
+   Sales Metrics:
+   - Revenue Trends: Sales over time
+   - Product Performance: Best-selling products
+   - Category Performance: Sales by category
+   - Time Analysis: Sales by time/day
+   - Staff Performance: Sales by staff member
+   - Location Performance: Sales by store location
+   ```
+
+#### Customer Analytics
+
+1. Navigate to **Retail → Analytics → Customer Insights**
+2. Analyze customer data:
+   ```markdown
+   Customer Metrics:
+   - Customer Acquisition: New customers over time
+   - Customer Retention: Repeat customer rate
+   - Customer Lifetime Value: CLV calculations
+   - Purchase Patterns: Buying behavior analysis
+   - Demographics: Customer demographic data
+   - Loyalty Program: Loyalty participation rates
+   ```
+
+### 2. Inventory Analytics
+
+#### Stock Analysis
+
+1. Navigate to **Retail → Analytics → Inventory**
+2. Analyze inventory:
+   ```markdown
+   Inventory Metrics:
+   - Stock Turnover: How quickly inventory sells
+   - Stock Levels: Current inventory status
+   - Aging Inventory: Old stock analysis
+   - Reorder Points: Optimal reorder quantities
+   - Supplier Performance: Supplier delivery times
+   - Lost Sales: Out-of-stock impact
+   ```
+
+#### Demand Forecasting
+
+1. Navigate to **Retail → Analytics → Forecasting**
+2. View forecasts:
+   ```markdown
+   Forecasting Features:
+   - Sales Forecasting: Predict future sales
+   - Demand Planning: Plan inventory needs
+   - Seasonal Trends: Seasonal demand patterns
+   - Trend Analysis: Market trend identification
+   - Alerts: Low stock and overstock alerts
+   ```
+
+## Mobile Features
+
+### 1. Mobile POS
+
+#### Mobile Sales Processing
+
+1. Open mobile app
+2. Navigate to **Retail → POS**
+3. Process sales on mobile:
+   ```markdown
+   Mobile POS Features:
+   - Product Search: Quick product lookup
+   - Barcode Scanning: Camera-based scanning
+   - Mobile Payments: Process payments on device
+   - Receipt Printing: Bluetooth printer support
+   - Offline Mode: Process sales without internet
+   - Sync: Automatic data synchronization
+   ```
+
+#### Inventory Management
+
+1. Navigate to **Retail → Inventory** on mobile
+2. Manage inventory:
+   ```markdown
+   Mobile Inventory Features:
+   - Stock Count: Mobile stock counting
+   - Receiving: Receive shipments on mobile
+   - Transfers: Transfer stock between locations
+   - Adjustments: Make stock adjustments
+   - Barcode Scanning: Scan barcodes with camera
+   - Photos: Add product photos
+   ```
+
+### 2. Customer Management
+
+#### Mobile Customer Lookup
+
+1. Navigate to **Retail → Customers** on mobile
+2. Access customer information:
+   ```markdown
+   Mobile Customer Features:
+   - Customer Search: Find customers quickly
+   - Purchase History: View customer purchases
+   - Loyalty Points: Check point balance
+   - Contact Info: Access contact details
+   - Notes: Add customer notes
+   - Communication: Call or email customers
+   ```
+
+## Troubleshooting
+
+### 1. Common Issues
+
+#### POS Issues
+
+**Transaction Failures**
+- Check internet connection
+- Verify payment gateway status
+- Confirm customer payment method
+- Restart POS application
+- Contact technical support if needed
+
+**Barcode Scanning Issues**
+- Clean camera lens
+- Ensure good lighting
+- Check barcode condition
+- Update mobile app
+- Try manual entry
+
+#### Inventory Issues
+
+**Stock Discrepancies**
+- Perform stock count
+- Check recent transactions
+- Review transfer records
+- Examine return processing
+- Investigate potential theft
+
+**Sync Issues**
+- Check internet connection
+- Verify cloud sync settings
+- Restart mobile application
+- Update application
+- Contact technical support
+
+### 2. Performance Issues
+
+**Slow System Response**
+- Check internet speed
+- Close unused applications
+- Clear browser cache
+- Update mobile app
+- Check system status page
+
+**Mobile App Issues**
+- Ensure latest version
+- Check device compatibility
+- Restart mobile device
+- Clear app data
+- Reinstall if needed
+
+## Best Practices
+
+### 1. Inventory Management
+
+**Stock Control**
+- Perform regular stock counts
+- Set appropriate reorder points
+- Monitor slow-moving items
+- Track expiration dates
+- Implement FIFO rotation
+
+**Supplier Management**
+- Maintain good supplier relationships
+- Negotiate better pricing
+- Monitor supplier performance
+- Diversify supplier base
+- Maintain accurate records
+
+### 2. Sales Processing
+
+**Customer Service**
+- Train staff on product knowledge
+- Implement upselling techniques
+- Handle returns professionally
+- Maintain customer records
+- Personalize customer experience
+
+**Payment Processing**
+- Offer multiple payment options
+- Ensure secure payment processing
+- Reconcile payments daily
+- Handle payment issues promptly
+- Maintain transaction records
+
+### 3. Malaysian Business Practices
+
+**SST Compliance**
+- Keep accurate SST records
+- Issue proper invoices
+- File SST returns on time
+- Stay updated on SST changes
+- Maintain proper documentation
+
+**Cultural Considerations**
+- Respect Malaysian business hours
+- Consider religious holidays
+- Use appropriate language
+- Maintain professional relationships
+- Understand local customs
+
+## Conclusion
+
+The Retail Module provides comprehensive solutions for Malaysian retail businesses. By following this guide, you can effectively manage your retail operations, maintain compliance with Malaysian regulations, and provide excellent customer service.
+
+Remember to:
+1. **Stay Compliant**: Keep up with SST and other regulations
+2. **Use Mobile Features**: Take advantage of mobile capabilities
+3. **Monitor Performance**: Regularly review sales and inventory metrics
+4. **Train Staff**: Ensure staff are properly trained
+5. **Provide Good Service**: Focus on customer satisfaction
+
+For additional support:
+- **Help Center**: Comprehensive knowledge base
+- **Video Tutorials**: Step-by-step video guides
+- **Community Forum**: Connect with other users
+- **Technical Support**: support@yourplatform.com
+- **Training Resources**: training@yourplatform.com
+
+Success with the Retail Module comes from understanding your customers, managing your inventory efficiently, and staying compliant with Malaysian business regulations. Use this guide as your reference for maximizing the value of your retail operations.