initial: bootstrap from BukidBountyApp base

ai-docs/features-recommendations.md

@@ -0,0 +1,86 @@
+# System Scan & Feature Recommendations
+
+This document outlines recommended changes, improvements, and new features for the BukidBountyApp based on recent system-wide scans and development patterns.
+
+## 🏗️ Architecture & Technical Improvements
+
+### 1. Unified API Response & Error Handling [HIGH PRIORITY]
+- **Current State**: `executeRequest.js` is a basic fetch wrapper. Axios is used directly in stores without global interceptors.
+- **Recommendation**: Transition all API calls to a centralized Axios instance with global interceptors.
+- **Action**: Implement a standard response structure `{ success: boolean, data: any, message: string }`. Automatically handle 401 (Logout), 403 (Forbidden), and 500 (Server Error) via global toast notifications.
+- **Benefit**: Reduces boilerplate in components and ensures consistent error feedback.
+
+### 2. Model Boot Traits / HasStandardFields
+- **Current State**: `ModelSavingListener` handles `hashkey`, `created_by`, and `updated_by` globally.
+- **Recommendation**: Move this logic to a `HasStandardFields` trait.
+- **Benefit**: Cleaner model definitions and avoids global listener overhead for models that don't need these fields.
+
+### 3. Real-time Synchronization (WebSockets)
+- **Recommendation**: Integrate WebSockets for live updates.
+- **Targets**: 
+  - Real-time sale notifications for Store Owners.
+  - Live shipment status updates for Buyers.
+  - POS session updates across multiple terminals.
+- **Benefit**: Makes the application feel alive and reduces manual refreshing.
+
+### 4. PWA & Offline Support (Advanced)
+- **Current State**: `PosMain.vue` has basic local storage for access keys, but no offline transaction capability.
+- **Recommendation**: Implement IndexedDB for `PosMain.vue` to allow full offline operation.
+- **Action**: Store product catalog and pending transactions locally. Auto-sync when back online using Background Sync API.
+- **Benefit**: Critical for farm locations with poor connectivity.
+
+### 5. Defensive Middleware & Null Safety
+- **Recommendation**: Audit all middleware (especially `EnsureUserGroupIsActive`) for null checks.
+- **Benefit**: Prevents "Call to a member function on null" errors during user role/group transitions.
+
+---
+
+## 💎 UI/UX Enhancements
+
+### 1. Skeleton Screens [PENDING]
+- **Current State**: `HomeUltimate.vue` and others use a generic `LoadingSpinner`.
+- **Recommendation**: Replace spinners with content-matching Skeleton Loaders.
+- **Benefit**: Improves perceived performance and reduces layout shift (CLS).
+
+### 2. Premium Micro-animations
+- **Recommendation**: Add subtle transitions for page changes and modal entries.
+- **Action**: Implement "Success" Lottie animations for completed transactions in POS.
+- **Benefit**: Increases user satisfaction and perceived app quality.
+
+### 3. Dynamic Dashboard Activity
+- **Current State**: `HomeUltimate.vue` recent activity is hardcoded placeholders.
+- **Recommendation**: Connect the "Recent System Activity" list to real audit logs or transaction history.
+- **Benefit**: Provides immediate value and transparency to administrators.
+
+### 4. Compact Mode for Data Tables
+- **Recommendation**: Add a "Compact Mode" toggle in User Settings for dense lists (Users, Transactions).
+- **Benefit**: Improves productivity for power users managing large datasets.
+
+---
+
+## 🚀 New Feature Recommendations
+
+### 1. POS "Quick-Clear" & Reset [COMPLETED]
+- **Description**: A dedicated button to completely reset the current POS cart with a confirmation modal.
+- **Status**: Implemented via `/api/pos/clear` and `PosMain.vue` UI.
+
+### 2. QR-Based Logistics Tracking
+- **Description**: Scan QR codes at each stage of the shipment lifecycle (Picked up -> In Transit -> Delivered).
+- **Benefit**: Enhances trust and transparency in the supply chain.
+
+### 3. Advanced Ultimate Tools
+- **Description**: Add Redis Memory Monitor and live SQL profiling to the Ultimate Console.
+- **Benefit**: Empower system admins to diagnose performance issues in real-time.
+
+### 4. Farmer-to-Store Bidding Board
+- **Description**: A digital board where stores post needs and farmers bid to fulfill them.
+- **Benefit**: Bridges the gap between production and retail demand.
+
+---
+
+## 📈 Roadmap Suggestions
+
+1.  **Phase 1 (Stability)**: Unified API Handling, `HasStandardFields` Trait, Middleware Null-Safety.
+2.  **Phase 2 (Experience)**: Skeleton Screens, Dynamic Activity Logs, POS Reset Button.
+3.  **Phase 3 (Logistics)**: QR Shipment Tracking, Offline POS (IndexedDB).
+4.  **Phase 4 (Marketplace)**: Bidding Board, Advanced Ultimate Monitoring.