Planning

The Planning page is the central hub for project management, zone oversight, and team coordination. It provides comprehensive tools for monitoring zone status, managing work sessions, coordinating team members, and performing bulk operations.

📋 Overview

Component Name: planning
Route: /planning
Access: Project-based permissions with role-dependent features
Purpose: Comprehensive project planning, zone management, and team coordination

The Planning page serves as the operational center for:

• Zone Management - Monitor and control individual zones
• Team Coordination - Track and manage registered users
• Bulk Operations - Perform actions on multiple zones
• Session Management - Monitor and control work sessions
• Quality Control - Manage flags, blocking, and verification

---

🔑 Access Requirements

🎯 Basic Access:

• Active Project - Must be assigned to a current project
• Project Registration - Must be registered in the project

📊 Feature-Specific Permissions:

Feature	Required Permission	Description
Zone Session Management	zone-sessions.upsert	Create/modify work sessions
Zone Blocking	zones.block	Block/unblock zones
Zone Flags	zones.flags	Manage zone flags
PDF Generation	pdfs.view	Generate and view checklists
User Registration	projects.register	View registered users panel

---

🎨 Interface Layout

🖥️ Desktop Layout (>768px)

┌──────────────────────────────────────────────────────────┐
│                Zone Grid (75%)           │ Right Panel   │
│  ┌─────────────────────────────────────┐ │  (25%)        │
│  │    Zone Search & Pagination         │ │ ┌───────────┐ │
│  ├─────────────────────────────────────┤ │ │Zone Info  │ │
│  │                                     │ │ ├───────────┤ │
│  │         Zone Grid Display           │ │ │Filters    │ │
│  │      (Color-coded zones)            │ │ ├───────────┤ │
│  │                                     │ │ │Multi      │ │
│  │                                     │ │ │Actions    │ │
│  │                                     │ │ ├───────────┤ │
│  └─────────────────────────────────────┘ │ │Users      │ │
└──────────────────────────────────────────────────────────┘

📱 Mobile Layout (≤768px)

┌───────────────────────────────────────────┐
│             Zone Grid (100%)              │
│  ┌─────────────────────────────────────┐  │
│  │    Zone Search & Pagination         │  │
│  ├─────────────────────────────────────┤  │
│  │                                     │  │
│  │         Zone Grid Display           │  │
│  │                                     │  │
│  └─────────────────────────────────────┘  │
│ ┌─────┬─────┬─────┬─────────────────────┐ │
│ │🔽   │👥   │📱   │☑️                   │ │
│ │Filt │User │Apps │Multi                │ │
│ └─────┴─────┴─────┴─────────────────────┘ │
└───────────────────────────────────────────┘

---

🎯 Core Components

1️⃣ Zone Grid Display 🎯

Visual Elements:

• Color-coded backgrounds indicating zone status
• Zone codes prominently displayed
• Flag indicators showing special conditions
• Session counters for multiple scan sessions
• Click/tap selection for individual zones

Zone Status Colors:

Status	Color	Meaning
Scan Plan	🟦 Light Blue	Ready for scanning
Scan Busy	🟨 Yellow	Currently being scanned
Scan Ready	🟩 Green	Scan completed
Verify Plan	🟠 Orange	Ready for verification
Verify Busy	🟪 Purple	Currently being verified
Verify Ready	✅ Light Green	Verification complete
Export	⚫ Dark	Ready for export
Blocked	🔴 Red	Cannot proceed

Interactive Features:

• Single click - View zone details
• Multi-select mode - Select multiple zones for bulk actions
• Search filtering - Find specific zones
• Pagination - Navigate through large zone lists

2️⃣ Zone Search & Pagination 🔍

Search Functionality:

• Real-time filtering as you type
• Zone code search - Find by identifier
• Multi-criteria filtering via filter panel
• Result count display

Pagination Controls:

• Page navigation with configurable page size (default: 100)
• Total count indicator
• Next/Previous navigation
• Direct page jumping

3️⃣ Right Panel (Desktop) / Bottom Bar (Mobile) 📊

---

🔧 Zone Management Features

📍 Zone Information Panel

Purpose: Display detailed information about selected zone

Information Displayed:

• Zone code and description
• Current status and history
• Associated work sessions
• Zone properties (division, flags, etc.)
• Progress and completion details

Available Actions:

Action	Icon	Permission	Description
Verify	✅	zone-sessions.upsert	Start verification process
Set Scanned	📝	zone-sessions.upsert	Mark as scanned
Set Verified	✓	zone-sessions.upsert	Mark as verified
Block Zone	🚫	zones.block	Prevent further work
Unblock Zone	✅	zones.block	Resume work capability
Generate PDF	📄	pdfs.view	Create checklist
Move Sessions	🔄	zone-sessions.upsert	Transfer to another zone

🏷️ Zone Flags Management

Permission: zones.flags

Flag Operations:

• Toggle flags on/off for zones
• Internal flags - System-defined with translations
• Custom flags - Project-specific flags
• Bulk flag application via multi-actions
• Visual flag indicators on zone grid

Flag Types:

• Internal Flags - Translated system flags
• Custom Flags - Project-specific identifiers
• Unknown Flags - Legacy or external flags

---

👥 Registered Users Panel

📊 User Management

Permission: projects.register

User List Features:

• Search functionality - Find users by name/username
• Session filtering - Filter by active session count
• Status indicators - Show user availability
• Click to assign - Direct user-to-zone assignment

Filter Options:

Filter	Description	Use Case
All Users	Show all registered users	General overview
1 Open Session	Users with exactly one active session	Available for assignment
2+ Open Sessions	Users with multiple active sessions	Potential conflicts

User Information:

• Full name and username display
• Current session status
• Availability indicators
• Role and permissions context

🎯 User Assignment Process

1. Select zone from grid
2. Choose user from registered users panel
3. Select action type (Scan or Verify)
4. Confirm assignment - Session created automatically

---

🔄 Multi-Actions Panel

☑️ Multi-Selection Mode

Permission: zone-sessions.upsert + active registration

Activation:

• Checkbox toggle in panel header
• URL parameter when accessing with multiple zone IDs
• Session persistence - maintains selection across navigation

Selection Features:

• Click zones to add/remove from selection
• Selection counter showing number of selected zones
• Individual removal from selected zones list
• Visual indicators on selected zones

🛠️ Bulk Operations

Available Actions:

Action	Icon	Permission	Description
Verify Zones	✅	zone-sessions.upsert	Start verification for all
Block Zones	🚫	zones.block	Block multiple zones
Unblock Zones	✅	zones.block	Unblock multiple zones
Set Scanned	📝	zone-sessions.upsert	Mark all as scanned
Set Verified	✓	zone-sessions.upsert	Mark all as verified
Download PDFs	📄	pdfs.view	Generate multiple checklists

Smart Action Availability:

• Context-aware enabling - Actions only available when applicable
• Status validation - Prevents invalid state transitions
• Permission checking - Respects user permissions
• Batch processing - Handles large selections efficiently

📋 Selected Zones Management

• Expandable list showing all selected zones
• Zone details - Code, status, division
• Individual removal option
• Status color coding consistent with main grid
• Real-time updates as selections change

---

🔍 Advanced Filtering

📊 Filter Panel

Purpose: Narrow down zone display based on multiple criteria

Filter Categories:

Category	Options	Description
Status	All zone workflow states	Filter by current status
Division	Project-specific divisions	Group by physical location
Warehouse Code	Storage location codes	Filter by warehouse
Flags	All available flags	Show zones with specific flags
Priority	High, Medium, Low	Filter by work priority
Extra Fields	Custom project fields	Project-specific filtering

Filter Features:

• Multi-select options - Choose multiple values per category
• Select All/Clear All shortcuts
• Filter counter - Shows number of active filters
• Persistent storage - Remembers settings between sessions
• Real-time application - Updates grid immediately

Advanced Options:

• Separate Charts - Create individual chart filters
• Combined filtering - Multiple categories work together
• Exclusion filters - Show everything except selected
• Custom ranges - Numeric and date range filtering

---

📱 Mobile Optimizations

🎮 Mobile Navigation Bar

┌─────┬─────┬─────┬─────────────────────┐
│ 🔽  │ 👥  │ 📱  │ ☑️                  │
│Filt │User │Apps │Multi-Actions        │
└─────┴─────┴─────┴─────────────────────┘

Button Functions:

• Filter 🔽 - Open filter panel overlay
• Users 👥 - Show registered users panel
• Apps 📱 - Return to main planning view
• Multi-Actions ☑️ - Toggle multi-selection mode

📊 Mobile Adaptations:

• Full-screen panels - Filters and users take full screen
• Touch-friendly zones - Larger touch targets
• Swipe navigation - Navigate between panels
• Simplified layouts - Essential information only
• Quick actions - Direct access to common operations

---

🔄 Real-Time Features

📊 Live Updates

• Zone status changes reflected immediately
• Session updates show real-time progress
• User availability updates as sessions change
• Filter results update with data changes

🔔 Session Management

• Active session tracking - Monitor ongoing work
• Session conflict detection - Prevent overlapping work
• Automatic cleanup - Handle abandoned sessions
• Progress monitoring - Track completion status

---

💡 How to Use

🎯 Basic Zone Monitoring:

1. View zone grid for overall project status
2. Click zones to see detailed information
3. Use filters to focus on specific areas
4. Monitor color changes for status updates

👥 Team Coordination:

1. Open Users panel to see team availability
2. Filter by session count to find available workers
3. Click user to assign to selected zone
4. Choose action type (Scan/Verify) as needed

🔄 Bulk Operations:

1. Enable multi-actions mode via checkbox
2. Select multiple zones by clicking
3. Choose bulk action from multi-actions panel
4. Confirm operation when prompted

🏷️ Flag Management:

1. Select zone requiring flag update
2. Open zone info panel
3. Toggle desired flags on/off
4. Changes apply immediately

📊 Advanced Filtering:

1. Open filter panel
2. Select criteria for each category
3. Use Select All/Clear for efficiency
4. Apply filters - results update automatically

---

❓ Troubleshooting

📋 Planning page not accessible?

• Verify you're assigned to an active project
• Check if you have project registration
• Ensure project is not in closed state
• Contact project manager for access

🎯 Zones not showing?

• Check filter settings - may be too restrictive
• Verify project has zones created
• Clear all filters and try again
• Refresh page if data seems stale

👥 Users panel empty?

• Verify you have projects.register permission
• Check if users are registered in current project
• Ensure project has active team members
• Contact administrator for user management

🔄 Multi-actions not working?

• Check zone-sessions.upsert permission
• Verify you're registered in the project
• Ensure project is in active state
• Select zones before attempting actions

🏷️ Can't modify flags?

• Verify zones.flags permission
• Check if zone is in modifiable state
• Ensure zone is not blocked
• Confirm flag configuration exists

📄 PDF generation failing?

• Check pdfs.view permission
• Verify zone has necessary data
• Ensure PDF templates are configured
• Try individual PDF before bulk generation

📱 Mobile interface issues?

• Use bottom navigation bar for panel switching
• Tap zones firmly for selection
• Use swipe gestures for navigation
• Rotate device if layout appears cramped

---

🔧 Technical Details

📊 Data Sources:

• Zones Collection - Zone status, properties, and flags
• Zone Sessions - Active work sessions and history
• User Registrations - Project team members and roles
• Zone Flags - Available flags and configurations

🔄 Real-Time Subscriptions:

• Zone updates - Status changes and modifications
• Session tracking - Active session monitoring
• User availability - Session count updates
• Flag changes - Flag modifications and additions

💾 Performance Features:

• Paginated loading - Loads zones in chunks (100 default)
• Reactive subscriptions - Updates only changed data
• Filter persistence - Remembers settings in session storage
• Optimized queries - Efficient database operations

🔄 State Management:

• URL-based routing - Zone and user selections in URL
• Session persistence - Filter and selection state
• Reactive updates - Automatic UI updates with data changes
• Mobile adaptation - Responsive layout adjustments

---

🎯 Summary

The Planning page provides comprehensive project management through:

✅ Visual zone management with color-coded status grid
✅ Team coordination tools with user assignment capabilities
✅ Bulk operation support for efficient multi-zone management
✅ Advanced filtering system for targeted zone selection
✅ Real-time updates synchronized with ongoing work
✅ Mobile-optimized interface for field use
✅ Role-based access control for secure operations
✅ Session management for work tracking and coordination

📝 Note: Planning page access and features depend on project registration and role-based permissions. Contact your project administrator for access to specific features.