Add CLAUDE.md, MkDocs docs, .claude/rules
- CLAUDE.md: Comprehensive documentation for Lehrer KI platform - docs-src: Klausur, Voice, Agent-Core, KI-Pipeline docs - mkdocs.yml: Lehrer-specific nav with blue theme - docker-compose: Added docs service (port 8010, profile: docs) - .claude/rules: testing, docs, open-source, abiturkorrektur, vocab-worksheet, multi-agent, experimental-dashboard Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Benjamin Boenisch
169
docs-src/architecture/zeugnis-system.md
Normal file
169
docs-src/architecture/zeugnis-system.md
Normal file
@@ -0,0 +1,169 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user