@cplace/mcp-server 1.6.0 → 1.6.2

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-ctts-main-projectmanagerReportGrid/research.md

@@ -1,178 +0,0 @@
-# Widget Research: cf.cplace.ctts.main.projectmanagerReportGrid
-
-## Quick Description
-
-The Project Manager Report Grid widget displays time booking data in a tabular format from a project leader's perspective, showing which employees worked on which projects and for how long during a selected time period.
-
-## Purpose
-
-This widget is part of the CTTS (Collaborative Time Tracking System) timebooking solution and provides project managers/leaders with a comprehensive overview of time bookings across their projects. It aggregates and displays time tracking data to help project managers monitor resource allocation and time spent on different projects by team members.
-
-## Key Concepts
-
-### 1. Report Types
-The widget is specifically designed for the **Project Manager View** (PROJECT_VIEW) report type, which differs from the Employee View. It shows data organized by projects and employees rather than by individual employee timesheets.
-
-### 2. Representative Mode
-The widget supports viewing time tracking data on behalf of other users (substitution/representative mode). This is controlled through the `RepresentativeStorage.PROJECTMANAGER_REPORTS` storage, allowing authorized users to view reports for different project managers.
-
-### 3. Time Period Selection
-Users can select a date range to view time tracking data:
-- Start and end date selection (year and month)
-- The selected date range is persisted per user and space
-- Previous selections are remembered when returning to the widget
-
-### 4. Data Structure
-The widget displays:
-- **Projects**: The booked targets (pages) that employees worked on
-- **Employees**: The people who booked time to projects
-- **Time Data**: Hours/time booked per project per employee
-- **Project Distribution**: Percentage distribution showing how team members' time is allocated across projects
-- **Additional Person Attributes**: Configurable custom attributes from employee profiles
-
-## Configuration Options
-
-### Widget Configuration
-
-The widget supports one main configuration option:
-
-**REPORT_PERSON_ATTRIBUTES** (`cf.cplace.ctts.main.reportPersonAttributes`)
-- Type: Multi-string attribute with dynamic enumeration
-- Purpose: Allows selection of additional person attributes to display in the report
-- Label: "Choose custom attributes"
-- Use case: Display extra information about employees (e.g., department, role, cost center) alongside their time bookings
-
-This configuration is loaded from the widget configuration and used by `ReportAdditionalAttributes` to enrich the report data with custom person information.
-
-### App Configuration
-
-The widget respects app-level configurations from `MainAppConfiguration`, particularly:
-- **ALLOWED_GROUPS**: Determines who can view the report through permission checking
-- **showDataFromThisWorkspaceOnly**: Filters which booked targets are visible based on workspace membership
-
-## Use Cases
-
-### Primary Use Case: Project Time Oversight
-A project manager wants to see how much time team members have spent on various projects during a specific month or quarter to:
-- Monitor project progress through time investment
-- Identify resource allocation patterns
-- Verify that team members are booking time correctly
-- Prepare for project reviews or billing
-
-### Use Case: Cross-Project Analysis
-A project manager overseeing multiple projects wants to understand:
-- Which employees are working on which projects
-- How employee time is distributed across projects (percentage view)
-- Whether resources are balanced or overallocated
-
-### Use Case: Custom Reporting
-An organization needs to include additional employee information in project reports, such as:
-- Cost center information for budget tracking
-- Employee seniority level for capacity planning
-- Department information for cross-functional project analysis
-
-They configure the `REPORT_PERSON_ATTRIBUTES` setting to include these custom attributes in the report grid.
-
-### Use Case: Representative/Substitute Viewing
-A project manager is on vacation, and their substitute needs to review project time bookings. The substitute uses the representative mode to view the project manager's reports without switching user accounts.
-
-## Related Widgets
-
-### cf.cplace.ctts.main.projectmanagerReportChart
-- **Relationship**: Companion widget to the grid view
-- **Difference**: Displays the same project manager time tracking data in a chart/graphical format instead of a table
-- **Shared Code**: Both widgets use the same `ReportWidgetSubstitution` base class and `ReportHandler` for data retrieval
-- **Use Together**: Organizations typically offer both widgets so users can choose between tabular data (grid) and visual analysis (chart)
-
-### cf.cplace.ctts.main.employeeReportGrid
-- **Relationship**: Similar widget but from employee perspective
-- **Difference**: Shows time bookings from an individual employee's viewpoint rather than a project manager's overview
-- **Report Type**: Uses EMPLOYEE_VIEW instead of PROJECT_VIEW
-
-### cf.cplace.ctts.main.MainWidget
-- **Relationship**: The primary time booking widget
-- **Difference**: Used for entering time bookings, while the project manager report grid is for viewing/analyzing already entered data
-- **Data Flow**: Time entered in MainWidget becomes the data displayed in the report grid
-
-## Technical Architecture
-
-### Handler Chain
-1. Widget renders with initial state using `ReportWidgetSubstitution`
-2. User interactions trigger `ReportHandler` via AJAX
-3. `ReportHandler` delegates to `ReportProjectManager` for data generation
-4. `ReportProjectManager` uses `ReportProjectManagerDatabaseUtilities` to query time bookings
-5. Data is returned as JSON through `ProjectReportBaseData` structure
-
-### Data Flow
-1. Widget initialization loads saved date range from `ReportDateRangeStore`
-2. Frontend sends request with date range and current user ID
-3. Backend queries time booking database for projects managed by the selected user
-4. Results are filtered by workspace visibility rules
-5. Additional person attributes are loaded if configured
-6. Project distribution percentages are calculated
-7. Data is serialized as JSON and sent to frontend for display
-
-### Key Classes
-- **ProjectmanagerReportGridWidgetDefinition**: Widget definition and configuration type
-- **ReportWidgetSubstitution**: Template substitution providing state and handlers
-- **ReportHandler**: HTTP handler for report data requests
-- **ReportProjectManager**: Business logic for generating project manager report data
-- **ReportAdditionalAttributes**: Manages custom person attributes in reports
-- **RepresentativeTool**: Manages representative/substitute user selection
-
-## Dependencies and Prerequisites
-
-### Required Permissions
-- User must be member of groups defined in `MainAppConfiguration.ALLOWED_GROUPS`
-- Without proper group membership, the widget displays "View not allowed" message
-
-### Data Prerequisites
-- Time bookings must exist in the system (entered via MainWidget)
-- Projects/targets must be properly configured as time booking targets
-- Project manager assignments must be configured (determines which projects a user can see)
-
-### Related Features
-- **Time Tracking Export**: Integration with time tracking export functionality (button visible if export templates configured)
-- **Project Manager Configuration App**: Used to assign project managers to projects/targets
-- **Representative System**: Requires representative/substitute user configuration
-
-## Frontend Integration
-
-### State Object
-The widget provides a comprehensive state object to the frontend including:
-- `reportHandlerURL`: Endpoint for fetching report data
-- `selectRepresentativeHandlerURL`: Endpoint for selecting substitute user
-- `clearRepresentativeHandlerURL`: Endpoint for clearing substitute selection
-- `selectTimeTrackingExportHandlerURL`: Endpoint for time tracking export
-- `uid`: Widget ID
-- `availableYears`: List of years with booking data
-- `startYear`, `startMonth`, `endYear`, `endMonth`: Current date range
-- `showTimeTrackingButton`: Boolean flag for export functionality
-- Representative/substitute user information
-
-### User Interface Elements
-Based on the localization messages, the widget likely provides:
-- Date range selectors (start/end year and month)
-- Representative/substitute user selection
-- Employee and project columns
-- Time data display (hours/percentage)
-- Time tracking export button (if configured)
-- Custom attribute columns (if configured)
-
-## Localization
-
-### Widget Name
-- **English**: "Project Leader table view Time Tracking"
-- **German**: "Projektleiter Tabelle Report Zeiterfassung"
-
-### Configuration Labels
-- **English**: "Choose custom attributes"
-- **German**: "Wählen Sie weitere Attribute"
-
-### Report Headline
-- **English**: "Project Leader Report Timebooking"
-- **German**: "Report Projektleiteransicht"
-
-## Summary
-
-The Project Manager Report Grid widget is a specialized reporting widget that provides project managers with a tabular view of time bookings across their projects. It enables oversight of resource allocation, supports custom employee attributes for enriched reporting, and integrates with the broader CTTS time tracking ecosystem. The widget is highly configurable, supports representative viewing for delegation scenarios, and works in tandem with its chart counterpart for flexible data visualization options.

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

@@ -1,332 +0,0 @@
-# Widget Research: cf.cplace.ctts.main.widget
-
-## Widget Overview
-
-**Widget ID:** `cf.cplace.ctts.main.widget`
-**Repository:** cplace-ctts
-**Plugin:** cf.cplace.ctts.main
-**Definition Class:** `cf.cplace.ctts.main.script.MainWidgetDefinition`
-
-## Purpose
-
-The CTTS (cplace Time Tracking System) main widget is an interactive time tracking and booking interface that allows users to record, manage, and monitor their work hours across various projects and targets within specified time periods.
-
-**Short Description:**
-This widget provides a comprehensive time tracking grid interface where users can book hours to different targets (projects/activities), view time in different formats and time units (day/week/month), manage favorites, and submit time entries for approval through a monthly release workflow.
-
-## Core Functionality
-
-### 1. Time Booking Grid
-- **Interactive data grid** using Handsontable for recording time bookings
-- Users book time entries to various **targets** (projects, activities, or other entities defined in the system)
-- Each booking contains:
-  - Date
-  - Booked time (in seconds, supports negative values for corrections)
-  - Target reference (what the time was booked to)
-  - Optional description
-  - User reference
-
-### 2. Time Period Views
-The widget supports multiple time unit views:
-- **Day view**: Track time on a daily basis
-- **Week view** (default): See and edit an entire week at once
-- **Month view**: View and manage monthly time bookings
-- Optional "one value for month view" mode where a single total can be entered for the entire month
-
-### 3. Calendar Integration
-- **Calendar view** toggle for visual date selection
-- **Week picker** component for easy navigation between time periods
-- Weeks in the calendar can be made clickable (configurable)
-- "Today" button to quickly jump to the current date/week
-
-### 4. Time Format Options
-Users can toggle between different time format displays:
-- **Punctual time format**: Hours and minutes (e.g., "8:30")
-- **Decimal time format**: Decimal representation (e.g., "8.5" or "8,5" depending on locale)
-- Format preference is saved per user via UserConfig
-
-### 5. Target Management
-- **Add targets**: Users can add new booking targets through a dialog
-- **Favorites system**: Mark frequently-used targets as favorites for quick access
-- **Target filtering**: Configurable filters to control which targets users can select
-- **Distribution percentage**: Allocate time across targets by percentage
-- **Subsequent bookings**: Special mode for adding bookings to past months (with configurable limit)
-
-### 6. Representative/Delegate Booking
-- **Representative mode**: Authorized users can book time on behalf of other users
-- Configurable groups for:
-  - Representative time bookers (can only do representative bookings)
-  - Delegates (can be represented by others)
-- Visual indicator showing which user's time is being tracked
-
-### 7. Monthly Release Workflow
-- **Release month**: Submit time entries for a completed month
-- **Lock/unlock months**: Prevent changes to finalized time periods
-- **Revoke release**: Undo a month's release if needed
-- Privileged groups can edit locked cells
-- Admin override capabilities (configurable)
-
-### 8. Data Validation & Controls
-- **Maximum booking time per day**: Configurable limit (default: 10 hours)
-- **Overbook limit**: Warning threshold when exceeding daily limits
-- **Time fraction precision**: Configurable minimum time increment (1 sec, 1 min, 15 min, 30 min, 60 min)
-- **Negative bookings**: Optional support for negative time entries (corrections)
-- **Holiday/weekend handling**: Configurable whether holidays, Saturdays, and Sundays are bookable workdays
-- **Monthly negative bookings**: Control whether overall monthly total can be negative
-
-### 9. Data Display Options
-- **Sum line**: Shows totals, optionally with difference from target hours
-- **Sidebar**: Displays cell details and configurable attributes of selected targets
-- **Extended title text**: Larger header rows with more information
-- **Manual column resize**: Allow users to adjust column widths
-
-### 10. Data Actions
-- **Save**: Persist time booking changes
-- **Discard**: Revert unsaved changes
-- **Delete**: Remove booking entries for the current week
-- **Undo modal**: Confirmation dialog for destructive actions
-
-## Use Cases
-
-### Primary Use Cases
-
-1. **Individual Time Tracking**
-   - Employees track their daily/weekly work hours
-   - Book time to projects, tasks, or activities they work on
-   - View their time allocation across different targets
-   - Submit monthly timesheets for approval
-
-2. **Project Time Booking**
-   - Record time spent on specific projects or work packages
-   - Distribute time across multiple projects in a single day
-   - Track project-related hours for billing or resource planning
-
-3. **Administrative Time Management**
-   - Managers or assistants book time on behalf of team members
-   - HR or admin staff manage time entries for multiple users
-   - Corrections and adjustments to historical time data
-
-4. **Monthly Time Reporting**
-   - Users compile and submit their monthly working hours
-   - Managers review and approve released months
-   - Lock finalized periods to prevent further changes
-
-5. **Flexible Work Schedule Tracking**
-   - Support for part-time employees with varying hours
-   - Track overtime through overbook limits and warnings
-   - Handle irregular schedules (weekends, holidays)
-
-### Secondary Use Cases
-
-6. **Absence and Corrections**
-   - Use negative bookings to correct over-reported time
-   - Track non-working time on specific days
-
-7. **Multi-Workspace Operations**
-   - Users work across different organizational workspaces
-   - Filter targets by workspace
-   - Optionally restrict visibility to specific workspaces
-
-8. **Favorites and Quick Booking**
-   - Create favorite targets for frequently-used projects
-   - Quick time entry for routine activities
-   - Distribution percentages for regular allocations
-
-9. **Subsequent Booking (Retroactive Entries)**
-   - Add time entries to past months within a configurable limit
-   - Handle forgotten or delayed time reporting
-
-## Configuration Concepts
-
-### Widget-Level Configuration
-
-The widget can be configured with the following options:
-
-1. **Localized Title** (`LOCALIZED_TITLE`)
-   - Custom title for the widget instance
-
-2. **Height** (`HEIGHT`)
-   - Fixed height setting, or auto-height if not specified
-
-3. **Time Unit Per Page Mode** (`TIME_UNIT_PER_PAGE_MODE`)
-   - Options: Day, Week, Month
-   - Default: Month
-   - Controls the primary view granularity
-
-4. **Weeks in Calendar Are Clickable** (`WEEKS_IN_CALENDAR_ARE_CLICKABLE`)
-   - Boolean (default: true)
-   - Whether clicking weeks in calendar view changes the main grid
-
-5. **Default Time Format for Bookings** (`DEFAULT_TIME_FORMAT_FOR_BOOKINGS`)
-   - Options: Punctual (hours:minutes) or Decimal
-   - Default: Punctual
-   - Sets the initial time format for new users
-
-### App-Level Configuration
-
-The widget behavior is heavily influenced by app configuration settings in the workspace:
-
-#### Access Control
-- **Allowed Groups**: Groups with permission to use the widget
-- **Representative Time Booker Groups**: Users who can only do representative bookings
-- **Representative Type**: Groups that can act as delegates
-- **Privilege Groups**: Extended rights for editing locked/released entries
-
-#### Target Selection
-- **Visibility Type**: All targets vs. only permitted targets
-- **Select Workspaces**: Limit target selection to specific workspaces
-- **Select Type Names**: Define which entity types can be used as targets
-- **Select Type Attributes**: Attributes to display in the sidebar
-- **Target Filter Script**: Custom JavaScript filter for target selection
-- **Show Data From This Workspace Only**: Restrict displayed data by workspace
-
-#### Time Booking Rules
-- **Max Time Fraction**: Minimum bookable time increment (1 sec to 60 min)
-- **Default Maximum Working Hours Per Day**: Standard workday length
-- **Overbook Limit Per Day**: Warning threshold for excessive hours
-- **Allow Booking Only In Current Month**: Restrict historical entries
-- **Months Limit For Subsequent Booking**: How far back subsequent bookings are allowed
-- **Allow Negative Numbers For Bookings**: Enable correction entries
-- **Allow Overall Monthly Negative Bookings**: Allow negative monthly totals
-
-#### Workday Configuration
-- **Holidays Are Workdays**: Whether public holidays are bookable
-- **Saturdays Are Workdays**: Saturday booking enabled
-- **Sundays Are Workdays**: Sunday booking enabled
-
-#### Display & Behavior
-- **Targets As Favorites**: New targets default to favorites
-- **Show Difference In Sum Line**: Display variance from target hours
-- **Extended Title Text**: Larger header rows
-- **Manual Column Resize**: User-adjustable column widths
-- **One Value For Month View**: Accept single monthly total instead of daily breakdown
-- **Can Admins Edit Locked Cells**: Admin override for locked periods
-- **Allow Editing Of Non-Addable Targets**: Edit cells for targets no longer in selection
-
-#### Data Import
-- **Allowed Groups Import Aggregated Times**: Groups permitted to import time data files
-
-## Technical Architecture
-
-### Key Components
-
-1. **Definition Layer**
-   - `MainWidgetDefinition`: Widget registration and configuration type binding
-   - `MainWidgetConfiguration`: Widget-specific configuration type definition
-   - `MainAppConfiguration`: App-level configuration type definition
-
-2. **Data Layer**
-   - `TimeBookingData`: Individual time booking entries (date, time, user, description)
-   - `BookingRow`: Groups bookings by target
-   - `MonthFlag`: Tracks released/locked month status
-   - `TargetFlag`: Flags for booking targets
-   - `FavoriteTarget`: User's favorite target references
-   - `BookingRowMetaData`: Additional metadata for booking rows
-
-3. **Handler Layer** (Backend API endpoints)
-   - Grid data loading and saving
-   - Calendar view data
-   - Favorites management (save/delete)
-   - Target selection and filtering
-   - Release dialog and submission
-   - Representative selection and clearing
-   - Time format preferences
-   - Distribution percentage management
-   - Locked months checking
-
-4. **Frontend Layer**
-   - AngularJS-based UI components
-   - Handsontable integration for grid display
-   - Week picker component
-   - Calendar component
-   - Sidebar for cell details
-   - Various modal dialogs (undo, release, warnings)
-
-5. **Extension Points**
-   - `AdditionalHolidaysAppExtension`: Plugin-provided holiday calendars
-   - `TargetTimeManager`: Calculates target working hours per user/date
-   - `RepresentativeExtensionPointOnceADayTask`: Daily task for representative updates
-   - Custom filters for person and target selection
-
-### Data Handlers
-
-The widget communicates with the backend through multiple specialized handlers:
-
-- **GridDataLoadHandler**: Load booking data for display
-- **GridDataSaveHandler**: Persist time booking changes
-- **CalendarViewDataHandler**: Provide calendar-specific data
-- **FavoritesDataSaveHandler/DeleteHandler**: Manage favorite targets
-- **EditReleaseDialogHandler**: Open release dialog
-- **SubmitReleaseDialogHandler**: Process month release/revoke
-- **RepresentativeEditHandler/ClearHandler**: Manage representative mode
-- **DistributionPercentageWriteHandler**: Save distribution settings
-- **TimeFormatSaveHandler**: Persist user time format preference
-- **LockedMonthsCheckerHandler**: Validate month lock status
-
-## Relationships to Other Widgets
-
-The CTTS main widget is part of a larger time tracking solution that includes:
-
-1. **Employee Report Grid Widget** (`cf.cplace.ctts.main.employeeReportGrid`)
-   - Related reporting widget for employee-centric views
-
-2. **Employee Report Chart Widget** (`cf.cplace.ctts.main.employeeReportChart`)
-   - Visual/chart representation of employee time data
-
-3. **Project Manager Report Grid Widget** (`cf.cplace.ctts.main.projectmanagerReportGrid`)
-   - Project-focused reporting for managers
-
-4. **Project Manager Report Chart Widget** (`cf.cplace.ctts.main.projectmanagerReportChart`)
-   - Chart visualization for project manager reports
-
-The main widget focuses on **data entry and individual time tracking**, while the report widgets provide **aggregated analysis and visualization** from different perspectives (employee vs. project manager).
-
-## Prerequisites and Dependencies
-
-### Required
-- Access to a workspace where the CTTS app is configured
-- User must be in an allowed group (per app configuration)
-- At least one booking target type must be configured
-- Workspace selection must be configured
-
-### Optional
-- Calendar/holiday configuration for accurate workday detection
-- Target time configuration (via TargetTimeManager) for "should" hours display
-- Representative permissions for booking on behalf of others
-- Privilege group membership for editing locked periods
-- Import permissions for bulk time data loading
-
-## Key User Workflows
-
-### Basic Time Entry Workflow
-1. User opens widget → sees current week by default
-2. Clicks "Add target" (+ button)
-3. Selects project/activity from available targets
-4. Enters hours in grid cells for each day
-5. Clicks save (floppy disk icon) to persist entries
-6. Optionally marks favorite targets with star icon
-
-### Monthly Submission Workflow
-1. User completes all time entries for the month
-2. Reviews totals in sum line
-3. Clicks "Release month" button (share icon)
-4. Confirms release in dialog
-5. Month becomes read-only (locked) after release
-6. Privileged users or admins can revoke if needed
-
-### Representative Booking Workflow
-1. Authorized user clicks representative button
-2. Selects person to represent from filtered list
-3. Widget shows "Booking as: [Selected User]"
-4. Books time on behalf of that person
-5. Clears representative mode when done
-
-### Time Format Toggle
-1. User sees current format (e.g., "8:30")
-2. Toggles switch to decimal format
-3. Display updates to "8.5" (or "8,5" in German locale)
-4. Preference is saved automatically for future sessions
-
-## Summary
-
-The `cf.cplace.ctts.main.widget` is a feature-rich, enterprise-grade time tracking widget designed for comprehensive work hour management. It combines flexible data entry (supporting multiple time units, formats, and precision levels), robust workflow controls (release/lock mechanisms), administrative capabilities (representative booking, privilege overrides), and extensive configurability to adapt to various organizational time tracking requirements. The widget serves as the primary data entry point in the CTTS solution, complemented by separate reporting widgets for analysis and visualization.