================================================================================
                          FON2FIX POS SYSTEM SITEMAP (v8.0)
================================================================================

[DOMAIN] STAFF SYSTEM (system.fon2fix.com.my / localhost)
Access: Staff Login Required (RBAC - Role-Based Access Control)
Base Path: /my_pos/

================================================================================
1. CORE FILES & ARCHITECTURE
================================================================================

A. ENTRY POINTS & AUTHENTICATION
   - index.php (v8.0)
     * Login page with secure session handling
     * Session: FONFIX_SYSTEM_ID
     * Validates credentials against 'users' table
     * Redirects authenticated users to dashboard.php
     * Features: CSRF protection, secure cookie settings

   - logout.php
     * Destroys user session
     * Redirects to index.php

--------------------------------------------------------------------------------

B. MAIN APPLICATION
   - dashboard.php (v17.0)
     * Single-page application with tabbed interface
     * No-refresh architecture (AJAX-based)
     * Contains all modules: Repair Job, Retail Sale, Stock, Report, Staff
     * Features:
       - Toast notifications (success/error)
       - Real-time table updates
       - QR code scanning integration
       - PDF generation (html2pdf.js)
       - Chart.js integration for reports
       - Bulk stock import with flexible text format parsing
       - Stock merge duplicate detection
       - Uppercase conversion for stock items
       - Clickable category breakdown in reports
       - Device model searchable dropdown with add-new option

--------------------------------------------------------------------------------

C. BACKEND API
   - api.php (v16.0)
     * Central API endpoint for all operations
     * Handles: CRUD operations, permissions, activity logging
     * Actions include:
       - job_create, job_update, job_delete
       - stock_add, stock_update, stock_transfer
       - sale_create, sale_refund
       - report_get, report_export
       - staff_management
       - backup_trigger
       - insert_stock_item (with smart merge logic)
       - merge_duplicate_stocks
       - convert_stock_to_uppercase
       - fetch_device_models
       - bulk_import_stock
     * Auto-creates: expenses table, activity_logs table
     * Permission checks via checkLivePermission()
     * Activity logging via logActivity()
     * Stock merge: Case-insensitive matching (name, type, category, supplier, cost)
     * Category profit calculation with detailed breakdown

--------------------------------------------------------------------------------

D. VIEWER PAGES (Read-Only)
   - invoice.php
     * Displays/prints invoice for repair jobs
     * URL: invoice.php?id={job_id}
     * Features: Pattern lock drawing, professional layout
     * Maps database columns to display format

   - receipt.php (v14.4)
     * Displays/prints receipt for retail sales
     * URL: receipt.php?id={invoice_id|job_id}[&token={token}]
     * Features: Itemized billing, warranty info, QR code
     * Supports both job_id and invoice_id lookup
     * Token verification for secure access
     * Displays "Warranty: No Warranty" under each item when applicable

--------------------------------------------------------------------------------

E. UTILITY FILES
   - backup.php
     * Full system backup (SQL + source code)
     * Creates ZIP archive with:
       - Database dump (SQL)
       - All PHP files
       - Configuration files
     * Access: Requires authentication
     * Output: FONFIX_FULL_BACKUP_{timestamp}.zip

   - export_data.php
     * Export data to CSV/Excel format
     * Types: jobs, sales, stock, expenses
     * Filters: Date range, branch
     * Access: Restricted by branch for non-admins

   - sync_to_backup.php
     * Automated backup synchronization
     * Can be triggered via cron job

   - uptime_monitor.php
     * System health monitoring
     * Tracks system availability

--------------------------------------------------------------------------------

F. CONFIGURATION & HELPERS
   - db.php
     * Centralized database connection (PDO)
     * Database: MySQL/MariaDB
     * Connection pooling and error handling

   - config.php
     * System configuration settings
     * Environment variables

   - helpers.php
     * Shared utility functions
     * Common helper methods for various modules

   - manifest.json
     * PWA manifest for mobile app capabilities

================================================================================
2. DASHBOARD MODULES (All within dashboard.php)
================================================================================

A. 🔧 REPAIR JOB MODULE
   1. Create Job Ticket
      - Fields: Branch, Customer (autocomplete), Phone, Device Model, IMEI
      - Fields: Device Issue, Passcode, Payment Status, Deposit, Price
      - Fields: Status (Pending/Repairing/Ready/Completed), Remarks
      - Auto-generates Job ID: JS-{branch_prefix}{number}
      - Integration: Can receive online bookings from external portal

   2. Job List & Search
      - Real-time search: Name, Phone, Job ID, IMEI
      - Filters: Branch, Status, Date Range
      - Status indicators: Unpaid/Partial/Paid
      - Payment status calculation: (price - deposit)

   3. Job Actions
      - [✏️] Edit: Update job details (permission-based)
      - [🗑️] Delete: Remove job (permission-based)
      - [📄] Invoice: Opens invoice.php?id={job_id}
      - [💬] WhatsApp: Generates message with receipt link
      - [↩️] Restore: Restore deleted jobs (permission-based)

--------------------------------------------------------------------------------

B. 🛒 RETAIL SALE MODULE (Point of Sale)
   1. POS Interface
      - QR Code Scanner: Auto-detects and adds items to cart
      - Cart Management: Add/Remove items, adjust quantities
      - Stock Integration: Auto-deducts from branch inventory
      - Payment Methods: Cash, QR, Card, Later
      - Customer Selection: Autocomplete from customers table

   2. Sales History
      - Listing: Recent sales with payment methods
      - Filters: Date range, branch, payment method
      - Invoice ID format: {branch_prefix}-{timestamp}

   3. Refund System
      - [↩️] Smart Refund Logic:
        * Creates negative entry for accounting
        * Prevents double refunds (API validation)
        * Button disabled/greyed if already refunded
        * Requires can_refund permission

--------------------------------------------------------------------------------

C. 📦 STOCK MANAGEMENT MODULE
   1. Inventory List
      - Dual-branch tracking: Stock Gombak vs Stock Sri Rampai
      - Columns: Item Name, Type, Category, Quantity, Cost, Price, Supplier, Branch
      - Real-time search and filtering (by name, supplier, category)
      - Low stock indicators
      - Grouped by Type (Part/Retail) and Category

   2. Stock Operations
      - Add Stock: New items with QR code generation
        * Repair Parts: Category-first selection, searchable device model dropdown
        * Step-by-step form: Category → Device Model → Part Name
        * Auto-generates part name from device model + part name
      - Update Stock: Edit quantities, prices, details
      - Transfer Stock: Move between branches (audit log)
      - Delete Stock: Remove items (permission-based)
      - Merge Duplicate Stock: Automatic detection and merging
        * Matches by: name, type, category, supplier, AND cost (case-insensitive)
        * Same item + same supplier + same cost = merged
        * Same item + different supplier/cost = separate entries
      - Bulk Import: Paste text list with flexible format parsing
        * Supports WhatsApp timestamp removal
        * Auto-detects categories
        * Handles various supplier formats
      - Convert to Uppercase: Batch conversion of stock text fields
        * Converts: type, model_group, device_model, part_name, supplier, category
        * Preserves data integrity, only changes case

   3. QR Code Tools
      - Generate QR codes for physical inventory
      - High-resolution printing support
      - Scanner integration in POS

   4. Stock Activity Logs
      - View all stock-related activities
      - Tracks: ADD, UPDATE, DELETE, TRANSFER operations
      - Shows user, timestamp, and action details

--------------------------------------------------------------------------------

D. 📈 REPORT & ANALYTICS MODULE
   1. Report Filters
      - Date Range: Start and end date pickers
      - Branch Selection: All branches or specific branch
      - Report Type: Sales, Expenses, Profit/Loss

   2. Visualizations
      - Doughnut Chart: Payment methods breakdown
      - Pie Chart: Branch performance comparison
      - Line Chart: Sales trends over time (daily)
      - Removed: Sales by Staff, Hourly Sales charts

   3. Data Calculations
      - Net Profit: Sales - Cost - Expenses
      - Branch-wise breakdown
      - Category Profit Breakdown (clickable for details)
        * Shows Sales, Cost, and Profit per category
        * Click category to view detailed breakdown modal
      - Improved category profit calculation:
        * Extracts item prices from repair strings when available
        * Uses cost-based proportional distribution
        * More accurate profit calculations
      - Export to CSV/PDF

   4. Top Selling Items
      - Lists top 10 items by quantity sold
      - Displays in table format

--------------------------------------------------------------------------------

E. 👥 STAFF MANAGEMENT MODULE
   (Visible to Master role or 'Endie' user only)
   1. Staff List
      - View all staff members
      - Columns: Username, Role, Branch, Permissions

   2. Staff Operations
      - Add Staff: Create new user accounts
      - Edit Staff: Update role, branch, permissions
      - Delete Staff: Remove user accounts
      - Password Reset: Change user passwords

   3. Permission System (RBAC)
      - Roles: Master, Staff
      - Permissions: 
        * can_edit, can_delete, can_transfer, can_refund, can_restore
        * can_add_cross_branch_stock
        * can_view_stock_logs
        * can_merge_stock
        * can_bulk_ops, can_bulk_print, can_bulk_import
        * can_convert_uppercase
      - Branch Restriction: restrict_branch flag
      - Master/Endie: Full access, bypass all restrictions
      - Job Editing Restrictions: Non-master users can only edit customer name and phone for retail sales

================================================================================
3. DATABASE STRUCTURE
================================================================================

A. PRIMARY TABLES
   - jobs
     * Repair job records
     * Fields: id, job_id, invoice_id, branch, owner_name, owner_phone, 
       device_name, device_issue, device_imei, passcode, price, deposit,
       status, outlet, created_at, updated_at, token

   - retail_sales
     * Point of sale transactions
     * Fields: id, invoice_id, branch, customer_name, customer_phone,
       items (JSON), total, payment_method, created_at, refunded

   - stock_list
     * Inventory items
     * Fields: id, type, model_group, device_model, part_name, category, 
       cost, selling_price, supplier, stock_gombak, stock_sr, 
       created_at, updated_at
     * Type: 'Part' or 'Retail'
     * Category: LCD, Battery, Housing, Back Glass, Camera, etc.
     * Supports case-insensitive matching for merging

   - customers
     * Customer database for autocomplete
     * Fields: id, name, phone, created_at

   - users
     * Staff accounts and permissions
     * Fields: id, username, password (hashed), role, assigned_branch,
       restrict_branch, can_edit, can_delete, can_transfer, can_refund,
       can_restore, created_at

   - expenses
     * Expense tracking
     * Fields: id, branch, date, description, amount, created_by, created_at

   - activity_logs
     * Audit trail
     * Fields: id, user, action, description, created_at
   
   - stock_activity_logs
     * Stock-specific activity tracking
     * Fields: id, user, action, description, created_at
     * Tracks: ADD_STOCK, UPDATE_STOCK, DELETE_STOCK, TRANSFER_STOCK, MERGE_DUPLICATES

--------------------------------------------------------------------------------

B. INDEXES
   - Performance indexes on: job_id, branch, status, created_at, user, action

================================================================================
4. SYSTEM FEATURES & INTEGRATIONS
================================================================================

A. SECURITY
   - Session-based authentication
   - CSRF token protection
   - SQL injection prevention (PDO prepared statements)
   - Password hashing (password_hash/password_verify)
   - Permission-based access control
   - Branch-level restrictions

B. NOTIFICATIONS
   - Toast notifications (success/error)
   - Real-time feedback on actions
   - WhatsApp integration for customer communication

C. EXTERNAL INTEGRATIONS
   - WhatsApp Web API (wa.me links)
   - QR Code generation (QRious library)
   - QR Code scanning (html5-qrcode)
   - PDF generation (html2pdf.js)
   - Charts (Chart.js)

D. MOBILE SUPPORT
   - PWA manifest (manifest.json)
   - Responsive design
   - Touch-friendly interface
   - Mobile-optimized forms

================================================================================
5. ARCHIVED FILES
================================================================================

Location: /Archives-Executed/
These are historical migration/fix scripts that have been executed:
   - add_database_indexes.php
   - check_customer_data.php
   - check_db.php
   - debugger.php
   - fix_invoice.php
   - fix_retail_prefix.php
   - fix_retail_status.php
   - health_check.php
   - install_db.php
   - migrate_completed_to_retail.php
   - migrate_stock_shortcode.php
   - restore_customer_data.php
   - test_telegram.php

================================================================================
6. ADDITIONAL FILES
================================================================================

   - readme.txt: Technical documentation
   - logo.png: Company logo (used in invoices/receipts)
   - database_dump.sql: Database backup/structure reference
   - debug_log.txt: Debug logging output
   - monitor_backup_status.txt: Backup status tracking
   - php.ini: PHP configuration overrides

================================================================================
7. RECENT UPDATES & ENHANCEMENTS
================================================================================

A. Stock Management Improvements (v16.0+)
   - Smart stock merging with case-insensitive matching
   - Bulk import with flexible text format parsing
   - Uppercase conversion tool for data standardization
   - Device model searchable dropdown with add-new functionality
   - Category-first form flow for repair parts
   - Enhanced stock activity logging

B. Report Enhancements (v17.0+)
   - Removed Sales by Staff and Hourly Sales charts
   - Added clickable category profit breakdown
   - Improved category profit calculation accuracy
   - Better price extraction from repair strings
   - Cost-based proportional distribution for multi-item jobs

C. Receipt Improvements (v14.4+)
   - Displays "Warranty: No Warranty" under each item when applicable
   - Enhanced warranty information visibility

D. Permission System Expansion
   - Added granular permissions for stock operations
   - Bulk operations permissions
   - Stock log viewing permissions
   - Merge and uppercase conversion permissions

E. Backup & Sync Improvements
   - Enhanced restore_from_sync.php with cURL fallback
   - Better error handling for missing PHP extensions
   - Excludes config files during backup sync

================================================================================
END OF SITEMAP
================================================================================
Last Updated: January 2026
Version: 8.0