@cplace/test-mcp-server 1.0.0 → 1.1.0

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-qrCodeWidget/research.md

@@ -0,0 +1,130 @@
+# QR Code Widget Research
+
+## Widget Overview
+
+**Widget ID:** `cf.cplace.qrCodeWidget`
+**Repository:** `cplace-utility-widgets`
+**Definition Class:** `cf.cplace.qrCodeWidget/src/main/java/cf/cplace/qrCodeWidget/script/QrCodeWidgetDefinition.java`
+
+## Purpose and Description
+
+**Short Description (1-2 sentences):**
+The QR Code Widget generates a QR code containing the URL of the page on which it is placed, allowing users to quickly access the page by scanning the code with a mobile device.
+
+**Detailed Description:**
+This widget dynamically generates a QR code that encodes the absolute URL of the embedding cplace page. When users scan the QR code with a mobile device camera or QR code reader app, they are directed to that specific page. The widget uses the ZXing (Zebra Crossing) library for QR code generation, which is an industry-standard open-source barcode processing library.
+
+## Use Cases
+
+### Primary Use Cases
+
+1. **Mobile Access to Pages**
+   - Enable quick access to cplace pages from mobile devices
+   - Users can scan a QR code displayed on screen (e.g., during presentations) to open the page on their phone
+
+2. **Physical-Digital Integration**
+   - Print QR codes for display in physical spaces (offices, warehouses, production floors)
+   - Link physical assets or locations to their corresponding cplace pages
+   - Enable offline-to-online workflows where scanning leads to digital information
+
+3. **Meeting and Presentation Support**
+   - Display QR codes during meetings so attendees can quickly access related pages
+   - Share page links without manually typing URLs or sending emails
+
+4. **Asset and Inventory Tracking**
+   - Generate QR codes for equipment, inventory items, or project assets
+   - Print and attach codes to physical items for quick lookups
+
+5. **Documentation and Reports**
+   - Include QR codes in exported documents or PDFs
+   - Allow readers to access the live, up-to-date page version
+
+### Problem Solved
+
+The widget solves the challenge of quickly sharing page links, especially when:
+- URLs are long and difficult to type manually
+- Users need mobile access to pages displayed on large screens
+- Physical items need to be linked to digital records
+- Quick, touchless access is preferred
+
+## Configuration Options
+
+### Main Configuration Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| **Title** | Localized String | (empty) | Optional title displayed above the widget |
+| **Height** | Number | - | Fixed height of the widget in pixels |
+| **Show Frame** | Boolean | `false` | Whether to display a widget frame/border around the QR code. When false, the "quiet zone" (white margin around QR code) is removed |
+| **QR Code Size** | Number | `300` | Size of the QR code in pixels (both width and height) |
+| **Color** | Color (Hex) | `#000000` (black) | Color of the QR code modules (the dark squares) |
+| **Logo** | Document Reference | (none) | Optional image file to overlay centered on the QR code |
+
+### Configuration Details
+
+1. **Size Configuration**
+   - Default size is 300x300 pixels
+   - Can be adjusted for different display contexts (larger for presentations, smaller for inline use)
+
+2. **Visual Customization**
+   - Color can be changed to match branding
+   - Logo can be added for brand recognition
+   - The QR code uses high error correction (Level H) to ensure readability even with a logo overlay
+
+3. **Frame/Quiet Zone**
+   - `SHOW_FRAME = false` (default): Widget has no padding, quiet zone removed
+   - `SHOW_FRAME = true`: Widget displays with standard frame and quiet zone (4-unit margin)
+
+## Technical Context
+
+### Dependencies
+
+- **ZXing Library (3.3.3)**: Google's open-source barcode processing library
+  - `com.google.zxing:core` - Core barcode processing
+  - `com.google.zxing:javase` - Java SE image processing utilities
+
+### Architecture
+
+1. **Widget Definition** (`QrCodeWidgetDefinition.java`)
+   - Defines widget kind, name, icon (`fa-qrcode`)
+   - Provides content substitution for template rendering
+   - Configures handler URL with widget parameters
+
+2. **Handler** (`GenerateQrCodeHandler.java`)
+   - Generates QR code on-demand via HTTP request
+   - Creates QR code image using ZXing library
+   - Optionally merges custom logo into QR code center
+   - Returns base64-encoded PNG image
+
+3. **Frontend Directive** (`qrCodeWidgetDirective.ts`)
+   - AngularJS directive for rendering the widget
+   - Fetches QR code image from handler
+   - Displays the generated QR code image
+
+### QR Code Generation Details
+
+- **Format**: QR Code (2D barcode)
+- **Error Correction**: Level H (highest, ~30% data recovery)
+- **Output**: Base64-encoded PNG image
+- **Content**: Absolute URL of the embedding page
+
+## Related Widgets
+
+The QR Code Widget is part of the `cplace-utility-widgets` repository, which contains other utility-focused widgets:
+
+- `cf.cplace.dynamicCodeBlockWidget` - Code display widget
+- `cf.cplace.extendedTreeTableWidget` - Extended tree table display
+- `cf.cplace.treeTableWidget` - Tree table display
+- `cf.cplace.videoWidget` - Video embedding widget
+
+These are standalone utility widgets that enhance cplace pages with specific functionality. They are not tightly coupled and can be used independently.
+
+## Prerequisites and Dependencies
+
+- **cplace Platform**: Requires the cplace platform (`cf.cplace.platform`)
+- **No Solution Dependencies**: This is a standalone utility widget with no dependencies on specific cplace solutions
+- **Browser Support**: Requires a modern browser with JavaScript enabled (AngularJS-based rendering)
+
+## Summary
+
+The QR Code Widget is a simple, focused utility widget that provides quick mobile access to cplace pages through scannable QR codes. It's valuable for bridging physical and digital contexts, enabling meeting attendees to access pages quickly, and simplifying URL sharing. The widget offers reasonable customization (size, color, logo) while maintaining ease of use with sensible defaults.

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-resourceManagement-resourcePlannerDefinition/research.md

@@ -0,0 +1,331 @@
+# Resource Planner Widget Research
+
+## Widget Information
+- **Widget ID**: `cf.cplace.resourceManagement.resourcePlannerDefinition`
+- **Widget Name**: Resource Planner
+- **Repository**: `cplace-resource-management`
+- **Definition Class**: `ResourcePlannerWidgetDefinition.java`
+
+## Brief Description
+
+The Resource Planner widget provides an **overview of resource allocations and utilization**. It displays hierarchical resource or planning item data in a table format with time-based columns, allowing users to visualize and manage capacity, allocations, and workload over configurable time periods with color-coded utilization indicators.
+
+## Purpose and Core Functionality
+
+The Resource Planner widget is a sophisticated visualization tool designed to help organizations manage and monitor resource capacity and utilization. It serves as the primary interface for:
+
+1. **Visualizing Resource Allocation**: Displays resources (people, equipment, etc.) or planning items (projects, tasks, etc.) in a hierarchical tree structure with time-period columns showing allocations or capacity.
+
+2. **Tracking Utilization**: Provides color-coded visualization of utilization levels (low, medium, high) based on configurable thresholds, making it easy to identify over- or under-utilized resources.
+
+3. **Time-Based Planning**: Shows resource data across configurable time intervals (day, week, month, quarter, year) with dynamic or static date ranges.
+
+4. **Hierarchical Organization**: Supports parent-child relationships to organize resources or planning items in a tree structure with customizable grouping levels.
+
+5. **Interactive Data Management**: Provides actions and charts for deeper analysis and data manipulation within the widget.
+
+## Core Concepts
+
+### Tree Type: Resources vs. Planning Items
+
+The widget can display data in two fundamentally different modes (defined by `TreeType` enum):
+
+- **RESOURCE Mode**: Displays resources (e.g., people, teams, equipment) and their capacity/allocation
+- **PLANNINGITEM Mode**: Displays planning items (e.g., projects, tasks, work packages) and their resource requirements
+
+The search configuration determines which mode is used - it must return either only resources or only planning items, not both.
+
+### Calculation Distribution Types
+
+The widget supports two calculation methods for distributing values over time periods (`CalculationSelection`):
+
+- **Relative Distribution**: Resources and planning items maintain a constant proportion throughout the time period (e.g., 50% allocation remains 50% for the entire duration)
+- **Absolute Distribution**: Fixed values are distributed across the specified time period (e.g., 40 hours spread across a month)
+
+### Tree Structure and Hierarchy
+
+The widget organizes data hierarchically using:
+- **Root Node Selection**: Defines the top-level entries in the tree
+- **Parent-Child Relationships**: Configurable reference attributes that define the tree structure
+- **Collapse Level**: Controls which levels of the tree are expanded or collapsed by default
+- **Tree Structure Attributes**: Multiple reference attributes can be selected to build complex hierarchies
+
+## Use Cases
+
+### 1. Resource Capacity Planning
+**Scenario**: A project management office needs to track team member availability and allocations across multiple projects.
+
+**Configuration**:
+- Tree Type: RESOURCE
+- Data Source: Search for team members and organizational units
+- Tree Structure: Team hierarchy (Department → Team → Person)
+- Time Range: Next 6 months with monthly intervals
+- First Search: Planned project allocations
+- Second Search: Actual time bookings
+
+**Value**: Identify over-allocated resources, find available capacity, balance workload across teams.
+
+### 2. Project Portfolio Overview
+**Scenario**: Program managers need to visualize all active projects and their resource demands over time.
+
+**Configuration**:
+- Tree Type: PLANNINGITEM
+- Data Source: Search for projects and work packages
+- Tree Structure: Program → Project → Work Package
+- Time Range: Current quarter with weekly intervals
+- Utilization Colors: Show projects at risk (over-allocated) in red
+
+**Value**: Track project progress, identify resource bottlenecks, prioritize work based on capacity.
+
+### 3. Multi-Level Resource Allocation
+**Scenario**: An organization needs to compare resource demand vs. supply across multiple dimensions.
+
+**Configuration**:
+- Data Source: All resources or planning items
+- First Search: Resource demand from project plans
+- Second Search: Available resource capacity
+- Charts: Visualize demand vs. capacity trends
+- Actions: Quick actions to adjust allocations or create new bookings
+
+**Value**: Proactive capacity management, early warning of resource shortages, data-driven staffing decisions.
+
+### 4. Department Workload Analysis
+**Scenario**: Department managers need to monitor team utilization and ensure balanced workloads.
+
+**Configuration**:
+- Tree Type: RESOURCE
+- Data Source: Department members grouped by role
+- Utilization Boundaries: Low < 60%, Medium 60-100%, High > 100%
+- Color Coding: Visual indicators for under/over-utilization
+- Time Interval: Weeks or months depending on planning horizon
+
+**Value**: Quickly identify workload imbalances, redistribute work, prevent burnout.
+
+### 5. Dynamic Time-Based Reporting
+**Scenario**: Different stakeholders need to view resource data at different time granularities.
+
+**Configuration**:
+- Allowed Intervals: Day, Week, Month, Quarter, Year
+- Date Calculation: Dynamic (e.g., "start: -1 month, end: +3 months from today")
+- Default Chart: Stacked column chart showing trends
+- Additional Columns: Custom attributes like skills, location, cost center
+
+**Value**: Flexible reporting that adapts to different planning horizons and stakeholder needs.
+
+## Configuration Concepts
+
+### Data Sources and Searches
+
+The widget uses multiple search configurations to define what data to display:
+
+1. **Primary Data Source** (`SELECT_NODE`):
+   - Defines the main resources or planning items to display
+   - Must return either resources OR planning items (determined by type configuration)
+   - Supports sorting by attribute and order (ascending/descending)
+
+2. **Root Node Selection** (`SELECT_ROOT_NODE`):
+   - Defines the top-level entries in the tree hierarchy
+   - Default: Pages in current space that embed the widget page
+
+3. **First Search** (`SELECT_FIRST_GROUP`):
+   - Optional secondary search for comparison (e.g., planned demand)
+   - Results displayed in charts with customizable label (default: "Demand")
+   - Can be enabled/disabled with checkbox
+
+4. **Second Search** (`SELECT_SECOND_GROUP`):
+   - Optional tertiary search for comparison (e.g., actual allocation)
+   - Results displayed in charts with customizable label (default: "Allocation")
+   - Can be enabled/disabled with checkbox
+
+### Time Range Configuration
+
+Three modes for defining the visible time range (`DateCalculation`):
+
+1. **Static**: Fixed start and end dates
+   - Configuration: `PERIOD_START_STATIC`, `PERIOD_END_STATIC`
+   - Use case: Planning for a specific project phase or fiscal year
+
+2. **Dynamic**: Relative to current date
+   - Configuration: `PERIOD_START_VALUE_DYNAMIC` + `PERIOD_START_UNIT_DYNAMIC`
+   - Example: "-3 months to +6 months from today"
+   - Units: Day, Week, Month, Quarter, Year
+   - Use case: Rolling time windows that stay current
+
+3. **Attribute-Based**: Derived from date attributes on the pages
+   - Configuration: `PERIOD_START_ATTRIBUTE`, `PERIOD_END_ATTRIBUTE`
+   - Use case: Show resource allocation for the duration of each project
+
+### Time Intervals
+
+Configurable granularity for time columns:
+- **Available Options**: Day, Week, Month, Quarter, Year
+- **Allowed Intervals**: Multi-select which intervals users can switch between
+- **Default Interval**: Initial interval shown when widget loads
+
+### Utilization Visualization
+
+Color-coded indicators for resource utilization:
+
+1. **Boundaries**:
+   - `BOUNDARY_LOW`: Threshold for underutilization (default: 60%)
+   - `BOUNDARY_HIGH`: Threshold for overutilization (default: 100%)
+
+2. **Colors**:
+   - `COLOR_LOW`: Low utilization color (default: light blue #D7F0FF)
+   - `COLOR_MEDIUM`: Medium utilization color (default: light green #CFF1C8)
+   - `COLOR_HIGH`: High utilization color (default: light red #FFE5E6)
+
+3. **Weekends**:
+   - `CHECKBOX_WEEKENDS`: Option to include/exclude weekends from working days
+
+### Display Customization
+
+1. **Tree Display**:
+   - `TREE_STRUCTURE`: Reference attributes defining parent-child relationships
+   - `COLLAPSE_LEVEL`: Default expansion level (0 = all expanded)
+
+2. **Columns**:
+   - `ATTRIBUTES_CONFIGURATION`: Additional columns to display (attributes from the pages)
+   - Columns can be pinned, sorted, and reordered by users
+
+3. **Actions** (`ACTION_SELECTION`):
+   - Custom actions available for selected pages
+   - Defined via separate Action pages with scripts
+   - Example: "Create booking", "Adjust allocation", "Export data"
+
+4. **Charts** (`CHART_SELECTION`):
+   - Custom charts for data visualization
+   - Defined via separate Chart pages with configurations
+   - `DEFAULT_CHART`: Chart shown by default
+   - Example: Column charts, line charts for trend analysis
+
+5. **Widget Display**:
+   - `TITLE`: Localized widget title
+   - `HEIGHT`: Fixed height in pixels (optional)
+
+### Advanced Features
+
+1. **Time-Bounded Values (TBV) Support**:
+   - Handles attributes with time-varying values
+   - Automatically aggregates values for each time period
+
+2. **Configuration Migration**:
+   - Version tracking (`VERSION` attribute)
+   - Automatic migration service for backward compatibility
+
+3. **User Preferences**:
+   - Per-user time period selections are saved
+   - Column visibility and ordering persisted per user
+
+4. **Performance Optimization**:
+   - Lazy loading of additional columns
+   - Endpoint for fetching additional info on demand
+
+## Related Features
+
+### Actions
+- Custom scripts that can be executed for selected pages in the widget
+- Configured via `ResourceManagementActionsApp`
+- Example use cases: Bulk updates, data exports, workflow triggers
+
+### Charts
+- Visual analytics overlays on the resource planning data
+- Configured via `ResourceManagementChartApp`
+- Supports multiple chart types for trend analysis and comparison
+
+### Tooltips
+- Custom tooltip configurations for providing additional context
+- Configurable per tooltip type via `TooltipType` pages
+
+## Prerequisites and Dependencies
+
+### Type Configurations Required
+
+The widget requires specific type configurations to distinguish resources from planning items:
+
+1. **Resource Type Configuration** (`ResourceTypeConfigType`):
+   - Defines which custom types represent resources
+   - Includes attributes for capacity, availability, allocation
+
+2. **Planning Item Type Configuration** (`PlanningItemTypeConfigType`):
+   - Defines which custom types represent planning items
+   - Includes attributes for effort, duration, resource requirements
+
+### Related Apps
+
+1. **Resource Management Actions App**: For defining custom actions
+2. **Resource Management Chart App**: For defining custom charts
+3. **Time-Bounded Values Plugin** (optional): For advanced time-based attribute handling
+
+### Data Model Requirements
+
+- Custom types must be configured as either Resource or Planning Item
+- Reference attributes needed for tree hierarchy
+- Date attributes for time-based calculations
+- Numeric attributes for capacity/allocation values
+
+## Technical Architecture
+
+### Backend Components
+
+1. **Widget Definition** (`ResourcePlannerWidgetDefinition.java`):
+   - Extends `WidgetDefinition`
+   - Defines configuration type and rendering behavior
+   - Handles dynamic property visibility based on configuration
+
+2. **Configuration DTOs**:
+   - `ResourcePlannerWidgetConfigDTO`: Widget configuration
+   - `ResponseDTO`: Data sent to frontend
+   - `AdditionalColumnsDTO`: Dynamic column data
+
+3. **REST Endpoints** (`WidgetController.java`):
+   - `/resourceplanner`: Main data endpoint with time range parameters
+   - `/additionalInfos`: Lazy-loaded column data
+
+4. **Services**:
+   - `ConfigDataCollectionService`: Collects and processes widget configuration
+   - `ResponseService`: Builds tree structure and response data
+   - `UserConfigService`: Manages user-specific preferences
+
+### Frontend Components
+
+Located in `cplace-resource-management-fe` repository:
+- `cf-resource-planning-shell-lib`: Main widget shell
+- `cf-resource-planning-lib`: Table rendering
+- `cf-resource-planning-chart-lib`: Chart visualizations
+- `cf-resource-planning-toolbar-lib`: Toolbar and controls
+- `cf-resource-planning-data-management-lib`: Data handling
+
+### Key Classes
+
+1. **Type Definitions**:
+   - `ResourcePlannerWidgetTypes.RESOURCE_PLANNER_WIDGET`: All configuration attributes
+   - `TimeInterval`: Supported time intervals (Day, Week, Month, Quarter, Year)
+   - `CalculationSelection`: Relative vs. Absolute distribution
+   - `DateCalculation`: Static, Dynamic, or Attribute-based time ranges
+
+2. **Model Classes**:
+   - `ResourcePlannerConfigData`: Processed configuration data
+   - `ResourcePlannerTimePeriods`: Time range and interval settings
+   - `TreeType`: Resource vs. Planning Item mode
+   - `ValueTypeConfigs`: Resource/Planning Item type configurations
+
+## Summary
+
+The Resource Planner widget is a comprehensive tool for resource capacity planning and utilization tracking. Its key strengths are:
+
+1. **Flexibility**: Supports both resource-centric and planning-item-centric views
+2. **Hierarchy**: Displays complex organizational and project structures
+3. **Time-Based**: Configurable time ranges and intervals for different planning horizons
+4. **Visual Clarity**: Color-coded utilization indicators for at-a-glance status
+5. **Extensibility**: Custom actions, charts, and columns for specific needs
+6. **Comparison**: Multiple search groups for demand vs. capacity analysis
+
+**Primary Use Case**: Organizations need to visualize, track, and optimize resource allocation across projects and time periods, ensuring balanced workloads and identifying capacity gaps or surpluses.
+
+**When to Use This Widget**: Choose the Resource Planner when you need to answer questions like:
+- Who is available to work on this project?
+- Are any team members over-allocated?
+- What are the resource requirements for our project portfolio?
+- How does our capacity compare to demand over the next quarter?
+- Which projects are at risk due to resource constraints?