123 lines
5.8 KiB
Markdown
123 lines
5.8 KiB
Markdown
# EAMCO Auto-Delivery API
|
|
|
|
The **EAMCO Auto-Delivery API** is an intelligent microservice responsible for managing and automating heating oil deliveries. Using a predictive model based on weather data, it estimates when customers will need a refill and helps schedule deliveries proactively.
|
|
|
|
This service is the backbone of the automatic delivery program, featuring a self-correcting algorithm that refines its predictions over time, ensuring customers never run out of oil.
|
|
|
|
[](https://www.python.org/)
|
|
[](https://fastapi.tiangolo.com/)
|
|
[](https://www.postgresql.org/)
|
|
|
|
---
|
|
|
|
## Core Features
|
|
|
|
- **Predictive Fuel Estimation**: The core `FuelEstimator` script calculates daily fuel consumption for each automatic delivery customer based on historical temperature data (Heating Degree Days).
|
|
- **Intelligent K-Factor**: Each customer has a unique "K-Factor" (house consumption factor) that represents their home's specific fuel usage rate.
|
|
- **Self-Correcting Algorithm**: After a delivery is completed, the service uses the actual gallons delivered to refine the customer's K-Factor, making future predictions progressively more accurate.
|
|
- **Automated Delivery Ticketing**: Automatically identifies customers who are low on fuel and provides endpoints to create delivery tickets.
|
|
- **Driver and Delivery Management**: Offers API endpoints to view upcoming deliveries for all customers or for specific drivers.
|
|
- **Weather Integration**: Fetches daily temperature data from a weather API to feed its prediction model.
|
|
|
|
## How It Works
|
|
|
|
The service's intelligence lies in its daily estimation and refinement cycle:
|
|
|
|
1. **Daily Update**: A scheduled job calls the `/main/update/auto` endpoint.
|
|
2. **Fetch Temperature**: The service ensures it has the latest daily temperature from an external weather API.
|
|
3. **Estimate Consumption**: For each customer, it calculates the day's estimated fuel consumption using the temperature and the customer's unique K-Factor.
|
|
4. **Identify Low-Fuel Customers**: It queries for customers whose estimated remaining gallons have fallen below a certain threshold.
|
|
5. **Create Tickets**: The system (or a user) can then create a delivery ticket for these customers via the `/confirm/auto/create/{autoid}` endpoint.
|
|
6. **Confirm Delivery**: Once the delivery is made, a `PUT` request to `/confirm/auto/update/{autoid}` with the actual `gallons_delivered` is made.
|
|
7. **Refine K-Factor**: This is the crucial step. The service compares its predicted usage against the actual usage (based on gallons delivered) and adjusts the K-Factor, improving the accuracy of all future predictions for that customer.
|
|
|
|
---
|
|
|
|
## API Endpoints
|
|
|
|
### Main Triggers
|
|
|
|
- `GET /main/temp`
|
|
- **Description**: Manually triggers the fetch and storage of the current day's temperature.
|
|
- `GET /main/update/auto`
|
|
- **Description**: The main cron job entry point. Triggers the daily fuel consumption update for all automatic delivery customers.
|
|
- `GET /main/update/normal`
|
|
- **Description**: Triggers the daily fuel consumption update for "normal" (non-auto) customers.
|
|
|
|
### Delivery & Ticket Management
|
|
|
|
- `POST /confirm/auto/create/{autoid}`
|
|
- **Description**: Creates a new delivery ticket for an automatic delivery customer, often with pre-authorization details.
|
|
- `PUT /confirm/auto/update/{autoid}`
|
|
- **Description**: Confirms a delivery by providing the actual gallons delivered. This triggers the K-Factor refinement.
|
|
- `GET /delivery/all/customers`
|
|
- **Description**: Returns a list of all automatic delivery customers, ordered by who needs a delivery most urgently.
|
|
- `GET /delivery/driver/{driver_employee_id}`
|
|
- **Description**: Gets a list of all pending automatic deliveries assigned to a specific driver.
|
|
|
|
---
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.10+
|
|
- PostgreSQL database
|
|
- Access to a weather API (configured in settings).
|
|
|
|
### 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.
|
|
|
|
### 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>`, with interactive docs at `http://localhost:<your_port>/docs`.
|
|
|
|
#### Using Docker
|
|
|
|
The project includes Dockerfiles for containerized deployment.
|
|
|
|
- **Build the image:**
|
|
```bash
|
|
docker build -f Dockerfile.local -t eamco_auto_api:local .
|
|
```
|
|
- **Run the container:**
|
|
```bash
|
|
docker run -d -p <your_port>:<your_port> --env MODE=LOCAL --name auto_api eamco_auto_api:local
|
|
```
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
eamco_auto_api/
|
|
├── app/
|
|
│ ├── models/ # SQLAlchemy ORM models (Auto_Delivery, Tickets_Auto_Delivery)
|
|
│ ├── routers/ # API endpoint definitions (main, confirm, delivery)
|
|
│ ├── schema/ # Pydantic models (if any)
|
|
│ └── script/ # Core logic (FuelEstimator, temp_getter)
|
|
├── 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
|
|
```
|