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
114 lines
5.5 KiB
Markdown
114 lines
5.5 KiB
Markdown
# capacity-planning Specification
|
||
|
||
## Purpose
|
||
TBD - created by archiving change headroom-foundation. Update Purpose after archive.
|
||
## Requirements
|
||
### Requirement: Calculate individual capacity
|
||
The system SHALL calculate individual team member capacity for a given month based on availability, holidays, PTO, and weekends.
|
||
|
||
#### Scenario: Calculate capacity for full month
|
||
- **WHEN** calculating capacity for a team member with full availability (1.0) for all working days in February 2026
|
||
- **AND** February has 20 working days (28 days - 8 weekend days)
|
||
- **AND** the team member has no PTO or holidays
|
||
- **THEN** the system calculates individual capacity as 20 person-days
|
||
|
||
#### Scenario: Calculate capacity with half-day availability
|
||
- **WHEN** a team member has availability of 0.5 for 10 working days in a month
|
||
- **THEN** the system calculates capacity as 5 person-days (10 days × 0.5)
|
||
|
||
#### Scenario: Calculate capacity with PTO
|
||
- **WHEN** a team member has PTO for 3 working days in a month
|
||
- **AND** the month has 22 working days
|
||
- **AND** the team member has full availability (1.0) for all other days
|
||
- **THEN** the system calculates capacity as 19 person-days (22 - 3 days PTO)
|
||
|
||
#### Scenario: Calculate capacity with holidays
|
||
- **WHEN** a month has 2 company holidays
|
||
- **AND** a team member has 22 working days after removing weekends
|
||
- **AND** the team member has full availability (1.0)
|
||
- **THEN** the system calculates capacity as 20 person-days (22 - 2 holidays)
|
||
|
||
#### Scenario: Calculate capacity with mixed availability
|
||
- **WHEN** a team member has 10 days at 1.0 availability, 5 days at 0.5 availability, and 3 days at 0 availability in a month
|
||
- **THEN** the system calculates capacity as 12.5 person-days (10×1.0 + 5×0.5 + 3×0)
|
||
|
||
### Requirement: Calculate team capacity
|
||
The system SHALL calculate total team capacity by summing individual capacities for all active team members.
|
||
|
||
#### Scenario: Calculate team capacity for month
|
||
- **WHEN** Team Member A has 20 person-days capacity
|
||
- **AND** Team Member B has 18 person-days capacity
|
||
- **AND** Team Member C has 15 person-days capacity
|
||
- **THEN** the system calculates team capacity as 53 person-days
|
||
|
||
#### Scenario: Exclude inactive team members from team capacity
|
||
- **WHEN** calculating team capacity
|
||
- **AND** one team member has active status set to false
|
||
- **THEN** the system excludes the inactive team member from the team capacity calculation
|
||
|
||
### Requirement: Calculate possible revenue
|
||
The system SHALL calculate possible revenue based on team capacity and hourly rates.
|
||
|
||
#### Scenario: Calculate possible revenue for team
|
||
- **WHEN** Team Member A has 160 hours capacity at $150/hour
|
||
- **AND** Team Member B has 144 hours capacity at $125/hour
|
||
- **AND** Team Member C has 120 hours capacity at $175/hour
|
||
- **THEN** the system calculates possible revenue as $63,000 (160×$150 + 144×$125 + 120×$175)
|
||
|
||
### Requirement: Track availability per day
|
||
The system SHALL allow setting daily availability as 0 (unavailable), 0.5 (half day), or 1.0 (full day).
|
||
|
||
#### Scenario: Set full day availability
|
||
- **WHEN** setting availability for a specific date to 1.0
|
||
- **THEN** the system records the team member as fully available for that day
|
||
|
||
#### Scenario: Set half day availability
|
||
- **WHEN** setting availability for a specific date to 0.5
|
||
- **THEN** the system records the team member as half-day available for that day
|
||
|
||
#### Scenario: Set unavailable
|
||
- **WHEN** setting availability for a specific date to 0
|
||
- **THEN** the system records the team member as unavailable for that day
|
||
|
||
#### Scenario: Reject invalid availability values
|
||
- **WHEN** attempting to set availability to a value other than 0, 0.5, or 1.0
|
||
- **THEN** the system rejects the input with validation error "Availability must be 0, 0.5, or 1.0"
|
||
|
||
### Requirement: Manage holidays
|
||
The system SHALL allow defining company-wide holidays that reduce available working days for all team members.
|
||
|
||
#### Scenario: Add company holiday
|
||
- **WHEN** an admin defines December 25, 2026 as a company holiday "Christmas Day"
|
||
- **THEN** the system marks that date as a non-working day for all team members
|
||
|
||
#### Scenario: Holidays affect capacity calculation
|
||
- **WHEN** calculating capacity for a month with 2 company holidays
|
||
- **THEN** the system automatically excludes those days from all team members' capacity calculations
|
||
|
||
### Requirement: Manage PTO requests
|
||
The system SHALL allow team members to request PTO which reduces their individual capacity.
|
||
|
||
#### Scenario: Submit PTO request
|
||
- **WHEN** a team member submits PTO for February 10-12, 2026
|
||
- **THEN** the system creates a PTO record with start date, end date, and status "approved"
|
||
|
||
#### Scenario: Approve PTO request
|
||
- **WHEN** a manager approves a PTO request
|
||
- **THEN** the system updates the PTO status to "approved"
|
||
- **AND** the system automatically reduces the team member's capacity for those dates to 0
|
||
|
||
#### Scenario: Delete PTO request
|
||
- **WHEN** a manager deletes an existing PTO request
|
||
- **THEN** the PTO record is removed
|
||
- **AND** individual, team, and revenue capacity caches for affected months are refreshed
|
||
|
||
#### Scenario: PTO affects capacity calculation
|
||
- **WHEN** calculating capacity for a team member with approved PTO for 3 days
|
||
- **THEN** the system excludes those 3 days from the capacity calculation
|
||
|
||
#### Scenario: Override PTO day availability
|
||
- **WHEN** a PTO day is manually set to half day availability (0.5)
|
||
- **THEN** the system keeps the PTO marker for that date
|
||
- **AND** the capacity calculation uses the explicit availability override instead of forcing 0
|
||
|