# Appointment History

## Overview

Appointment History records **appointments** — the append-only journal of appointment events that change a Worker's organizational placement: hire, transfer, promotion, secondment, concurrent posting, return, and termination. Each event captures both an **effective date** (when it takes effect) and an **issue date** (when it was ordered), so future-dated appointments can be issued and reviewed ahead of time. This is the first-class Japanese-enterprise concept that COMPANY and TeamSpirit Enterprise own and SMB tools lack (issues #7, #13).

Where `Assignment` holds the effective-dated world state, AppointmentHistory holds the immutable event log that produced it; together they reconstruct the organization as of any date and form part of the audit trail that replaces the deprecated audit module (ADR-013, ADR-016).

## Business Purpose

- Provide the authoritative appointment record Japanese enterprises require for HR governance and audit
- Enable future-dated appointments (issue an appointment today effective next month) and see upcoming moves
- Reconstruct "the org chart as of any past or future date" by replaying appointments alongside effective-dated Assignments
- Contribute an immutable who/when/what trail without the deprecated audit module (ADR-013)

## Process Flow

```mermaid
flowchart TD
    A[Issue appointment with type + effectiveDate + issuedAt] --> B{Future-dated?}
    B -- Yes --> C[Appended now, visible in upcoming appointments]
    C --> D[On effectiveDate: creates/changes Assignment]
    B -- No --> D
    D --> E[Append immutable AppointmentHistory entry linked to Assignment]
    E --> F{Correction needed?}
    F -- Yes --> G[Append compensating entry; original preserved]
```

## Scenario Patterns

- **Hire appointment**: a HIRE event with no from-Position, creating the first Assignment on its effective date
- **Transfer / promotion**: a TRANSFER or PROMOTION event records from-Position and to-Position and drives an Assignment transfer
- **Future-dated appointment**: issued ahead of time; visible as upcoming and not effective until its date
- **Secondment / concurrent**: SECONDMENT or CONCURRENT events model cross-entity or dual-post placements
- **Termination**: a TERMINATION event with no to-Position closes the Assignment and employment
- **Correction**: an erroneous appointment is corrected by a new compensating entry; the original is never mutated or deleted
- **Point-in-time reconstruction**: querying `asOf` a date replays appointments + Assignment generations to render the org chart then

## Test Cases

- recording a HIRE appointment creates the initial Assignment on its effective date
- a future-dated appointment appears in upcoming appointments and is not effective until its date
- a TRANSFER appointment records both from-Position and to-Position
- appointment entries are never modified or deleted; corrections append a new entry
- listing a Worker's appointments returns them in chronological order
- a CREATE_SECONDARY_ASSIGNMENT appointment opens a non-primary Assignment

## Reference Links

- Data-model design research (appointment history, point-in-time org): https://github.com/tailor-sandbox/Omakase-ERP-attendance/issues/7
- Customization reality (COMPANY / TeamSpirit Enterprise appointment-history): https://github.com/tailor-sandbox/Omakase-ERP-attendance/issues/13