business-as-code 2.0.1 → 2.1.1

package/src/entities/goals.js

@@ -0,0 +1,799 @@
+/**
+ * Goal Entity Types (Nouns)
+ *
+ * Goal tracking entities: Goal, OKR, KPI, Metric.
+ *
+ * @packageDocumentation
+ */
+// =============================================================================
+// Goal
+// =============================================================================
+/**
+ * Goal entity
+ *
+ * Represents a strategic or operational goal.
+ */
+export const Goal = {
+    singular: 'goal',
+    plural: 'goals',
+    description: 'A strategic or operational goal',
+    properties: {
+        // Identity
+        name: {
+            type: 'string',
+            description: 'Goal name/title',
+        },
+        description: {
+            type: 'string',
+            optional: true,
+            description: 'Goal description',
+        },
+        // Classification
+        type: {
+            type: 'string',
+            optional: true,
+            description: 'Goal type',
+            examples: ['strategic', 'operational', 'tactical'],
+        },
+        category: {
+            type: 'string',
+            optional: true,
+            description: 'Goal category',
+            examples: ['growth', 'revenue', 'customer', 'product', 'operations', 'people', 'financial'],
+        },
+        priority: {
+            type: 'string',
+            optional: true,
+            description: 'Priority level',
+            examples: ['critical', 'high', 'medium', 'low'],
+        },
+        // Timeline
+        startDate: {
+            type: 'date',
+            optional: true,
+            description: 'Start date',
+        },
+        targetDate: {
+            type: 'date',
+            optional: true,
+            description: 'Target completion date',
+        },
+        completedAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'Actual completion time',
+        },
+        // Progress
+        progress: {
+            type: 'number',
+            optional: true,
+            description: 'Progress percentage (0-100)',
+        },
+        confidence: {
+            type: 'number',
+            optional: true,
+            description: 'Confidence level (0-100)',
+        },
+        // Success Criteria
+        successMetrics: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Success metrics',
+        },
+        targetValue: {
+            type: 'number',
+            optional: true,
+            description: 'Target value for primary metric',
+        },
+        currentValue: {
+            type: 'number',
+            optional: true,
+            description: 'Current value for primary metric',
+        },
+        unit: {
+            type: 'string',
+            optional: true,
+            description: 'Metric unit',
+        },
+        // Status
+        status: {
+            type: 'string',
+            description: 'Goal status',
+            examples: ['draft', 'active', 'on-track', 'at-risk', 'behind', 'completed', 'cancelled'],
+        },
+    },
+    relationships: {
+        owner: {
+            type: 'Worker',
+            required: false,
+            description: 'Goal owner',
+        },
+        team: {
+            type: 'Team',
+            required: false,
+            description: 'Responsible team',
+        },
+        department: {
+            type: 'Department',
+            required: false,
+            description: 'Responsible department',
+        },
+        parent: {
+            type: 'Goal',
+            required: false,
+            description: 'Parent goal',
+        },
+        children: {
+            type: 'Goal[]',
+            description: 'Sub-goals',
+        },
+        dependencies: {
+            type: 'Goal[]',
+            description: 'Goals this depends on',
+        },
+        kpis: {
+            type: 'KPI[]',
+            description: 'Related KPIs',
+        },
+    },
+    actions: [
+        'create',
+        'update',
+        'activate',
+        'updateProgress',
+        'markAtRisk',
+        'complete',
+        'cancel',
+        'extend',
+        'archive',
+    ],
+    events: [
+        'created',
+        'updated',
+        'activated',
+        'progressUpdated',
+        'markedAtRisk',
+        'completed',
+        'cancelled',
+        'extended',
+        'overdue',
+        'archived',
+    ],
+};
+// =============================================================================
+// OKR (Objective and Key Results)
+// =============================================================================
+/**
+ * OKR entity
+ *
+ * Represents an objective with measurable key results.
+ */
+export const OKR = {
+    singular: 'okr',
+    plural: 'okrs',
+    description: 'An objective with measurable key results',
+    properties: {
+        // Objective
+        objective: {
+            type: 'string',
+            description: 'Objective statement',
+        },
+        description: {
+            type: 'string',
+            optional: true,
+            description: 'Objective description',
+        },
+        // Classification
+        type: {
+            type: 'string',
+            optional: true,
+            description: 'OKR type',
+            examples: ['company', 'department', 'team', 'individual'],
+        },
+        category: {
+            type: 'string',
+            optional: true,
+            description: 'OKR category',
+            examples: ['growth', 'product', 'customer', 'operations', 'people'],
+        },
+        // Period
+        period: {
+            type: 'string',
+            optional: true,
+            description: 'OKR period (e.g., "Q1 2025", "H1 2025")',
+        },
+        startDate: {
+            type: 'date',
+            optional: true,
+            description: 'Period start date',
+        },
+        endDate: {
+            type: 'date',
+            optional: true,
+            description: 'Period end date',
+        },
+        // Progress
+        progress: {
+            type: 'number',
+            optional: true,
+            description: 'Overall progress (0-100)',
+        },
+        confidence: {
+            type: 'number',
+            optional: true,
+            description: 'Confidence level (0-1)',
+        },
+        grade: {
+            type: 'number',
+            optional: true,
+            description: 'Final grade (0-1)',
+        },
+        // Key Results count
+        keyResultCount: {
+            type: 'number',
+            optional: true,
+            description: 'Number of key results',
+        },
+        completedKeyResultCount: {
+            type: 'number',
+            optional: true,
+            description: 'Completed key results',
+        },
+        // Status
+        status: {
+            type: 'string',
+            description: 'OKR status',
+            examples: ['draft', 'active', 'on-track', 'at-risk', 'behind', 'completed', 'cancelled'],
+        },
+    },
+    relationships: {
+        owner: {
+            type: 'Worker',
+            required: false,
+            description: 'OKR owner',
+        },
+        team: {
+            type: 'Team',
+            required: false,
+            description: 'Responsible team',
+        },
+        department: {
+            type: 'Department',
+            required: false,
+            description: 'Responsible department',
+        },
+        parent: {
+            type: 'OKR',
+            required: false,
+            description: 'Parent OKR (alignment)',
+        },
+        children: {
+            type: 'OKR[]',
+            description: 'Aligned child OKRs',
+        },
+        keyResults: {
+            type: 'KeyResult[]',
+            description: 'Key results',
+        },
+    },
+    actions: [
+        'create',
+        'update',
+        'activate',
+        'addKeyResult',
+        'removeKeyResult',
+        'updateProgress',
+        'updateConfidence',
+        'grade',
+        'complete',
+        'cancel',
+        'archive',
+    ],
+    events: [
+        'created',
+        'updated',
+        'activated',
+        'keyResultAdded',
+        'keyResultRemoved',
+        'progressUpdated',
+        'confidenceUpdated',
+        'graded',
+        'completed',
+        'cancelled',
+        'archived',
+    ],
+};
+// =============================================================================
+// KeyResult
+// =============================================================================
+/**
+ * KeyResult entity
+ *
+ * Represents a measurable key result within an OKR.
+ */
+export const KeyResult = {
+    singular: 'key-result',
+    plural: 'key-results',
+    description: 'A measurable key result within an OKR',
+    properties: {
+        // Description
+        description: {
+            type: 'string',
+            description: 'Key result description',
+        },
+        // Metric
+        metric: {
+            type: 'string',
+            description: 'Metric being measured',
+        },
+        unit: {
+            type: 'string',
+            optional: true,
+            description: 'Unit of measurement',
+        },
+        // Values
+        startValue: {
+            type: 'number',
+            optional: true,
+            description: 'Starting value',
+        },
+        targetValue: {
+            type: 'number',
+            description: 'Target value',
+        },
+        currentValue: {
+            type: 'number',
+            optional: true,
+            description: 'Current value',
+        },
+        // Progress
+        progress: {
+            type: 'number',
+            optional: true,
+            description: 'Progress percentage (0-100)',
+        },
+        confidence: {
+            type: 'number',
+            optional: true,
+            description: 'Confidence level (0-1)',
+        },
+        // Type
+        direction: {
+            type: 'string',
+            optional: true,
+            description: 'Direction of improvement',
+            examples: ['increase', 'decrease', 'maintain'],
+        },
+        measurementType: {
+            type: 'string',
+            optional: true,
+            description: 'How progress is measured',
+            examples: ['percentage', 'absolute', 'binary', 'milestone'],
+        },
+        // Status
+        status: {
+            type: 'string',
+            description: 'Key result status',
+            examples: ['not-started', 'on-track', 'at-risk', 'behind', 'completed'],
+        },
+    },
+    relationships: {
+        okr: {
+            type: 'OKR',
+            description: 'Parent OKR',
+        },
+        owner: {
+            type: 'Worker',
+            required: false,
+            description: 'Key result owner',
+        },
+        initiatives: {
+            type: 'Initiative[]',
+            description: 'Supporting initiatives',
+        },
+    },
+    actions: [
+        'create',
+        'update',
+        'updateValue',
+        'updateConfidence',
+        'complete',
+        'delete',
+    ],
+    events: [
+        'created',
+        'updated',
+        'valueUpdated',
+        'confidenceUpdated',
+        'completed',
+        'deleted',
+    ],
+};
+// =============================================================================
+// KPI (Key Performance Indicator)
+// =============================================================================
+/**
+ * KPI entity
+ *
+ * Represents a key performance indicator.
+ */
+export const KPI = {
+    singular: 'kpi',
+    plural: 'kpis',
+    description: 'A key performance indicator',
+    properties: {
+        // Identity
+        name: {
+            type: 'string',
+            description: 'KPI name',
+        },
+        description: {
+            type: 'string',
+            optional: true,
+            description: 'KPI description',
+        },
+        code: {
+            type: 'string',
+            optional: true,
+            description: 'KPI code (e.g., "MRR", "NPS")',
+        },
+        // Classification
+        category: {
+            type: 'string',
+            optional: true,
+            description: 'KPI category',
+            examples: ['financial', 'customer', 'operations', 'people', 'product', 'growth'],
+        },
+        type: {
+            type: 'string',
+            optional: true,
+            description: 'KPI type',
+            examples: ['leading', 'lagging'],
+        },
+        // Measurement
+        unit: {
+            type: 'string',
+            optional: true,
+            description: 'Unit of measurement',
+        },
+        format: {
+            type: 'string',
+            optional: true,
+            description: 'Display format',
+            examples: ['number', 'currency', 'percentage', 'duration'],
+        },
+        precision: {
+            type: 'number',
+            optional: true,
+            description: 'Decimal precision',
+        },
+        // Values
+        targetValue: {
+            type: 'number',
+            optional: true,
+            description: 'Target value',
+        },
+        currentValue: {
+            type: 'number',
+            optional: true,
+            description: 'Current value',
+        },
+        previousValue: {
+            type: 'number',
+            optional: true,
+            description: 'Previous period value',
+        },
+        baselineValue: {
+            type: 'number',
+            optional: true,
+            description: 'Baseline value',
+        },
+        // Thresholds
+        warningThreshold: {
+            type: 'number',
+            optional: true,
+            description: 'Warning threshold',
+        },
+        criticalThreshold: {
+            type: 'number',
+            optional: true,
+            description: 'Critical threshold',
+        },
+        direction: {
+            type: 'string',
+            optional: true,
+            description: 'Good direction',
+            examples: ['higher-is-better', 'lower-is-better', 'target'],
+        },
+        // Tracking
+        frequency: {
+            type: 'string',
+            optional: true,
+            description: 'Measurement frequency',
+            examples: ['realtime', 'hourly', 'daily', 'weekly', 'monthly', 'quarterly'],
+        },
+        lastMeasuredAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'Last measurement time',
+        },
+        // Calculation
+        formula: {
+            type: 'string',
+            optional: true,
+            description: 'Calculation formula',
+        },
+        dataSource: {
+            type: 'string',
+            optional: true,
+            description: 'Data source',
+        },
+        // Status
+        status: {
+            type: 'string',
+            optional: true,
+            description: 'KPI status',
+            examples: ['on-target', 'warning', 'critical', 'no-data'],
+        },
+    },
+    relationships: {
+        owner: {
+            type: 'Worker',
+            required: false,
+            description: 'KPI owner',
+        },
+        department: {
+            type: 'Department',
+            required: false,
+            description: 'Responsible department',
+        },
+        goals: {
+            type: 'Goal[]',
+            description: 'Related goals',
+        },
+        dashboard: {
+            type: 'Dashboard',
+            required: false,
+            description: 'Display dashboard',
+        },
+        history: {
+            type: 'KPIValue[]',
+            description: 'Historical values',
+        },
+    },
+    actions: [
+        'create',
+        'update',
+        'measure',
+        'setTarget',
+        'setThresholds',
+        'alert',
+        'archive',
+    ],
+    events: [
+        'created',
+        'updated',
+        'measured',
+        'targetSet',
+        'thresholdBreached',
+        'targetMet',
+        'alerted',
+        'archived',
+    ],
+};
+// =============================================================================
+// Metric
+// =============================================================================
+/**
+ * Metric entity
+ *
+ * Represents a general business metric or measurement.
+ */
+export const Metric = {
+    singular: 'metric',
+    plural: 'metrics',
+    description: 'A general business metric or measurement',
+    properties: {
+        // Identity
+        name: {
+            type: 'string',
+            description: 'Metric name',
+        },
+        description: {
+            type: 'string',
+            optional: true,
+            description: 'Metric description',
+        },
+        // Classification
+        category: {
+            type: 'string',
+            optional: true,
+            description: 'Metric category',
+        },
+        tags: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Tags',
+        },
+        // Value
+        value: {
+            type: 'number',
+            description: 'Current value',
+        },
+        unit: {
+            type: 'string',
+            optional: true,
+            description: 'Unit of measurement',
+        },
+        // Timestamp
+        timestamp: {
+            type: 'datetime',
+            description: 'Measurement timestamp',
+        },
+        period: {
+            type: 'string',
+            optional: true,
+            description: 'Measurement period',
+        },
+        // Source
+        source: {
+            type: 'string',
+            optional: true,
+            description: 'Data source',
+        },
+    },
+    relationships: {
+        kpi: {
+            type: 'KPI',
+            required: false,
+            description: 'Related KPI',
+        },
+    },
+    actions: [
+        'record',
+        'update',
+        'delete',
+    ],
+    events: [
+        'recorded',
+        'updated',
+        'deleted',
+    ],
+};
+// =============================================================================
+// Initiative
+// =============================================================================
+/**
+ * Initiative entity
+ *
+ * Represents a strategic initiative or project supporting goals.
+ */
+export const Initiative = {
+    singular: 'initiative',
+    plural: 'initiatives',
+    description: 'A strategic initiative or project supporting goals',
+    properties: {
+        // Identity
+        name: {
+            type: 'string',
+            description: 'Initiative name',
+        },
+        description: {
+            type: 'string',
+            optional: true,
+            description: 'Initiative description',
+        },
+        // Classification
+        type: {
+            type: 'string',
+            optional: true,
+            description: 'Initiative type',
+            examples: ['project', 'program', 'experiment', 'improvement'],
+        },
+        priority: {
+            type: 'string',
+            optional: true,
+            description: 'Priority level',
+            examples: ['critical', 'high', 'medium', 'low'],
+        },
+        // Timeline
+        startDate: {
+            type: 'date',
+            optional: true,
+            description: 'Start date',
+        },
+        endDate: {
+            type: 'date',
+            optional: true,
+            description: 'End date',
+        },
+        // Progress
+        progress: {
+            type: 'number',
+            optional: true,
+            description: 'Progress percentage (0-100)',
+        },
+        // Resources
+        budget: {
+            type: 'number',
+            optional: true,
+            description: 'Allocated budget',
+        },
+        budgetCurrency: {
+            type: 'string',
+            optional: true,
+            description: 'Budget currency',
+        },
+        spent: {
+            type: 'number',
+            optional: true,
+            description: 'Amount spent',
+        },
+        // Status
+        status: {
+            type: 'string',
+            description: 'Initiative status',
+            examples: ['proposed', 'approved', 'in-progress', 'on-hold', 'completed', 'cancelled'],
+        },
+    },
+    relationships: {
+        owner: {
+            type: 'Worker',
+            required: false,
+            description: 'Initiative owner',
+        },
+        team: {
+            type: 'Team',
+            required: false,
+            description: 'Responsible team',
+        },
+        goals: {
+            type: 'Goal[]',
+            description: 'Supported goals',
+        },
+        keyResults: {
+            type: 'KeyResult[]',
+            description: 'Supported key results',
+        },
+    },
+    actions: [
+        'create',
+        'update',
+        'approve',
+        'start',
+        'pause',
+        'resume',
+        'complete',
+        'cancel',
+        'archive',
+    ],
+    events: [
+        'created',
+        'updated',
+        'approved',
+        'started',
+        'paused',
+        'resumed',
+        'completed',
+        'cancelled',
+        'archived',
+    ],
+};
+// =============================================================================
+// Exports
+// =============================================================================
+export const GoalEntities = {
+    Goal,
+    OKR,
+    KeyResult,
+    KPI,
+    Metric,
+    Initiative,
+};
+export const GoalCategories = {
+    objectives: ['Goal', 'OKR', 'KeyResult'],
+    measurement: ['KPI', 'Metric'],
+    execution: ['Initiative'],
+};