Files

Santhosh Janardhanan f87ccccc4d Based on the provided specification, I will summarize the changes and

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

2026-04-20 16:38:41 -04:00

4.2 KiB

Raw Blame History

allocation-validation Specification

Purpose

TBD - created by archiving change headroom-foundation. Update Purpose after archive.

Requirements

Requirement: Detect over-allocation

The system SHALL flag allocations that exceed approved estimates with RED indicator.

Scenario: Project over-allocated

WHEN a project has approved estimate of 100 hours
AND total allocations sum to 120 hours
THEN the system displays RED indicator with text "120% allocated (OVER by 20 hours)"

Scenario: Over-allocation threshold

WHEN total allocations exceed approved estimate by more than 5%
THEN the system displays RED flag
AND the system shows warning message "Will overcharge client"

Requirement: Detect under-allocation

The system SHALL flag allocations that fall short of approved estimates with YELLOW indicator.

Scenario: Project under-allocated

WHEN a project has approved estimate of 100 hours
AND total allocations sum to 80 hours
THEN the system displays YELLOW indicator with text "80% allocated (UNDER by 20 hours)"

Scenario: Under-allocation warning

WHEN total allocations are less than approved estimate by more than 5%
THEN the system displays YELLOW flag
AND the system shows warning message "Will undercharge client (revenue loss)"

Requirement: Display optimal allocation

The system SHALL display GREEN indicator when allocations match approved estimates.

Scenario: Perfect allocation

WHEN a project has approved estimate of 100 hours
AND total allocations sum to exactly 100 hours
THEN the system displays GREEN indicator with text "100% allocated (OPTIMAL)"

Scenario: Within tolerance

WHEN a project has approved estimate of 100 hours
AND total allocations sum to 102 hours (within 5% tolerance)
THEN the system displays GREEN indicator with text "102% allocated (within tolerance)"

Requirement: Validate person capacity

The system SHALL warn when a team member's allocations exceed their monthly capacity.

Scenario: Person under capacity

WHEN a team member has capacity of 160 hours
AND total allocations sum to 120 hours
THEN the system displays utilization as 75% with no warning

Scenario: Person at capacity

WHEN a team member has capacity of 160 hours
AND total allocations sum to 160 hours
THEN the system displays utilization as 100% with GREEN indicator

Scenario: Person over capacity

WHEN a team member has capacity of 160 hours
AND total allocations sum to 180 hours
THEN the system displays utilization as 113% with YELLOW warning "Over-allocated by 20 hours"

Scenario: Person severely over capacity

WHEN a team member has capacity of 160 hours
AND total allocations sum to 200 hours (125% or more)
THEN the system displays utilization as 125% with RED warning "Severely over-allocated by 40 hours"

Requirement: Aggregate validation across months

The system SHALL validate allocations across multiple months for multi-month projects.

Scenario: Multi-month project validation

WHEN a project has approved estimate of 120 hours
AND forecasted effort is: Feb 40h, Mar 60h, Apr 20h
AND actual allocations are: Feb 38h, Mar 62h, Apr 20h
THEN the system validates total allocations (38+62+20=120) against approved estimate (120)
AND displays overall GREEN indicator
AND displays monthly warnings where allocations deviate from forecast

Requirement: Real-time validation feedback

The system SHALL provide immediate validation feedback as allocations are created or modified.

Scenario: Immediate feedback on create

WHEN a manager creates an allocation that causes a project to exceed approved estimate
THEN the system immediately displays RED indicator on the allocation matrix
AND the system shows tooltip "This allocation causes project over-allocation"

Scenario: Immediate feedback on update

WHEN a manager increases an allocation and the team member becomes over-capacity
THEN the system immediately updates the utilization percentage
AND the system changes the team member's column header color to YELLOW or RED

4.2 KiB Raw Blame History