@dssp/dkpi 1.0.0-y.0 → 1.0.0

package/KPI-STATISTICS-SERVICE.md

@@ -0,0 +1,233 @@
+# KPI Statistics Service Implementation
+
+## Overview
+
+This implementation provides GraphQL services for KPI statistics visualization, specifically designed for box plots and radar charts. The service analyzes KPI values across different geographical groups and provides real-time statistical data for completed projects.
+
+## GraphQL Types
+
+### KpiBoxPlotStats
+Box plot statistics for KPI values:
+- `geoGroup`: Geographical group identifier
+- `kpiName`: KPI name (optional for aggregated data)
+- `minVal`: Minimum score value
+- `q1Val`: First quartile (25th percentile)
+- `medVal`: Median value (50th percentile)
+- `q3Val`: Third quartile (75th percentile)
+- `maxVal`: Maximum score value
+
+### KpiRadarStats
+Radar chart statistics for KPI values:
+- `geoGroup`: Geographical group identifier
+- `kpiName`: KPI name
+- `avgScore`: Average KPI score
+- `projectCount`: Number of projects in calculation
+
+## GraphQL Queries
+
+### 1. kpiZValueBoxPlotStats
+Returns box plot statistics for Z-category KPIs grouped by geographical region.
+
+**Query:**
+```graphql
+query GetZValueBoxPlot($geoGroup: String) {
+  kpiZValueBoxPlotStats(geoGroup: $geoGroup) {
+    geoGroup
+    minVal
+    q1Val
+    medVal
+    q3Val
+    maxVal
+  }
+}
+```
+
+**Parameters:**
+- `geoGroup` (optional): Filter by specific geographical group
+
+### 2. kpiYValueBoxPlotStats
+Returns box plot statistics for Y-category KPIs, broken down by both geographical region and individual KPI names.
+
+**Query:**
+```graphql
+query GetYValueBoxPlot($geoGroup: String) {
+  kpiYValueBoxPlotStats(geoGroup: $geoGroup) {
+    geoGroup
+    kpiName
+    minVal
+    q1Val
+    medVal
+    q3Val
+    maxVal
+  }
+}
+```
+
+**Parameters:**
+- `geoGroup` (optional): Filter by specific geographical group
+
+### 3. kpiRadarStats
+Returns radar chart statistics for KPIs matching a specific pattern.
+
+**Query:**
+```graphql
+query GetRadarStats($kpiPattern: String!, $geoGroup: String) {
+  kpiRadarStats(kpiPattern: $kpiPattern, geoGroup: $geoGroup) {
+    geoGroup
+    kpiName
+    avgScore
+    projectCount
+  }
+}
+```
+
+**Parameters:**
+- `kpiPattern`: SQL LIKE pattern for KPI names (default: '%')
+- `geoGroup` (optional): Filter by specific geographical group
+
+### 4. kpiComprehensiveStats
+Returns comprehensive statistics for all KPIs across completed projects.
+
+**Query:**
+```graphql
+query GetComprehensiveStats($geoGroup: String, $includeOngoing: Boolean) {
+  kpiComprehensiveStats(geoGroup: $geoGroup, includeOngoing: $includeOngoing) {
+    geoGroup
+    kpiName
+    avgScore
+    projectCount
+  }
+}
+```
+
+**Parameters:**
+- `geoGroup` (optional): Filter by specific geographical group
+- `includeOngoing` (default: false): Include ongoing projects in analysis
+
+## Usage Examples
+
+### JavaScript/Frontend Usage
+
+```typescript
+import { client } from '@operato/graphql'
+import gql from 'graphql-tag'
+
+// Get Z-category box plot data for all regions
+const getZBoxPlotData = async () => {
+  const result = await client.query({
+    query: gql`
+      query {
+        kpiZValueBoxPlotStats {
+          geoGroup
+          minVal
+          q1Val
+          medVal
+          q3Val
+          maxVal
+        }
+      }
+    `
+  })
+  return result.data.kpiZValueBoxPlotStats
+}
+
+// Get Y-category box plot data for specific region
+const getYBoxPlotData = async (region: string) => {
+  const result = await client.query({
+    query: gql`
+      query GetYBoxPlot($geoGroup: String) {
+        kpiYValueBoxPlotStats(geoGroup: $geoGroup) {
+          geoGroup
+          kpiName
+          minVal
+          q1Val
+          medVal
+          q3Val
+          maxVal
+        }
+      }
+    `,
+    variables: { geoGroup: region }
+  })
+  return result.data.kpiYValueBoxPlotStats
+}
+
+// Get radar chart data for X-category KPIs
+const getRadarData = async () => {
+  const result = await client.query({
+    query: gql`
+      query {
+        kpiRadarStats(kpiPattern: "X%") {
+          geoGroup
+          kpiName
+          avgScore
+          projectCount
+        }
+      }
+    `
+  })
+  return result.data.kpiRadarStats
+}
+```
+
+### Data Processing for Charts
+
+```typescript
+// Process box plot data for Chart.js or similar
+const processBoxPlotData = (data: KpiBoxPlotStats[]) => {
+  return data.map(item => ({
+    label: item.geoGroup,
+    data: [item.minVal, item.q1Val, item.medVal, item.q3Val, item.maxVal]
+  }))
+}
+
+// Process radar data for radar charts
+const processRadarData = (data: KpiRadarStats[]) => {
+  const groupedData = data.reduce((acc, item) => {
+    if (!acc[item.geoGroup]) {
+      acc[item.geoGroup] = []
+    }
+    acc[item.geoGroup].push({
+      label: item.kpiName,
+      value: item.avgScore
+    })
+    return acc
+  }, {} as Record<string, Array<{label: string, value: number}>>)
+
+  return groupedData
+}
+```
+
+## Database Schema Requirements
+
+The service expects the following database structure:
+
+- `kpi_values` table with columns: `id`, `score`, `kpi_id`, `kpi_org_scope_id`, `domain_id`
+- `kpis` table with columns: `id`, `name`
+- `projects` table with columns: `id`, `geo_group`, `end_date`
+
+## Security
+
+All queries require KPI query privileges:
+- Category: "kpi"
+- Privilege: "query"
+- Domain owner granted: true
+- Super user granted: true
+
+## Performance Considerations
+
+1. **Indexing**: Ensure indexes on:
+   - `kpi_values.kpi_id`
+   - `kpi_values.kpi_org_scope_id`
+   - `kpi_values.domain_id`
+   - `projects.end_date`
+   - `projects.geo_group`
+   - `kpis.name`
+
+2. **Caching**: Consider implementing GraphQL query result caching for frequently accessed statistics.
+
+3. **Aggregation**: The percentile calculations may be expensive on large datasets. Consider pre-computing statistics for better performance.
+
+## File Location
+
+Implementation: `/Users/super/Documents/GitHub/dssp/packages/dkpi/server/service/kpi/kpi-query.ts`

package/_index.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="google" content="notranslate" />
-    <title>Digital KPI Platform</title>
+    <title>Digital platform-based KPI Navigator</title>
     <meta name="generator" content="Things Factory Starter Kit" />
     <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no" />
     <meta name="description" content="Build Smarter with Every Metric" />
@@ -20,7 +20,7 @@
 
     <!-- Add to homescreen for Chrome on Android. Fallback for manifest.json -->
     <meta name="mobile-web-app-capable" content="yes" />
-    <meta name="application-name" content="Digital KPI Platform" />
+    <meta name="application-name" content="Digital platform-based KPI Navigator" />
     <meta name="application-description" content="Build Smarter with Every Metric" />
     <meta name="application-copyright" content="Copyright © hatiolab.com. All Rights Reserved." />
     <link rel="application-icon" href="/assets/manifest/icon-96x96.png" />
@@ -28,7 +28,7 @@
     <!-- Add to homescreen for Safari on iOS -->
     <meta name="apple-mobile-web-app-capable" content="yes" />
     <meta name="apple-mobile-web-app-status-bar-style" content="default" />
-    <meta name="apple-mobile-web-app-title" content="Digital KPI Platform" />
+    <meta name="apple-mobile-web-app-title" content="Digital platform-based KPI Navigator" />
 
     <!-- Homescreen icons -->
     <link rel="apple-touch-icon" href="/assets/manifest/icon-48x48.png" />
@@ -46,7 +46,7 @@
     <meta name="twitter:card" content="summary" />
     <meta name="twitter:site" content="@username" />
     <meta property="og:type" content="website" />
-    <meta property="og:site_name" content="Digital KPI Platform, Build Smarter with Every Metric" />
+    <meta property="og:site_name" content="Digital platform-based KPI Navigator, Build Smarter with Every Metric" />
     <meta property="og:image" content="/assets/manifest/image-metaog.png" />
 
     <!-- Performance tip: hint to the browser to start the handshake for the fonts site -->
@@ -61,10 +61,5 @@
   <body class="light">
     <things-app></things-app>
     <noscript> Please enable JavaScript to view this website. </noscript>
-    <!-- Load webcomponents-loader.js to check and load any polyfills your browser needs -->
-    <script src="/node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>
-    <script src="/node_modules/web-animations-js/web-animations-next.min.js"></script>
-    <script src="/node_modules/@hatiolab/things-scene/things-scene-min.js"></script>
-    <!-- Built with love using PWA Starter Kit -->
   </body>
 </html>

package/assets/helps/index.md

@@ -1 +1 @@
-# Digital Digital KPI Platform
+# Digital Digital platform-based KPI Navigator

package/assets/manifest.json

@@ -1,7 +1,7 @@
 {
-  "name": "Digital KPI Platform",
+  "name": "Digital platform-based KPI Navigator",
   "short_name": "dkpi",
-  "description": "Digital KPI Platform, Build Smarter with Every Metric",
+  "description": "Digital platform-based KPI Navigator, Build Smarter with Every Metric",
   "icons": [
     {
       "src": "manifest/icon-192x192.png",

package/config/config.development.js

@@ -1,5 +1,6 @@
 module.exports = {
-  subdomain: 'system',
+  subdomain: null,
+  domainTypes: ['domain', 'project'],
   applianceJwtExpiresIn: '10y',
   /* database field encryption key : 32 bytes - must be changed by every installation */
   dataEncryptionKey: 'V6g5oHJZb7KcazJyL6cM95XvIDouon5b',

package/config/config.production.js

@@ -1,5 +1,6 @@
 module.exports = {
-  subdomain: 'system',
+  subdomain: null,
+  domainTypes: ['domain', 'project'],
   applianceJwtExpiresIn: '10y',
   /* database field encryption key : 32 bytes - must be changed by every installation */
   dataEncryptionKey: 'V6g5oHJZb7KcazJyL6cM95XvIDouon5b',