boc/EMPLOYEE_LIFECYCLE_SPEC.md

# Employee Lifecycle Platform — Teknisk Specifikation

## Version: 1.0
## Datum: 2026-07-29
## Status: Designfas

---

## 1. Övergripande Systemarkitektur

### 1.1 Arkitekturprinciper
- **API First**: All funktionalitet exponeras via REST API
- **Event Driven**: Kafka för händelseflöden
- **Modulär**: Varje domän är en isolerad modul
- **Domain Driven Design**: Tydliga bounded contexts
- **Plugin-baserat**: Integrationer via plugin-arkitektur
- **Immutable History**: Ingen data raderas, endast append
- **RBAC**: Rollbaserad åtkomstkontroll på alla nivåer

### 1.2 Teknisk Stack
- **Backend**: Go (befintlig BOC-backend)
- **Database**: PostgreSQL (befintlig)
- **Cache**: Redis (befintlig)
- **Event Bus**: Kafka (förberedd)
- **Search**: PostgreSQL full-text + Elasticsearch (framtida)
- **Files**: S3-kompatibel lagring
- **Queue**: Redis/RabbitMQ för bakgrundsjobb

### 1.3 Modulstruktur
```
employee/
├── profile/          # Profilhantering
├── onboarding/       # Onboarding wizard
├── documents/        # Dokumentmotor
├── timeline/         # Tidslinje
├── competence/       # Kompetensregister
├── training/         # Utbildningssystem
├── certification/    # Certifieringsmotor
├── tasks/            # Uppgiftsbibliotek
├── performance/      # Prestationsmotor
├── attendance/       # Närvaro
├── briefing/         # Daily briefing (finns)
└── integrations/     # Plugin-system
```

---

## 2. Datamodell

### 2.1 Core Entities

#### Employee (Medarbetare)
```sql
CREATE TABLE employees (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL REFERENCES tenants(id),
    
    -- Personuppgifter
    first_name VARCHAR(100) NOT NULL,
    last_name VARCHAR(100) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    phone VARCHAR(20),
    personal_number VARCHAR(20), -- Svenskt personnummer
    birth_date DATE,
    
    -- Profil
    avatar_url VARCHAR(500),
    bio TEXT,
    
    -- Anställning
    employment_type VARCHAR(20), -- full_time, part_time, consultant, intern
    employment_status VARCHAR(20), -- active, probation, notice, terminated
    start_date DATE,
    end_date DATE,
    probation_end_date DATE,
    notice_period_days INTEGER DEFAULT 30,
    
    -- Organisation
    department_id UUID REFERENCES departments(id),
    team_id UUID REFERENCES teams(id),
    manager_id UUID REFERENCES employees(id),
    role_id UUID REFERENCES roles(id),
    
    -- Ekonomi
    salary DECIMAL(12,2),
    salary_currency VARCHAR(3) DEFAULT 'SEK',
    bank_account VARCHAR(50),
    bank_clearing VARCHAR(10),
    
    -- Kontakt
    address TEXT,
    postal_code VARCHAR(10),
    city VARCHAR(100),
    country VARCHAR(2) DEFAULT 'SE',
    
    -- Metadata
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    created_by UUID REFERENCES employees(id),
    version INTEGER DEFAULT 1
);
```

#### EmployeeTimeline (Tidslinje)
```sql
CREATE TABLE employee_timeline_events (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    employee_id UUID NOT NULL REFERENCES employees(id),
    event_type VARCHAR(50) NOT NULL, -- hired, promoted, review, leave, etc.
    event_date DATE NOT NULL,
    title VARCHAR(255) NOT NULL,
    description TEXT,
    metadata JSONB, -- flexibla data per event-typ
    created_by UUID REFERENCES employees(id),
    created_at TIMESTAMP DEFAULT NOW()
);
```

#### Competence (Kompetens)
```sql
CREATE TABLE competences (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL REFERENCES tenants(id),
    name VARCHAR(100) NOT NULL,
    category VARCHAR(50), -- technical, soft_skill, language, etc.
    description TEXT,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE employee_competences (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    employee_id UUID REFERENCES employees(id),
    competence_id UUID REFERENCES competences(id),
    level INTEGER CHECK (level BETWEEN 1 AND 5), -- 1=beginner, 5=expert
    acquired_date DATE,
    validated_by UUID REFERENCES employees(id),
    notes TEXT,
    UNIQUE(employee_id, competence_id)
);
```

#### Document (Dokument)
```sql
CREATE TABLE employee_documents (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    employee_id UUID REFERENCES employees(id),
    document_type VARCHAR(50) NOT NULL, -- contract, nda, policy, etc.
    title VARCHAR(255) NOT NULL,
    template_id UUID REFERENCES document_templates(id),
    
    -- Innehåll
    content JSONB, -- strukturerat innehåll
    file_url VARCHAR(500),
    file_type VARCHAR(50),
    
    -- Signering
    signature_status VARCHAR(20) DEFAULT 'draft', -- draft, sent, signed, expired
    signed_by_employee_at TIMESTAMP,
    signed_by_company_at TIMESTAMP,
    signature_method VARCHAR(20), -- digital, manual
    
    -- Versionering
    version INTEGER DEFAULT 1,
    parent_id UUID REFERENCES employee_documents(id), -- för versioner
    
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);
```

#### Training (Utbildning)
```sql
CREATE TABLE trainings (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL REFERENCES tenants(id),
    title VARCHAR(255) NOT NULL,
    description TEXT,
    category VARCHAR(50), -- onboarding, compliance, skill, etc.
    format VARCHAR(20), -- video, text, quiz, workshop
    content JSONB, -- modulär struktur
    duration_minutes INTEGER,
    mandatory BOOLEAN DEFAULT false,
    valid_for_days INTEGER, -- hur länge certifiering gäller
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE employee_trainings (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    employee_id UUID REFERENCES employees(id),
    training_id UUID REFERENCES trainings(id),
    status VARCHAR(20) DEFAULT 'assigned', -- assigned, in_progress, completed, expired
    progress_percent INTEGER DEFAULT 0,
    started_at TIMESTAMP,
    completed_at TIMESTAMP,
    expires_at TIMESTAMP,
    score INTEGER, -- för quiz/test
    certificate_url VARCHAR(500),
    UNIQUE(employee_id, training_id)
);
```

#### Task (Uppgift)
```sql
CREATE TABLE task_templates (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL REFERENCES tenants(id),
    title VARCHAR(255) NOT NULL,
    description TEXT,
    category VARCHAR(50),
    priority VARCHAR(20) DEFAULT 'medium',
    estimated_duration_minutes INTEGER,
    checklist JSONB, -- array av steg
    required_role_ids UUID[], -- vilka roller som får uppgiften
    required_competence_ids UUID[],
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE employee_tasks (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    employee_id UUID REFERENCES employees(id),
    template_id UUID REFERENCES task_templates(id),
    title VARCHAR(255) NOT NULL,
    description TEXT,
    status VARCHAR(20) DEFAULT 'pending', -- pending, in_progress, completed, cancelled
    priority VARCHAR(20) DEFAULT 'medium',
    due_date DATE,
    completed_at TIMESTAMP,
    completed_by UUID REFERENCES employees(id),
    checklist_progress JSONB,
    assigned_by UUID REFERENCES employees(id),
    assigned_at TIMESTAMP DEFAULT NOW(),
    source VARCHAR(50), -- onboarding, role, manual, automation
    source_id UUID -- referens till t.ex. onboarding_id
);
```

#### Performance (Prestation)
```sql
CREATE TABLE performance_reviews (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    employee_id UUID REFERENCES employees(id),
    reviewer_id UUID REFERENCES employees(id),
    review_period_start DATE,
    review_period_end DATE,
    review_type VARCHAR(20), -- annual, quarterly, probation, ad_hoc
    
    -- Bedömningar
    ratings JSONB, -- {competence_id: score, ...}
    goals JSONB, -- {goal: description, status: achieved/partial/missed}
    strengths TEXT[],
    improvements TEXT[],
    
    -- Feedback
    employee_comments TEXT,
    reviewer_comments TEXT,
    
    status VARCHAR(20) DEFAULT 'draft', -- draft, submitted, acknowledged
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE performance_kpis (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    employee_id UUID REFERENCES employees(id),
    kpi_name VARCHAR(100) NOT NULL,
    kpi_value DECIMAL(10,2),
    target_value DECIMAL(10,2),
    period VARCHAR(20), -- weekly, monthly, quarterly
    period_start DATE,
    created_at TIMESTAMP DEFAULT NOW()
);
```

---

## 3. API Design

### 3.1 REST Endpoints

#### Employee Profile
```
GET    /api/v1/employees                    # Lista medarbetare
POST   /api/v1/employees                    # Skapa medarbetare
GET    /api/v1/employees/{id}               # Hämta profil
PUT    /api/v1/employees/{id}               # Uppdatera profil
GET    /api/v1/employees/{id}/timeline      # Tidslinje
GET    /api/v1/employees/{id}/competences   # Kompetenser
GET    /api/v1/employees/{id}/documents     # Dokument
GET    /api/v1/employees/{id}/trainings     # Utbildningar
GET    /api/v1/employees/{id}/tasks         # Uppgifter
GET    /api/v1/employees/{id}/performance   # Prestation
```

#### Onboarding
```
POST   /api/v1/onboarding                   # Starta onboarding
GET    /api/v1/onboarding/{id}              # Hämta status
PUT    /api/v1/onboarding/{id}/step/{step}  # Uppdatera steg
POST   /api/v1/onboarding/{id}/complete     # Slutför
```

#### Documents
```
GET    /api/v1/documents/templates          # Lista mallar
POST   /api/v1/documents                    # Skapa dokument
GET    /api/v1/documents/{id}               # Hämta dokument
POST   /api/v1/documents/{id}/sign          # Signera
GET    /api/v1/documents/{id}/versions      # Versioner
```

#### Training
```
GET    /api/v1/trainings                    # Lista utbildningar
POST   /api/v1/trainings                    # Skapa utbildning
POST   /api/v1/trainings/{id}/assign        # Tilldela
POST   /api/v1/trainings/{id}/complete      # Markera klar
```

#### Tasks
```
GET    /api/v1/tasks                        # Lista uppgifter
POST   /api/v1/tasks                        # Skapa uppgift
PUT    /api/v1/tasks/{id}                   # Uppdatera
POST   /api/v1/tasks/{id}/complete          # Slutför
```

### 3.2 Event Bus (Kafka Topics)

```
employee.created
employee.updated
employee.onboarding.started
employee.onboarding.completed
employee.document.signed
employee.training.completed
employee.certification.expired
employee.task.assigned
employee.task.completed
employee.performance.review.submitted
employee.attendance.changed
employee.role.changed
employee.manager.changed
```

---

## 4. Implementationsplan

### Fas 1: Core (Vecka 1-2)
- [ ] Databasschema
- [ ] Employee CRUD API
- [ ] Profilsida (frontend)
- [ ] Tidslinje

### Fas 2: Onboarding (Vecka 3-4)
- [ ] Onboarding wizard
- [ ] Dokumentgenerering
- [ ] Digital signering (integration)
- [ ] Task-automatisering

### Fas 3: Kompetens & Utbildning (Vecka 5-6)
- [ ] Kompetensregister
- [ ] Utbildningssystem
- [ ] Certifieringsmotor
- [ ] Quiz/test-system

### Fas 4: Prestation & Uppgifter (Vecka 7-8)
- [ ] Prestationsmotor
- [ ] Medarbetarsamtal
- [ ] Uppgiftsbibliotek
- [ ] To-do engine

### Fas 5: Integrationer (Vecka 9-10)
- [ ] Microsoft 365
- [ ] Google Workspace
- [ ] Slack
- [ ] SSO/Identitetsleverantörer

### Fas 6: Dashboard & Analys (Vecka 11-12)
- [ ] Dashboards
- [ ] Rapporter
- [ ] KPI-visualisering
- [ ] Exportfunktioner

---

## 5. Säkerhet

### 5.1 RBAC Modell
```
Role: admin
  - Alla rättigheter

Role: manager
  - Läsa/uppdatera egna teammedlemmar
  - Skapa uppgifter
  - Godkänna dokument
  - Se rapporter för team

Role: employee
  - Läsa/uppdatera egen profil
  - Se egna uppgifter
  - Signera egna dokument
  - Se egen tidslinje

Role: hr
  - Läsa alla medarbetare
  - Skapa/uppdatera anställningar
  - Hantera dokument
  - Se alla rapporter
```

### 5.2 Audit Log
Alla ändringar loggas:
- Vilken användare
- Vilken tid
- Vilken resurs
- Vilken åtgärd
- Före/efter värden

---

## 6. Integrationer

### 6.1 Plugin-arkitektur
```go
type IntegrationPlugin interface {
    Name() string
    Version() string
    
    // Provisionering
    ProvisionUser(user Employee) error
    DeprovisionUser(userID string) error
    
    // Synkronisering
    SyncUsers() error
    SyncGroups() error
    
    // Events
    HandleEvent(event Event) error
}
```

### 6.2 Förberedda integrationer
- Microsoft 365 (Azure AD)
- Google Workspace
- Slack
- GitHub
- AWS IAM
- Fortnox (bokföring)
- Scrive (digital signering)

---

## 7. Nästa Steg

1. **Godkänn specifikation**
2. **Skapa migrations** för databasschema
3. **Implementera core API** (Employee CRUD)
4. **Bygga profilsida** i frontend
5. **Implementera onboarding wizard**

---

*Denna specifikation är levande och uppdateras kontinuerligt.*