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)

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)

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)

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)

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)

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)

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)

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

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.