updated readme

README.md

@@ -0,0 +1,118 @@
+# 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
+```