SemesterapparatsManager/README.md

# SemesterapparatsManager

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PySide6](https://img.shields.io/badge/PySide6-Qt6-green.svg)](https://doc.qt.io/qtforpython/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

A comprehensive desktop application for managing semester course reserve collections (Semesterapparate) at the University of Education Freiburg. This tool streamlines the workflow of creating, managing, and maintaining both physical and digital course reserves, with integrated citation management powered by Zotero.

## 📋 Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Architecture](#architecture)
- [Installation](#installation)
- [Usage](#usage)
- [Development](#development)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [License](#license)

## 🎯 Overview

SemesterapparatsManager is a Python-based graphical application designed to simplify the complex workflow of academic course reserve management. It provides librarians and staff with tools to:

- **Manage Physical Reserves**: Track books, media, and materials reserved for courses
- **Handle Digital Collections**: Process, scan, and catalog digital course materials
- **Automate Citations**: Generate proper bibliographic citations using Zotero integration
- **Communicate**: Send automated emails to professors about reserve status
- **Analyze**: View statistics and search through historical data
- **Integrate**: Connect with library catalogs (SWB, DNB) and vendor APIs (Lehmanns)

### Key Technologies

- **Framework**: PySide6 (Qt6) for cross-platform GUI
- **Database**: SQLite with migration support
- **APIs**: Integration with SWB, DNB, Zotero, OpenAI, and catalog services
- **Document Processing**: Word, PDF, CSV, and XML parsing
- **Bibliography**: Zotero-based citation management

## ✨ Features

### Course Reserve Management

- **Create & Edit**: Add new semester apparatus with book and media entries
- **Extend Duration**: Extend existing reserves for additional semesters  
- **Smart Search**: Find reserves by semester, professor, subject, or signature
- **Availability Checking**: Automated checks against library catalog
- **New Edition Detection**: Background thread to find newer editions of books

### Digital Collection Features

- **Document Parsing**: Extract information from submitted Word/PDF forms
- **Smart Splitting**: Automatically split multi-part book sections
- **Citation Generation**: Create proper citations for all digital files
- **ELSA Integration**: Manage electronic semester apparatus (ELSA) workflows
- **File Management**: Track and recreate files from database

### Communication & Notifications

- **Email Templates**: Pre-configured templates for common scenarios
- **Professor Notifications**: Automated emails for creation, extension, or dissolution
- **Message System**: Attach messages to specific reserves or broadcast to all

### Data & Analytics

- **Statistics Dashboard**: Visualize creation and deletion trends
- **Advanced Search**: Multi-criteria search across all reserves
- **Export**: Generate reports and documentation
- **Calendar View**: Timeline of reserve activities

### Administration

- **User Management**: Create, edit, and delete system users
- **Professor Database**: Maintain professor contact information
- **Settings Configuration**: Customize database paths, temp directories, API keys
- **Backup & Migration**: Database migration support for schema updates

## 🏗️ Architecture

### Project Structure

```
SemesterapparatsManager/
├── src/
│   ├── core/              # Domain models & constants
│   │   ├── models.py      # BookData, Prof, Apparat, Semester, etc.
│   │   ├── constants.py   # Application constants
│   │   └── semester.py    # Semester handling logic
│   ├── database/          # Data persistence layer
│   │   ├── connection.py  # Database class & operations
│   │   ├── schemas.py     # SQL schema definitions
│   │   └── migrations/    # SQL migration files
│   ├── services/          # External API integrations
│   │   ├── catalogue.py   # RDS catalog scraping
│   │   ├── sru.py         # SWB/DNB library API client
│   │   ├── lehmanns.py    # Lehmanns bookstore API
│   │   ├── zotero.py      # Zotero integration
│   │   ├── webadis.py     # WebADIS automation
│   │   └── openai.py      # OpenAI API integration
│   ├── parsers/           # Document & file parsing
│   │   ├── csv_parser.py  # CSV parsing
│   │   ├── word_parser.py # Word document parsing
│   │   ├── pdf_parser.py  # PDF text extraction
│   │   ├── xml_parser.py  # XML parsing
│   │   └── transformers/  # Bibliography format conversion
│   ├── documents/         # Document generation
│   │   └── generators.py  # Word/PDF document creation
│   ├── background/        # Background tasks & threading
│   │   ├── autoadder.py   # Automatic book addition
│   │   ├── availability_checker.py  # Catalog availability
│   │   ├── book_grabber.py          # Catalog metadata retrieval
│   │   └── new_editions.py          # New edition detection
│   ├── ui/                # User interface components
│   │   ├── userInterface.py  # Main application window
│   │   ├── dialogs/       # Dialog windows
│   │   └── widgets/       # Reusable UI widgets
│   ├── admin/             # Administrative functions
│   │   └── commands.py    # Admin CLI commands
│   ├── utils/             # Utility functions
│   │   ├── files.py       # File operations
│   │   ├── sorting.py     # Custom sorting logic
│   │   └── blob.py        # Binary data handling
│   ├── shared/            # Cross-cutting concerns
│   │   ├── logging.py     # Centralized logging
│   │   └── config.py      # Configuration management
│   └── errors/            # Custom exceptions
│       └── database.py    # Database-specific errors
├── tests/                 # Test suite
├── docs/                  # Documentation
├── mail_vorlagen/         # Email templates
├── config.yaml            # Application configuration
├── main.py                # Application entry point
└── README.md
```

### Architecture Principles

**Layered Architecture**:
```
UI Layer (PySide6 Qt Widgets)
    ↓
Background Tasks (QThread workers)
    ↓
Business Logic (Core models & operations)
    ↓
Services Layer (External API integrations)
    ↓
Data Access Layer (Database & file operations)
```

**Key Design Patterns**:
- **Repository Pattern**: Database class abstracts data persistence
- **Service Layer**: External integrations isolated in `services/`
- **Observer Pattern**: Qt signals/slots for event-driven updates
- **Factory Pattern**: Document and citation generators
- **Strategy Pattern**: Multiple parsing strategies for different file formats

## 🚀 Installation

### Prerequisites

- Python 3.10 or higher
- [uv](https://github.com/astral-sh/uv) - Fast Python package installer and resolver (recommended)
  ```bash
  # Install uv (Windows PowerShell)
  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
  
  # Or using pip
  pip install uv
  ```

### Setup Steps (Using uv - Recommended)

1. **Clone the repository**:
   ```bash
   git clone https://github.com/yourusername/SemesterapparatsManager.git
   cd SemesterapparatsManager
   ```

2. **Create virtual environment and install dependencies**:
   ```bash
   # uv automatically creates venv and installs dependencies
   uv sync
   ```

3. **Configure application**:
   - First launch will present a setup wizard
   - Configure database path, temp directory, and API keys
   - Create admin user account

4. **Run the application**:
   ```bash
   uv run python main.py
   ```

### Alternative Setup (Using pip/venv)

<details>
<summary>Click to expand traditional pip installation steps</summary>

1. **Create virtual environment**:
   ```bash
   python -m venv .venv
   ```

2. **Activate virtual environment**:
   - Windows (PowerShell):
     ```powershell
     .venv\Scripts\Activate.ps1
     ```
   - Linux/Mac:
     ```bash
     source .venv/bin/activate
     ```

3. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

4. **Run the application**:
   ```bash
   python main.py
   ```

</details>

### Building Executable

To build a standalone executable:

```bash
# Using uv
uv run pyinstaller --noconfirm --onedir --windowed \
  --icon='icons/app.ico' \
  --name='SemesterapparatsManager' \
  --clean \
  --add-data='config.yaml;.' \
  --add-data='icons;icons' \
  main.py
```

Or use the provided build task (see `pyproject.toml`).

## 📖 Usage

### First Time Setup

1. **Launch Application**: Run `python main.py`
2. **Setup Wizard**: Configure basic settings
   - Database location
   - Temporary files directory
   - Library catalog credentials (optional)
   - API keys (Zotero, OpenAI - optional)
3. **Create Admin User**: Set up your admin credentials
4. **Login**: Use your credentials to access the main interface

### Creating a Semester Apparatus

1. **Navigate**: Main window → "Neuer Apparat" (New Apparatus)
2. **Fill Details**:
   - Semester (e.g., WiSe 2024/25)
   - Professor information
   - Course subject
   - Apparatus number
3. **Add Books**: Click "Buch hinzufügen" (Add Book)
   - Enter signature or search by title
   - System fetches metadata from catalog
   - Add multiple books as needed
4. **Add Media**: Click "Medium hinzufügen" (Add Media)
   - DVDs, CDs, or other media types
5. **Save**: Confirm and create the apparatus
6. **Generate Email**: Optionally send notification to professor

### Managing Digital Collections (ELSA)

1. **Upload Form**: Submit Word/PDF form with book chapter information
### Setting Up Development Environment

1. **Install all dependencies** (including dev dependencies):
   ```bash
   # Using uv (recommended)
   uv sync --all-extras
   
   # Or using pip
   pip install -r requirements-dev.txt
   ```

2. **Enable logging**:
   ```python
   from src.shared.logging import configure
   configure("DEBUG")  # In main.py
   ```

3. **Run tests**:
   ```bash
   # Using uv
   uv run pytest tests/
   
   # Or with activated venv
   pytest tests/
   ```ministrative Tasks

- **User Management**: Admin → Users → Create/Edit/Delete
- **Professor Database**: Admin → Professors → Manage contacts
- **System Settings**: Edit → Settings → Configure paths and APIs
- **Database Maintenance**: Admin → Database → Run migrations

## 🛠️ Development

### Setting Up Development Environment

1. **Install dev dependencies**:
   ```bash
   pip install -r requirements-dev.txt
   ```

2. **Enable logging**:
   ```python
   from src.shared.logging import configure
   configure("DEBUG")  # In main.py
   ```

3. **Run tests**:
   ```bash
   pytest tests/
   ```

### Project Standards

- **Code Style**: Follow PEP 8
- **Type Hints**: Use type annotations where possible
- **Docstrings**: Google-style docstrings for all public functions
- **Logging**: Use centralized logger from `src.shared.logging`
- **Imports**: Use new structure (see MIGRATION_GUIDE.md)

### Database Migrations

To create a new migration:

1. Create file: `src/database/migrations/V###__description.sql`
2. Use sequential numbering (V001, V002, etc.)
3. Write idempotent SQL (use `IF NOT EXISTS`)
4. Test migration on copy of production database

Example:
```sql
-- V003__add_user_preferences.sql
CREATE TABLE IF NOT EXISTS user_preferences (
    user_id INTEGER PRIMARY KEY,
    theme TEXT DEFAULT 'light',
    language TEXT DEFAULT 'de',
    FOREIGN KEY (user_id) REFERENCES user(id)
);
```

### Adding New Features

**New Service Integration**:
1. Create module in `src/services/`
2. Implement client class with proper error handling
3. Add to `src/services/__init__.py`
4. Document API requirements

**New Document Parser**:
1. Create module in `src/parsers/`
2. Implement parsing function returning core models
3. Add to `src/parsers/__init__.py`
4. Write unit tests

**New UI Dialog**:
1. Design in Qt Designer (`.ui` file)
2. Convert: `pyside6-uic dialog.ui -o dialog_ui.py`
3. Create dialog class in `src/ui/dialogs/`
4. Connect signals to business logic
### Building Documentation

```bash
# Using uv
uv run mkdocs build
uv run mkdocs serve  # View at http://localhost:8000

# Or with activated venv
mkdocs build
mkdocs serve
```*[API Documentation](docs/)**: Detailed module documentation
- **[User Manual](docs/index.md)**: Complete user guide (MkDocs)

### Building Documentation

```bash
mkdocs build
mkdocs serve  # View at http://localhost:8000
```

## 🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Commit** your changes (`git commit -m 'Add amazing feature'`)
4. **Push** to the branch (`git push origin feature/amazing-feature`)
5. **Open** a Pull Request

### Code Review Checklist

- [ ] Code follows project style guidelines
- [ ] All tests pass
- [ ] New features have tests
- [ ] Documentation is updated
- [ ] No sensitive data in commits
- [ ] Import paths use new structure

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- **University of Education Freiburg**: Project sponsor and primary user
- **Qt/PySide6**: Excellent cross-platform GUI framework
- **Zotero**: Citation management integration
- **SWB/DNB**: Library catalog services

## 📞 Support

For questions, issues, or feature requests:
- **Issues**: [Gitea Issues](https://git.theprivateserver.de/PHB/SemesterapparatsManager/issues)
- **Email**: alexander.kirchner@ph-freiburg.de
- **Documentation**: [Read the Docs](https://semesterapparatsmanager.readthedocs.io)

## 🗺️ Roadmap

TBD
---

**Built with ❤️ for academic libraries**