AI Agent Instructions - Attendance PDF Generator

Project Overview

Excel → PDF converter for German attendance lists. Reads attendance data from multi-sheet Excel files (monthly) and generates personalized PDF reports with form filling. Critical: This is a professional Windows terminal project for business use.

Architecture & Data Flow

Core Components


### PDF Structure (Form Fields)
- `person.name`: Person's full name
- `monat_jahr`: Month/Year in format "MM/YYYY"
- `datum.0` through `datum.22`: Date fields (23 rows max)
- `anwesend.0` through `anwesend.22`: Dropdown fields (X, K, KK, E, F, P, U)
- `plan.0-22`, `ist.0-22`: Hours fields (controlled by JavaScript - see below)

## Development Workflows

### Setup
```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements-dev.txt  # includes pytest

CLI Usage (Click-based)

# Main entry point
python generate.py <command>

Testing

pytest tests/ -v

Test philosophy: File-independent. Tests validate config mappings and business logic, NOT specific Excel files. Never hardcode "Max, Mustermann" or specific filenames in tests.

Code Inspection Tools

python src/test_pdf_fields.py  # Inspect PDF template fields (creates TEST_FIELDS.pdf)

Code Conventions

Configuration Over Code

Config, settings, temporals and any kind of Data must be read from and written into json files in the directory /data

Language & Style

All config labels/descriptions: German only
Code comments: English
User-facing messages: German preferred

When Making Changes

Update ./schema.json first (single source of truth) and config.json if needed
Run tests after any edit: pytest tests/ -v
Check CLI still works: python fill_pdf.py validate
Never modify test data files in data/ directory
Git commit messages: Describe business logic changes, not just code changes

Questions Before Implementing

Per project conventions (.github/instructions/main.instructions.md):

Ask clarifying questions instead of guessing
Suggest step-by-step approach rather than implementing everything at once
Confirm understanding of business requirements before coding

2.2 KiB Raw Blame History