@things-factory/kpi 9.0.31 → 9.0.32

package/server/service/kpi-metric-value/kpi-metric-value-mutation.ts

@@ -47,7 +47,7 @@ export class KpiMetricValueMutation {
       valueDate,
       periodType,
       value: metricValue.value,
-      group: metricValue.group,
+      org: metricValue.org,
       unit: metricValue.unit,
       meta: metricValue.meta,
       domain: domain,
@@ -60,14 +60,14 @@ export class KpiMetricValueMutation {
 
   @Directive('@transaction')
   @Directive('@privilege(category: "kpi", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
-  @Mutation(returns => KpiMetricValue, { description: 'Record a metric value by metric name, value, meta, and group.' })
+  @Mutation(returns => KpiMetricValue, { description: 'Record a metric value by metric name, value, meta, and org.' })
   async recordKpiMetricValue(
     @Arg('metricName', { description: 'Metric code/name.' }) metricName: string,
     @Arg('value', type => Float, { nullable: true, description: 'Metric value (number).' }) value: number | null,
     @Arg('meta', type => ScalarObject, { nullable: true, description: 'Extended or non-numeric information (JSON).' })
     meta: any,
-    @Arg('group', { nullable: true, description: 'Group key for this value (organization, line, user, etc.)' })
-    group: string | null,
+    @Arg('org', { nullable: true, description: 'Organizational unit for this value (project, department, company, employee, etc.)' })
+    org: string | null,
     @Ctx() context: ResolverContext
   ): Promise<KpiMetricValue> {
     const { domain, user, tx } = context.state
@@ -84,7 +84,7 @@ export class KpiMetricValueMutation {
         metric: { id: metric.id },
         valueDate,
         periodType,
-        group,
+        org,
         domain: { id: domain.id }
       }
     })
@@ -100,7 +100,7 @@ export class KpiMetricValueMutation {
         meta,
         valueDate,
         periodType,
-        group,
+        org,
         domain,
         creator: user,
         updater: user

package/server/service/kpi-metric-value/kpi-metric-value-type.ts

@@ -29,8 +29,8 @@ export class NewKpiMetricValue {
   })
   meta?: any
 
-  @Field({ nullable: true, description: 'Group key for this value (organization, line, user, etc.)' })
-  group?: string
+  @Field({ nullable: true, description: 'Organizational unit for this value (project, department, company, employee, etc.)' })
+  org?: string
 }
 
 @InputType({
@@ -65,8 +65,8 @@ export class KpiMetricValuePatch {
   })
   meta?: any
 
-  @Field({ nullable: true, description: 'Group key for this value (organization, line, user, etc.)' })
-  group?: string
+  @Field({ nullable: true, description: 'Organizational unit for this value (project, department, company, employee, etc.)' })
+  org?: string
 
   @Field({ nullable: true, description: 'Custom flag for update operations (internal use).' })
   cuFlag?: string

package/server/service/kpi-metric-value/kpi-metric-value.ts

@@ -16,7 +16,7 @@ import { KpiPeriodType } from '../kpi/kpi'
 import { User } from '@things-factory/auth-base'
 
 @Entity()
-@Index('ix_kpi_metric_value_latest', ['domain', 'metric', 'valueDate', 'group'], { unique: true })
+@Index('ix_kpi_metric_value_latest', ['domain', 'metric', 'valueDate', 'org'], { unique: true })
 @ObjectType({ description: 'Current value for each KPI metric (can be used for both state and history).' })
 export class KpiMetricValue {
   @PrimaryGeneratedColumn('uuid')
@@ -60,8 +60,8 @@ export class KpiMetricValue {
   periodType: KpiPeriodType
 
   @Column({ default: '' })
-  @Field({ nullable: true, description: 'Group key for this value (organization, line, user, etc.)' })
-  group?: string
+  @Field({ nullable: true, description: 'Organizational unit for this value (project, department, company, employee, etc.)' })
+  org?: string
 
   @Column({ type: 'simple-json', nullable: true })
   @Field(type => ScalarObject, { nullable: true })

package/server/service/kpi-org-scope/index.ts

@@ -0,0 +1,11 @@
+export * from './kpi-org-scope'
+export * from './kpi-org-scope-type'
+export * from './kpi-org-scope-query'
+export * from './kpi-org-scope-mutation'
+
+import { KpiOrgScope } from './kpi-org-scope'
+import { KpiOrgScopeQuery } from './kpi-org-scope-query'
+import { KpiOrgScopeMutation } from './kpi-org-scope-mutation'
+
+export const entities = [KpiOrgScope]
+export const resolvers = [KpiOrgScopeQuery, KpiOrgScopeMutation]

package/server/service/kpi-org-scope/kpi-org-scope-mutation.ts

@@ -0,0 +1,173 @@
+import { Resolver, Mutation, Arg, Ctx, Directive } from 'type-graphql'
+import { In } from 'typeorm'
+import { getRepository } from '@things-factory/shell'
+
+import { KpiOrgScope } from './kpi-org-scope'
+import { NewKpiOrgScope, KpiOrgScopePatch } from './kpi-org-scope-type'
+
+@Resolver(KpiOrgScope)
+export class KpiOrgScopeMutation {
+  @Directive('@privilege(category: "kpi", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
+  @Directive('@transaction')
+  @Mutation(returns => KpiOrgScope, { description: 'Create a new KPI org-scope mapping with the provided details.' })
+  async createKpiOrgScope(
+    @Arg('kpiOrgScope', { description: 'Input object containing details for the new org-scope mapping.' })
+    kpiOrgScope: NewKpiOrgScope,
+    @Ctx() context: ResolverContext
+  ): Promise<KpiOrgScope> {
+    const { domain, user, tx } = context.state
+
+    // Check if org already exists for this domain
+    const existingOrgScope = await getRepository(KpiOrgScope, tx).findOne({
+      where: { domain: { id: domain.id }, org: kpiOrgScope.org }
+    })
+
+    if (existingOrgScope) {
+      throw new Error(`Organization '${kpiOrgScope.org}' already has a scope mapping in this domain`)
+    }
+
+    const entity: Partial<KpiOrgScope> = {
+      ...kpiOrgScope,
+      domain,
+      creator: user,
+      updater: user
+    }
+
+    return await getRepository(KpiOrgScope, tx).save(entity)
+  }
+
+  @Directive('@privilege(category: "kpi", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
+  @Directive('@transaction')
+  @Mutation(returns => [KpiOrgScope], {
+    description: 'Update multiple KPI org-scope mappings with the provided patches.'
+  })
+  async updateMultipleKpiOrgScope(
+    @Arg('patches', type => [KpiOrgScopePatch], {
+      description: 'Array of patch objects for updating org-scope mappings.'
+    })
+    patches: KpiOrgScopePatch[],
+    @Ctx() context: ResolverContext
+  ): Promise<KpiOrgScope[]> {
+    const { domain, user, tx } = context.state
+
+    const ids = patches.map(patch => patch.id)
+    const existingOrgScopes = await getRepository(KpiOrgScope, tx).find({
+      where: {
+        domain: { id: domain.id },
+        id: In(ids)
+      }
+    })
+
+    if (existingOrgScopes.length !== patches.length) {
+      throw new Error('Some org-scope mappings not found or not accessible')
+    }
+
+    const updatedOrgScopes: KpiOrgScope[] = []
+
+    for (const patch of patches) {
+      const existingOrgScope = existingOrgScopes.find(os => os.id === patch.id)
+      if (!existingOrgScope) continue
+
+      // Check if org is being changed and if new org already exists
+      if (patch.org && patch.org !== existingOrgScope.org) {
+        const duplicateOrgScope = await getRepository(KpiOrgScope, tx).findOne({
+          where: {
+            domain: { id: domain.id },
+            org: patch.org,
+            id: In(ids.filter(id => id !== patch.id))
+          }
+        })
+        if (duplicateOrgScope) {
+          throw new Error(`Organization '${patch.org}' already has a scope mapping in this domain`)
+        }
+      }
+
+      const updatedEntity: Partial<KpiOrgScope> = {
+        ...existingOrgScope,
+        ...patch,
+        updater: user,
+        updatedAt: new Date()
+      }
+
+      const savedOrgScope = await getRepository(KpiOrgScope, tx).save(updatedEntity)
+      updatedOrgScopes.push(savedOrgScope)
+    }
+
+    return updatedOrgScopes
+  }
+
+  @Directive('@privilege(category: "kpi", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
+  @Directive('@transaction')
+  @Mutation(returns => Boolean, { description: 'Delete KPI org-scope mappings by their IDs.' })
+  async deleteKpiOrgScopes(
+    @Arg('ids', type => [String], { description: 'Array of org-scope mapping IDs to delete.' }) ids: string[],
+    @Ctx() context: ResolverContext
+  ): Promise<boolean> {
+    const { domain, tx } = context.state
+
+    const existingOrgScopes = await getRepository(KpiOrgScope, tx).find({
+      where: {
+        domain: { id: domain.id },
+        id: In(ids)
+      }
+    })
+
+    if (existingOrgScopes.length === 0) {
+      throw new Error('No org-scope mappings found to delete')
+    }
+
+    // Soft delete
+    await getRepository(KpiOrgScope, tx).softDelete(existingOrgScopes.map(os => os.id))
+
+    return true
+  }
+
+  @Directive('@privilege(category: "kpi", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
+  @Directive('@transaction')
+  @Mutation(returns => [KpiOrgScope], { description: 'Bulk create or update KPI org-scope mappings.' })
+  async bulkUpsertKpiOrgScopes(
+    @Arg('orgScopes', type => [NewKpiOrgScope], { description: 'Array of org-scope mapping data for bulk upsert.' })
+    orgScopes: NewKpiOrgScope[],
+    @Ctx() context: ResolverContext
+  ): Promise<KpiOrgScope[]> {
+    const { domain, user, tx } = context.state
+
+    const orgs = orgScopes.map(os => os.org)
+    const existingOrgScopes = await getRepository(KpiOrgScope, tx).find({
+      where: {
+        domain: { id: domain.id },
+        org: In(orgs)
+      }
+    })
+
+    const results: KpiOrgScope[] = []
+
+    for (const orgScopeData of orgScopes) {
+      const existing = existingOrgScopes.find(os => os.org === orgScopeData.org)
+
+      if (existing) {
+        // Update existing
+        const updatedEntity: Partial<KpiOrgScope> = {
+          ...existing,
+          ...orgScopeData,
+          updater: user,
+          updatedAt: new Date()
+        }
+        const updated = await getRepository(KpiOrgScope, tx).save(updatedEntity)
+        results.push(updated)
+      } else {
+        // Create new
+        const newEntity: Partial<KpiOrgScope> = {
+          ...orgScopeData,
+          domain,
+          creator: user,
+          updater: user
+        }
+        const saved = await getRepository(KpiOrgScope, tx).save(newEntity)
+        results.push(saved)
+      }
+    }
+
+    return results
+  }
+}

package/server/service/kpi-org-scope/kpi-org-scope-query.ts

@@ -0,0 +1,127 @@
+import { Resolver, Query, FieldResolver, Root, Args, Arg, Ctx, Directive } from 'type-graphql'
+import { Domain, getQueryBuilderFromListParams, getRepository, ListParam } from '@things-factory/shell'
+import { User } from '@things-factory/auth-base'
+
+import { KpiOrgScope } from './kpi-org-scope'
+import { KpiOrgScopeList } from './kpi-org-scope-type'
+
+@Resolver(KpiOrgScope)
+export class KpiOrgScopeQuery {
+  @Directive('@privilege(category: "kpi", privilege: "query", domainOwnerGranted: true, superUserGranted: true)')
+  @Query(returns => KpiOrgScope!, {
+    nullable: true,
+    description: 'Fetch a single KPI org-scope mapping by its unique identifier.'
+  })
+  async kpiOrgScope(
+    @Arg('id', { description: 'Unique identifier of the org-scope mapping to fetch.' }) id: string,
+    @Ctx() context: ResolverContext
+  ): Promise<KpiOrgScope> {
+    const { domain } = context.state
+
+    return await getRepository(KpiOrgScope).findOne({
+      where: { domain: { id: domain.id }, id }
+    })
+  }
+
+  @Directive('@privilege(category: "kpi", privilege: "query", domainOwnerGranted: true, superUserGranted: true)')
+  @Query(returns => KpiOrgScopeList, {
+    description: 'Fetch multiple KPI org-scope mappings with filters and pagination'
+  })
+  async kpiOrgScopes(
+    @Args(type => ListParam) params: ListParam,
+    @Ctx() context: ResolverContext
+  ): Promise<KpiOrgScopeList> {
+    const { domain } = context.state
+
+    const queryBuilder = getQueryBuilderFromListParams({
+      domain,
+      params,
+      repository: await getRepository(KpiOrgScope),
+      searchables: ['org', 'scope01', 'scope02', 'scope03', 'scope04', 'scope05']
+    })
+
+    const [items, total] = await queryBuilder.getManyAndCount()
+
+    return { items, total }
+  }
+
+  @Directive('@privilege(category: "kpi", privilege: "query", domainOwnerGranted: true, superUserGranted: true)')
+  @Query(returns => [String], { description: 'Get distinct values for a specific scope field' })
+  async kpiOrgScopeValues(
+    @Arg('scopeField', { description: 'Scope field to get distinct values from' })
+    scopeField: 'scope01' | 'scope02' | 'scope03' | 'scope04' | 'scope05',
+    @Ctx() context: ResolverContext,
+    @Arg('searchTerm', { nullable: true, description: 'Optional search term to filter values' }) searchTerm?: string
+  ): Promise<string[]> {
+    const { domain } = context.state
+
+    const queryBuilder = getRepository(KpiOrgScope)
+      .createQueryBuilder('orgScope')
+      .select(`DISTINCT orgScope.${scopeField}`, 'value')
+      .where('orgScope.domain_id = :domainId', { domainId: domain.id })
+      .andWhere(`orgScope.${scopeField} IS NOT NULL`)
+      .andWhere(`orgScope.${scopeField} != ''`)
+      .andWhere('orgScope.active = true')
+
+    if (searchTerm) {
+      queryBuilder.andWhere(`orgScope.${scopeField} ILIKE :searchTerm`, {
+        searchTerm: `%${searchTerm}%`
+      })
+    }
+
+    const results = await queryBuilder.getRawMany()
+    return results.map(r => r.value).filter(v => v)
+  }
+
+  @Directive('@privilege(category: "kpi", privilege: "query", domainOwnerGranted: true, superUserGranted: true)')
+  @Query(returns => [String], { description: 'Get distinct org values' })
+  async kpiOrgValues(
+    @Ctx() context: ResolverContext,
+    @Arg('searchTerm', { nullable: true, description: 'Optional search term to filter org values' }) searchTerm?: string
+  ): Promise<string[]> {
+    const { domain } = context.state
+
+    const queryBuilder = getRepository(KpiOrgScope)
+      .createQueryBuilder('orgScope')
+      .select('DISTINCT orgScope.org', 'value')
+      .where('orgScope.domain_id = :domainId', { domainId: domain.id })
+      .andWhere('orgScope.active = true')
+
+    if (searchTerm) {
+      queryBuilder.andWhere('orgScope.org ILIKE :searchTerm', {
+        searchTerm: `%${searchTerm}%`
+      })
+    }
+
+    const results = await queryBuilder.getRawMany()
+    return results.map(r => r.value)
+  }
+
+  @Directive('@privilege(category: "kpi", privilege: "query", domainOwnerGranted: true, superUserGranted: true)')
+  @Query(returns => KpiOrgScope, { nullable: true, description: 'Find org-scope mapping by org identifier' })
+  async kpiOrgScopeByOrg(
+    @Arg('org', { description: 'Organization identifier to search for' }) org: string,
+    @Ctx() context: ResolverContext
+  ): Promise<KpiOrgScope | undefined> {
+    const { domain } = context.state
+
+    return await getRepository(KpiOrgScope).findOne({
+      where: { domain: { id: domain.id }, org }
+    })
+  }
+
+  @FieldResolver(type => Domain)
+  async domain(@Root() kpiOrgScope: KpiOrgScope): Promise<Domain> {
+    return kpiOrgScope.domainId && (await getRepository(Domain).findOneBy({ id: kpiOrgScope.domainId }))
+  }
+
+  @FieldResolver(type => User)
+  async creator(@Root() kpiOrgScope: KpiOrgScope): Promise<User> {
+    return kpiOrgScope.creatorId && (await getRepository(User).findOneBy({ id: kpiOrgScope.creatorId }))
+  }
+
+  @FieldResolver(type => User)
+  async updater(@Root() kpiOrgScope: KpiOrgScope): Promise<User> {
+    return kpiOrgScope.updaterId && (await getRepository(User).findOneBy({ id: kpiOrgScope.updaterId }))
+  }
+}

package/server/service/kpi-org-scope/kpi-org-scope-type.ts

@@ -0,0 +1,68 @@
+import { InputType, Field, ID, ObjectType, Int } from 'type-graphql'
+import { KpiOrgScope } from './kpi-org-scope'
+
+@InputType({ description: 'Input type for creating a new KPI org-scope mapping' })
+export class NewKpiOrgScope {
+  @Field({ description: 'Organizational unit identifier' })
+  org: string
+
+  @Field({ nullable: true, description: 'First scope dimension' })
+  scope01?: string
+
+  @Field({ nullable: true, description: 'Second scope dimension' })
+  scope02?: string
+
+  @Field({ nullable: true, description: 'Third scope dimension' })
+  scope03?: string
+
+  @Field({ nullable: true, description: 'Fourth scope dimension' })
+  scope04?: string
+
+  @Field({ nullable: true, description: 'Fifth scope dimension' })
+  scope05?: string
+
+  @Field({ nullable: true, description: 'Human-readable name or description' })
+  displayName?: string
+
+  @Field({ nullable: true, description: 'Active status' })
+  active?: boolean
+}
+
+@InputType({ description: 'Input type for updating an existing KPI org-scope mapping' })
+export class KpiOrgScopePatch {
+  @Field(type => ID, { description: 'ID of the org-scope mapping to update' })
+  id: string
+
+  @Field({ nullable: true, description: 'Organizational unit identifier' })
+  org?: string
+
+  @Field({ nullable: true, description: 'First scope dimension' })
+  scope01?: string
+
+  @Field({ nullable: true, description: 'Second scope dimension' })
+  scope02?: string
+
+  @Field({ nullable: true, description: 'Third scope dimension' })
+  scope03?: string
+
+  @Field({ nullable: true, description: 'Fourth scope dimension' })
+  scope04?: string
+
+  @Field({ nullable: true, description: 'Fifth scope dimension' })
+  scope05?: string
+
+  @Field({ nullable: true, description: 'Human-readable name or description' })
+  displayName?: string
+
+  @Field({ nullable: true, description: 'Active status' })
+  active?: boolean
+}
+
+@ObjectType({ description: 'List of KPI org-scope mappings with pagination' })
+export class KpiOrgScopeList {
+  @Field(type => [KpiOrgScope], { description: 'Array of KPI org-scope mappings' })
+  items: KpiOrgScope[]
+
+  @Field(type => Int, { description: 'Total count of items' })
+  total: number
+}

package/server/service/kpi-org-scope/kpi-org-scope.ts

@@ -0,0 +1,123 @@
+import {
+  CreateDateColumn,
+  UpdateDateColumn,
+  DeleteDateColumn,
+  Entity,
+  Index,
+  Column,
+  RelationId,
+  ManyToOne,
+  PrimaryGeneratedColumn,
+  EntityManager
+} from 'typeorm'
+import { ObjectType, Field, ID } from 'type-graphql'
+
+import { Domain } from '@things-factory/shell'
+import { User } from '@things-factory/auth-base'
+
+@Entity()
+@Index('ix_kpi_org_scope_0', (orgScope: KpiOrgScope) => [orgScope.domain, orgScope.entityType, orgScope.entityId], {
+  unique: true
+})
+@ObjectType({
+  description:
+    'KPI organization scope mapping entity. Maps business entities to various scope dimensions for KPI analysis using generic reference pattern.'
+})
+export class KpiOrgScope {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { description: 'Unique identifier for this org-scope mapping.' })
+  readonly id: string
+
+  @ManyToOne(type => Domain)
+  @Field({ nullable: true, description: 'Domain (tenant) to which this org-scope mapping belongs.' })
+  domain?: Domain
+
+  @RelationId((orgScope: KpiOrgScope) => orgScope.domain)
+  @Field({ nullable: true, description: 'ID of the domain (tenant) for this org-scope mapping.' })
+  domainId?: string
+
+  @Column()
+  @Field({ description: 'Type of the referenced business entity (e.g., Project, Department, Company, Employee)' })
+  entityType: string
+
+  @Column()
+  @Field({ description: 'ID of the referenced business entity' })
+  entityId: string
+
+  @Column()
+  @Field({ description: 'Name of the referenced business entity (denormalized for performance and convenience)' })
+  entityName: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Legacy org field for backward compatibility' })
+  org?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'First scope dimension (e.g., geographical region, business unit)' })
+  scope01?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Second scope dimension (e.g., product line, customer segment)' })
+  scope02?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Third scope dimension (e.g., process type, technology stack)' })
+  scope03?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Fourth scope dimension (e.g., cost center, profit center)' })
+  scope04?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Fifth scope dimension (e.g., risk level, priority tier)' })
+  scope05?: string
+
+  @CreateDateColumn()
+  @Field({ nullable: true, description: 'Timestamp when this org-scope mapping was created.' })
+  createdAt?: Date
+
+  @UpdateDateColumn()
+  @Field({ nullable: true, description: 'Timestamp when this org-scope mapping was last updated.' })
+  updatedAt?: Date
+
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'User who created this org-scope mapping.' })
+  creator?: User
+
+  @RelationId((orgScope: KpiOrgScope) => orgScope.creator)
+  @Field({ nullable: true, description: 'ID of the user who created this org-scope mapping.' })
+  creatorId?: string
+
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'User who last updated this org-scope mapping.' })
+  updater?: User
+
+  @RelationId((orgScope: KpiOrgScope) => orgScope.updater)
+  @Field({ nullable: true, description: 'ID of the user who last updated this org-scope mapping.' })
+  updaterId?: string
+
+  // Helper methods for Generic Reference Pattern
+  async getReferencedEntity(entityManager: EntityManager): Promise<any> {
+    try {
+      const repository = entityManager.getRepository(this.entityType)
+      return await repository.findOne({ where: { id: this.entityId } })
+    } catch (error) {
+      console.warn(`Failed to get referenced entity ${this.entityType}:${this.entityId}`, error)
+      return null
+    }
+  }
+
+  async validateEntityReference(entityManager: EntityManager): Promise<boolean> {
+    try {
+      const entity = await this.getReferencedEntity(entityManager)
+      return !!entity
+    } catch {
+      return false
+    }
+  }
+
+  // Convenience getter for display purposes
+  get displayName(): string {
+    return this.entityName || `${this.entityType}:${this.entityId}` || this.org || 'Unknown'
+  }
+}

package/server/service/kpi-statistic/kpi-statistic.ts

@@ -21,6 +21,12 @@ import { Kpi, KpiPeriodType } from '../kpi/kpi'
   kpiStatistic.valueDate,
   kpiStatistic.periodType
 ])
+@Index('ix_kpi_statistic_scope', (kpiStatistic: KpiStatistic) => [
+  kpiStatistic.domain,
+  kpiStatistic.kpi,
+  kpiStatistic.scope,
+  kpiStatistic.valueDate
+])
 @ObjectType({
   description:
     'KPI Statistics Entity - Stores comprehensive statistical information for KPIs and Categories including central tendency measures (mean, median), dispersion metrics (standard deviation, variance), range indicators (min, max), and percentile distributions (25th, 75th percentiles, IQR). Supports both KPI and Category targets with flexible period-based aggregation (daily, weekly, monthly, yearly). Includes extensible JSON fields for additional metrics and metadata for calculation tracking.'
@@ -54,6 +60,10 @@ export class KpiStatistic {
   @Field(type => KpiPeriodType, { description: 'Aggregation period type for this statistic.' })
   periodType: KpiPeriodType
 
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Statistical scope - null for overall statistics, category value for scoped statistics (e.g., "서울", "부장", "대규모")' })
+  scope?: string
+
   // === 핵심 통계 필드 (14개) ===
 
   // 1. 기본 정보 (3개)