## 1. Preconditions

- [x] 1.1 Note the agreed premise: every account holds exactly one position. The deactivation guard's count of active employees relies on it — see Decision 4 in design.md.

## 2. Schema

- [x] 2.1 Add migration: `departments.is_active` as `tinyInteger` default `1`, following the `contract_types` precedent in `2025_04_24_133818_add_company_id_and_is_active_to_contract_types_table.php`.
- [x] 2.2 Add migration: `positions.is_active` as `tinyInteger` default `1`.
- [x] 2.3 Add `is_active` to `$fillable` on `app/Models/Department.php` and `app/Models/Position.php`, and expose it on the admin relation data so listings report status.

## 3. Cascading availability

Reverses the original derived design — see Decision 1 in design.md. The scope indirection from 3.1 stays, so the four call sites are untouched.

- [x] 3.1 Add a scope on `app/Models/Position.php` that selects only positions available for assignment. This scope is the single place the rule lives — see Decision 2 in design.md.
- [x] 3.2 Add the matching scope on `app/Models/Department.php` for active departments.
- [x] 3.3 Add a method that answers availability for a single already-loaded position, for use by validation and by single-record checks.
- [x] 3.4 Reduce `Position::scopeAvailable()` to a test of `positions.is_active` alone, dropping the join to `department`. Leave its callers unchanged.
- [x] 3.5 Reduce `Position::scopeFilterByStatus()` the same way, so filtering by inactive no longer has to consider the department.
- [x] 3.6 On deactivating a department, set every position in it inactive, inside the same transaction as the department's own write.
- [x] 3.7 On reactivating a department, set every position in it active, in the same transaction.
- [x] 3.8 Refuse activating a position whose department is inactive, with a distinct `status_code` telling the admin to reactivate the department first.
- [x] 3.9 Refuse creating a position in an inactive department, with the same `status_code`.
- [x] 3.10 Expose an inactive-position count on the responses that describe one department — `show` and `update` — so the admin can see what reactivating would switch back on, without listing payloads paying a `COUNT` per record. See Decision 1b.
- [x] 3.11 Backfill: set `is_active = 0` on every position whose department is already inactive, so existing data satisfies the invariant. No such rows exist yet if no department has been deactivated; the migration must still be safe to run.

## 4. Assignment validation

- [x] 4.1 Add a rule class under `app/Rules/` that fails when a position id is not available for assignment, alongside the existing `OnCompany` rule.
- [x] 4.2 Apply the rule in `EmployeeController@store`.
- [x] 4.3 Apply the rule in `EmployeeController@update`.
- [x] 4.4 Apply the rule in `EmployeeController@changeCompany`.
- [x] 4.5 Apply the rule in `Account::createOrUpdate` (`app/Models/Account.php`), which resolves a position by name.
- [x] 4.6 Add the error message for an unavailable position to the language files used by these endpoints.
- [x] 4.7 Verify an employee already holding a position that later becomes unavailable is not affected on unrelated updates.

## 4b. Employee reactivation gate

- [x] 4b.1 In `EmployeeController@update`, detect a transition from status `quit_job` to `active` and check the position the employee will hold, independently of whether the request carries `positions`.
- [x] 4b.2 Run that check without the "already holds it" exemption, so resubmitting the same unavailable position is still refused — see Decision 9 in design.md.
- [x] 4b.3 Apply the same gate in `EmployeeController@updateStatus` (`PUT /admin/employees/{id}/update-status`), which today validates only `status`. Refuse without extending that endpoint to accept `positions`.
- [x] 4b.4 Make the refusal message ask for a different position, so the admin knows the remedy is the employee update operation with `positions`.
- [x] 4b.5 Confirm editing an employee who stays `quit_job` is still not blocked, and that marking an `active` employee as `quit_job` is never blocked.

## 5. Status through the update form

The guard is unchanged; only where it runs moves. The dedicated endpoints shipped first and are being folded into the normal update, so the front end can save information and status in one request and cannot leave status changed while the rest of the form failed to save.

- [x] 5.1 Implement the active-employee guard for a department, refusing while any employee with status `active` holds a position in it, counting only `Employee::$activeStatus`.
- [x] 5.2 Make the refusal response identify the blocking employees so the admin knows who to reassign.
- [x] 5.3 Implement the same guard for a position.
- [x] 5.4 Extract the guard into one place used by both departments and positions, so the deactivation rule has a single implementation.
- [x] 5.5 Accept `'is_active' => 'sometimes|in:0,1'` in `DepartmentController@update` and `PositionController@update`.
- [x] 5.5a Accept `'is_active' => 'sometimes|in:0,1'` in `DepartmentController@store` and `PositionController@store` as well, so a unit can be created already retired. No guard is needed there: a record being created holds no employees.
- [x] 5.6 Run the extracted guard in both update actions before `$model->update($data)`, only when the request would turn an active record inactive, and return the same `status_code` and `employees[]` payload the dedicated endpoints returned.
- [x] 5.7 Leave reactivation ungated: turning `is_active` back on through the update form has no employee precondition.
- [x] 5.8 Remove `DepartmentController@deactivate`, `DepartmentController@reactivate`, `PositionController@deactivate` and `PositionController@reactivate`, and drop their routes from `routes/v1/api_admin.php`, together with the `@OA` annotations documenting them.
- [x] 5.9 Confirm the update actions still enforce `departments_update` / `positions_update` so dropping the dedicated routes loses no authorisation.

## 6. Remove bulk transfer

Built, then withdrawn at the product's request — the front end does not call it. See Decision 5 in design.md.

- [x] 6.1 Remove `DepartmentController@transfer` and `PositionController@transfer`.
- [x] 6.2 Drop `POST /{id}/transfer` for both prefixes from `routes/v1/api_admin.php`.
- [x] 6.3 Remove the `@OA` annotations documenting those routes. No change was needed: the transfer actions never carried `@OA` blocks.
- [x] 6.4 Remove language entries added only for transfer responses, leaving the deactivation refusal messages intact.
- [x] 6.5 Delete `app/Classes/Helpers/EmployeeTransfer.php`, whose only callers are the two transfer actions.
- [x] 6.5a Keep `app/Classes/Helpers/DeactivationGuard.php` and the `activeEmployees()` relation on `Department` and `Position`. The guard reads that relation and the update actions call the guard, so neither belongs to transfer even though the transfer actions also passed `activeEmployees()` in.
- [x] 6.6 Confirm the API documentation no longer advertises the transfer routes. Verified by inspection rather than by regenerating: `storage/api-docs/api-docs.json`, `routes/v1/api_admin.php` and `php artisan route:list` all have no `transfer` entry. `l5-swagger:generate` cannot run — `CashPayrollController` declares eight `@OA` paths copied from `PayrollController` without the `/cash` prefix, so swagger-php cannot merge the duplicates and reports it against `PayrollController:76`. Pre-existing and tracked separately; note that the generator deletes `storage/api-docs/api-docs.json` before failing. The committed docs therefore stay stale for `include_inactive` and the new `is_active` request fields.

## 7. Leader cleanup defect

- [x] 7.1 In `EmployeeController@changeCompany` (around line 2904), replace `Company::find($positionIds[0])` with the company that actually owns the target position, via the existing `Position::getCompany()`. See Decision 8 in design.md for how the defect behaves.
- [x] 7.2 Confirm a same-company move no longer clears leaders unnecessarily, and that a cross-company move still clears them in both directions.

## 8. Excel import

- [x] 8.1 Restrict position resolution in `EmployeeController@import` to available positions, so a retired duplicate stops competing for a name.
- [x] 8.2 Report `position_unavailable` when exclusion is what emptied the candidate set — the name would have matched, but every match was unavailable — instead of `position_not_found`.
- [x] 8.3 Add the `position_unavailable` reason text to the import error language entries, so it renders in the error file produced by `employee-import-error-file`.
- [x] 8.4 Verify a row with an unavailable position collects that reason alongside any other failures on the same row.

## 9. Listings

- [x] 9.1 Report `is_active` on the admin department and position list and detail responses.
- [x] 9.2 Add a status filter to the admin department and position lists, returning both active and inactive when no filter is given.
- [x] 9.3 Restrict the department and position endpoints used for assignment selection to available records only, using the scopes from 3.1 and 3.2.
- [x] 9.4 Leave report and employee-search filters able to select inactive departments and positions, so historical records stay queryable.
- [x] 9.5 Accept an opt-in `include_inactive` parameter on `DepartmentController@getList` and `PositionController@getList`, the admin-public selection lists, so historical filters can still offer retired records. Default stays available-only.
- [x] 9.5a When inactive records are included, order them below the available ones and apply the caller's sort within each group, so a picker meets usable records first.
- [x] 9.6 Document the parameter in the `@OA` annotations of both endpoints.

## 10. Verification

- [x] 10.1 Deactivate a department with no employees; confirm every position in it becomes inactive and disappears from assignment lists. Verified over HTTP: both positions went inactive and no longer appeared in the selection list.
- [x] 10.1a Create a department with `is_active` of 0 and confirm it is created inactive; create one without the field and confirm it is active. Verified: 0 and 1 respectively.
- [x] 10.2 Reactivate that department; confirm every position in it is active again, and that the department reported the inactive-position count beforehand. Verified: the count read 2 before reactivating and 0 after, and both positions came back active — including the one deactivated on its own.
- [x] 10.2a Confirm a position cannot be activated while its department is inactive, and cannot be created there either. Verified over HTTP: both refuse with 400 `department_inactive`.
- [x] 10.2b Confirm deactivating a single position does not touch its department or the other positions. Verified: the department stayed active and the sibling position was untouched.
- [x] 10.2c Confirm the position payload alone answers availability — no client needs the department's status to decide. Verified: `/admin/public/positions?include_inactive=1` returns each position's own `is_active`, with the inactive ones ordered below the active ones.
- [x] 10.3 Attempt to deactivate a department holding an active employee; confirm refusal and that the blocking employee is named. Verified: 400 `department_has_active_employee` with a one-entry `employees` array.
- [x] 10.3a Reassign that employee through `PUT /admin/employees/{id}`, then deactivate the department; confirm it succeeds. Verified: the same deactivation that had been refused went through once the employee had moved.
- [x] 10.3b Confirm `POST /admin/departments/{id}/transfer` and `POST /admin/positions/{id}/transfer` no longer exist, and that neither appears in the generated API documentation. Verified: both 404, and no `transfer` in api-docs.json.
- [x] 10.7 Import a file whose row names a deactivated position; confirm reason code `position_unavailable` and that other rows still import. Verified: the row reported `position_unavailable`, the other two rows imported.
- [x] 10.8 Import a file whose row names a position duplicated across an active and a deactivated department; confirm it resolves to the active one. Verified: with "Phòng ban" blank it resolved to the active department and was not reported as `position_ambiguous`.
- [x] 10.9 Confirm employees already assigned to a deactivated position still appear in employee lists, reports and their existing payroll and contract records. Verified against an employee holding a contract: still listed, contract still opens with its stored preview, position and department still resolve, and the position is still selectable with `include_inactive=1`.
- [x] 10.10 Mark an employee as quit, deactivate their department, then clear "Đánh dấu nghỉ" via `PUT /admin/employees/{id}` with a body carrying only `status` and `quit_date`; confirm the reactivation is refused and names the remedy. Verified: 400 `employee_reactivation_unavailable_position`.
- [x] 10.11 Repeat the reactivation attempt via `PUT /admin/employees/{id}/update-status`; confirm it is refused the same way. Verified: 400, same status code.
- [x] 10.12 Repeat the reactivation while resubmitting the employee's own unavailable position; confirm it is still refused. Verified: 400, the "already holds it" exemption does not apply.
- [x] 10.13 Reactivate the same employee in one request that also assigns an available position; confirm the employee becomes `active` in the new position. Verified. Note the position must be in the employee's own company — `@update` refuses a cross-company move with `employee_invalid_position_on_different_company`, which is pre-existing and unrelated.
- [x] 10.14 Confirm the deactivated department still reports no active employees after all of the above. Verified: zero.
