Headroom - Foundation

openspec/changes/headroom-foundation/specs/role-based-access/spec.md

@@ -0,0 +1,105 @@
+## ADDED Requirements
+
+### Requirement: Enforce Superuser permissions
+The system SHALL grant Superusers full access to all functionality without restrictions.
+
+#### Scenario: Superuser creates team member
+- **WHEN** a Superuser creates a new team member
+- **THEN** the system allows the action
+
+#### Scenario: Superuser views all data
+- **WHEN** a Superuser requests any data (projects, allocations, reports)
+- **THEN** the system returns the requested data without access restrictions
+
+### Requirement: Enforce Manager permissions
+The system SHALL allow Managers to create/edit their own projects and allocate resources from their own team.
+
+#### Scenario: Manager creates project
+- **WHEN** a Manager creates a new project
+- **THEN** the system associates the project with the Manager
+- **AND** the Manager can edit the project
+
+#### Scenario: Manager views all projects (read-only for others)
+- **WHEN** a Manager requests the list of all projects
+- **THEN** the system returns all projects
+- **AND** projects owned by other Managers are marked as read-only
+
+#### Scenario: Manager allocates own team member
+- **WHEN** a Manager allocates a team member from their own team to a project
+- **THEN** the system allows the allocation
+
+#### Scenario: Manager cannot allocate other team's members
+- **WHEN** a Manager attempts to allocate a team member from another Manager's team
+- **THEN** the system rejects the request with error "Cannot allocate team members from other teams"
+
+#### Scenario: Manager approves estimates
+- **WHEN** a Manager approves an estimate for their own project
+- **THEN** the system updates the project status and sets the approved estimate
+
+### Requirement: Enforce Developer permissions
+The system SHALL allow Developers to view their own allocations and log their own hours.
+
+#### Scenario: Developer views own allocations
+- **WHEN** a Developer requests their allocations
+- **THEN** the system returns only projects where the Developer is allocated
+
+#### Scenario: Developer logs own hours
+- **WHEN** a Developer logs hours for a project they are allocated to
+- **THEN** the system accepts the hours
+
+#### Scenario: Developer cannot log hours for other team members
+- **WHEN** a Developer attempts to log hours on behalf of another team member
+- **THEN** the system rejects the request with error "Cannot log hours for other team members"
+
+#### Scenario: Developer views assigned project details
+- **WHEN** a Developer requests details for a project they are allocated to
+- **THEN** the system returns project details (title, status, their allocation)
+
+#### Scenario: Developer cannot view unassigned projects
+- **WHEN** a Developer requests details for a project they are not allocated to
+- **THEN** the system returns 403 Forbidden error
+
+#### Scenario: Developer cannot allocate resources
+- **WHEN** a Developer attempts to create or modify an allocation
+- **THEN** the system rejects the request with error "Insufficient permissions"
+
+### Requirement: Enforce Top Brass permissions
+The system SHALL allow Top Brass to view all reports but prevent any modifications.
+
+#### Scenario: Top Brass views all reports
+- **WHEN** Top Brass requests forecast, utilization, cost, allocation, or variance reports
+- **THEN** the system returns the requested report with all data
+
+#### Scenario: Top Brass cannot modify data
+- **WHEN** Top Brass attempts to create, update, or delete any entity (project, allocation, team member)
+- **THEN** the system rejects the request with error "Read-only access"
+
+#### Scenario: Top Brass views cross-team data
+- **WHEN** Top Brass views reports
+- **THEN** the system includes data from all teams without restrictions
+
+### Requirement: Role-based API endpoints
+The system SHALL protect API endpoints with role-based middleware.
+
+#### Scenario: Unauthorized access attempt
+- **WHEN** a user attempts to access an endpoint without the required role
+- **THEN** the system returns 403 Forbidden error
+- **AND** logs the unauthorized access attempt
+
+#### Scenario: Token includes role information
+- **WHEN** a user authenticates
+- **THEN** the JWT token includes the user's role
+- **AND** API middleware validates the role for each request
+
+### Requirement: Model-level authorization
+The system SHALL enforce authorization at the model level using Laravel Policies.
+
+#### Scenario: Policy check for project update
+- **WHEN** a Manager attempts to update a project
+- **THEN** the system checks the ProjectPolicy to verify ownership
+- **AND** allows the update only if the Manager owns the project or is a Superuser
+
+#### Scenario: Policy check for allocation creation
+- **WHEN** a user attempts to create an allocation
+- **THEN** the system checks the AllocationPolicy to verify the user has permission
+- **AND** for Managers, verifies the team member belongs to their team