@things-factory/kpi 9.0.31 → 9.0.33

package/helps/kpi/kpi-category.md

@@ -1,160 +0,0 @@
-# KpiCategory
-
-Paragraphs are separated by a blank line.
-
-2nd paragraph. _Italic_, **bold**, and `monospace`. Itemized lists
-look like:
-
-- this one
-- that one
-- the other one
-
-Note that --- not considering the asterisk --- the actual text
-content starts at 4-columns in.
-
-> Block quotes are
-> written like so.
->
-> They can span multiple paragraphs,
-> if you like.
-
-Use 3 dashes for an em-dash. Use 2 dashes for ranges (ex., "it's all
-in chapters 12--14"). Three dots ... will be converted to an ellipsis.
-Unicode is supported. ☺
-
-## An h2 header
-
-Here's a numbered list:
-
-1. first item
-2. second item
-3. third item
-
-Note again how the actual text starts at 4 columns in (4 characters
-from the left side). Here's a code sample:
-
-# Let me re-iterate ...
-
-for i in 1 .. 10 { do-something(i) }
-
-As you probably guessed, indented 4 spaces. By the way, instead of
-indenting the block, you can use delimited blocks, if you like:
-
-```
-define foobar() {
-print "Welcome to flavor country!";
-}
-```
-
-(which makes copying & pasting easier). You can optionally mark the
-delimited block for Pandoc to syntax highlight it:
-
-```python
-import time
-# Quick, count to ten!
-for i in range(10):
-# (but not *too* quick)
-time.sleep(0.5)
-print(i)
-```
-
-### An h3 header
-
-Now a nested list:
-
-1. First, get these ingredients:
-
-- carrots
-- celery
-- lentils
-
-2. Boil some water.
-
-3. Dump everything in the pot and follow
-   this algorithm:
-
-find wooden spoon
-uncover pot
-stir
-cover pot
-balance wooden spoon precariously on pot handle
-wait 10 minutes
-goto first step (or shut off burner when done)
-
-Do not bump wooden spoon or it will fall.
-
-Notice again how text always lines up on 4-space indents (including
-that last line which continues item 3 above).
-
-Here's a link to [a website](http://foo.bar), to a [local
-doc](local-doc.html), and to a [section heading in the current
-doc](#an-h2-header). Here's a footnote [^1].
-
-[^1]: Some footnote text.
-
-Tables can look like this:
-
-Name Size Material Color
-
----
-
-All Business 9 leather brown
-Roundabout 10 hemp canvas natural
-Cinderella 11 glass transparent
-
-Table: Shoes sizes, materials, and colors.
-
-(The above is the caption for the table.) Pandoc also supports
-multi-line tables:
-
----
-
-Keyword Text
-
----
-
-red Sunsets, apples, and
-other red or reddish
-things.
-
-green Leaves, grass, frogs
-and other things it's
-not easy being.
-
----
-
-A horizontal rule follows.
-
----
-
-Here's a definition list:
-
-apples
-: Good for making applesauce.
-
-oranges
-: Citrus!
-
-tomatoes
-: There's no "e" in tomatoe.
-
-Again, text is indented 4 spaces. (Put a blank line between each
-term and its definition to spread things out more.)
-
-Here's a "line block" (note how whitespace is honored):
-
-| Line one
-| Line too
-| Line tree
-
-and images can be specified like so:
-
-![example image](example-image.jpg 'An exemplary image')
-
-Inline math equation: $\omega = d\phi / dt$. Display
-math should get its own line like so:
-
-$$I = \int \rho R^{2} dV$$
-
-And note that you can backslash-escape any punctuation characters
-which you wish to be displayed literally, ex.: \`foo\`, \*bar\*, etc.

package/server/service/kpi-category/index.ts

@@ -1,7 +0,0 @@
-import { KpiCategory } from './kpi-category'
-import { KpiCategoryQuery } from './kpi-category-query'
-import { KpiCategoryMutation } from './kpi-category-mutation'
-
-export const entities = [KpiCategory]
-export const resolvers = [KpiCategoryQuery, KpiCategoryMutation]
-export const subscribers = []

package/server/service/kpi-category/kpi-category-mutation.ts

@@ -1,217 +0,0 @@
-import { Resolver, Mutation, Arg, Ctx, Directive } from 'type-graphql'
-import { getRepository } from '@things-factory/shell'
-import { KpiCategory } from './kpi-category'
-import { NewKpiCategory, KpiCategoryPatch } from './kpi-category-type'
-import { KpiCategoryValueResult } from './kpi-category-query'
-import { parseFormula } from '../../calculator/parser'
-import { evaluateFormula } from '../../calculator/evaluator'
-import { builtinFunctions } from '../../calculator/functions'
-import { KpiValueProvider } from '../../controllers/kpi-value-provider'
-import { getDefaultValueDate } from '../utils/value-date-util'
-import { KpiPeriodType } from '../kpi/kpi'
-import { KpiValueScoreService } from '../kpi-value/kpi-value-score.service'
-import { KpiCategoryValue } from '../kpi-category-value/kpi-category-value'
-
-@Resolver(KpiCategory)
-export class KpiCategoryMutation {
-  @Directive('@transaction')
-  @Directive('@privilege(category: "kpi", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
-  @Mutation(returns => KpiCategory, { description: 'Create a new KPI category.' })
-  async createKpiCategory(
-    @Arg('kpiCategory') kpiCategory: NewKpiCategory,
-    @Ctx() context: ResolverContext
-  ): Promise<KpiCategory> {
-    const { domain, user, tx } = context.state
-
-    const result = await getRepository(KpiCategory, tx).save({
-      ...kpiCategory,
-      domain,
-      creator: user,
-      updater: user
-    })
-
-    return result
-  }
-
-  @Directive('@transaction')
-  @Directive('@privilege(category: "kpi", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
-  @Mutation(returns => KpiCategory, { description: 'Update an existing KPI category.' })
-  async updateKpiCategory(
-    @Arg('id') id: string,
-    @Arg('patch') patch: KpiCategoryPatch,
-    @Ctx() context: ResolverContext
-  ): Promise<KpiCategory> {
-    const { domain, user, tx } = context.state
-
-    const kpiCategory = await getRepository(KpiCategory, tx).findOne({
-      where: { id, domain: { id: domain.id } }
-    })
-    if (!kpiCategory) {
-      throw new Error(`KPI category with id ${id} not found`)
-    }
-
-    Object.assign(kpiCategory, {
-      ...patch,
-      updater: user
-    })
-
-    return await getRepository(KpiCategory, tx).save(kpiCategory)
-  }
-
-  @Directive('@transaction')
-  @Directive('@privilege(category: "kpi", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
-  @Mutation(returns => Boolean, { description: 'Delete a KPI category.' })
-  async deleteKpiCategory(@Arg('id') id: string, @Ctx() context: ResolverContext): Promise<boolean> {
-    const { domain, tx } = context.state
-
-    const kpiCategory = await getRepository(KpiCategory, tx).findOne({
-      where: { id, domain: { id: domain.id } }
-    })
-    if (!kpiCategory) {
-      throw new Error(`KPI category with id ${id} not found`)
-    }
-
-    await getRepository(KpiCategory, tx).remove(kpiCategory)
-    return true
-  }
-
-  @Directive('@transaction')
-  @Directive('@privilege(category: "kpi", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
-  @Mutation(returns => KpiCategoryValueResult, { description: 'Calculate KPI category value and score.' })
-  async calculateKpiValue(
-    @Arg('categoryId') categoryId: string,
-    @Arg('valueDate', { nullable: true }) valueDate: string,
-    @Arg('group', { nullable: true }) group: string,
-    @Ctx() context: ResolverContext
-  ): Promise<KpiCategoryValueResult> {
-    const { domain, user, tx } = context.state
-
-    // 1. 카테고리 정보 조회
-    const category = await getRepository(KpiCategory, tx).findOne({
-      where: { id: categoryId, domain: { id: domain.id } }
-    })
-    if (!category) return { score: null }
-
-    // 기본 계산 기준일 설정 (카테고리 periodType 사용)
-    const defaultDate = valueDate || getDefaultValueDate(category.periodType || KpiPeriodType.DAY, 'last')
-
-    // 2. 카테고리 formula가 있으면 formula로 계산
-    if (category.formula) {
-      const ast = parseFormula(category.formula)
-      const provider = new KpiValueProvider({
-        valueDate: defaultDate,
-        group,
-        domainId: domain.id,
-        tx
-      })
-      const evalContext = { functions: builtinFunctions, provider }
-      const value = await evaluateFormula(ast, evalContext)
-      // 카테고리 formula 결과를 score로 변환 (0-1 범위)
-      const score = value !== null && value !== undefined && !isNaN(value) ? Math.max(0, Math.min(1, value)) : null
-
-      // KpiCategoryValue에 저장 (for formula case)
-      const kpiCategoryValue = getRepository(KpiCategoryValue, tx).create({
-        domainId: domain.id,
-        categoryId: categoryId,
-        valueDate: defaultDate,
-        group,
-        score,
-        creator: user,
-        updater: user
-      })
-      await getRepository(KpiCategoryValue, tx).save(kpiCategoryValue)
-
-      return {
-        score,
-        valueDate: defaultDate,
-        group
-      }
-    }
-
-    // 3. formula가 없으면 KPI score들의 가중 평균으로 category score 계산
-    const { Kpi } = require('../kpi/kpi')
-    const kpis = await getRepository(Kpi, tx).find({
-      where: { domain: { id: domain.id }, category: { id: categoryId } }
-    })
-    if (!kpis.length) return { score: null }
-
-    // 가중치 정규화를 위한 전체 가중치 합 계산
-    let totalWeightSum = 0
-    for (const kpi of kpis as any[]) {
-      const weight = kpi.weight ?? 1
-      totalWeightSum += weight
-    }
-
-    // 가중치가 0이면 기본값 1로 설정
-    if (totalWeightSum === 0) {
-      totalWeightSum = kpis.length
-    }
-
-    let weightedScoreSum = 0
-
-    for (const kpi of kpis as any[]) {
-      // KPI value 계산
-      let value = null
-      if (kpi.formula) {
-        const ast = parseFormula(kpi.formula)
-        const provider = new KpiValueProvider({
-          valueDate: defaultDate,
-          group,
-          domainId: domain.id,
-          tx
-        })
-        const evalContext = { functions: builtinFunctions, provider }
-        value = await evaluateFormula(ast, evalContext)
-      } else {
-        const { KpiValue } = require('../kpi-value/kpi-value')
-        const kpiValue = await getRepository(KpiValue, tx).findOne({
-          where: {
-            kpi: { id: kpi.id },
-            valueDate: defaultDate,
-            group: group ?? '',
-            domain: { id: domain.id }
-          }
-        })
-        value = (kpiValue as any)?.value ?? 0
-      }
-
-      // KPI score 계산
-      const scoreService = new KpiValueScoreService()
-      let kpiScore = null
-      if (value !== null && value !== undefined) {
-        let scoreResult = await scoreService.calculateScoreFromFormula(kpi as any, value)
-        if (!scoreResult) {
-          scoreResult = scoreService.calculateScoreFromLookup(kpi as any, value)
-        }
-        kpiScore = scoreResult?.score ?? null
-      }
-
-      // 정규화된 가중치 계산 (전체 가중치 합으로 나누어 비율로 변환)
-      const normalizedWeight = (kpi.weight ?? 1) / totalWeightSum
-      if (kpiScore !== null) {
-        weightedScoreSum += kpiScore * normalizedWeight
-      }
-    }
-
-    // category score 계산 (정규화된 가중치로 계산된 결과)
-    const categoryScore = weightedScoreSum
-
-    // KpiCategoryValue에 저장
-    const kpiCategoryValue = getRepository(KpiCategoryValue, tx).create({
-      domainId: domain.id,
-      categoryId: categoryId,
-      valueDate: defaultDate,
-      group,
-      score: categoryScore,
-      creator: user,
-      updater: user
-    })
-    await getRepository(KpiCategoryValue, tx).save(kpiCategoryValue)
-
-    return {
-      score: categoryScore,
-      valueDate: defaultDate,
-      group
-    }
-  }
-}

package/server/service/kpi-category/kpi-category-query.ts

@@ -1,87 +0,0 @@
-import { Resolver, Query, FieldResolver, Float, Root, Args, Arg, Ctx, Directive, ObjectType, Field } from 'type-graphql'
-import { Domain, getQueryBuilderFromListParams, getRepository, ListParam } from '@things-factory/shell'
-import { User } from '@things-factory/auth-base'
-import { KpiCategory } from './kpi-category'
-import { KpiCategoryList } from './kpi-category-type'
-import { Kpi } from '../kpi/kpi'
-import { KpiValue } from '../kpi-value/kpi-value'
-import { parseFormula } from '../../calculator/parser'
-import { evaluateFormula } from '../../calculator/evaluator'
-import { builtinFunctions } from '../../calculator/functions'
-import { KpiValueProvider } from '../../controllers/kpi-value-provider'
-import { getDefaultValueDate } from '../utils/value-date-util'
-import { KpiPeriodType } from '../kpi/kpi'
-import { KpiValueScoreService } from '../kpi-value/kpi-value-score.service'
-
-@ObjectType()
-export class KpiCategoryValueResult {
-  @Field(type => Float, { nullable: true, description: 'Performance score for this category (0-1 range)' })
-  score?: number
-
-  @Field({ nullable: true })
-  valueDate?: string
-
-  @Field({ nullable: true })
-  group?: string
-}
-
-@Resolver(KpiCategory)
-export class KpiCategoryQuery {
-  @Directive('@privilege(category: "kpi", privilege: "query", domainOwnerGranted: true, superUserGranted: true)')
-  @Query(returns => KpiCategory!, {
-    nullable: true,
-    description: 'Fetch a single KPI category by its unique identifier.'
-  })
-  async kpiCategory(
-    @Arg('id', { description: 'Unique identifier of the KPI category to fetch.' }) id: string,
-    @Ctx() context: ResolverContext
-  ): Promise<KpiCategory> {
-    const { domain } = context.state
-
-    return await getRepository(KpiCategory).findOne({
-      where: { domain: { id: domain.id }, id }
-    })
-  }
-
-  @Directive('@privilege(category: "kpi", privilege: "query", domainOwnerGranted: true, superUserGranted: true)')
-  @Query(returns => KpiCategoryList, { description: 'To fetch multiple KpiCategories' })
-  async kpiCategories(
-    @Args(type => ListParam) params: ListParam,
-    @Ctx() context: ResolverContext
-  ): Promise<KpiCategoryList> {
-    const { domain } = context.state
-
-    const queryBuilder = getQueryBuilderFromListParams({
-      domain,
-      params,
-      repository: await getRepository(KpiCategory),
-      searchables: ['name', 'description']
-    })
-
-    const [items, total] = await queryBuilder.getManyAndCount()
-
-    return { items, total }
-  }
-
-  @FieldResolver(type => [Kpi])
-  async kpis(@Root() kpiCategory: KpiCategory): Promise<Kpi[]> {
-    return await getRepository(Kpi).find({
-      where: { domain: { id: kpiCategory.domainId }, category: { id: kpiCategory.id } }
-    })
-  }
-
-  @FieldResolver(type => Domain)
-  async domain(@Root() kpiCategory: KpiCategory): Promise<Domain> {
-    return kpiCategory.domainId && (await getRepository(Domain).findOneBy({ id: kpiCategory.domainId }))
-  }
-
-  @FieldResolver(type => User)
-  async updater(@Root() kpiCategory: KpiCategory): Promise<User> {
-    return kpiCategory.updaterId && (await getRepository(User).findOneBy({ id: kpiCategory.updaterId }))
-  }
-
-  @FieldResolver(type => User)
-  async creator(@Root() kpiCategory: KpiCategory): Promise<User> {
-    return kpiCategory.creatorId && (await getRepository(User).findOneBy({ id: kpiCategory.creatorId }))
-  }
-}

package/server/service/kpi-category/kpi-category-type.ts

@@ -1,73 +0,0 @@
-import { ObjectType, Field, InputType, Int, ID } from 'type-graphql'
-
-import { KpiCategory } from './kpi-category'
-import { KpiPeriodType } from '../kpi/kpi'
-
-@InputType({
-  description: 'Input type for creating a new KPI category. Used in mutations to provide category details.'
-})
-export class NewKpiCategory {
-  @Field({ description: 'Name of the KPI category.' })
-  name: string
-
-  @Field({ nullable: true, description: 'Detailed description of this KPI category.' })
-  description?: string
-
-  @Field({ nullable: true, description: 'Whether this category is active (usable) or not.' })
-  active?: boolean
-
-  @Field({ nullable: true, description: 'Aggregation formula using child KPI codes.' })
-  formula?: string
-
-  @Field({ nullable: true, description: 'Weight for aggregation in higher-level summary.' })
-  weight?: number
-
-  @Field(type => KpiPeriodType, {
-    nullable: true,
-    description:
-      'Calculation formula for category score using KPI score variables. Example: "avg(sales_score, profit_score)" or "sales_score * 0.6 + profit_score * 0.4". If not provided, weighted average of child KPI scores will be used.'
-  })
-  periodType?: KpiPeriodType
-}
-
-@InputType({
-  description: 'Input type for updating an existing KPI category. Used in mutations to patch category details.'
-})
-export class KpiCategoryPatch {
-  @Field(type => ID, { nullable: true, description: 'ID of the KPI category to update.' })
-  id?: string
-
-  @Field({ nullable: true, description: 'Name of the KPI category.' })
-  name?: string
-
-  @Field({ nullable: true, description: 'Detailed description of this KPI category.' })
-  description?: string
-
-  @Field({ nullable: true, description: 'Whether this category is active (usable) or not.' })
-  active?: boolean
-
-  @Field({
-    nullable: true,
-    description:
-      'Calculation formula for category score using KPI score variables. Example: "avg(sales_score, profit_score)" or "sales_score * 0.6 + profit_score * 0.4". If not provided, weighted average of child KPI scores will be used.'
-  })
-  formula?: string
-
-  @Field({ nullable: true, description: 'Weight for aggregation in higher-level summary.' })
-  weight?: number
-
-  @Field(type => KpiPeriodType, { nullable: true, description: 'Aggregation period type for this category.' })
-  periodType?: KpiPeriodType
-
-  @Field({ nullable: true, description: 'Custom flag for update operations (internal use).' })
-  cuFlag?: string
-}
-
-@ObjectType()
-export class KpiCategoryList {
-  @Field(type => [KpiCategory])
-  items: KpiCategory[]
-
-  @Field(type => Int)
-  total: number
-}

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

@@ -1,95 +0,0 @@
-import {
-  CreateDateColumn,
-  UpdateDateColumn,
-  Entity,
-  Index,
-  Column,
-  RelationId,
-  ManyToOne,
-  OneToMany,
-  PrimaryGeneratedColumn
-} from 'typeorm'
-import { ObjectType, Field, Int, ID } from 'type-graphql'
-
-import { Domain } from '@things-factory/shell'
-import { User } from '@things-factory/auth-base'
-import { Kpi } from '../kpi/kpi'
-import { KpiPeriodType } from '../kpi/kpi'
-
-@Entity()
-@Index('ix_kpi_category_0', (kpiCategory: KpiCategory) => [kpiCategory.domain, kpiCategory.name], {
-  unique: true
-})
-@ObjectType({
-  description:
-    'KPI category entity. Represents a classification or group for KPIs. Supports hierarchical (tree) structure.'
-})
-export class KpiCategory {
-  @PrimaryGeneratedColumn('uuid')
-  @Field(type => ID, { description: 'Unique identifier for this KPI category.' })
-  readonly id: string
-
-  @ManyToOne(type => Domain)
-  @Field({ nullable: true, description: 'Domain (tenant) to which this KPI category belongs.' })
-  domain?: Domain
-
-  @RelationId((category: KpiCategory) => category.domain)
-  @Field({ nullable: true, description: 'ID of the domain (tenant) for this KPI category.' })
-  domainId?: string
-
-  @Column()
-  @Field({ description: 'Name of the KPI category.' })
-  name: string
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Detailed description of this KPI category.' })
-  description?: string
-
-  @Column({ nullable: false, default: false })
-  @Field({ nullable: true, description: 'Whether this category is active (usable) or not.' })
-  active?: boolean
-
-  @Column({ nullable: true })
-  @Field({
-    nullable: true,
-    description:
-      'Calculation formula for category score using KPI score variables. Example: "avg(sales_score, profit_score)" or "sales_score * 0.6 + profit_score * 0.4". If not provided, weighted average of child KPI scores will be used.'
-  })
-  formula?: string
-
-  @Column({ type: 'float', nullable: true, default: 1 })
-  @Field({ nullable: true, description: 'Weight for aggregation in higher-level summary.' })
-  weight?: number
-
-  @Column({ default: 'DAY' })
-  @Field(type => KpiPeriodType, { description: 'Aggregation period type for this category.' })
-  periodType: KpiPeriodType
-
-  @ManyToOne(type => User, { nullable: true })
-  @Field(type => User, { nullable: true, description: 'User who created this KPI category.' })
-  creator?: User
-
-  @RelationId((category: KpiCategory) => category.creator)
-  @Field({ nullable: true, description: 'ID of the user who created this KPI category.' })
-  creatorId?: string
-
-  @ManyToOne(type => User, { nullable: true })
-  @Field(type => User, { nullable: true, description: 'User who last updated this KPI category.' })
-  updater?: User
-
-  @RelationId((category: KpiCategory) => category.updater)
-  @Field({ nullable: true, description: 'ID of the user who last updated this KPI category.' })
-  updaterId?: string
-
-  @CreateDateColumn()
-  @Field({ nullable: true, description: 'Timestamp when this KPI category was created.' })
-  createdAt?: Date
-
-  @UpdateDateColumn()
-  @Field({ nullable: true, description: 'Timestamp when this KPI category was last updated.' })
-  updatedAt?: Date
-
-  @OneToMany(type => Kpi, kpi => kpi.category)
-  @Field(type => [Kpi], { nullable: true, description: 'List of KPIs belonging to this category.' })
-  kpis?: Kpi[]
-}

package/server/service/kpi-category-value/index.ts

@@ -1,7 +0,0 @@
-import { KpiCategoryValue } from './kpi-category-value'
-import { KpiCategoryValueQuery } from './kpi-category-value-query'
-import { KpiCategoryValueMutation } from './kpi-category-value-mutation'
-
-export const entities = [KpiCategoryValue]
-export const resolvers = [KpiCategoryValueQuery, KpiCategoryValueMutation]
-export const subscribers = []