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
86 lines
4.0 KiB
Markdown
86 lines
4.0 KiB
Markdown
# actuals-tracking Specification
|
||
|
||
## Purpose
|
||
Enable team members to track actual hours worked per project per month for comparison against allocations.
|
||
## Requirements
|
||
### Requirement: Log hours worked
|
||
The system SHALL allow team members to log actual hours worked per project per month.
|
||
|
||
#### Scenario: Log hours for current month
|
||
- **WHEN** a team member logs 35 hours worked on "Project X" for February 2026
|
||
- **THEN** the system creates an actuals record
|
||
- **AND** the system associates the hours with the team member, project, and month
|
||
|
||
#### Scenario: Cannot log negative hours
|
||
- **WHEN** attempting to log -5 hours
|
||
- **THEN** the system rejects the request with validation error "Hours logged must be greater than or equal to 0"
|
||
|
||
#### Scenario: Cannot log hours for future months
|
||
- **WHEN** attempting to log hours for a month that hasn't started yet
|
||
- **THEN** the system rejects the request with validation error "Cannot log hours for future months"
|
||
|
||
### Requirement: Update logged hours (incremental)
|
||
The system SHALL allow team members to update previously logged hours using incremental updates.
|
||
|
||
#### Scenario: Incremental weekly updates
|
||
- **WHEN** a team member logs 10 hours in week 1 of February
|
||
- **AND** logs an additional 8 hours in week 2 of February
|
||
- **AND** the system updates the total to 18 hours for February
|
||
- **THEN** the system accumulates the hours for the monthly aggregate
|
||
- **AND** the system preserves all notes from each update
|
||
|
||
### Requirement: View actuals summary with variance
|
||
The system SHALL display actual hours worked in a matrix view showing allocated, actual, and variance data.
|
||
|
||
#### Scenario: View monthly actuals matrix
|
||
- **WHEN** a manager views actuals for February 2026
|
||
- **THEN** the system displays projects as rows and team members as columns
|
||
- **AND** each cell shows:
|
||
- **Allocated hours** (from allocation records)
|
||
- **Actual hours** (from actuals records)
|
||
- **Variance %** = ((Actual - Allocated) / Allocated) × 100
|
||
- **Variance indicator**: GREEN (≤5%), YELLOW (5-20%), RED (>20%)
|
||
|
||
#### Scenario: Show variance indicators
|
||
- **WHEN** viewing the actuals matrix
|
||
- **THEN** cells are color-coded based on variance:
|
||
- GREEN: Within ±5% of allocation (on track)
|
||
- YELLOW: 5-20% variance (attention needed)
|
||
- RED: >20% variance (significant deviation)
|
||
|
||
### Requirement: Cannot log hours to inactive projects
|
||
The system SHALL prevent logging hours to projects in "Done" or "Cancelled" status (configurable via global setting).
|
||
|
||
#### Scenario: Attempt to log hours to done project
|
||
- **WHEN** attempting to log hours for a project with status "Done"
|
||
- **AND** the global system configuration `allow_actuals_on_inactive_projects` is false
|
||
- **THEN** the system rejects the request with error "Cannot log hours to completed projects"
|
||
|
||
#### Scenario: Allow logging to done project if configured
|
||
- **WHEN** the global configuration `allow_actuals_on_inactive_projects` is true
|
||
- **AND** a team member logs hours to a "Done" project
|
||
- **THEN** the system accepts the hours (for edge cases where work continues after project closure)
|
||
|
||
### Requirement: Actuals data entry is manual
|
||
The system SHALL support manual entry of actual hours without integration to time-tracking tools (MVP).
|
||
|
||
#### Scenario: Manual monthly entry
|
||
- **WHEN** a team member enters actual hours worked via the web interface
|
||
- **THEN** the system accepts the input without requiring integration with external time-tracking systems
|
||
|
||
#### Scenario: No automated time import
|
||
- **WHEN** viewing actuals entry interface
|
||
- **THEN** the system does not provide options to import from Jira, Harvest, Toggl, or other time-tracking tools (deferred to Phase 2)
|
||
|
||
### Requirement: Track actuals notes
|
||
The system SHALL allow optional notes when logging hours.
|
||
|
||
#### Scenario: Log hours with notes
|
||
- **WHEN** a team member logs 40 hours with notes "Focused on API development and bug fixes"
|
||
- **THEN** the system stores the notes alongside the hours logged
|
||
|
||
#### Scenario: View notes in matrix
|
||
- **WHEN** viewing the actuals matrix
|
||
- **THEN** clicking on a cell shows the history of logged hours with timestamps and notes
|
||
|