108 lines
4.5 KiB
Markdown
108 lines
4.5 KiB
Markdown
# EAMCO Office API
|
|
|
|
The **EAMCO Office API** is the central, monolithic backend service for the entire EAMCO office management application. Built with the Flask framework, it serves as the operational hub that powers the day-to-day activities of the business, from customer management to delivery dispatch.
|
|
|
|
This application is the "single source of truth" for many core business entities and orchestrates interactions with the other specialized microservices like `eamco_authorize` and `eamco_auto_api`.
|
|
|
|
[](https://www.python.org/)
|
|
[](https://flask.palletsprojects.com/)
|
|
[](https://www.postgresql.org/)
|
|
|
|
---
|
|
|
|
## Core Features
|
|
|
|
This is a comprehensive application covering a wide range of business functions, organized into modular components:
|
|
|
|
- **Customer Relationship Management (CRM)**: Full lifecycle management of customer data, addresses, and history.
|
|
- **Authentication & Authorization**: Secure user login, session management, and role-based access control using `Flask-Login` and `Flask-Bcrypt`.
|
|
- **Delivery & Service Hub**: Core logic for scheduling, creating, and tracking oil deliveries and other customer services.
|
|
- **Employee Management**: Manages employee profiles, roles, and assignments.
|
|
- **Financial & Payment Orchestration**: Integrates with other services to handle payment processing and financial calculations.
|
|
- **Reporting & Statistics**: Generates business reports and aggregates data for dashboards.
|
|
- **Promotion Engine**: Manages discount codes and promotional offers.
|
|
- **Admin Panel**: Provides administrators with tools to manage the entire system.
|
|
- **Full-Text Search**: Offers powerful search capabilities across different business domains.
|
|
|
|
---
|
|
|
|
## Technical Architecture
|
|
|
|
- **Framework**: Built with **Flask**, a powerful and flexible Python web framework.
|
|
- **Database**: Uses **PostgreSQL** as its primary data store, with **Flask-SQLAlchemy** as the ORM.
|
|
- **Serialization**: Employs **Marshmallow** (`flask-marshmallow`) for robust object serialization and data validation between the database models and the API.
|
|
- **Authentication**: Leverages `Flask-Login` for managing user sessions and `Flask-Bcrypt` for secure password hashing.
|
|
- **Web Forms**: Uses `Flask-WTF` for handling form submissions, indicating that it may serve some traditional web pages in addition to being a pure JSON API.
|
|
- **Deployment**: Production-ready, using `gunicorn` as the WSGI server. The `runProduction.py` script is likely the entry point for a production environment.
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.10+
|
|
- A running PostgreSQL database.
|
|
- A running Redis instance (for `Flask-Session`).
|
|
|
|
### 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 loaded into the Flask app context. Key settings include `SQLALCHEMY_DATABASE_URI` and `SECRET_KEY`. Refer to the settings files (`settings_*.py`) for details.
|
|
|
|
### Running the Service
|
|
|
|
#### For Development
|
|
|
|
The `app.py` file is configured to run the Flask development server, which provides live reloading.
|
|
|
|
```bash
|
|
python app.py
|
|
```
|
|
|
|
The application will be available at `http://localhost:4056`.
|
|
|
|
#### For Production (using Gunicorn)
|
|
|
|
The `runProduction.py` script is the intended entry point for production.
|
|
|
|
```bash
|
|
# Example of running with Gunicorn
|
|
gunicorn --bind 0.0.0.0:4056 runProduction:app
|
|
```
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
The application is organized into a modular structure, where each directory in `app/` represents a distinct functional domain.
|
|
|
|
```
|
|
eamco_office_api/
|
|
├── app/
|
|
│ ├── admin/
|
|
│ ├── auth/
|
|
│ ├── customer/
|
|
│ ├── delivery/
|
|
│ ├── employees/
|
|
│ ├── money/
|
|
│ ├── payment/
|
|
│ ├── reports/
|
|
│ ├── search/
|
|
│ ├── stats/
|
|
│ └── ... (many other modules)
|
|
├── app.py # Development server entry point
|
|
├── runProduction.py # Production server entry point
|
|
├── config.py # Application configuration loading
|
|
├── settings_dev.py # Development-specific settings
|
|
├── requirements.txt # Python dependencies
|
|
└── README.md # This file
|
|
```
|