Add README documentation

Document project overview, features, database schema, configuration, commands, and getting started guide.
2026-04-02 08:21:55 +02:00
parent 7a172c6fdb
commit e71c83538f
1 changed files with 184 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -1,2 +1,186 @@
 # 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:
+
+```bash
+cp config.example.toml config.dev.toml  # or config.test.toml
+```
+
+Edit `config.dev.toml`:
+```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
+
+```bash
+# 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
+
+```bash
+# 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
+- [x] Database schema for transactions, customers, cards
+- [x] CSV import to MariaDB
+- [x] Multi-environment support (dev/test/prod)
+- [x] Configuration via TOML files
+- [x] Invoice generation (HTML output)
+- [x] 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)
+   ```bash
+   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+   ```
+
+2. Create database user and grant permissions in MariaDB
+   ```sql
+   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
+   ```bash
+   cp config.example.toml config.dev.toml
+   # Edit config.dev.toml with your credentials
+   ```
+
+4. Setup database and import data
+   ```bash
+   cargo run -- db setup --env dev
+   cargo run -- import input/409.csv --env dev
+   ```
+
+## License
+
+See LICENSE file.