Headroom - Foundation

openspec/changes/headroom-foundation/specs/master-data-management/spec.md

@@ -0,0 +1,119 @@
+## ADDED 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