Santhosh Janardhanan
f87ccccc4d
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
105 lines
5.1 KiB
Markdown
105 lines
5.1 KiB
Markdown
# 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"
|
|
|