# employee-contract-position Specification

## Purpose
TBD - created by archiving change add-contract-position. Update Purpose after archive.
## Requirements
### Requirement: Employee Contract Position Field
Each employee record SHALL have a `contract_position` text field that can be viewed and edited independently of the employee's current position assignment (`account_position`).

#### Scenario: Viewing an employee's contract position
- **WHEN** an admin retrieves an employee's profile
- **THEN** the response includes the employee's `contract_position` value

#### Scenario: Updating an employee's contract position
- **WHEN** an admin updates an employee record with a new `contract_position` value
- **THEN** the new value is persisted
- **AND** subsequent reads of that employee return the updated value

#### Scenario: Contract position is independent of current position
- **WHEN** an employee's current position assignment changes
- **THEN** the employee's `contract_position` value is not automatically changed

### Requirement: Contract Position Backfill on Introduction
When the `contract_position` field is introduced, every existing employee SHALL have it seeded from their current position, so no employee is left with a value that silently differs from what their contracts previously displayed.

#### Scenario: Employee with a current position assigned
- **WHEN** the `contract_position` field is added for an employee who has a current position assigned
- **THEN** `contract_position` is set to the name of that current position

#### Scenario: Employee with no current position assigned
- **WHEN** the `contract_position` field is added for an employee who has no current position assigned
- **THEN** `contract_position` is left empty

### Requirement: Filtering Employees by Contract Position
The admin employee list SHALL support filtering by `contract_position`, matching employees whose `contract_position` contains the given text.

#### Scenario: Filtering by a matching contract position
- **WHEN** an admin requests the employee list with a `contract_position` filter value
- **THEN** the response includes only employees whose `contract_position` contains that value

#### Scenario: Filtering with no matches
- **WHEN** an admin requests the employee list with a `contract_position` filter value that matches no employee
- **THEN** the response is an empty list

### Requirement: Contract Position in Employee Export
The employee export SHALL include a `contract_position` column, distinct from the existing live-position column.

#### Scenario: Exporting employees
- **WHEN** an admin exports the employee list
- **THEN** the exported data includes a "Vị trí HĐ" column with each employee's `contract_position` value
- **AND** the existing "Vị trí" column continues to show the employee's live current position, unchanged

### Requirement: Contract Document Position Source
Contract documents that render the `employee_position` field SHALL source its value from the employee's `contract_position`, not from the employee's live current position.

#### Scenario: Generating a contract document
- **WHEN** a contract document is generated or previewed for an employee and references the `employee_position` field
- **THEN** the rendered value equals that employee's `contract_position`
- **AND** it does so even if the employee's current position assignment has since changed to something different