# Zeugnis-System - Architecture Documentation

## Overview

The Zeugnis (Certificate) System enables schools to generate official school certificates with grades, attendance data, and remarks. It extends the existing School-Service with comprehensive grade management and certificate generation workflows.

## Architecture Diagram

```
                                         ┌─────────────────────────────────────┐
                                         │      Python Backend (Port 8000)     │
                                         │   backend/frontend/modules/school.py │
                                         │                                     │
                                         │  ┌─────────────────────────────────┐ │
                                         │  │   panel-school-certificates     │ │
                                         │  │   - Klassenauswahl              │ │
                                         │  │   - Notenspiegel                │ │
                                         │  │   - Zeugnis-Wizard (5 Steps)    │ │
                                         │  │   - Workflow-Status             │ │
                                         │  └─────────────────────────────────┘ │
                                         └──────────────────┬──────────────────┘
                                                            │
                                                            ▼
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│                              School-Service (Go, Port 8084)                              │
├─────────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                         │
│  ┌─────────────────────┐  ┌─────────────────────┐  ┌─────────────────────────────────┐  │
│  │  Grade Handlers     │  │ Statistics Handlers │  │    Certificate Handlers         │  │
│  │                     │  │                     │  │                                 │  │
│  │ GetClassGrades      │  │ GetClassStatistics  │  │ GetCertificateTemplates         │  │
│  │ GetStudentGrades    │  │ GetSubjectStatistics│  │ GetClassCertificates            │  │
│  │ UpdateOralGrade     │  │ GetStudentStatistics│  │ GenerateCertificate             │  │
│  │ CalculateFinalGrades│  │ GetNotenspiegel     │  │ BulkGenerateCertificates        │  │
│  │ LockFinalGrade      │  │                     │  │ FinalizeCertificate             │  │
│  │ UpdateGradeWeights  │  │                     │  │ GetCertificatePDF               │  │
│  └─────────────────────┘  └─────────────────────┘  └─────────────────────────────────┘  │
│                                                                                         │
└─────────────────────────────────────────────────────────────────────────────────────────┘
                                                            │
                                                            ▼
                                         ┌─────────────────────────────────────┐
                                         │         PostgreSQL Database          │
                                         │                                     │
                                         │  Tables:                            │
                                         │  - grade_overview                   │
                                         │  - exam_results                     │
                                         │  - students                         │
                                         │  - classes                          │
                                         │  - subjects                         │
                                         │  - certificates                     │
                                         │  - attendance                       │
                                         └─────────────────────────────────────┘
```

## Zeugnis Workflow (Role Chain)

The certificate workflow follows a strict approval chain from subject teachers to school principal:

```
┌──────────────────┐    ┌──────────────────┐    ┌────────────────────────┐    ┌────────────────────┐    ┌──────────────────┐
│   FACHLEHRER     │───▶│  KLASSENLEHRER   │───▶│  ZEUGNISBEAUFTRAGTER   │───▶│    SCHULLEITUNG    │───▶│   SEKRETARIAT    │
│   (Subject       │    │  (Class          │    │  (Certificate          │    │    (Principal)     │    │   (Secretary)    │
│   Teacher)       │    │   Teacher)       │    │   Coordinator)         │    │                    │    │                  │
└──────────────────┘    └──────────────────┘    └────────────────────────┘    └────────────────────┘    └──────────────────┘
        │                       │                         │                           │                        │
        ▼                       ▼                         ▼                           ▼                        ▼
   Grades Entry            Approve               Quality Check              Sign-off & Lock            Print & Archive
   (Oral/Written)          Grades                 & Review
```

### Workflow States

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   DRAFT     │────▶│  SUBMITTED  │────▶│  REVIEWED   │────▶│   SIGNED    │────▶│   PRINTED   │
│   (Entwurf) │     │ (Eingereicht)│    │ (Geprueft)  │     │(Unterzeichnet)    │ (Gedruckt)  │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
      │                   │                   │                   │
      ▼                   ▼                   ▼                   ▼
  Fachlehrer        Klassenlehrer      Zeugnisbeauftragter   Schulleitung
```

## RBAC Integration

### Certificate-Related Roles

| Role | German | Description |
|------|--------|-------------|
| `FACHLEHRER` | Fachlehrer | Subject teacher - enters grades |
| `KLASSENLEHRER` | Klassenlehrer | Class teacher - approves class grades |
| `ZEUGNISBEAUFTRAGTER` | Zeugnisbeauftragter | Certificate coordinator - quality control |
| `SCHULLEITUNG` | Schulleitung | Principal - final sign-off |
| `SEKRETARIAT` | Sekretariat | Secretary - printing & archiving |

### Certificate Resource Types

| ResourceType | Description |
|--------------|-------------|
| `ZEUGNIS` | Final certificate document |
| `ZEUGNIS_VORLAGE` | Certificate template (per Bundesland) |
| `ZEUGNIS_ENTWURF` | Draft certificate (before approval) |
| `FACHNOTE` | Subject grade |
| `KOPFNOTE` | Head grade (Arbeits-/Sozialverhalten) |
| `BEMERKUNG` | Certificate remarks |
| `STATISTIK` | Class/subject statistics |
| `NOTENSPIEGEL` | Grade distribution chart |

## German Grading System

| Grade | Meaning | Points |
|-------|---------|--------|
| 1 | sehr gut (excellent) | 15-13 |
| 2 | gut (good) | 12-10 |
| 3 | befriedigend (satisfactory) | 9-7 |
| 4 | ausreichend (adequate) | 6-4 |
| 5 | mangelhaft (poor) | 3-1 |
| 6 | ungenuegend (inadequate) | 0 |

### Grade Calculation

```
Final Grade = (Written Weight * Written Avg) + (Oral Weight * Oral Avg)

Default weights:
- Written (Klassenarbeiten): 50%
- Oral (muendliche Note): 50%

Customizable per subject/student via UpdateGradeWeights endpoint.
```

## API Routes (School-Service)

### Grade Management

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/school/grades/:classId` | Get class grades |
| GET | `/api/v1/school/grades/student/:studentId` | Get student grades |
| PUT | `/api/v1/school/grades/:studentId/:subjectId/oral` | Update oral grade |
| POST | `/api/v1/school/grades/calculate` | Calculate final grades |
| PUT | `/api/v1/school/grades/:studentId/:subjectId/lock` | Lock final grade |

### Statistics

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/school/statistics/:classId` | Class statistics |
| GET | `/api/v1/school/statistics/:classId/subject/:subjectId` | Subject statistics |
| GET | `/api/v1/school/statistics/student/:studentId` | Student statistics |
| GET | `/api/v1/school/statistics/:classId/notenspiegel` | Grade distribution |

### Certificates

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/school/certificates/templates` | List templates |
| GET | `/api/v1/school/certificates/class/:classId` | Class certificates |
| POST | `/api/v1/school/certificates/generate` | Generate single |
| POST | `/api/v1/school/certificates/generate-bulk` | Generate bulk |
| GET | `/api/v1/school/certificates/detail/:id/pdf` | Download PDF |

## Security Considerations

1. **RBAC Enforcement**: All certificate operations check user role permissions
2. **Tenant Isolation**: Teachers only see their own classes/students
3. **Audit Trail**: All grade changes and approvals logged
4. **Lock Mechanism**: Finalized certificates cannot be modified
5. **Workflow Enforcement**: Cannot skip approval steps