📋 Build Work Instruction Editor (Dienstanweisungs-Konfigurator)

[kevalyq]

Feature Description

Create a React-based work instruction builder with drag-and-drop interface, template library, and standard text blocks for creating Dienstanweisungen (work instructions).

🔗 Related Epic

Backend Epic: SecPal/api#101 (Work Instructions Management)
Backend Foundation: SecPal/api#102 (Phase 1 - MUST be completed first)

⚠️ This issue DEPENDS on the backend API being implemented first (SecPal/api#102).

---

User Stories

• As a Manager, I want to create work instructions from templates so that I save time
• As a Manager, I want to drag-and-drop sections so that I can quickly structure instructions
• As a Manager, I want to insert standard legal text so that compliance is ensured
• As a Manager, I want to preview the instruction so that I know how it looks before publishing

Acceptance Criteria

Core Editor Features

• Drag-and-drop section editor (React DnD or @dnd-kit/core)
• Section types: Heading, Paragraph, List, Standard Block
• Template selector sidebar
• Standard text blocks library sidebar
• Real-time preview pane
• Save as draft functionality
• Publish instruction (triggers acknowledgment workflow)

Template Management

• Template list view
• Create new template from instruction
• Template categories: General, Site-Specific, Safety
• System templates (read-only, marked with icon)
• Organization templates (editable)

Standard Blocks

• Pre-loaded German legal/compliance text blocks:
  • DSGVO Grundsatz (Data Protection)
  • Meldepflichten (Reporting Obligations)
  • Brandschutz Grundregeln (Fire Safety Basics)
  • Erste Hilfe Verpflichtungen (First Aid Duties)
• Locked blocks (cannot be edited when inserted)
• Visual indicator for locked content
• Search/filter standard blocks

UI/UX

• Responsive design (works on desktop + tablet)
• Autosave every 30 seconds
• Keyboard shortcuts (Ctrl+S to save, etc.)
• Undo/Redo functionality
• Character/word count
• Instruction metadata form (title, valid from/until, scope)

Integration

• API integration: POST /api/v1/work-instructions
• API integration: GET /api/v1/work-instruction-templates
• API integration: GET /api/v1/standard-blocks
• Form validation (required fields)
• Error handling + user feedback

Technical Notes

Tech Stack

• React 18+
• TypeScript
• React DnD (drag-and-drop) or @dnd-kit/core
• TipTap or Slate.js (rich text editor for paragraphs)
• TailwindCSS (styling)

Component Structure

WorkInstructionBuilder/
  ├── InstructionEditor.tsx (main container)
  ├── Sidebar/
  │   ├── TemplateList.tsx
  │   └── StandardBlockList.tsx
  ├── Editor/
  │   ├── SectionList.tsx (drag-drop container)
  │   ├── SectionEditor.tsx (individual section)
  │   └── RichTextEditor.tsx (paragraph editing)
  ├── Preview/
  │   └── InstructionPreview.tsx
  └── Toolbar/
      └── ActionToolbar.tsx (save, publish, etc.)

Data Model (Frontend State)

interface WorkInstruction {
  id?: string;
  title: string;
  instructionNumber?: string;
  version: number;
  sections: Section[];
  validFrom: Date;
  validUntil?: Date;
  scope: 'all_employees' | 'specific_employees' | 'by_role' | 'by_location';
  scopeCriteria?: string[];
  requiresAcknowledgment: boolean;
  acknowledgmentDeadlineDays: number;
  status: 'draft' | 'review' | 'published';
}

interface Section {
  id: string;
  type: 'heading' | 'paragraph' | 'list' | 'standard_block';
  content: string | StandardBlock;
  order: number;
  locked?: boolean;
}

interface StandardBlock {
  id: string;
  name: string;
  category: string;
  content: string;
  isLocked: boolean;
}

Design Mockup

┌─────────────────────────────────────────────────────────────────┐
│ Dienstanweisung erstellen                         [Speichern] [Veröffentlichen] │
├──────────────┬──────────────────────────────┬──────────────────┤
│ Vorlagen     │ Editor                       │ Vorschau         │
│              │                              │                  │
│ □ Allgemein  │ ┌────────────────────────┐   │ ┌──────────────┐ │
│   ✓ Verhalt. │ │ Titel: Brandschutz...  │   │ │ Brandschutz  │ │
│   □ Datensch.│ │ Gültig ab: 01.11.2025  │   │ │ Objekt A     │ │
│              │ └────────────────────────┘   │ │              │ │
│ □ Objekt-    │                              │ │ 1. Einleitu..│ │
│   spezifisch │ ▦ Einleitung (Überschrift)   │ │ 2. Grundreg..│ │
│              │   Drag me ↕                  │ │ ...          │ │
│ Standard-    │                              │ │              │ │
│ bausteine    │ ▦ Absatz                     │ └──────────────┘ │
│              │   Lorem ipsum...             │                  │
│ 🔒 DSGVO     │                              │                  │
│ 🔒 Meldepfl. │ + Absatz hinzufügen          │                  │
│ □ Brandsch.  │ + Liste hinzufügen           │                  │
│              │ + Standardbaustein einfügen  │                  │
└──────────────┴──────────────────────────────┴──────────────────┘

Dependencies

• CRITICAL DEPENDENCY: Phase 1: Backend API Foundation for Work Instructions api#102 (Backend API Foundation MUST be completed and merged first)
• Related to: [EPIC] Work Instructions Management (Dienstanweisungen) api#101 (Epic: Work Instructions Management)

Reference

• Backend Epic: [EPIC] Work Instructions Management (Dienstanweisungen) api#101
• Backend API: Phase 1: Backend API Foundation for Work Instructions api#102
• OpenAPI Spec: Will be defined in SecPal/contracts after backend implementation
• docs/feature-requirements.md - Section "Work Instructions Management"
• Figma designs: TBD

Milestone

🎯 v0.3.0 - Work Instructions MVP

Labels

• priority: high 🟠
• type: feature ✨
• component: frontend
• effort: L (1-2 weeks)
• blocked (waiting for Phase 1: Backend API Foundation for Work Instructions api#102)

---

📝 Implementation Timeline (Hybrid Approach)

Sprint 2-3: Backend API Implementation (SecPal/api#102) - IN PROGRESS
Sprint 4-5: Frontend Editor Implementation (this issue) - WAITING ON BACKEND

⚠️ Do not start frontend work until backend PR is merged!