# 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

