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
124 lines
4.1 KiB
Markdown
124 lines
4.1 KiB
Markdown
# master-data-management Specification
|
|
|
|
## Purpose
|
|
TBD - created by archiving change headroom-foundation. Update Purpose after archive.
|
|
## Requirements
|
|
### Requirement: Manage roles
|
|
The system SHALL allow Superusers to configure team member roles.
|
|
|
|
#### Scenario: Create new role
|
|
- **WHEN** a Superuser creates a role "DevOps Engineer"
|
|
- **THEN** the system stores the role
|
|
- **AND** the role becomes available for team member assignment
|
|
|
|
#### Scenario: Update role
|
|
- **WHEN** a Superuser updates a role description
|
|
- **THEN** the system updates the role
|
|
- **AND** existing team members with that role are not affected
|
|
|
|
#### Scenario: Cannot delete role in use
|
|
- **WHEN** a Superuser attempts to delete a role that is assigned to team members
|
|
- **THEN** the system rejects the deletion with error "Cannot delete role in use by team members"
|
|
|
|
#### Scenario: View roles list
|
|
- **WHEN** a user requests the list of roles
|
|
- **THEN** the system returns all configured roles
|
|
|
|
### Requirement: Manage project statuses
|
|
The system SHALL allow Superusers to configure project status options.
|
|
|
|
#### Scenario: Create custom status
|
|
- **WHEN** a Superuser creates a new status "Client Review"
|
|
- **AND** sets the order as 5 (between "Estimate Approved" and "Funded")
|
|
- **THEN** the system adds the status to the workflow
|
|
|
|
#### Scenario: Set status as billable or non-billable
|
|
- **WHEN** configuring a status
|
|
- **THEN** the Superuser can mark it as billable (TRUE) or non-billable (FALSE)
|
|
- **AND** non-billable statuses may exclude projects from revenue forecasts
|
|
|
|
#### Scenario: Reorder statuses
|
|
- **WHEN** a Superuser changes the order of statuses
|
|
- **THEN** the system updates the status sequence
|
|
- **AND** project workflow reflects the new order
|
|
|
|
### Requirement: Manage project types
|
|
The system SHALL allow Superusers to configure project types.
|
|
|
|
#### Scenario: Default project types
|
|
- **WHEN** the system is initialized
|
|
- **THEN** it includes default types: "Project" (billable) and "Support" (ongoing ops)
|
|
|
|
#### Scenario: Create custom project type
|
|
- **WHEN** a Superuser creates a new type "Internal Initiative"
|
|
- **THEN** the system stores the type
|
|
- **AND** the type becomes available when creating projects
|
|
|
|
### Requirement: Manage availability options
|
|
The system SHALL enforce availability values as 0, 0.5, or 1.0.
|
|
|
|
#### Scenario: Availability options are fixed
|
|
- **WHEN** setting team member availability
|
|
- **THEN** the system restricts values to 0, 0.5, or 1.0
|
|
- **AND** rejects any other value
|
|
|
|
#### Scenario: Availability options are documented
|
|
- **WHEN** a user views the availability field
|
|
- **THEN** the system displays help text:
|
|
- "0 = Unavailable (PTO, holiday)"
|
|
- "0.5 = Half day"
|
|
- "1.0 = Full day"
|
|
|
|
### Requirement: Seed master data
|
|
The system SHALL provide initial master data on installation.
|
|
|
|
#### Scenario: Seed roles
|
|
- **WHEN** the system is installed
|
|
- **THEN** it creates default roles:
|
|
- Frontend Developer
|
|
- Backend Developer
|
|
- QA Engineer
|
|
- DevOps Engineer
|
|
- UX Designer
|
|
- Project Manager
|
|
- Architect
|
|
|
|
#### Scenario: Seed project statuses
|
|
- **WHEN** the system is installed
|
|
- **THEN** it creates default statuses with correct order:
|
|
1. NA/Support
|
|
2. Initial
|
|
3. Gathering Estimates
|
|
4. Estimate Pending Approval
|
|
5. Estimate Rework
|
|
6. Estimate Approved
|
|
7. Funded
|
|
8. Scheduled
|
|
9. In-Progress
|
|
10. Ready for Prod
|
|
11. Done
|
|
12. On-Hold
|
|
13. Cancelled
|
|
|
|
#### Scenario: Seed project types
|
|
- **WHEN** the system is installed
|
|
- **THEN** it creates default types:
|
|
- Project (billable)
|
|
- Support (ongoing ops)
|
|
|
|
### Requirement: Master data API endpoints
|
|
The system SHALL provide read-only API endpoints for master data.
|
|
|
|
#### Scenario: Get roles
|
|
- **WHEN** any authenticated user requests GET /api/master-data/roles
|
|
- **THEN** the system returns the list of all roles
|
|
|
|
#### Scenario: Get project statuses
|
|
- **WHEN** any authenticated user requests GET /api/master-data/statuses
|
|
- **THEN** the system returns the list of all project statuses in order
|
|
|
|
#### Scenario: Get project types
|
|
- **WHEN** any authenticated user requests GET /api/master-data/types
|
|
- **THEN** the system returns the list of all project types
|
|
|