# department-position-status Specification

## Purpose
Defines the active status of departments and positions: how a department's status cascades onto its positions, when deactivation is refused because active employees remain, how reactivation is disclosed and performed, how unavailable positions are rejected on employee assignment and reactivation, and how listings report and filter by status.

## Requirements

### Requirement: Department and Position Active Status
Every department and every position SHALL carry an active status. Creating one MAY set that status; when the creating request does not, the new record SHALL be active. Every department and position that exists when this status is introduced SHALL be active.

Creation SHALL NOT be subject to the active-employee precondition that governs deactivation, because a record that does not yet exist can hold no employees.

#### Scenario: Creating a department without specifying status
- **WHEN** an admin creates a department without specifying its status
- **THEN** that department is active

#### Scenario: Creating a position without specifying status
- **WHEN** an admin creates a position without specifying its status
- **THEN** that position is active

#### Scenario: Creating a department as inactive
- **WHEN** an admin creates a department and specifies that it is inactive
- **THEN** that department is inactive
- **AND** its positions are not available for assignment

#### Scenario: Creating a position as inactive
- **WHEN** an admin creates a position and specifies that it is inactive
- **THEN** that position is inactive
- **AND** it is not available for assignment

#### Scenario: Creating a position inside a deactivated department
- **WHEN** an admin creates a position in a department that is deactivated
- **THEN** the position is not created
- **AND** the response reports that the department must be reactivated first

#### Scenario: Existing records are active on introduction
- **WHEN** the active status is introduced for departments and positions
- **THEN** every department and position that already existed is active

### Requirement: A Position's Status Follows Its Department
A position SHALL be available for assignment exactly when its own status is active. The system SHALL maintain the invariant that no position is active while its department is inactive, by writing the department's status down onto its positions:
- deactivating a department SHALL set every position in it inactive;
- reactivating a department SHALL set every position in it active;
- a position SHALL NOT be made active while its department is inactive.

A client therefore reads a position's availability from that one status and SHALL NOT need to consult the department.

#### Scenario: Active position is available
- **WHEN** a position is active
- **THEN** the position is available for assignment

#### Scenario: Inactive position is not available
- **WHEN** a position is inactive
- **THEN** the position is not available for assignment

#### Scenario: Deactivating a department deactivates its positions
- **WHEN** a department containing two active positions is deactivated
- **THEN** both positions are inactive
- **AND** neither is available for assignment

#### Scenario: Reactivating a department reactivates its positions
- **WHEN** a department whose positions are all inactive is reactivated
- **THEN** every position in it is active
- **AND** each is available for assignment

#### Scenario: Reactivation does not distinguish why a position was inactive
- **WHEN** a department containing one position deactivated on its own and one deactivated by the department is reactivated
- **THEN** both positions are active
- **AND** the admin was told beforehand how many positions the reactivation would affect

#### Scenario: A position cannot be activated inside an inactive department
- **WHEN** an admin sets a position active while its department is inactive
- **THEN** the position is not changed
- **AND** the response reports that the department must be reactivated first

#### Scenario: Deactivating a position alone leaves its department untouched
- **WHEN** an admin deactivates a single position in an active department
- **THEN** that position is inactive
- **AND** its department and the other positions in it are unchanged

### Requirement: Disclosing the Effect of Reactivating a Department
Because reactivating a department reactivates every position in it, including positions that were deactivated on their own, the system SHALL make the size of that effect visible before the admin commits to it. Retrieving a single department SHALL report how many of its positions are currently inactive.

The count SHALL be carried by the responses that describe one department, not by payloads that list departments or that embed a department inside another record, so that listing many departments does not pay for a figure none of them uses.

#### Scenario: Retrieving one department reports how many positions reactivation would affect
- **WHEN** an admin retrieves a single department that is inactive and contains three inactive positions
- **THEN** the response reports that three positions are inactive

#### Scenario: Retrieving one department with no inactive positions
- **WHEN** an admin retrieves a single department whose positions are all active
- **THEN** the response reports that no positions are inactive

#### Scenario: Updating a department reports the count back
- **WHEN** an admin updates a department
- **THEN** the response reports how many of its positions are inactive

#### Scenario: Listing departments does not carry the count
- **WHEN** departments are listed, or a department is embedded in another record such as a position
- **THEN** the count is absent
- **AND** no per-record query is issued to produce it

### Requirement: Deactivating a Department Requires No Active Employees
The system SHALL refuse to deactivate a department while any employee with status `active` is assigned to a position in that department. Employees whose status is `quit_job` SHALL NOT prevent deactivation.

#### Scenario: Department still has active employees
- **WHEN** an admin deactivates a department in which at least one employee with status `active` holds a position
- **THEN** the department is not deactivated
- **AND** the response reports that active employees remain

#### Scenario: Department has only employees who have quit
- **WHEN** an admin deactivates a department whose only assigned employees have status `quit_job`
- **THEN** the department is deactivated
- **AND** the assignments of those employees are left unchanged

#### Scenario: Department has no employees at all
- **WHEN** an admin deactivates a department to which no employee is assigned
- **THEN** the department is deactivated

#### Scenario: Refusal names the blocking employees
- **WHEN** deactivation of a department is refused because active employees remain
- **THEN** the response identifies the employees that are blocking it

### Requirement: Deactivating a Position Requires No Active Employees
The system SHALL refuse to deactivate a position while any employee with status `active` holds that position. Employees whose status is `quit_job` SHALL NOT prevent deactivation.

#### Scenario: Position still has active employees
- **WHEN** an admin deactivates a position held by at least one employee with status `active`
- **THEN** the position is not deactivated
- **AND** the response reports that active employees remain

#### Scenario: Position has only employees who have quit
- **WHEN** an admin deactivates a position whose only holders have status `quit_job`
- **THEN** the position is deactivated
- **AND** the assignments of those employees are left unchanged

### Requirement: Reactivating a Department or Position
An admin SHALL be able to reactivate a deactivated department. Reactivating a department SHALL reactivate every position in it. A position SHALL only be reactivated on its own while its department is active.

#### Scenario: Reactivating a department
- **WHEN** an admin reactivates a deactivated department
- **THEN** the department is active
- **AND** every position in it is active and available for assignment

#### Scenario: Reactivating a position inside a deactivated department
- **WHEN** an admin reactivates a position whose department is still deactivated
- **THEN** the position is not changed
- **AND** the response reports that the department must be reactivated first

### Requirement: Position Assignment Rejects Unavailable Positions
Every operation that assigns a position to an employee SHALL reject a position that is not available for assignment. This SHALL hold for creating an employee, updating an employee, changing an employee's company, and importing employees. Returning an employee to active status is also gated, by the Reactivating an Employee Requires an Available Position requirement.

When an operation only edits an employee who already holds a position, the position the employee already holds SHALL NOT be rejected, so that an employee in a retired unit can still be corrected. This exemption SHALL NOT apply when the employee is being returned to active status.

#### Scenario: Creating an employee in a deactivated position
- **WHEN** an admin creates an employee with a position that is deactivated
- **THEN** the employee is not created
- **AND** the response reports the position as unavailable

#### Scenario: Creating an employee in a position of a deactivated department
- **WHEN** an admin creates an employee with an active position whose department is deactivated
- **THEN** the employee is not created
- **AND** the response reports the position as unavailable

#### Scenario: Moving an existing employee into an unavailable position
- **WHEN** an admin updates an employee to a position that is not available for assignment
- **THEN** the employee's assignment is not changed
- **AND** the response reports the position as unavailable

#### Scenario: Changing an employee's company into an unavailable position
- **WHEN** an admin changes an employee's company to a position that is not available for assignment
- **THEN** the employee's assignment is not changed
- **AND** the response reports the position as unavailable

#### Scenario: Employee already in a position that is later deactivated
- **WHEN** a position holding an employee becomes unavailable
- **THEN** that employee's existing assignment is unchanged
- **AND** the employee is still reported under that position

### Requirement: Reactivating an Employee Requires an Available Position
Returning an employee from status `quit_job` to status `active` SHALL be refused when the position that employee would hold is not available for assignment, and the refusal SHALL state that a different position must be chosen. The position the employee already holds SHALL NOT be exempted from this check. This SHALL hold whether the status is changed through the employee update operation or through the dedicated status-change operation.

Editing an employee who remains in status `quit_job` SHALL NOT be refused on these grounds.

#### Scenario: Reactivating into a deactivated position
- **WHEN** an admin changes an employee from status `quit_job` to status `active` and that employee holds a position that is deactivated
- **THEN** the employee's status is not changed
- **AND** the response reports that the position is unavailable and that a different position must be chosen

#### Scenario: Reactivating into a position of a deactivated department
- **WHEN** an admin changes an employee from status `quit_job` to status `active` and that employee holds an active position whose department is deactivated
- **THEN** the employee's status is not changed
- **AND** the response reports that the position is unavailable and that a different position must be chosen

#### Scenario: Reactivating while supplying an available position
- **WHEN** an admin changes an employee from status `quit_job` to status `active` in the same request that assigns an available position
- **THEN** the employee's status is `active`
- **AND** the employee holds the supplied position

#### Scenario: Resubmitting the same unavailable position does not bypass the check
- **WHEN** an admin changes an employee from status `quit_job` to status `active` in a request that supplies the unavailable position the employee already holds
- **THEN** the employee's status is not changed
- **AND** the response reports that the position is unavailable

#### Scenario: Dedicated status-change operation refuses reactivation
- **WHEN** an admin uses the dedicated status-change operation to return an employee to status `active` and that employee's position is not available for assignment
- **THEN** the employee's status is not changed
- **AND** the response reports that the position is unavailable and that a different position must be chosen

#### Scenario: Reactivating into an available position succeeds
- **WHEN** an admin returns an employee to status `active` and that employee's position is available for assignment
- **THEN** the employee's status is `active`
- **AND** the employee's position is unchanged

#### Scenario: Editing an employee who stays quit is not blocked
- **WHEN** an admin edits an employee whose status remains `quit_job` and whose position is not available for assignment
- **THEN** the edit is accepted
- **AND** the employee's position is unchanged

#### Scenario: Marking an active employee as quit is not blocked
- **WHEN** an admin changes an employee from status `active` to status `quit_job`
- **THEN** the change is accepted regardless of whether the employee's position is available

### Requirement: Leader Cleanup Uses the Target Position's Company
When deciding whether moving an employee to a new position crosses a company boundary, the system SHALL compare the employee's current company against the company that owns the target position.

#### Scenario: Move within the same company keeps leaders
- **WHEN** an employee is moved to a position whose owning company is the employee's current company
- **THEN** the employee's leader is unchanged
- **AND** the leader references of employees reporting to them are unchanged

#### Scenario: Move to another company clears leaders
- **WHEN** an employee is moved to a position whose owning company differs from the employee's current company
- **THEN** the employee has no leader
- **AND** every employee who reported to them has no leader

#### Scenario: Position identifier is not treated as a company identifier
- **WHEN** an employee whose current company has a given identifier is moved to a position whose own identifier equals that company identifier, and the position belongs to a different company
- **THEN** the move is treated as crossing a company boundary
- **AND** the employee has no leader
- **AND** every employee who reported to them has no leader

### Requirement: Listing Departments and Positions by Status
Endpoints that list departments or positions for administration SHALL report each record's status and SHALL support filtering by it, returning both active and inactive records when no filter is given. Endpoints that offer departments or positions for assignment SHALL return only records that are available for assignment, unless the caller explicitly asks for inactive records to be included.

Asking for inactive records SHALL be opt-in, so that a caller which says nothing keeps receiving only assignable records. It exists for callers that search or filter over historical data, where a department or position someone used to belong to must still be selectable.

When inactive records are included, they SHALL be ordered below the available ones rather than interleaved with them, and the caller's requested sort SHALL apply within each group. A caller picking from the list therefore meets the records it can still use first.

#### Scenario: Admin list includes inactive records
- **WHEN** an admin lists departments without a status filter
- **THEN** the response includes both active and deactivated departments
- **AND** each department reports its status

#### Scenario: Admin filters to inactive records
- **WHEN** an admin lists positions filtered to inactive
- **THEN** the response contains only positions that are not available for assignment

#### Scenario: Assignment list excludes unavailable positions
- **WHEN** a list of positions is requested for assigning an employee
- **THEN** the response contains only positions that are available for assignment

#### Scenario: Assignment list excludes positions of a deactivated department
- **WHEN** a list of positions is requested for assigning an employee and a department is deactivated
- **THEN** no position of that department appears in the response

#### Scenario: Caller opts in to inactive departments
- **WHEN** a caller requests the department selection list and asks for inactive records to be included
- **THEN** the response contains both active and inactive departments
- **AND** each department reports its status

#### Scenario: Caller opts in to inactive positions
- **WHEN** a caller requests the position selection list and asks for inactive records to be included
- **THEN** the response contains both active and inactive positions
- **AND** each position reports its status

#### Scenario: Opting in is off by default
- **WHEN** a caller requests either selection list without asking for inactive records
- **THEN** the response contains only records that are available for assignment

#### Scenario: Inactive records are listed below available ones
- **WHEN** a caller requests a selection list sorted by name ascending and asks for inactive records to be included
- **THEN** every available record appears before every inactive one
- **AND** the records within each group are ordered by name ascending
