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
3.8 KiB
3.8 KiB
cost-reporting Specification
Purpose
TBD - created by archiving change headroom-foundation. Update Purpose after archive.
Requirements
Requirement: Generate cost summary report
The system SHALL generate reports showing revenue forecasts based on allocations multiplied by hourly rates.
Scenario: View monthly cost report
- WHEN viewing cost report for February 2026
- THEN the system displays all projects with their allocated hours
- AND calculates revenue for each project based on team member hourly rates
- AND shows total revenue forecast for the month
Scenario: Cost breakdown by project
- WHEN viewing cost report for a specific project
- THEN the system displays allocation breakdown by team member
- AND shows hours allocated and hourly rate for each team member
- AND calculates total project cost as sum of (hours × rate) for all team members
Requirement: Filter cost report by project
The system SHALL allow filtering cost reports by project, client, or type.
Scenario: Filter by project type
- WHEN filtering cost report to show only "Project" type (billable)
- THEN the system displays revenue forecast for billable projects only
- AND excludes "Support" type projects
Scenario: Group by client
- WHEN grouping cost report by client
- THEN the system displays total revenue forecast per client
- AND shows breakdown of projects per client
Requirement: Filter cost report by team
The system SHALL allow filtering cost reports by team or team member.
Scenario: Cost report for team member
- WHEN filtering cost report to show allocations for "John Doe"
- THEN the system displays all projects where John Doe is allocated
- AND calculates John's contribution to revenue (his hours × his rate)
Scenario: Cost report for role
- WHEN filtering by "Backend Developer" role
- THEN the system displays revenue generated by all Backend Developers
- AND shows average hourly rate for the role
Requirement: Calculate total possible revenue
The system SHALL calculate maximum possible revenue if all team capacity were utilized at 100%.
Scenario: Possible revenue calculation
- WHEN viewing cost summary
- THEN the system calculates total team capacity (all team members' available hours)
- AND multiplies by each team member's hourly rate
- AND displays "Possible Revenue: $X if fully utilized"
Requirement: Calculate forecasted revenue
The system SHALL calculate forecasted revenue based on current allocations.
Scenario: Forecasted revenue based on allocations
- WHEN team has 1000 hours total capacity
- AND currently 850 hours are allocated across projects
- AND the weighted average hourly rate is $140
- THEN the system calculates forecasted revenue as $119,000 (850 × $140)
Requirement: Show revenue variance
The system SHALL display variance between possible revenue and forecasted revenue.
Scenario: Revenue gap analysis
- WHEN possible revenue is $150,000
- AND forecasted revenue is $119,000
- THEN the system displays revenue gap of $31,000 (20.7% underutilization)
Requirement: Multi-period cost forecast
The system SHALL generate cost forecasts across multiple months.
Scenario: Quarter revenue forecast
- WHEN viewing cost report for Q1 2026 (Jan-Mar)
- THEN the system displays monthly revenue forecast for each month
- AND calculates total Q1 revenue forecast
- AND shows monthly variance from possible revenue
Requirement: Export cost data
The system SHALL allow exporting cost report data (deferred to Phase 2 for PDF/CSV).
Scenario: View cost data on screen (MVP)
- WHEN viewing cost report
- THEN the system displays all cost data on screen in tabular format
- AND PDF/CSV export buttons are not available (Phase 2 feature)