open_workshop/README.md

# Open Workshop

**POS-basiertes Maschinenfreigabe- und Werkstattverwaltungssystem für Odoo**

Open Workshop ist eine modulare Erweiterung des Odoo POS-Systems zur Verwaltung von einweisungspflichtigen Maschinen und Geräten in Werkstätten, Makerspaces und FabLabs. Das System ermöglicht die Verwaltung von Maschinenfreigaben, Einweisungen und Equipment-Dokumentation.

---

## Hauptfunktionen

- **Maschinenfreigaben**: Verwaltung von kundenspezifischen Freigaben für einweisungspflichtige Geräte
- **Sicherheitskategorien**: Dreistufiges Kategoriesystem (grün/gelb/rot) für unterschiedliche Einweisungspflichten
- **POS-Integration**: Verkauf von Einweisungen und Anzeige von Maschinenfreigaben direkt am Point of Sale
- **Equipment-Verwaltung**: Vollständige Integration mit dem OCA Maintenance-Modul

- **Dokumentation**: Automatische Synchronisation von Equipment-Daten mit DokuWiki
- **Mitarbeiter-Display**: Dynamische Anzeige von Mitarbeiterdaten im POS Customer Display

---

## Module

### open_workshop_base
**Kernmodul** - Stellt die Basis-Funktionalität für das gesamte System bereit.

**Hauptfunktionen:**
- Maschinenmodelle mit Sicherheitskategorien (grün/gelb/rot)
- Bereiche (z.B. Holz, Metall, FabLab)
- Freigabeverwaltung (wer darf welche Maschine nutzen)
- Produktverknüpfungen für Einweisungen und Nutzung
- Integration mit OCA maintenance.equipment als Single Source of Truth

**Datenmodelle:**
- `ows.user` - Benutzerdaten (RFID, Geburtstag, Sicherheitsunterweisung)
- `ows.machine.area` - Maschinenbereiche mit Farbkodierung
- `ows.machine` - Maschinen (nutzt _inherits Pattern mit maintenance.equipment)
- `ows.machine.access` - Freigaben (Partner ↔ Maschine)
- `ows.machine.product` - Nutzungsprodukte für Maschinen
- `ows.machine.training` - Einweisungsprodukte für Maschinen

**Abhängigkeiten:** 
- OCA `maintenance` (Basis-Equipment-Verwaltung)
- OCA `maintenance_equipment_status` (Equipment-Statusverwaltung)

  ```bash
  git clone https://github.com/OCA/maintenance.git
  cd maintenance
  git reset --hard 5510275e
  ```

---

### open_workshop_pos
**POS-Integration** - Erweitert den Odoo Point of Sale um Maschinenfreigabe-Funktionalität.

**Hauptfunktionen:**
- **Machine Access List**: Übersichtsanzeige aller verfügbaren Maschinen welche Einweisungspflichtig sind, mit Freigabestatus für den aktuellen Kunden (roter Punkt)
- **Customer Sidebar**: Kundenspezifische Maschinenfreigaben am POS
- **POS Sidebar**: Maschinenauswahl und Statusanzeige
- **Automatische Freigabenvergabe**: Beim Verkauf eines Einweisungsprodukts wird dem Kunden automatisch die Freigabe für das zugehörige Gerät in der Datenbank erteilt

**Verwendungszweck:**
Verkauf von Maschineneinweisungen und Anzeige bestehender Freigaben direkt am Kassensystem. Ermöglicht schnelle Prüfung, welcher Kunde auf welche einweisungspflichtigen Geräte zugreifen darf.

**Abhängigkeiten:**
- `open_workshop_base`
- `point_of_sale`

---

### open_workshop_pos_customer_display
**Mitarbeiter-Display** - Zeigt dynamisches Mitarbeiter-Namensschild im POS Customer Display.

**Hauptfunktionen:**
- Anzeige von Mitarbeiterfoto (generiert durch open_workshop_employee_imagegenerator)
- Darstellung von Name und Schwerpunkten (job_focus)
- Automatische Aktualisierung bei Kassiererwechsel
- Responsive Design mit Fallback auf Company-Logo

**Verwendungszweck:**
Darstellung der Mitarbeitenden am Kundendisplay, verbessert die Kundeninteraktion und Transparenz.

**Abhängigkeiten:**
- `point_of_sale`
- `hr`

---

### open_workshop_dokuwiki
**DokuWiki-Integration** - Synchronisiert Equipment-Daten aus Odoo mit einem DokuWiki-System.

**Hauptfunktionen:**
- Automatische Erstellung von Wiki-Seiten für Equipment
- Übersichtstabelle aller Equipment (DataTables mit Sortierung/Filterung)
- Status-Seiten für Include-Plugin (nur von Odoo generiert, read-only)
- Smart Button "Wiki öffnen" im Equipment-Formular
- Automatische Synchronisation bei Equipment-Änderungen

**Architektur-Prinzip:**
- Odoo generiert **NUR** `odoo-status/` Seiten (maschinengeneriert, read-only)
- Benutzer erstellen eigene Dokumentation in `{bereich}/` Namespaces
- Einbindung der Odoo-Daten via DokuWiki Include-Plugin

**Verwendungszweck:**
Zentrale Dokumentation aller Geräte mit automatisch aktualisiertem Status aus Odoo, kombiniert mit benutzergenerierten Anleitungen und Wartungshinweisen.

**Abhängigkeiten:**
- `open_workshop_base`
- `maintenance`
- `maintenance_equipment_status`

---

### 🎨 open_workshop_employee_imagegenerator
**Mitarbeiterfoto-Generator** - Upload und Zuschnitt von Mitarbeiterfotos direkt in Odoo.

**Hauptfunktionen:**
- Upload und Zuschnitt von Fotos auf festes Format (369x492 Pixel)
- Hinzufügen von Schwerpunktbereichen (job_focus)
- Integrierter Cropper.js für professionelle Bildbearbeitung
- Fester Crop-Frame (nur Bild bewegt sich, nicht der Rahmen)
- Integration im Employee-Formular über Button "Namensschild erstellen"

**Verwendungszweck:**
Erstellung von professionellen Mitarbeiterfotos für das POS Customer Display. Vereinfacht den Workflow durch direkten Upload in Odoo ohne externe Bildbearbeitung.

**Abhängigkeiten:**
- `hr`
- `web`

---

## Architektur & Datenfluss

### Datenmodell-Übersicht

```
┌─────────────────────────────────────────────────────────────┐
│                    OCA maintenance.equipment                 │
│  (Single Source of Truth für name, serial_no, cost, etc.)   │
└──────────────────────┬──────────────────────────────────────┘
                       │ _inherits (Delegation Pattern)
                       │
                       ▼
              ┌────────────────┐
              │  ows.machine   │ ◄────────┐
              │ (OWS-Features) │          │
              └────┬───────────┘          │
                   │                      │
         ┌─────────┼──────────────────────┤
         │         │                      │
         │         ▼                      │
         │  ┌──────────────────┐         │
         │  │ ows.machine.area │         │
         │  │   (Bereiche)     │         │
         │  └──────────────────┘         │
         │                                │
         ▼                                │
┌──────────────────┐            ┌────────┴─────────┐
│ ows.machine.     │            │ ows.machine.     │
│   product        │            │   training       │
│ (Nutzung)        │            │ (Einweisung)     │
└──────────────────┘            └──────────────────┘

┌──────────────────┐            ┌──────────────────┐
│  res.partner     │            │  ows.user        │
│  (Kunde)         │◄───────────│ (Benutzerdaten)  │
└────────┬─────────┘  1:1       └──────────────────┘
         │
         │ M:N
         │
         ▼
┌──────────────────┐            ┌──────────────────┐
│ ows.machine.     │            │  ows.machine     │
│   access         │───────────►│                  │
│ (Freigaben)      │            │                  │
└──────────────────┘            └──────────────────┘
```

### _inherits Pattern Erklärung

Das Modul nutzt das Odoo **_inherits Pattern** (Delegation/Prototypische Vererbung) für `ows.machine`:

**Wie es funktioniert:**
- `ows.machine` delegiert Basis-Felder an `maintenance.equipment`
- Beim Erstellen einer `ows.machine` wird automatisch ein `maintenance.equipment` erstellt
- Felder wie `name`, `serial_no`, `cost`, `location` werden direkt von equipment übernommen
- **Keine Datenduplizierung!** Ein Equipment-Datensatz, zwei Modell-Sichten

**Vorteile:**
- `maintenance.equipment` bleibt die **Single Source of Truth** für Stammdaten
- Kompatibilität mit allen OCA Maintenance-Modulen
- `ows.machine` fügt nur OWS-spezifische Felder hinzu (category, area_id, etc.)
- Nahtlose Integration in bestehendes Maintenance-System

**Beispiel:**
```python
class OwsMachine(models.Model):
    _name = 'ows.machine'
    _inherits = {'maintenance.equipment': 'equipment_id'}
    
    equipment_id = fields.Many2one('maintenance.equipment', required=True, ondelete='cascade')
    category = fields.Selection(...)  # OWS-spezifisch
    area_id = fields.Many2one(...)    # OWS-spezifisch
```

Beim Zugriff auf `machine.name` wird automatisch `machine.equipment_id.name` zurückgegeben.

---

## 🔄 Modul-Zusammenhänge

### Installation & Abhängigkeiten

```
OCA maintenance ─────┐
OCA maintenance_     │
  equipment_status ──┤
                     ▼
            open_workshop_base ◄──────────┐
                     │                     │
         ┌───────────┼─────────────┐      │
         │           │             │      │
         ▼           ▼             ▼      │
  open_workshop  open_workshop  open_workshop
      _pos       _dokuwiki   _employee_
                              imagegenerator
         │                         │
         ▼                         │
  open_workshop_pos_              │
  customer_display ◄───────────────┘
```

**Installation:**

Die OCA Module `maintenance` und `maintenance_equipment_status` müssen im `addons_path` verfügbar sein. Sie werden automatisch mit installiert, wenn `open_workshop_base` installiert wird (siehe `depends` in der `__manifest__.py`).

  ```bash
  git clone https://github.com/OCA/maintenance.git
  cd maintenance
  git reset --hard 5510275e
  ```

**Installationsreihenfolge:**
1. `open_workshop_base` (Kernmodul - installiert OCA-Abhängigkeiten automatisch)
2. Optionale Module je nach Bedarf:
   - `open_workshop_pos` für POS-Integration
   - `open_workshop_dokuwiki` für Wiki-Dokumentation
   - `open_workshop_employee_imagegenerator` für Mitarbeiterfotos
   - `open_workshop_pos_customer_display` für Customer Display (benötigt imagegenerator)

---

## 🛠️ Entwicklungshinweise

### Wo finde ich was?

#### open_workshop_base
- **Models**: `/models/ows_models.py` - Alle Kern-Datenmodelle
- **Views**: `/views/` - Backend-Ansichten (Form, Tree, Kanban)
  - Erweiterte Views:
    - `res.partner` (Kontakte): Formular, Listenansicht - Maschinenfreigaben-Tab
    - `maintenance.equipment`: Formular, Listenansicht, Suchansicht - OWS-Felder
- **Security**: `/security/ir.model.access.csv` - Zugriffsrechte
- **Data**: `/data/` - Stammdaten (Equipment-Status, Bereiche)

#### open_workshop_pos
- **JavaScript**: `/static/src/js/` - POS Frontend-Logik
  - `ows_pos_sidebar.js` - POS Maschinensidebar
  - `ows_pos_customer_sidebar.js` - Kundensidebar
  - `ows_machine_access_list.js` - Zugriffsliste
- **Templates**: `/static/src/xml/` - OWL Templates für POS UI
- **Models**: `/models/pos_order.py` - POS Order Extensions

#### open_workshop_dokuwiki
- **Models**: `/models/`
  - `dokuwiki_client.py` - DokuWiki XML-RPC Client
  - `maintenance_equipment.py` - Equipment Extensions
- **Views**: `/views/`
  - Erweiterte Views:
    - `maintenance.equipment`: Smart Button "Wiki öffnen"
    - `maintenance.equipment.status`: DokuWiki-Synchronisation
- **Wizard**: `/wizard/` - Synchronisations-Assistenten

#### open_workshop_employee_imagegenerator
- **JavaScript**: `/static/src/js/employee_image_widget.js` - Cropper Widget
- **Templates**: `/static/src/xml/employee_image_widget.xml` - Widget UI
- **Views**: `/views/`
  - Erweiterte Views:
    - `hr.employee`: Button "Namensschild erstellen" im Formular
- **CSS**: `/static/src/css/` - Badge-Styling
- **Library**: `/static/lib/cropperjs/` - Cropper.js Integration

#### open_workshop_pos_customer_display
- **JavaScript**: `/static/src/js/customer_display.js` - Display-Logik
- **CSS**: `/static/src/css/employee_badge.css` - Badge-Styling

### Wichtige Methoden & RPC Calls

#### open_workshop_base
- `ows.machine.get_access_list_grouped(partner_id)` - Gruppierte Zugriffsliste für POS
  - Liefert alle Bereiche mit Maschinen und Zugriffssstatus für einen Partner
  - Wird vom POS Frontend verwendet

#### res.partner Extensions
- `machine_access_ids` - One2many zu allen Freigaben
- `machine_access_html` - Computed HTML-Tabelle für Backend-Ansicht im Res.partner / Kontakt Formular 
- `ows_user_id` - One2many zu ows.user (Benutzerdaten)

### Erweiterung des Systems

**Neue Sicherheitskategorie hinzufügen:**
1. In `ows_models.py` → `OwsMachine.category` Selection erweitern
2. Icon-Mapping in `_compute_category_icon()` aktualisieren
3. CSS in `/static/src/css/category_color.css` ergänzen

**Neuen Maschinenbereich erstellen:**
- Im Backend: **Wartung → Konfiguration → Bereiche**
- Oder via Data-File in `/data/` für Standardbereiche

**POS-UI anpassen:**
- OWL Templates in `/static/src/xml/` bearbeiten
- JavaScript-Komponenten in `/static/src/js/` erweitern
- CSS in `/static/src/css/` anpassen

---

## 📝 Technische Details

### Backend-Konfiguration

**Sicherheitskategorien zuweisen:**
- Menü: **Wartung → Ausrüstung** → [Equipment auswählen]
- Im Formular: Feld "Sicherheitskategorie" (🟢/🟡/🔴)
- Die Kategorie ist direkt am `ows.machine` / `maintenance.equipment` gespeichert

**Einweisungsprodukte zuweisen:**
- Menü: **Wartung → Ausrüstung** → [Equipment auswählen]
- Im Formular: Tab "Einweisungsprodukte"
- Button "Hinzufügen" → Produkt aus `product.product` auswählen
- Speichert Verknüpfung in `ows.machine.training` (Many2many über One2many)
- Beim Verkauf dieses Produkts am POS wird automatisch die Freigabe erteilt

**Nutzungsprodukte zuweisen:**
- Gleicher Weg wie Einweisungsprodukte
- Tab "Nutzungsprodukte" im Equipment-Formular
- Speichert Verknüpfung in `ows.machine.product`
- Diese Produkte können für Nutzungsgebühren verwendet werden

**Maschinenfreigaben manuell vergeben:**
- Menü: **Kontakte** → [Partner auswählen]
- Tab "Maschinenfreigaben" (von open_workshop_base hinzugefügt)
- Übersicht aller Bereiche und Maschinen mit aktuellem Freigabestatus
- Freigaben werden jedoch hauptsächlich automatisch über POS-Verkäufe vergeben

**Konfiguration:**
- **Bereiche**: Wartung → Konfiguration → Bereiche
- **Produkt-Zuordnungen**: Wartung → Konfiguration → Zuordnungen
  - Nutzungsprodukte (Übersicht aller Zuordnungen)
  - Einweisungsprodukte (Übersicht aller Zuordnungen)

---

### Sicherheitskategorien

- **🟢 Grün (Kategorie 1)**: Keine Einweisungspflicht, freier Zugang
- **🟡 Gelb (Kategorie 2)**: Empfohlene Einweisung, optionale Freigabe
- **🔴 Rot (Kategorie 3)**: Einweisung zwingend erforderlich, POS zeigt nur rote Maschinen

### Freigabenverwaltung

Freigaben werden in `ows.machine.access` gespeichert mit:
- Partner (Kunde)
- Maschine
- Datum der Freigabe
- Optional: Ablaufdatum
- Herkunft (granted_by_pos)

### DokuWiki Namespace-Struktur

```
{equipment_namespace}:
├── overview              # Übersichtstabelle (von Odoo)
└── odoo-status/          # Maschinengeneriert (read-only)
    ├── maschine_1        # Status-Seite für Include
    ├── maschine_2
    └── c_template        # Template für Status-Seiten

{bereich}:                # Benutzer-Namespaces
├── holz/
│   ├── maschine_1       # Benutzer-Dokumentation
│   └── maschine_2       # (inkludiert odoo-status via {{page>}})
└── metall/
    └── ...
```

---

## 📄 Lizenz

AGPL-3 (open_workshop_base)  
LGPL-3 (weitere Module)

---

## 👤 Autor

Matthias Lotz / Hobbyhimmel

---

## 🔗 Verwandte Projekte

- [OCA Maintenance](https://github.com/OCA/maintenance) - Basis Equipment-Verwaltung