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

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