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

generate.py              # CLI entry point (Click-based)
src/config_loader.py     # Loads config.json and schema.json
src/excel_reader.py      # Reads attendance data from Excel file
src/models.py            # Data models (participant, month, days)
src/validators.py        # Validation logic for Excel input data
src/pdf_filler.py        # Fills PDF form fields from model data
src/exceptions.py        # Custom exceptions for the entire pipeline

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

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.6 KiB Raw Blame History