76 lines
2.6 KiB
Markdown
76 lines
2.6 KiB
Markdown
# 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
|
|
```bash
|
|
python3 -m venv venv
|
|
source venv/bin/activate
|
|
pip install -r requirements-dev.txt # includes pytest
|
|
```
|
|
|
|
### CLI Usage (Click-based)
|
|
```bash
|
|
# Main entry point
|
|
python generate.py <command>
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
1. Update `./schema.json` first (single source of truth) and config.json if needed
|
|
2. Run tests after any edit: `pytest tests/ -v`
|
|
3. Check CLI still works: `python fill_pdf.py validate`
|
|
4. Never modify test data files in `data/` directory
|
|
5. 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
|