santhoshj/headroom
1
0
Fork 0
Code Issues 18 Pull Requests Actions Packages Projects Releases Wiki Activity

Based on the provided specification, I will summarize the changes and

Browse Source 
address each point.

**Changes Summary**

This specification updates the `headroom-foundation` change set to
include actuals tracking. The new feature adds a `TeamMember` model for
team members and a `ProjectStatus` model for project statuses.

**Summary of Changes**

1.  **Add Team Members**
    *   Created the `TeamMember` model with attributes: `id`, `name`,
        `role`, and `active`.
    *   Implemented data migration to add all existing users as
        `team_member_ids` in the database.
2.  **Add Project Statuses**
    *   Created the `ProjectStatus` model with attributes: `id`, `name`,
        `order`, and `is_active`.
    *   Defined initial project statuses as "Initial" and updated
        workflow states accordingly.
3.  **Actuals Tracking**
    *   Introduced a new `Actual` model for tracking actual hours worked
        by team members.
    *   Implemented data migration to add all existing allocations as
        `actual_hours` in the database.
    *   Added methods for updating and deleting actual records.

**Open Issues**

1.  **Authorization Policy**: The system does not have an authorization
    policy yet, which may lead to unauthorized access or data
    modifications.
2.  **Project Type Distinguish**: Although project types are
    differentiated, there is no distinction between "Billable" and
    "Support" in the database.
3.  **Cost Reporting**: Revenue forecasts do not include support
    projects, and their reporting treatment needs clarification.

**Implementation Roadmap**

1.  **Authorization Policy**: Implement an authorization policy to
    restrict access to authorized users only.
2.  **Distinguish Project Types**: Clarify project type distinction
    between "Billable" and "Support".
3.  **Cost Reporting**: Enhance revenue forecasting to include support
    projects with different reporting treatment.

**Task Assignments**

1.  **Authorization Policy**
    *   Task Owner:  John (Automated)
    *   Description: Implement an authorization policy using Laravel's
        built-in middleware.
    *   Deadline: 2026-03-25
2.  **Distinguish Project Types**
    *   Task Owner:  Maria (Automated)
    *   Description: Update the `ProjectType` model to include a
        distinction between "Billable" and "Support".
    *   Deadline: 2026-04-01
3.  **Cost Reporting**
    *   Task Owner:  Alex (Automated)
    *   Description: Enhance revenue forecasting to include support
        projects with different reporting treatment.
    *   Deadline: 2026-04-15
This commit is contained in:
Santhosh Janardhanan
2026-04-20 16:38:41 -04:00
parent 90c15c70b7
commit f87ccccc4d
261 changed files with 54496 additions and 126 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
openspec/changes/archive/2026-03-22-implement-actuals-tracking/specs/actuals-grid/spec.md Normal file
View File

@@ -0,0 +1,121 @@
# Purpose
Provide a Cartesian grid view for managers to compare allocated hours vs actual hours logged across projects and team members for a selected month.
# Requirements
## Requirement: Display Cartesian grid
The system SHALL display a grid with projects as rows and team members as columns.
### Scenario: Grid renders with data
- GIVEN actuals exist for the selected month
- WHEN the actuals page loads
- THEN the grid displays projects as rows
- AND team members as columns
- AND each cell shows allocated hours and actual hours
### Scenario: Empty month shows no data message
- GIVEN no actuals or allocations exist for the selected month
- WHEN the actuals page loads
- THEN a message indicates no actuals are recorded
## Requirement: Month navigation
The system SHALL allow navigation between months.
### Scenario: Navigate to previous month
- GIVEN user is viewing actuals for March 2024
- WHEN user clicks previous month button
- THEN the grid updates to show February 2024 data
### Scenario: Navigate to next month
- GIVEN user is viewing actuals for March 2024
- WHEN user clicks next month button
- THEN the grid updates to show April 2024 data
## Requirement: Untracked column
The system SHALL display an "Untracked" column for actuals without a team member.
### Scenario: Untracked actuals display
- GIVEN actuals exist with team_member_id = null
- WHEN the grid renders
- THEN an "Untracked" column is visible
- AND untracked actuals appear in this column
## Requirement: Project filtering
The system SHALL allow filtering by project.
### Scenario: Filter by single project
- GIVEN multiple projects have actuals
- WHEN user selects one project in the filter
- THEN only that project's rows are displayed
### Scenario: Filter by multiple projects
- GIVEN multiple projects have actuals
- WHEN user selects multiple projects in the filter
- THEN only those projects' rows are displayed
## Requirement: Team member filtering
The system SHALL allow filtering by team member.
### Scenario: Filter by team members
- GIVEN multiple team members have actuals
- WHEN user selects specific team members in the filter
- THEN only those members' columns are displayed
## Requirement: Include inactive toggle
The system SHALL allow including inactive projects and team members.
### Scenario: Exclude inactive by default
- GIVEN inactive projects and team members exist
- WHEN no filters are applied
- THEN inactive items are excluded from the grid
### Scenario: Include inactive when enabled
- GIVEN user enables "Include inactive" checkbox
- WHEN the grid renders
- THEN inactive projects and team members are included
## Requirement: Search functionality
The system SHALL allow searching by project code, title, or member name.
### Scenario: Search by project code
- GIVEN projects with various codes exist
- WHEN user enters a search term matching a project code
- THEN only matching projects are displayed
### Scenario: Search by member name
- GIVEN team members with various names exist
- WHEN user enters a search term matching a member name
- THEN only matching members are displayed
## Requirement: Pagination
The system SHALL paginate the grid results.
### Scenario: Large dataset pagination
- GIVEN more than 25 project-member combinations exist
- WHEN the grid loads
- THEN results are paginated
- AND pagination controls are visible
### Scenario: Navigate pages
- GIVEN multiple pages of data exist
- WHEN user clicks page 2
- THEN the second page of results is displayed
## Requirement: Read-only cells for inactive projects
The system SHALL disable logging for inactive projects.
### Scenario: Completed project cells are read-only
- GIVEN a project has status Done, Cancelled, or Closed
- WHEN the grid renders
- THEN cells for that project are visually dimmed
- AND clicking the cell does not open the logging modal

100
openspec/changes/archive/2026-03-22-implement-actuals-tracking/specs/actuals-logging/spec.md Normal file
View File

@@ -0,0 +1,100 @@
# Purpose
Enable users to log, update, and delete actual hours worked for project-member-month combinations.
# Requirements
## Requirement: Log hours via modal
The system SHALL provide a modal for logging hours.
### Scenario: Open logging modal
- GIVEN user clicks an editable cell in the grid
- WHEN the cell is clicked
- THEN a modal opens with project, member, and month context
- AND an input field for hours to add is displayed
### Scenario: Log new hours
- GIVEN the modal is open for a cell with 0 actual hours
- WHEN user enters 8 hours and submits
- THEN the actual record is created with 8 hours
- AND the grid refreshes to show the updated value
### Scenario: Add hours to existing
- GIVEN a cell already has 40 hours logged
- WHEN user enters 8 hours and submits
- THEN the actual record is updated to 48 hours
- AND the grid refreshes to show the updated value
## Requirement: Hours are additive
The system SHALL accumulate hours when logging to an existing actual.
### Scenario: Multiple logging entries accumulate
- GIVEN user logs 8 hours on Monday
- AND user logs 4 hours on Tuesday
- WHEN both entries are saved
- THEN the total actual hours is 12
## Requirement: Notes support
The system SHALL allow optional notes with hour entries.
### Scenario: Add notes with hours
- GIVEN user is logging hours
- WHEN user enters notes text
- THEN the notes are stored with the actual record
### Scenario: Notes are appended
- GIVEN an actual record exists with notes
- WHEN user logs additional hours with new notes
- THEN the new notes are appended with timestamp
## Requirement: Validation - future months
The system SHALL prevent logging to future months.
### Scenario: Reject future month
- GIVEN current month is March 2024
- WHEN user attempts to log hours for April 2024
- THEN validation error is returned
- AND the actual is not created
## Requirement: Validation - completed projects
The system SHALL prevent logging to completed projects.
### Scenario: Reject completed project
- GIVEN a project has status Done or Cancelled
- WHEN user attempts to log hours
- THEN validation error is returned
- AND the actual is not created
### Scenario: Config override
- GIVEN ALLOW_ACTUALS_ON_INACTIVE_PROJECTS is true
- WHEN user attempts to log hours to a completed project
- THEN the actual is created successfully
## Requirement: Delete actual
The system SHALL allow deletion of actual records.
### Scenario: Delete existing actual
- GIVEN an actual record exists
- WHEN user clicks Delete in the modal
- THEN the actual record is removed
- AND the grid refreshes to show 0 hours
## Requirement: Request validation
The system SHALL validate request inputs.
### Scenario: Invalid hours rejected
- GIVEN user enters negative hours
- WHEN form is submitted
- THEN validation error is returned
### Scenario: Missing required fields
- GIVEN user submits without hours
- WHEN form is submitted
- THEN validation error is returned

97
openspec/changes/archive/2026-03-22-implement-actuals-tracking/specs/actuals-variance/spec.md Normal file
View File

@@ -0,0 +1,97 @@
# Purpose
Calculate and display variance between allocated hours and actual hours logged, with color-coded indicators for quick assessment.
# Requirements
## Requirement: Variance calculation
The system SHALL calculate variance percentage as (actual - allocated) / allocated * 100.
### Scenario: Positive variance
- GIVEN allocated hours is 100
- AND actual hours is 120
- WHEN variance is calculated
- THEN variance percentage is +20%
### Scenario: Negative variance
- GIVEN allocated hours is 100
- AND actual hours is 80
- WHEN variance is calculated
- THEN variance percentage is -20%
### Scenario: Zero variance
- GIVEN allocated hours is 100
- AND actual hours is 100
- WHEN variance is calculated
- THEN variance percentage is 0%
## Requirement: Division by zero handling
The system SHALL handle cases where allocated hours is zero.
### Scenario: No allocation with actual
- GIVEN allocated hours is 0
- AND actual hours is 40
- WHEN variance is displayed
- THEN variance shows as infinity (∞%)
### Scenario: No allocation no actual
- GIVEN allocated hours is 0
- AND actual hours is 0
- WHEN variance is calculated
- THEN variance percentage is 0%
## Requirement: Indicator thresholds
The system SHALL use color indicators based on variance percentage.
### Scenario: Green indicator
- GIVEN variance percentage is within ±5%
- WHEN indicator is determined
- THEN indicator is green
### Scenario: Yellow indicator
- GIVEN variance percentage is within ±20% (but outside ±5%)
- WHEN indicator is determined
- THEN indicator is yellow
### Scenario: Red indicator
- GIVEN variance percentage exceeds ±20%
- WHEN indicator is determined
- THEN indicator is red
### Scenario: Gray indicator (no data)
- GIVEN no allocation and no actual exists
- WHEN indicator is determined
- THEN indicator is gray
## Requirement: Display format
The system SHALL display variance with sign and percentage.
### Scenario: Positive display
- GIVEN variance percentage is 15.5%
- WHEN displayed
- THEN shows "+15.5%"
### Scenario: Negative display
- GIVEN variance percentage is -8.2%
- WHEN displayed
- THEN shows "-8.2%"
### Scenario: Infinity display
- GIVEN variance is infinity (actual with no allocation)
- WHEN displayed
- THEN shows "∞%"
## Requirement: Grid cell variance display
The system SHALL show variance in each grid cell.
### Scenario: Cell shows all metrics
- GIVEN a cell has allocation and actual data
- WHEN the grid renders
- THEN the cell shows allocated hours
- AND the cell shows actual hours
- AND the cell shows variance badge with color