business-as-code 0.2.1 → 2.0.1

package/src/entities/goals.ts

@@ -0,0 +1,871 @@
+/**
+ * Goal Entity Types (Nouns)
+ *
+ * Goal tracking entities: Goal, OKR, KPI, Metric.
+ *
+ * @packageDocumentation
+ */
+
+import type { Noun } from 'ai-database'
+
+// =============================================================================
+// Goal
+// =============================================================================
+
+/**
+ * Goal entity
+ *
+ * Represents a strategic or operational goal.
+ */
+export const Goal: Noun = {
+  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: Noun = {
+  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: Noun = {
+  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: Noun = {
+  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: Noun = {
+  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: Noun = {
+  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'],
+} as const