# FinalCloseAndLockPeriod

## Permission Scope

periodManagement

## Overview

finalCloseAndLockPeriod transitions a PeriodClose from SOFT_LOCKED to PERMANENTLY_CLOSED status. This is the final step in the period-end close workflow. Once permanently closed, the accounting period becomes fully immutable — no further journal entries can be posted regardless of user role, and the period cannot be reopened. The underlying AccountingPeriod is also transitioned to PERMANENTLY_CLOSED status.

## Business Rules

- PeriodClose record must exist and be in SOFT_LOCKED status
- Only SOFT_LOCKED records can transition to PERMANENTLY_CLOSED
- Permanently closing a period makes it fully immutable; no further journal entries can be posted regardless of role
- The underlying AccountingPeriod is transitioned to PERMANENTLY_CLOSED status
- A permanently closed period cannot be reverted
- Updates completionPercentage to 100%
- Records the userId of the operator who finalized the close
- Emits an audit event recording the acting user, timestamp, and irreversible status transition

## Process Flow

```mermaid
flowchart TD
    A[Receive final close and lock request] --> B{PeriodClose record exists?}
    B -->|No| C[Return error: period close not found]
    B -->|Yes| D{PeriodClose in SOFT_LOCKED status?}
    D -->|No| E[Return error: invalid status transition]
    D -->|Yes| F[Transition PeriodClose to PERMANENTLY_CLOSED]
    F --> G[Transition AccountingPeriod to PERMANENTLY_CLOSED]
    G --> H[Set completionPercentage to 100%]
    H --> I[Emit audit event]
    I --> J[Return finalized PeriodClose]
```

## External Dependencies

- None (same-module mutation for accounting period status transition)

## Error Scenarios

- **PERIOD_CLOSE_NOT_FOUND**: Referenced period close does not exist
- **INVALID_STATUS_TRANSITION**: Requested status transition is not allowed from the current status

## Test Cases

- returns error when PeriodClose record does not exist
- returns error when PeriodClose is in UNDER_REVIEW status
- returns error when PeriodClose is in IN_PROGRESS status
- transitions SOFT_LOCKED PeriodClose to PERMANENTLY_CLOSED with completionPercentage 100
- also updates the associated AccountingPeriod to PERMANENTLY_CLOSED
- emits audit event recording status transition from SOFT_LOCKED to PERMANENTLY_CLOSED
