Update README: add testing section, production build, test infrastructure docs
This commit is contained in:
110
README.md
110
README.md
@@ -12,32 +12,45 @@ This project processes petroleum/fuel station transaction data from CSV files an
|
||||
- **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
|
||||
- **Test-Driven Development**: Comprehensive test suite with 45 tests
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
rusty-petroleum/
|
||||
├── Cargo.toml # Rust dependencies
|
||||
├── Cargo.lock # Locked dependency versions
|
||||
├── config.example.toml # Config template
|
||||
├── migrations/ # SQL schema files
|
||||
│ ├── 001_dev.sql
|
||||
│ ├── 001_test.sql
|
||||
│ ├── 001_prod.sql
|
||||
│ └── 002_schema.sql
|
||||
│ └── 002_schema.sql # Current schema
|
||||
├── input/ # CSV input files
|
||||
├── output/ # Generated invoices
|
||||
├── src/
|
||||
│ ├── lib.rs # Library crate (for testing)
|
||||
│ ├── main.rs # CLI entry point
|
||||
│ ├── config.rs # Configuration loading
|
||||
│ ├── db/ # Database layer
|
||||
│ │ ├── mod.rs
|
||||
│ │ ├── connection.rs
|
||||
│ │ ├── models.rs
|
||||
│ │ └── repository.rs
|
||||
│ ├── commands/ # CLI commands
|
||||
│ │ ├── mod.rs
|
||||
│ │ ├── db.rs # db setup/reset
|
||||
│ │ └── import.rs # CSV import
|
||||
│ └── invoice_generator.rs
|
||||
└── templates/ # HTML invoice templates
|
||||
├── templates/ # HTML invoice templates
|
||||
│ ├── index.html
|
||||
│ └── customer.html
|
||||
└── tests/ # Integration tests
|
||||
├── common/ # Test utilities
|
||||
│ ├── mod.rs
|
||||
│ ├── fixtures.rs
|
||||
│ └── test_db.rs
|
||||
├── config_test.rs # Config module tests
|
||||
├── import_test.rs # CSV parsing tests
|
||||
├── models_test.rs # Model tests
|
||||
└── repository_test.rs # Database tests
|
||||
```
|
||||
|
||||
## Database Schema
|
||||
@@ -45,26 +58,30 @@ rusty-petroleum/
|
||||
### customers
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| id | INT | Primary key |
|
||||
| id | INT UNSIGNED | Primary key |
|
||||
| customer_number | VARCHAR | Unique customer identifier |
|
||||
| card_report_group | TINYINT | Customer classification (1=fleet, 3/4=retail) |
|
||||
| card_report_group | TINYINT UNSIGNED | Customer classification (1=fleet, 3/4=retail) |
|
||||
| created_at | TIMESTAMP | Record creation time |
|
||||
| updated_at | TIMESTAMP | Last update time |
|
||||
|
||||
### cards
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| id | INT | Primary key |
|
||||
| id | INT UNSIGNED | Primary key |
|
||||
| card_number | VARCHAR | Unique card identifier |
|
||||
| customer_id | INT | FK to customers |
|
||||
| customer_id | INT UNSIGNED | FK to customers |
|
||||
| created_at | TIMESTAMP | Record creation time |
|
||||
| updated_at | TIMESTAMP | Last update time |
|
||||
|
||||
### transactions
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| id | BIGINT | Primary key |
|
||||
| id | BIGINT UNSIGNED | 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 |
|
||||
| amount | DECIMAL(10,2) | Transaction amount |
|
||||
| volume | DECIMAL(10,3) | Volume in liters |
|
||||
| price | DECIMAL(8,4) | Price per liter |
|
||||
| quality_code | INT | Product code |
|
||||
| quality_name | VARCHAR | Product name (95 Oktan, Diesel) |
|
||||
| card_number | VARCHAR | Card used (including anonymized) |
|
||||
@@ -73,14 +90,15 @@ rusty-petroleum/
|
||||
| pump | VARCHAR | Pump number |
|
||||
| receipt | VARCHAR | Receipt number |
|
||||
| control_number | VARCHAR | Control/verification number |
|
||||
| customer_id | INT | FK to customers (NULL for anonymized) |
|
||||
| customer_id | INT UNSIGNED | FK to customers (NULL for anonymized) |
|
||||
| created_at | TIMESTAMP | Record creation time |
|
||||
|
||||
## Configuration
|
||||
|
||||
Copy the example config and edit with your database credentials:
|
||||
|
||||
```bash
|
||||
cp config.example.toml config.dev.toml # or config.test.toml
|
||||
cp config.example.toml config.dev.toml # or config.test.toml or config.prod.toml
|
||||
```
|
||||
|
||||
Edit `config.dev.toml`:
|
||||
@@ -100,6 +118,12 @@ Config files are loaded in order:
|
||||
2. `config.<env>.toml` (environment-specific, gitignored)
|
||||
3. `config.example.toml` (fallback, tracked)
|
||||
|
||||
### Database Names by Environment
|
||||
|
||||
- `rusty_petroleum_dev` - Development
|
||||
- `rusty_petroleum_test` - Testing
|
||||
- `rusty_petroleum_prod` - Production
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
@@ -130,6 +154,53 @@ cargo run -- db reset --env dev
|
||||
cargo run -- generate input/409.csv output/
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
The project has a comprehensive test suite with 45 tests covering config, CSV parsing, models, and database operations.
|
||||
|
||||
```bash
|
||||
# Run all tests (lib + integration)
|
||||
cargo test
|
||||
|
||||
# Run only lib/unit tests (fast, no database needed)
|
||||
cargo test --lib
|
||||
|
||||
# Run only integration tests (requires test database)
|
||||
cargo test --tests
|
||||
|
||||
# Run a specific test file
|
||||
cargo test --test config_test
|
||||
cargo test --test import_test
|
||||
cargo test --test repository_test
|
||||
|
||||
# Run a specific test
|
||||
cargo test customer_insert_returns_id
|
||||
|
||||
# Run tests in release mode
|
||||
cargo test --release
|
||||
```
|
||||
|
||||
### Test Database Setup
|
||||
|
||||
Repository tests require a test database. Run setup before testing:
|
||||
|
||||
```bash
|
||||
cargo run -- db setup --env test
|
||||
```
|
||||
|
||||
## Production Build
|
||||
|
||||
Build an optimized binary for production:
|
||||
|
||||
```bash
|
||||
# Build release binary
|
||||
cargo build --release
|
||||
|
||||
# Run the binary
|
||||
./target/release/invoice-generator db setup --env prod
|
||||
./target/release/invoice-generator import data.csv --env prod
|
||||
```
|
||||
|
||||
## Current Status
|
||||
|
||||
### Implemented
|
||||
@@ -139,12 +210,12 @@ cargo run -- generate input/409.csv output/
|
||||
- [x] Configuration via TOML files
|
||||
- [x] Invoice generation (HTML output)
|
||||
- [x] Database setup/reset commands
|
||||
- [x] Unit tests (45 tests)
|
||||
|
||||
### TODO
|
||||
- [ ] Sales reporting queries (dashboard/API)
|
||||
- [ ] Customer invoice retrieval from database
|
||||
- [ ] Batch import across multiple CSV files
|
||||
- [ ] Unit tests
|
||||
- [ ] CI/CD pipeline
|
||||
|
||||
## Technology Stack
|
||||
@@ -154,6 +225,7 @@ cargo run -- generate input/409.csv output/
|
||||
- **ORM**: sqlx (async MySQL)
|
||||
- **Templating**: Askama (HTML templates)
|
||||
- **Config**: TOML
|
||||
- **Testing**: tokio-test, tempfile
|
||||
|
||||
## Getting Started
|
||||
|
||||
@@ -181,6 +253,12 @@ cargo run -- generate input/409.csv output/
|
||||
cargo run -- import input/409.csv --env dev
|
||||
```
|
||||
|
||||
5. Run tests
|
||||
```bash
|
||||
cargo test --lib # Unit tests (fast)
|
||||
cargo test --tests # Integration tests (requires DB)
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
See LICENSE file.
|
||||
|
||||
Reference in New Issue
Block a user