parent
4e94827206
commit
d81e3dcb34
|
|
@ -0,0 +1,21 @@
|
|||
MIT License
|
||||
|
||||
Copyright (c) 2026 Orink Hungary Kft.
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
283
README.md
283
README.md
|
|
@ -1,256 +1,71 @@
|
|||
# 🐙 Antares Data Exporter
|
||||
|
||||
<div align="center">
|
||||
|
||||
# Antares Data Exporter
|
||||
|
||||
|
||||
|
||||
**A powerful Rust utility for fetching Antares B2B product data and exporting to Excel**
|
||||
|
||||
[Features](#features) • [Installation](#installation) • [Usage](#usage) • [Configuration](#configuration) • [Architecture](#architecture)
|
||||
Rust utility to fetch product data from Antares B2B and export to Excel.
|
||||
|
||||
</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
|
||||
## Quick Start
|
||||
|
||||
```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
|
||||
# Edit .env with your credentials and output path
|
||||
cargo build --release
|
||||
|
||||
# Run the data exporter
|
||||
cargo run
|
||||
|
||||
# Or run the compiled binary directly
|
||||
./target/release/antares_get_data
|
||||
```
|
||||
|
||||
### What Happens on Execution
|
||||
## Configuration
|
||||
|
||||
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
|
||||
`.env` file:
|
||||
```env
|
||||
ANTARES_USERCODE=your_usercode
|
||||
ANTARES_PASSWORD=your_password_hash
|
||||
OUT=out
|
||||
```
|
||||
|
||||
**Invalid OUT path error:**
|
||||
```
|
||||
Ensure OUT is either:
|
||||
- A directory (created if missing): OUT=out
|
||||
- A .xlsx file: OUT=export/data.xlsx
|
||||
`OUT` can be:
|
||||
- Directory: `out` → creates `out/antares.xlsx`
|
||||
- File path: `exports/data.xlsx` → creates file there
|
||||
- Must be `.xlsx` extension if file path
|
||||
|
||||
## How It Works
|
||||
|
||||
1. Load credentials from `.env`
|
||||
2. Fetch product data from Antares B2B API (300s timeout)
|
||||
3. Save raw JSON to `antares.json`
|
||||
4. Export filtered data to Excel
|
||||
5. Log all operations to `log/YYYY-MM-DD.log`
|
||||
|
||||
## Excel Output
|
||||
|
||||
8 columns with selective field mapping and row filtering:
|
||||
|
||||
| Column | Source |
|
||||
|--------|--------|
|
||||
| BESZCIKKSZAM | [cikkszam](./src/template/antares.rs#L15) (required) |
|
||||
| GYCIKKSZAM | [cikkszam](./src/template/antares.rs#L15) |
|
||||
| BESZCIKKNEV | [cikk_megnevezes_rovid](./src/template/antares.rs#L14) or [cikk_megnevezes](./src/template/antares.rs#L13) (required) |
|
||||
| GYARTO | "EGYEB" |
|
||||
| CIKKAZON | [vonalkod](./src/template/antares.rs#L26) |
|
||||
| KESZLET | [szabad_keszlet](./src/template/antares.rs#L22) |
|
||||
| ME | [mennyisegi_egyseg_kod](./src/template/antares.rs#L17) |
|
||||
| EGYSEGAR | [netto_kisker_ar](./src/template/antares.rs#L19) or "Alap ár" [jellemzo](./src/template/antares.rs#L34) |
|
||||
|
||||
Rows skipped if `cikkszam` or product name missing.
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
cargo build
|
||||
cargo fmt --all -- --check
|
||||
cargo clippy --all-targets -- -D warnings
|
||||
cargo test
|
||||
```
|
||||
|
||||
**API timeout:**
|
||||
- Default timeout is 300 seconds (5 minutes)
|
||||
- Check your network connection
|
||||
- Verify Antares B2B service is available
|
||||
## License
|
||||
|
||||
## 📄 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>
|
||||
MIT License © 2026 Orink Hungary Kft.
|
||||
|
|
|
|||
Loading…
Reference in New Issue