256 lines
7.2 KiB
Markdown
256 lines
7.2 KiB
Markdown
# 🐙 Antares Data Exporter
|
||
|
||
<div align="center">
|
||
|
||
|
||
|
||
**A powerful Rust utility for fetching Antares B2B product data and exporting to Excel**
|
||
|
||
[Features](#features) • [Installation](#installation) • [Usage](#usage) • [Configuration](#configuration) • [Architecture](#architecture)
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
**Antares Data Exporter** is a high-performance Rust utility that seamlessly integrates with the Antares B2B web service to fetch product catalog data and export it to Excel with intelligent field mapping and business rule validation. Perfect for inventory management, data migration, and supply chain automation.
|
||
|
||
## ✨ Features
|
||
|
||
- 🚀 **Fast & Efficient** - Blocking HTTP client with 300-second timeout for reliable operations
|
||
- 📊 **Excel Export** - Intelligent field mapping with 8 carefully curated columns
|
||
- 🧠 **Smart Row Filtering** - Automatically skips incomplete records based on business rules
|
||
- 📝 **Dual Logging** - All events logged to both terminal and daily log files
|
||
- 🎯 **Flexible Output** - Support for custom file paths or directory-based exports
|
||
- 🔐 **Secure Credentials** - Environment-based credential management, no hardcoding
|
||
- 🏗️ **Modular Architecture** - Clean separation of concerns for easy extension
|
||
- 📦 **Auto Directory Creation** - Creates necessary directories on first run
|
||
|
||
## 🛠️ Technology Stack
|
||
|
||
- **Language:** Rust (2024 edition)
|
||
- **HTTP Client:** reqwest with blocking mode
|
||
- **Excel:** rust_xlsxwriter
|
||
- **Environment:** dotenv
|
||
- **Date/Time:** chrono
|
||
|
||
## 📋 Prerequisites
|
||
|
||
- Rust 1.70+ (with Cargo)
|
||
- Valid Antares B2B API credentials (usercode & password)
|
||
- Write access to create `log/`, `out/`, and `antares.json` at repo root
|
||
|
||
## 📥 Installation
|
||
|
||
```bash
|
||
# Clone the repository
|
||
git clone https://github.com/yourusername/antares_get_data.git
|
||
cd antares_get_data
|
||
|
||
# Create .env from template
|
||
cp .env.example .env
|
||
|
||
# Configure your credentials
|
||
nano .env # or your favorite editor
|
||
```
|
||
|
||
## ⚙️ Configuration
|
||
|
||
Edit `.env` with your Antares credentials and output preferences:
|
||
|
||
```env
|
||
# Antares B2B API credentials
|
||
ANTARES_USERCODE=your_usercode
|
||
ANTARES_PASSWORD=your_password_hash
|
||
|
||
# Output path for Excel file
|
||
# - Directory: Creates 'antares.xlsx' inside
|
||
# - File path (*.xlsx): Creates file at exact location
|
||
OUT=out
|
||
```
|
||
|
||
### OUT Path Examples
|
||
|
||
```env
|
||
OUT=out # → out/antares.xlsx
|
||
OUT=exports/data.xlsx # → exports/data.xlsx
|
||
OUT=/tmp/antares/report.xlsx # → /tmp/antares/report.xlsx
|
||
```
|
||
|
||
## 🚀 Usage
|
||
|
||
```bash
|
||
# Build the project
|
||
cargo build --release
|
||
|
||
# Run the data exporter
|
||
cargo run
|
||
|
||
# Or run the compiled binary directly
|
||
./target/release/antares_get_data
|
||
```
|
||
|
||
### What Happens on Execution
|
||
|
||
1. ✅ **Initialization** - Logger created, output directory prepared
|
||
2. 🔐 **Credential Loading** - Env vars validated and loaded
|
||
3. 🌐 **API Request** - Fetches product data from Antares B2B (300s timeout)
|
||
4. 📊 **Data Processing** - Deserializes JSON into typed structs
|
||
5. 📝 **JSON Export** - Saves raw response to `antares.json`
|
||
6. 📋 **Excel Export** - Generates filtered, formatted Excel file
|
||
7. 📋 **Logging** - All events logged to `log/YYYY-MM-DD.log` + terminal
|
||
|
||
## 📋 Excel Output
|
||
|
||
The generated Excel file contains 8 columns of curated product data:
|
||
|
||
| Column | Source | Notes |
|
||
|--------|--------|-------|
|
||
| BESZCIKKSZAM | cikkszam | Product ID (required) |
|
||
| GYCIKKSZAM | cikkszam | Duplicate of BESZCIKKSZAM |
|
||
| BESZCIKKNEV | cikk_megnevezes_rovid / cikk_megnevezes | Product name (required) |
|
||
| GYARTO | Constant: "EGYEB" | Manufacturer code |
|
||
| CIKKAZON | vonalkod | Barcode (if available) |
|
||
| KESZLET | szabad_keszlet | Available stock |
|
||
| ME | mennyisegi_egyseg_kod | Unit of measure |
|
||
| EGYSEGAR | netto_kisker_ar / "Alap ár" | Net unit price |
|
||
|
||
**Filtering Rules:**
|
||
- Rows are skipped if `BESZCIKKSZAM` is empty
|
||
- Rows are skipped if both `BESZCIKKNEV` sources are empty
|
||
- Product name prefers short form (`cikk_megnevezes_rovid`), falls back to full form
|
||
- Unit price prefers direct field; searches `cikk_jellemzok` for "Alap ár" if zero
|
||
|
||
## 📁 Project Structure
|
||
|
||
```
|
||
antares_get_data/
|
||
├── src/
|
||
│ ├── main.rs # Pipeline orchestration
|
||
│ ├── api/
|
||
│ │ ├── mod.rs
|
||
│ │ └── client.rs # Antares B2B URL builder
|
||
│ ├── tools/
|
||
│ │ ├── mod.rs
|
||
│ │ ├── excel.rs # Excel export with field mapping
|
||
│ │ └── logger.rs # Dual-output logging system
|
||
│ └── template/
|
||
│ ├── mod.rs
|
||
│ └── antares.rs # Serde models for API schema
|
||
├── .env.example # Configuration template
|
||
├── Cargo.toml # Rust dependencies
|
||
└── README.md # This file
|
||
```
|
||
|
||
## 🏗️ Architecture
|
||
|
||
### Modular Design
|
||
|
||
- **`src/api/client.rs`** - Builds Antares B2B API URLs
|
||
- **`src/tools/excel.rs`** - Intelligent Excel export with business rules
|
||
- **`src/tools/logger.rs`** - Dual logging (terminal + file) to `log/{YYYY-MM-DD}.log`
|
||
- **`src/template/antares.rs`** - Serde models matching Antares B2B schema
|
||
- **`src/main.rs`** - Clean orchestration without implementation details
|
||
|
||
### Pipeline Flow
|
||
|
||
```
|
||
Load Env Vars
|
||
↓
|
||
Initialize Logger
|
||
↓
|
||
Build API URL
|
||
↓
|
||
Fetch from Antares B2B (300s timeout)
|
||
↓
|
||
Deserialize JSON → Save to antares.json
|
||
↓
|
||
Export Filtered Data → Excel (with logging)
|
||
↓
|
||
Log Summary + Results
|
||
```
|
||
|
||
## 📝 Logging
|
||
|
||
All operations are logged to two destinations simultaneously:
|
||
|
||
**Terminal Output:**
|
||
```
|
||
[2026-04-30 16:30:15] ℹ Starting Antares data export
|
||
[2026-04-30 16:30:22] ✓ API call successful - Fetched 142 items
|
||
[2026-04-30 16:30:25] ✓ Export successful - 142 rows exported to out/antares_export.xlsx
|
||
```
|
||
|
||
**Log Files:** `log/2026-04-30.log` (daily rotation)
|
||
|
||
## 🧪 Development
|
||
|
||
```bash
|
||
# Format code
|
||
cargo fmt --all -- --check
|
||
|
||
# Lint with Clippy
|
||
cargo clippy --all-targets -- -D warnings
|
||
|
||
# Run tests
|
||
cargo test
|
||
|
||
# Build optimized release
|
||
cargo build --release
|
||
```
|
||
|
||
## 📦 Generated Artifacts
|
||
|
||
After running, you'll find:
|
||
|
||
- **`antares.json`** - Full, pretty-printed API response
|
||
- **`out/antares_export.xlsx`** - Filtered Excel export (or custom path)
|
||
- **`log/YYYY-MM-DD.log`** - Daily operation log
|
||
|
||
All are automatically created and git-ignored.
|
||
|
||
## 🔐 Security Notes
|
||
|
||
- ✅ Credentials stored only in `.env` (git-ignored)
|
||
- ✅ `.env.example` documents required variables without secrets
|
||
- ✅ No hardcoded credentials in source code
|
||
- ✅ API passwords transmitted over HTTPS only
|
||
|
||
## 🐛 Troubleshooting
|
||
|
||
**Missing ANTARES_USERCODE error:**
|
||
```
|
||
Create .env file in repo root with:
|
||
ANTARES_USERCODE=your_code
|
||
ANTARES_PASSWORD=your_password
|
||
OUT=out
|
||
```
|
||
|
||
**Invalid OUT path error:**
|
||
```
|
||
Ensure OUT is either:
|
||
- A directory (created if missing): OUT=out
|
||
- A .xlsx file: OUT=export/data.xlsx
|
||
```
|
||
|
||
**API timeout:**
|
||
- Default timeout is 300 seconds (5 minutes)
|
||
- Check your network connection
|
||
- Verify Antares B2B service is available
|
||
|
||
## 📄 License
|
||
|
||
[Add your license here]
|
||
|
||
## 🤝 Contributing
|
||
|
||
Contributions welcome! Please follow the module structure and keep the architecture clean.
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
**Built with ❤️ for Antares B2B integration**
|
||
|
||
</div> |