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.

---

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:

   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

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:

  docker build -f Dockerfile.local -t eamco_money_api:local .
  

• Run the container:

  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