rusty-petroleum/README.md

rusty-petroleum

A petroleum transaction invoice generator with MariaDB backend.

Overview

This project processes petroleum/fuel station transaction data from CSV files and generates customer invoices. It stores transaction data in MariaDB for both invoicing and sales reporting.

Features

• CSV Import: Import transaction data from fuel station CSV files into MariaDB
• Invoice Generation: Generate HTML invoices from CSV data (file-to-file mode)
• Multi-Environment: Separate databases for development, testing, and production
• Sales Reporting: Query transactions by customer, product, date range

Project Structure

rusty-petroleum/
├── Cargo.toml              # Rust dependencies
├── config.example.toml     # Config template
├── migrations/            # SQL schema files
│   ├── 001_dev.sql
│   ├── 001_test.sql
│   ├── 001_prod.sql
│   └── 002_schema.sql
├── input/                  # CSV input files
├── output/                 # Generated invoices
├── src/
│   ├── main.rs            # CLI entry point
│   ├── config.rs          # Configuration loading
│   ├── db/                # Database layer
│   │   ├── connection.rs
│   │   ├── models.rs
│   │   └── repository.rs
│   ├── commands/          # CLI commands
│   │   ├── db.rs          # db setup/reset
│   │   └── import.rs      # CSV import
│   └── invoice_generator.rs
└── templates/             # HTML invoice templates

Database Schema

customers

Column	Type	Description
id	INT	Primary key
customer_number	VARCHAR	Unique customer identifier
card_report_group	TINYINT	Customer classification (1=fleet, 3/4=retail)

cards

Column	Type	Description
id	INT	Primary key
card_number	VARCHAR	Unique card identifier
customer_id	INT	FK to customers

transactions

Column	Type	Description
id	BIGINT	Primary key
transaction_date	DATETIME	Transaction timestamp
batch_number	VARCHAR	Batch identifier
amount	DECIMAL	Transaction amount
volume	DECIMAL	Volume in liters
price	DECIMAL	Price per liter
quality_code	INT	Product code
quality_name	VARCHAR	Product name (95 Oktan, Diesel)
card_number	VARCHAR	Card used (including anonymized)
station	VARCHAR	Station ID
terminal	VARCHAR	Terminal ID
pump	VARCHAR	Pump number
receipt	VARCHAR	Receipt number
control_number	VARCHAR	Control/verification number
customer_id	INT	FK to customers (NULL for anonymized)

Configuration

Copy the example config and edit with your database credentials:

cp config.example.toml config.dev.toml  # or config.test.toml

Edit config.dev.toml:

[database]
host = "localhost"
port = 3306
user = "your_user"
password = "your_password"
name = "rusty_petroleum_dev"

Environment Config Loading

Config files are loaded in order:

1. config.toml (local override, gitignored)
2. config.<env>.toml (environment-specific, gitignored)
3. config.example.toml (fallback, tracked)

Commands

# Database management
cargo run -- db setup --env <dev|test|prod>   # Create database and schema
cargo run -- db reset --env <dev|test|prod>   # Drop and recreate database

# Import data
cargo run -- import <csv-file> --env <dev|test|prod>   # Import to database (default: prod)

# Generate invoices (file-to-file, no database)
cargo run -- generate <csv-file> <output-dir>

Usage Examples

# Setup development database
cargo run -- db setup --env dev

# Import transactions to dev database
cargo run -- import input/409.csv --env dev

# Reset development database
cargo run -- db reset --env dev

# Generate HTML invoices from CSV
cargo run -- generate input/409.csv output/

Current Status

Implemented

• Database schema for transactions, customers, cards
• CSV import to MariaDB
• Multi-environment support (dev/test/prod)
• Configuration via TOML files
• Invoice generation (HTML output)
• Database setup/reset commands

TODO

• Sales reporting queries (dashboard/API)
• Customer invoice retrieval from database
• Batch import across multiple CSV files
• Unit tests
• CI/CD pipeline

Technology Stack

• Language: Rust (Edition 2021)
• Database: MariaDB
• ORM: sqlx (async MySQL)
• Templating: Askama (HTML templates)
• Config: TOML

Getting Started

1. Install Rust (if not already installed)

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   

2. Create database user and grant permissions in MariaDB

   CREATE USER 'your_user'@'%' IDENTIFIED BY 'your_password';
   GRANT ALL PRIVILEGES ON rusty_petroleum_dev.* TO 'your_user'@'%';
   CREATE DATABASE rusty_petroleum_dev;
   

3. Setup configuration

   cp config.example.toml config.dev.toml
   # Edit config.dev.toml with your credentials
   

4. Setup database and import data

   cargo run -- db setup --env dev
   cargo run -- import input/409.csv --env dev
   

License

See LICENSE file.