# CreatePosition

## Permission Scope

`position`

## Overview

CreatePosition defines a new post under an organization Department (and optionally a Site), referencing a JobProfile for its role definition, starting as vacant with no incumbent.

## Business Rules

- Every Position references exactly one organization Department; Site reference is optional
- Every Position references exactly one JobProfile — a Position cannot be created without a role definition
- `headcount` defaults to 1 and represents the number of seats the Position represents
- A newly created Position has no incumbent; vacancy is derived from open Assignments against `headcount`, not stored (`listVacantPositions`)
- Effective-dated per ADR-013: the initial generation has an `effectiveStart` and no `effectiveEnd`

## Process Flow

```mermaid
flowchart TD
    A[Create Position: Department, optional Site, JobProfile, headcount] --> B{Department exists?}
    B -- No --> X[Reject: DEPARTMENT_NOT_FOUND]
    B -- Yes --> C{Site specified and exists?}
    C -- No --> Y[Reject: SITE_NOT_FOUND]
    C -- Yes --> D{JobProfile exists?}
    D -- No --> Z[Reject: JOB_PROFILE_NOT_FOUND]
    D -- Yes --> E[Create initial Position generation]
```

## External Dependencies

- organization::Department (cross-module) — the Department the Position belongs to
- organization::Site (cross-module, optional) — the Site the Position is located at
- [workforce::JobProfile](../model/JobProfile.md) model — the role definition referenced

## Error Scenarios

- **DEPARTMENT_NOT_FOUND**: the specified Department does not exist
- **SITE_NOT_FOUND**: the specified Site does not exist
- **JOB_PROFILE_NOT_FOUND**: the specified JobProfile does not exist
- **INVALID_HEADCOUNT**: `headcount` is less than 1

## Test Cases

- creates a Position under an existing Department and JobProfile, with a Site
- creates a Position with no Site (vacant, no incumbent)
- rejects when the Department does not exist
- rejects creating a Position with a non-existent Site
- rejects when the JobProfile does not exist
- rejects creating a Position with headcount less than 1