# ApproveAndLockPeriod

## Permission Scope

periodManagement

## Overview

approveAndLockPeriod transitions a PeriodClose from UNDER_REVIEW to SOFT_LOCKED status, indicating that the accounting team has approved the period's financial data. A soft-locked period prevents the accounting team from posting new journal entries while still allowing users with the advisor/auditor role to post final adjustments. This supports segregation of duties in the close workflow.

## Business Rules

- PeriodClose record must exist and be in UNDER_REVIEW status
- Only UNDER_REVIEW records can transition to SOFT_LOCKED
- Approval requires a user with the appropriate authorization role (e.g., controller or finance manager)
- Soft-locking a period prevents the accounting team from posting new journal entries to that period
- Soft-locked period still allows postings from users with the advisor/auditor role
- Updates completionPercentage to reflect progress
- Records the userId of the approver who locked the period
- Emits an audit event recording the acting user, timestamp, approval details, and status transition

## Process Flow

```mermaid
flowchart TD
    A[Receive approve and lock request] --> B{PeriodClose record exists?}
    B -->|No| C[Return error: period close not found]
    B -->|Yes| D{PeriodClose in UNDER_REVIEW status?}
    D -->|No| E[Return error: invalid status transition]
    D -->|Yes| F{User has authorization role?}
    F -->|No| G[Return error: insufficient permissions]
    F -->|Yes| H[Transition PeriodClose to SOFT_LOCKED]
    H --> I[Block accounting team postings for the period]
    I --> J[Update completionPercentage]
    J --> K[Emit audit event]
    K --> L[Return updated PeriodClose]
```

## External Dependencies

- [user-management::listUserRolesByUser](../../../user-management/docs/queries/ListUserRolesByUser.md) - Validates that the acting user has the required authorization role (controller or finance manager)

## 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
- **INSUFFICIENT_PERMISSIONS**: Acting user does not have the required authorization role (controller or finance manager)

## 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 already SOFT_LOCKED
- returns error when user lacks required permissions
- transitions UNDER_REVIEW PeriodClose to SOFT_LOCKED with approvedByUserId and completionPercentage
- emits audit event recording status transition from UNDER_REVIEW to SOFT_LOCKED
