Santhosh Janardhanan
90c15c70b7
Backend: - Add ActualController with Cartesian product query (all projects × members) - Add ActualsService for variance calculations (∞% when actual>0, allocated=0) - Add ActualResource for API response formatting - Add migration for notes column on actuals table - Add global config for inactive project logging (ALLOW_ACTUALS_ON_INACTIVE_PROJECTS) - Implement filters: project_ids[], team_member_ids[], include_inactive, search - Add pagination support (25 per page default) - Register /api/actuals routes Frontend: - Create MultiSelect component with portal rendering (z-index fix for sidebar) - Compact trigger mode to prevent badge overflow - SSR-safe with browser guards - Keyboard navigation and accessibility - Create Pagination component with smart ellipsis - Rebuild actuals page with: - Full Cartesian matrix (shows all projects × members, not just allocations) - Filter section with project/member multi-select - Active filters display area with badge wrapping - URL persistence for all filter state - Month navigation with arrows - Variance display (GREEN ≤5%, YELLOW 5-20%, RED >20%, ∞% for zero allocation) - Read-only cells for inactive projects - Modal for incremental hours logging with notes - Add actualsService with unwrap:false to preserve pagination meta - Add comprehensive TypeScript types for grid items and pagination OpenSpec: - Update actuals-tracking spec with clarified requirements - Mark Capability 6: Actuals Tracking as complete in tasks.md - Update test count: 157 backend tests passing Fixes: - SSR error: Add browser guards to portal rendering - Z-index: Use portal to escape stacking context (sidebar z-30) - Filter overlap: Separate badge display from dropdown triggers - Member filter: Derive visible members from API response data - Pagination meta: Disable auto-unwrap to preserve response structure
82 lines
3.9 KiB
Markdown
82 lines
3.9 KiB
Markdown
## ADDED Requirements
|
||
|
||
### Requirement: Log hours worked
|
||
The system SHALL allow team members to log actual hours worked per project per month.
|
||
|
||
#### Scenario: Log hours for current month
|
||
- **WHEN** a team member logs 35 hours worked on "Project X" for February 2026
|
||
- **THEN** the system creates an actuals record
|
||
- **AND** the system associates the hours with the team member, project, and month
|
||
|
||
#### Scenario: Cannot log negative hours
|
||
- **WHEN** attempting to log -5 hours
|
||
- **THEN** the system rejects the request with validation error "Hours logged must be greater than or equal to 0"
|
||
|
||
#### Scenario: Cannot log hours for future months
|
||
- **WHEN** attempting to log hours for a month that hasn't started yet
|
||
- **THEN** the system rejects the request with validation error "Cannot log hours for future months"
|
||
|
||
### Requirement: Update logged hours (incremental)
|
||
The system SHALL allow team members to update previously logged hours using incremental updates.
|
||
|
||
#### Scenario: Incremental weekly updates
|
||
- **WHEN** a team member logs 10 hours in week 1 of February
|
||
- **AND** logs an additional 8 hours in week 2 of February
|
||
- **AND** the system updates the total to 18 hours for February
|
||
- **THEN** the system accumulates the hours for the monthly aggregate
|
||
- **AND** the system preserves all notes from each update
|
||
|
||
### Requirement: View actuals summary with variance
|
||
The system SHALL display actual hours worked in a matrix view showing allocated, actual, and variance data.
|
||
|
||
#### Scenario: View monthly actuals matrix
|
||
- **WHEN** a manager views actuals for February 2026
|
||
- **THEN** the system displays projects as rows and team members as columns
|
||
- **AND** each cell shows:
|
||
- **Allocated hours** (from allocation records)
|
||
- **Actual hours** (from actuals records)
|
||
- **Variance %** = ((Actual - Allocated) / Allocated) × 100
|
||
- **Variance indicator**: GREEN (≤5%), YELLOW (5-20%), RED (>20%)
|
||
|
||
#### Scenario: Show variance indicators
|
||
- **WHEN** viewing the actuals matrix
|
||
- **THEN** cells are color-coded based on variance:
|
||
- GREEN: Within ±5% of allocation (on track)
|
||
- YELLOW: 5-20% variance (attention needed)
|
||
- RED: >20% variance (significant deviation)
|
||
|
||
### Requirement: Cannot log hours to inactive projects
|
||
The system SHALL prevent logging hours to projects in "Done" or "Cancelled" status (configurable via global setting).
|
||
|
||
#### Scenario: Attempt to log hours to done project
|
||
- **WHEN** attempting to log hours for a project with status "Done"
|
||
- **AND** the global system configuration `allow_actuals_on_inactive_projects` is false
|
||
- **THEN** the system rejects the request with error "Cannot log hours to completed projects"
|
||
|
||
#### Scenario: Allow logging to done project if configured
|
||
- **WHEN** the global configuration `allow_actuals_on_inactive_projects` is true
|
||
- **AND** a team member logs hours to a "Done" project
|
||
- **THEN** the system accepts the hours (for edge cases where work continues after project closure)
|
||
|
||
### Requirement: Actuals data entry is manual
|
||
The system SHALL support manual entry of actual hours without integration to time-tracking tools (MVP).
|
||
|
||
#### Scenario: Manual monthly entry
|
||
- **WHEN** a team member enters actual hours worked via the web interface
|
||
- **THEN** the system accepts the input without requiring integration with external time-tracking systems
|
||
|
||
#### Scenario: No automated time import
|
||
- **WHEN** viewing actuals entry interface
|
||
- **THEN** the system does not provide options to import from Jira, Harvest, Toggl, or other time-tracking tools (deferred to Phase 2)
|
||
|
||
### Requirement: Track actuals notes
|
||
The system SHALL allow optional notes when logging hours.
|
||
|
||
#### Scenario: Log hours with notes
|
||
- **WHEN** a team member logs 40 hours with notes "Focused on API development and bug fixes"
|
||
- **THEN** the system stores the notes alongside the hours logged
|
||
|
||
#### Scenario: View notes in matrix
|
||
- **WHEN** viewing the actuals matrix
|
||
- **THEN** clicking on a cell shows the history of logged hours with timestamps and notes
|