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

5.1 KiB

Raw Blame History

project-lifecycle Specification

Purpose

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

Requirements

Requirement: Create project

The system SHALL allow authorized users to create projects with project code, title, type, and status.

Scenario: Create new project

WHEN a manager creates a project with code "PROJ-001", title "Client Dashboard Redesign", and type "Project"
THEN the system creates the project with initial status "Initial"
AND the system assigns a unique identifier to the project

Scenario: Project code must be unique

WHEN attempting to create a project with a code that already exists
THEN the system rejects the request with validation error "Project code must be unique"

Requirement: Project status state machine

The system SHALL enforce project status transitions according to defined workflow states.

Scenario: Valid status transition

WHEN a project in "Initial" status transitions to "Gathering Estimates"
THEN the system updates the project status

Scenario: Project reaches Estimate Approved

WHEN a project transitions to "Estimate Approved" status
THEN the system requires approved estimate to be set
AND the approved estimate must be greater than 0

Scenario: Project workflow progression

WHEN a project progresses through statuses: Initial → Gathering Estimates → Estimate Pending Approval → Estimate Approved → Funded → Scheduled → In-Progress → Ready for Prod → Done
THEN the system allows each transition in sequence

Scenario: Estimate rework path

WHEN a project in "Estimate Pending Approval" status requires changes
THEN the system allows transition back to "Estimate Rework" status
AND from "Estimate Rework" the project can return to "Estimate Pending Approval"

Scenario: Project on hold

WHEN a project is placed "On-Hold" from any active status
THEN the system allows the transition
AND allocations for future months are flagged but not deleted

Scenario: Project cancelled

WHEN a project is marked as "Cancelled"
THEN the system prevents new allocations
AND existing allocations are preserved for historical tracking

Requirement: Manage approved estimate

The system SHALL track the total approved billable hours for each project.

Scenario: Set approved estimate

WHEN a project reaches "Estimate Approved" status with approved estimate of 120 hours
THEN the system stores the approved estimate
AND the approved estimate becomes the baseline for allocation validation

Scenario: Update approved estimate

WHEN a manager updates the approved estimate from 120 to 150 hours
THEN the system updates the approved estimate
AND the system re-validates all allocations against the new estimate

Requirement: Manage forecasted effort

The system SHALL track month-by-month breakdown of forecasted effort for each project.

Scenario: Set forecasted effort

WHEN a manager sets forecasted effort for a 120-hour project as: February 40h, March 60h, April 20h
THEN the system stores the forecasted effort as JSON: {"2026-02": 40, "2026-03": 60, "2026-04": 20}

Scenario: Forecasted effort must equal approved estimate

WHEN the sum of forecasted effort (40 + 60 + 20 = 120) equals the approved estimate (120)
THEN the system accepts the forecasted effort

Scenario: Forecasted effort validation fails

WHEN the sum of forecasted effort (40 + 60 + 30 = 130) exceeds the approved estimate (120) by more than 5%
THEN the system rejects the forecasted effort with validation error "Forecasted effort exceeds approved estimate"

Scenario: Under-forecasted effort

WHEN the sum of forecasted effort (40 + 50 + 10 = 100) is less than the approved estimate (120)
THEN the system displays a YELLOW warning "Under-forecasted by 20 hours"

Requirement: Distinguish project types

The system SHALL differentiate between "Project" (billable) and "Support" (ongoing ops) project types.

Scenario: Billable project

WHEN a project is created with type "Project"
THEN the system tracks it as billable work
AND it appears in revenue forecasts

Scenario: Support project

WHEN a project is created with type "Support"
THEN the system tracks it as ongoing operations
AND it appears in capacity allocation but may have different reporting treatment

Requirement: Cannot allocate to completed or cancelled projects

The system SHALL prevent new allocations to projects in "Done" or "Cancelled" status.

Scenario: Attempt to allocate to done project

WHEN attempting to create an allocation for a project with status "Done"
THEN the system rejects the allocation with error "Cannot allocate to completed projects"

Scenario: Attempt to allocate to cancelled project

WHEN attempting to create an allocation for a project with status "Cancelled"
THEN the system rejects the allocation with error "Cannot allocate to cancelled projects"

5.1 KiB Raw Blame History