# EAMCO Money API

The **EAMCO Money API** is a specialized microservice that acts as the financial calculator for the EAMCO ecosystem. Its sole responsibility is to process completed deliveries, calculate all associated costs and profits, and create a permanent financial record for each transaction.

This service is typically called after a delivery has been successfully completed. It crunches the numbers to determine profitability, fees, discounts, and final totals.

[![Language](https://img.shields.io/badge/Language-Python%203.11-blue)](https://www.python.org/)
[![Framework](https://img.shields.io/badge/Framework-FastAPI-green)](https://fastapi.tiangolo.com/)
[![Database](https://img.shields.io/badge/Database-PostgreSQL-blue)](https://www.postgresql.org/)

---

## Core Features

- **Post-Delivery Financial Processing**: Takes a completed delivery ID and calculates a full financial breakdown.
- **Detailed Profit Analysis**: Determines profitability by breaking down the transaction into:
    - Total revenue from the customer for oil.
    - Total cost of oil from the supplier.
    - Revenue from additional fees (e.g., same-day service, prime).
    - Costs incurred from promotional discounts.
    - Final net profit for the delivery.
- **Handles Multiple Delivery Types**: Provides distinct logic for calculating the financials of standard, on-demand deliveries versus automated, subscription-based deliveries.
- **Immutable Financial Records**: Saves the detailed financial breakdown into the `money_delivery` table, ensuring a permanent and accurate record for accounting and analysis.

## How It Works

The workflow for this service is straightforward:

1.  **Delivery Completion**: Another service (e.g., the driver's app or the main office app) marks a delivery as complete.
2.  **Trigger Calculation**: That service then makes a `POST` request to this API, providing the ID of the completed delivery ticket.
    - `/delivery/add/{delivery_id}` for standard deliveries.
    - `/delivery/add/auto/{auto_ticket_id}` for automatic deliveries.
3.  **Data Aggregation**: The Money API retrieves all relevant information from the database:
    - The `delivery` or `tickets_auto_delivery` record.
    - The current oil prices from `pricing_oil_oil`.
    - Any promotional details from `promo_promo`.
4.  **Calculation**: It performs all the necessary calculations to determine costs, fees, discounts, and profit.
5.  **Record Creation**: A new entry is created and saved in the `money_delivery` table, storing this detailed financial snapshot.

---

## API Endpoints

### Delivery Financials

- `POST /delivery/add/{delivery_id_order}`
  - **Description**: Triggers the financial calculation for a completed **standard** delivery.
  - **Action**: Creates a new `money_delivery` record with a full profit and loss breakdown.

- `POST /delivery/add/auto/{auto_ticket_id}`
  - **Description**: Triggers the financial calculation for a completed **automatic** delivery.
  - **Action**: Creates a new `money_delivery` record based on the auto-delivery ticket details.

- `GET /delivery/order/money/{delivery_id_order}`
  - **Description**: Retrieves the previously calculated financial record for a specific delivery.

---

## Getting Started

### Prerequisites

- Python 3.10+
- A running PostgreSQL database with the required EAMCO schema.

### Installation

1.  **Clone the repository and navigate into it.**

2.  **Create a virtual environment and install dependencies:**
    ```bash
    python -m venv venv
    source venv/bin/activate
    pip install -r requirements.txt
    ```

3.  **Configure your environment:**
    The application's configuration is managed by environment variables set in `settings_local.py`, `settings_dev.py`, or `settings_prod.py`. The `MODE` environment variable determines which configuration to use. Ensure your database connection URI is set correctly in the appropriate settings file.

### Running the Service

#### For Development

```bash
export MODE=DEVELOPMENT
uvicorn main:app --reload --host 0.0.0.0 --port <your_port>
```

The API will be available at `http://localhost:<your_port>`.

#### Using Docker

-   **Build the image:**
    ```bash
    docker build -f Dockerfile.local -t eamco_money_api:local .
    ```
-   **Run the container:**
    ```bash
    docker run -d -p <your_port>:<your_port> --env MODE=LOCAL --name money_api eamco_money_api:local
    ```

---

## Project Structure

```
eamco_money_api/
├── app/
│   ├── models/           # SQLAlchemy ORM models
│   ├── routers/          # API endpoint definitions (delivery.py)
│   └── schema/           # Pydantic models (if any)
├── config.py             # Logic for loading environment-specific settings
├── database.py           # SQLAlchemy engine and session setup
├── main.py               # FastAPI application entry point
├── settings_local.py     # Settings for the LOCAL environment
├── requirements.txt      # Python dependencies
└── README.md             # This file
```