# RevertSoftLock

## Permission Scope

periodManagement

## Overview

revertSoftLock transitions a PeriodClose from SOFT_LOCKED back to IN_PROGRESS status, allowing the close workflow to be revisited. This is used when errors are discovered after the period was soft-locked but before permanent close. After reverting, the accounting team can post corrections and re-run the close checklist steps. This operation is only permitted before permanent close.

## Business Rules

- PeriodClose record must exist and be in SOFT_LOCKED status
- Only SOFT_LOCKED records can be reverted
- Reverting a permanently closed period is not permitted
- After revert, the PeriodClose returns to IN_PROGRESS status, allowing the full checklist to be re-executed
- Updates completionPercentage to reflect the rollback
- Records the userId of the operator who reverted the soft lock
- Emits an audit event recording the acting user, timestamp, and status transition from SOFT_LOCKED to IN_PROGRESS

## Process Flow

```mermaid
flowchart TD
    A[Receive revert soft 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 IN_PROGRESS]
    F --> G[Update completionPercentage]
    G --> H[Emit audit event]
    H --> I[Return updated PeriodClose]
```

## External Dependencies

- None (same-module read for period close lookup)

## 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
- **PERIOD_PERMANENTLY_CLOSED**: Cannot revert a period close that has already been permanently closed

## Test Cases

- returns error when PeriodClose record does not exist
- returns error when PeriodClose is in NOT_STARTED status
- returns error when PeriodClose is in IN_PROGRESS status
- returns error when PeriodClose is in UNDER_REVIEW status
- returns error when PeriodClose is PERMANENTLY_CLOSED
- transitions SOFT_LOCKED period close to IN_PROGRESS
- emits audit event recording status transition and acting user
