kniha_jizd_web/README.md

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)

./start.sh docker

Option 2: Local Development

Prerequisites:

• Python 3.11+
• Node.js 20+

Setup:

# 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

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

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

# 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