# BeginClose

## Overview

beginClose transitions a PeriodClose record from NOT_STARTED to IN_PROGRESS status, indicating that the close checklist execution has begun. This is the first step after initiating the close and signals that the accounting team is actively working through the close workflow.

## Business Rules

- PeriodClose record must exist and be identified by the period close `id`
- PeriodClose must be in NOT_STARTED status
- Only NOT_STARTED records can transition to IN_PROGRESS
- Records the userId of the operator who began the close
- Updates completionPercentage to reflect progress
- Emits an audit event via the audit module recording the acting user, timestamp, previous status (NOT_STARTED), and new status (IN_PROGRESS)

## Process Flow

```mermaid
flowchart TD
    A[Receive begin close request] --> B{PeriodClose record exists?}
    B -->|No| C[Return error: period close not found]
    B -->|Yes| D{PeriodClose in NOT_STARTED status?}
    D -->|No| E[Return error: invalid status transition]
    D -->|Yes| F[Transition PeriodClose to IN_PROGRESS]
    F --> G[Record acting user]
    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**: No PeriodClose record matches the given id
- **INVALID_STATUS_TRANSITION**: PeriodClose is not in NOT_STARTED status; only NOT_STARTED can transition to IN_PROGRESS

## Test Cases

- returns error when PeriodClose record does not exist
- returns error when PeriodClose is already IN_PROGRESS
- returns error when PeriodClose is in SUBLEDGERS_VERIFIED status
- returns error when PeriodClose is in PERMANENTLY_CLOSED status
- transitions NOT_STARTED PeriodClose to IN_PROGRESS
- records the acting user who began the close
- emits audit event recording status transition from NOT_STARTED to IN_PROGRESS and acting user
