Initial commit - Journey book (kniha jízd) automation system

Features: - FastAPI backend for scraping attendance and journey book data - Deterministic kilometer distribution with random variance - Refueling form filling with km values - Next.js frontend with date range selector - Docker deployment setup 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-10 15:41:11 +02:00
commit 3b5d9fd940
40 changed files with 3777 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,166 @@
+# Kniha Jízd - Journey Book Management System
+
+Modern web application for automated journey book management with data scraping, calculation, and Excel export.
+
+## Features
+
+✅ **Web Interface** - Modern React/Next.js UI
+✅ **Data Scraping** - Automatic attendance & journey data fetching
+✅ **Smart Calculation** - Random kilometer distribution with configurable variance
+✅ **Excel Export** - Download processed data
+✅ **Sick Day Filtering** - Automatic exclusion of vacation/sick days
+✅ **Fuel Tracking** - Refueling entry management
+
+## Tech Stack
+
+- **Backend:** FastAPI (Python 3.11+)
+- **Frontend:** Next.js 15 + TypeScript + Tailwind CSS
+- **Data Processing:** Pandas, NumPy
+- **Scraping:** BeautifulSoup4, Requests
+
+## Quick Start
+
+### Option 1: Docker (Recommended)
+
+```bash
+./start.sh docker
+```
+
+### Option 2: Local Development
+
+**Prerequisites:**
+- Python 3.11+
+- Node.js 20+
+
+**Setup:**
+
+```bash
+# 1. Install backend dependencies
+cd backend
+pip install -r requirements.txt
+
+# 2. Configure credentials
+cp .env.example .env
+nano .env  # Edit with your credentials
+
+# 3. Install frontend dependencies
+cd ../frontend
+npm install
+
+# 4. Start both services
+cd ..
+./start.sh
+```
+
+**Access:**
+- 📊 Frontend: http://localhost:3000 (or http://YOUR_SERVER_IP:3000)
+- 🔧 Backend API: http://localhost:8000 (or http://YOUR_SERVER_IP:8000)
+- 📖 API Docs: http://localhost:8000/docs
+
+**For external access:** See [NETWORK_SETUP.md](NETWORK_SETUP.md)
+
+## Usage
+
+1. **Enter Credentials** - Company login details
+2. **Select Month** - Choose period to process
+3. **Set Kilometers** - Starting and ending odometer values
+4. **Configure Vehicle** - SPZ registration (default: 4SH1148)
+5. **Adjust Variance** - Random distribution factor (0.1 = 10%)
+6. **Calculate** - Preview processed data
+7. **Export** - Download Excel file
+
+## API Endpoints
+
+### `POST /api/scrape/attendance`
+Scrape attendance data for sick/vacation days
+
+### `POST /api/scrape/journeybook`
+Scrape journey book entries
+
+### `POST /api/calculate`
+Full pipeline: scrape → filter → calculate
+
+### `POST /api/export/excel`
+Generate and download Excel file
+
+## Project Structure
+
+```
+kniha_jizd/
+├── backend/
+│   ├── api/
+│   │   └── main.py          # FastAPI endpoints
+│   ├── scrapers/
+│   │   ├── attendance_scraper.py
+│   │   └── journeybook_scraper.py
+│   ├── calculators/
+│   │   └── kilometer_calculator.py
+│   ├── models/
+│   │   └── journey.py       # Pydantic models
+│   └── requirements.txt
+├── frontend/
+│   ├── app/
+│   │   ├── components/
+│   │   │   ├── JourneyForm.tsx
+│   │   │   └── DataPreview.tsx
+│   │   ├── page.tsx         # Main page
+│   │   └── layout.tsx
+│   └── package.json
+├── old/                     # Original scripts (archived)
+├── docker-compose.yml
+└── start.sh
+```
+
+## Configuration
+
+### Backend `.env`
+
+```env
+USERNAME=your_username
+PASSWORD=your_password
+VEHICLE_REGISTRATION=4SH1148
+```
+
+### Variance Parameter
+
+Controls kilometer distribution randomness:
+- `0.0` - Equal distribution
+- `0.1` - 10% variance (recommended)
+- `0.2` - 20% variance (more random)
+
+## Future Enhancements (Phase 2)
+
+- 📊 Dashboard with statistics
+- 📈 Fuel efficiency charts
+- 💰 Cost tracking
+- 🗺️ Route history
+- 📑 PDF reports
+- 🔐 User authentication
+- 💾 Database persistence
+
+## Migrated Features
+
+All functionality from original 3-script pipeline:
+1. ✅ `knihajizd.py` → `scrapers/`
+2. ✅ `fill_table.py` → `calculators/`
+3. ✅ `fill_web.py` → Future: Playwright automation
+
+## Development
+
+```bash
+# Backend hot reload
+cd backend
+uvicorn api.main:app --reload
+
+# Frontend hot reload
+cd frontend
+npm run dev
+
+# Build for production
+npm run build
+npm start
+```
+
+## License
+
+MIT