3b5d9fd940
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>
167 lines
4.0 KiB
Markdown
167 lines
4.0 KiB
Markdown
# 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
|