# Adjustment File Complete

This Lambda function is responsible for completing adjustment file ingestion.

## Overview

Triggered by the Step Function after a batch has been processed.

**Position in Workflow:**
```
EventBridge
  ↓ file_upload.completed
Adjustment File Initialize
  ↓ adjustment_batch.initialized
[Adjustment File Prepare]
  ↓ adjustment_batch.prepared
Adjustment File Process Batch
  ↓ adjustment_batch.processed
Adjustment File Complete         ← You are here
```

**Workflow Steps:**

## Event Schema

**Input Event:**
```json
{
  "detail-type": "adjustment_batch.processed",
  "detail": {
    "metadata": {
      "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
      "target_id": 456,
      "target_type": "worksheet_flowthrough_batch"
    },
    "data": {
      "TBD": true
    }
  }
}
```

**Output Response:**
```json
{
  "detail_type": "adjustment_batch.completed",
  "detail": {
    "metadata": {
      "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
      "target_id": 456,
      "target_type": "worksheet_flowthrough_batch"
    },
    "data": {
      "TBD": true
    }
  }
}
```

## Performance Characteristics

- **Typical Duration:** TBD seconds
- **Memory Requirements:** Low
- **Expected Volume:** Low frequency (per batch initialization)

## Architecture & Design

*   **Hexagonal Architecture:** Separation of concerns between the core logic (`processor.py`), data access (`connectors/`), and schemas (`schemas/`).
*   **Type Safety:** Uses **Pydantic** models for strict typing of events and responses.
*   **Robust Error Handling:** Distinguishes between transient (retriable) and permanent (non-retriable) errors.
*   **Resource Management:** Ensures temporary files are cleaned up after processing.

## Database Dependencies

**Tables:**
- `worksheet_flowthrough_batch` (read/write) - Updates batch status and error codes

**Key Operations:**
- TBD

## Edge Cases & Error Handling

| Scenario | Error Type | Behavior | Retry Strategy |
| :--- | :--- | :--- | :--- |

## Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `ENVIRONMENT` | Deployment environment | `qa`, `prod` |
| `MYSQL_DB_HOST` | MySQL database host | `qa-db-royalty-accounting.theorchard.io` |
| `MYSQL_DB_NAME` | MySQL database name | `royalty_accounting` |
| `MYSQL_DB_USER` | MySQL username | `royalties` |

## Requirements

- Python 3.13
- [uv](https://docs.astral.sh/uv/) - Fast Python package manager
- Docker (for containerized testing)

## Local Development

### Setup
1.  Copy the environment file:
    ```bash
    cp .env.shadow .env
    ```
2.  Install dependencies:
    ```bash
    make env_dev
    ```

### Running Tests
*   **Unit Tests:** `make test` (runs pytest with coverage)
*   **Linting:** `make lint` (check) or `make lint_fix` (auto-fix)
*   **Formatting:** `make format` (check) or `make format_fix` (auto-fix)
*   **Docker Tests:** `make docker_test` (runs linting and tests inside a container)
*   **Integration Tests:** `make docker_test_local_integration` (runs integration tests in Docker with full service dependencies)

### Running Locally
Run the Lambda function handler locally as a script:
```bash
make run
```

Or run as a Docker container:
```bash
make docker_local_up
```

## Deployment

Deploys via the [Jenkins pipeline](https://pipeline.theorchard.io/job/lambda-abacus-pipeline/). A webhook triggers the deploy for changes in this directory.