@dssp/dcsp 1.0.2 → 1.0.6

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

@@ -0,0 +1,198 @@
+import { KpiMetricValue, KpiMetricValuePatch } from '@things-factory/kpi';
+import { Attachment, NewAttachment } from '@things-factory/attachment-base';
+/**
+ * 외부 시스템 데이터 수집 결과 — 시스템별 한 row.
+ * UI "자동 수집" 버튼이 시나리오 호출 후 시스템별 성공·오류 표시에 사용.
+ */
+declare class ExternalDataCollectionResult {
+    source: string;
+    label: string;
+    ok: boolean;
+    message: string;
+    data?: any;
+}
+export declare class KpiMetricValueMutation {
+    updateKpiMetricValuesCumulative(patches: KpiMetricValuePatch[], context: ResolverContext): Promise<KpiMetricValue[]>;
+    updateKpiMetricValuesAssessment(patches: KpiMetricValuePatch[], context: ResolverContext): Promise<KpiMetricValue[]>;
+    /**
+     * KpiMetricValue 의 unique 조합 (domain, metric, valueDate, org) 기준 진짜 upsert.
+     *
+     * 기존 mutation 의 `repo.save({...patch})` 는 patch.id 만 보고 update/insert 결정해
+     * 같은 metric × 같은 valueDate × 같은 org 인데 patch.id 가 새 UUID 인 경우 unique
+     * 인덱스 (ix_kpi_metric_value_latest) 위반 에러 또는 row 누적 위험. 정확한 upsert
+     * 동작을 보장하기 위해 조합 lookup → 기존 id 사용 → save.
+     *
+     * 월별 metric (periodType=MONTH, valueDate=YYYY-MM-01) 의 단일 row 정책을 자연 충족.
+     *
+     * **도메인 컨텍스트 스위치**: caller (운영자) 가 system 도메인일 수 있어 patch.org
+     * (= projectId) 로 프로젝트 테넌트 도메인을 lookup 해 그 컨텍스트로 저장. 모든
+     * patch 가 같은 projectId 라 가정 (한 번의 mutation = 한 프로젝트의 값들).
+     */
+    private upsertKpiMetricValues;
+    updateKpiMetricValuesSentiment(attachment: NewAttachment, context: ResolverContext): Promise<Attachment | null>;
+    /**
+     * FileUpload 스트림을 버퍼로 읽기
+     */
+    private readFileToBuffer;
+    /**
+     * Buffer로부터 FileUpload 객체 생성
+     */
+    private createFileUploadFromBuffer;
+    /**
+     * operator-runner 서비스 호출 (Buffer 사용)
+     */
+    private callOperatorRunnerServiceWithBuffer;
+    /**
+     * 메트릭 값 저장
+     */
+    private saveMetricValue;
+    finalizeProjectWithKpiRecalculation(projectId: string, context: ResolverContext): Promise<boolean>;
+    /**
+     * 완공 처리 없이 KPI 만 재계산 — 진행 중 프로젝트의 중간 결과 산정 용도.
+     * DB 에 이미 저장된 KpiMetricValue 만 가지고 formula 평가. 외부 시나리오 (juso/
+     * allbaro/kiscon) 자동 수집은 의도적으로 호출하지 않음 — 외부 수집은 사용자가
+     * "자동 수집" 버튼 (`collectProjectExternalData`) 으로 명시적으로 실행하는 흐름.
+     * 권한은 `kpi:recalculate` 로 분리해 finalize 보다 가볍게 부여 가능.
+     */
+    recalculateProjectKpi(projectId: string, context: ResolverContext): Promise<boolean>;
+    /**
+     * UI "자동 수집" 버튼 전용 mutation. 외부 시스템 3종 시나리오를 순차 호출하고
+     * 시스템별 성공/실패 + 메시지를 반환. UI 는 결과를 보고 카드별 상태 (성공·오류) 를 표시.
+     *
+     * 시나리오는 도메인 EnvVar (주소·자격증명·서비스키 등) 만으로 동작하므로 파라미터 X.
+     * 한 시스템 실패가 다른 시스템 수집을 막지 않도록 try/catch 로 격리.
+     *
+     * 운영 현실: 키스콘·올바로는 시공사 ID/PW 가 자주 미확보 → 오류 흔함. 세움터는 공공
+     * 데이터 서비스키만으로 동작 가능. UI 는 시스템별로 명확한 오류 메시지 노출.
+     */
+    collectProjectExternalData(projectId: string, context: ResolverContext): Promise<ExternalDataCollectionResult[]>;
+    /**
+     * 프로젝트 정보 수정 화면의 "정보 연동" 버튼 전용 — 세움터 수집.
+     * BuildingComplex 기본 속성 (area / floorAreaRatio / siteType / structureType /
+     * coverageRatio / householdCount 등) 자동 채움 목적.
+     *
+     * **완공/완공전 케이스 통합**: 완공 단지는 건축물대장, 완공 전(택지지구·정비사업 블록)
+     * 단지는 주택인허가에 연면적이 있다. `collectSaeumteo` 가 주소 하나로 대장 → (연면적
+     * 없으면) 인허가 순으로 시도해 하나의 세움터 결과로 반환.
+     *
+     * address 인자가 있으면 시나리오 실행 전에 canonical EnvVar 로 upsert — 운영자가 폼에서
+     * 방금 입력한 주소를 시나리오가 곧바로 사용. (블록형이면 `…블럭 (단지명)` 형태.)
+     *
+     * **도메인 스위치**: mutation 호출은 system / 운영자 도메인에서 일어나지만 시나리오·
+     * EnvVar 는 **프로젝트가 속한 도메인** 에 있어야 자연. project.domain 으로 컨텍스트
+     * 스위치 후 그 도메인에서 EnvVar upsert + 시나리오 실행.
+     */
+    collectProjectBasicInfo(projectId: string, address: string, context: ResolverContext): Promise<ExternalDataCollectionResult>;
+    /**
+     * mutation 호출이 system / 운영자 도메인에서 일어나도 시나리오·EnvVar 는 **프로젝트
+     * 테넌트 도메인** 에서 동작해야 자연. project.code 로 자식 (테넌트) 도메인을 찾아
+     * 컨텍스트 사본 만들어 반환.
+     *
+     * 테넌트 도메인 매핑: Domain.subdomain = project.code AND Domain.extType = 'project'
+     * (promoteProjectToTenant mutation 이 그렇게 생성). project.domain 자체는 부모
+     * 도메인이라 외부 연동 EnvVar 가 거기 있을 일이 없어 사용 부적합.
+     *
+     * 테넌트 도메인이 없거나 (= 아직 승격 안 됨) project.code 가 비어있으면 원본
+     * 컨텍스트 그대로 반환 (방어). project 자체가 없으면 throw.
+     */
+    private switchToProjectDomain;
+    /**
+     * 컨텍스트의 도메인에 EnvVar 1개 upsert. 시나리오가 도메인 EnvVar 를 우선 참조하는
+     * 정책이라, 폼에서 입력한 주소를 시나리오 입력으로 흘리는 다리 역할.
+     */
+    private upsertEnvVar;
+    /**
+     * 단일 시나리오 호출 + result unwrap + 실패 판정 — collectProjectExternalData 의
+     * loop 본체와 같은 로직을 1건짜리로 분리.
+     */
+    private runSingleScenario;
+    /**
+     * 외부 시스템 3종 시나리오 순차 실행 + 시스템별 결과 수집.
+     */
+    private runExternalDataScenariosWithResults;
+    /**
+     * 세움터 수집 — 완공/완공전 케이스를 **하나의 세움터 결과**로 통합.
+     *
+     * 완공 단지는 건축물대장(building-info)에, 완공 전(택지지구·정비사업 블록) 단지는
+     * 인허가에 연면적이 있다. 인허가는 **용도별로 소스가 갈린다**:
+     *  - 주택(공동주택) → 주택인허가(housing-permit, 사업계획승인)
+     *  - 비주택(복합·노유자·근생·업무 등) → 건축인허가(building-permit block, 건축허가)
+     * 주소 하나로 세 소스를 순차 시도 — **대장 → 주택인허가 → 건축인허가**. 각 블록 소스는
+     * nameFilter(사업명)가 실제로 매칭될 때만 값을 내고, 매칭 없으면 빈 결과로 통과하므로
+     * (태스크 레벨에서 미매칭=빈결과 보장) **순서와 무관하게 잘못된 소스를 집지 않는다**.
+     * 저장된 용도 필드는 신뢰불가(예: 노유자 복합시설도 building_usage=RESIDENTIAL)라
+     * 사전 라우팅 대신 이 nameFilter 기반 사슬을 쓴다. 출력 필드가 세 소스 동일
+     * (totArea→area 등)이라 downstream 매핑·클로버 방지는 그대로 동작.
+     *
+     * 주소 소스: `address` 인자(정보연동 버튼) 우선, 없으면 도메인 canonical EnvVar
+     * (`Step::건축물관리대장조회::address::query`). 각 시나리오가 자기 EnvVar 를 참조하므로
+     * canonical 주소를 세 키에 동기화한 뒤 실행 — **프로젝트당 주소 1개** 유지.
+     * (블록형 프로젝트는 canonical 에 `…블럭 (단지명)` 을 넣으면 juso 가 자동 분기.)
+     */
+    private collectSaeumteo;
+    /** 시나리오 result 에 유효한 연면적(area>0)이 있는지. 완공/완공전 채택 판정용. */
+    private hasArea;
+    /** 컨텍스트 도메인의 EnvVar 값 읽기 (없으면 undefined). */
+    private readEnvVar;
+    /**
+     * finalize 흐름용 시나리오 호출. 결과 형태 없이 진행만 — finalize 의 KPI 재계산이 곧
+     * 이어지므로 시스템별 결과를 클라이언트에 돌려줄 필요 없음. 실패는 warning 만.
+     */
+    private runExternalDataScenarios;
+    /**
+     * 프로젝트의 모든 KPI Value들을 계층적으로 재계산합니다.
+     * 1. 기존 KPI Value 삭제 (중복 방지)
+     * 2. Leaf KPIs (자식이 없는 KPI): formula 기반 계산
+     * 3. Parent KPIs (자식이 있는 KPI): 자식 KPI scores의 weighted average 계산
+     */
+    private recalculateProjectKpiValues;
+    /**
+     * 개별 KPI Value를 재계산합니다.
+     * 항상 최신 버전의 KPI를 사용하여 계산합니다.
+     */
+    private recalculateKpiValue;
+    /**
+     * scoreFormula를 사용한 성과 점수 계산
+     */
+    private calculateScoreFromFormula;
+    /**
+     * KPI의 grades lookup table을 이용한 성과 점수 변환
+     * 1D (기존 배열) 및 2D (X13 공정률×편차) lookup 모두 지원
+     */
+    private calculateScoreFromLookup;
+    /**
+     * 2D lookup table에서 점수 계산 (X13: 공정률 × 편차 → 점수 1~5)
+     *
+     * 단위 정합:
+     *   - deviationValue (= KpiMetric '일정 이탈 수준' value): % 단위 (예: 2.5 = 2.5%).
+     *   - row.boundary*: ratio 단위 (예: 0.025 = 2.5%).
+     *   - 비교 전 deviationValue 를 /100 해서 ratio 로 변환.
+     */
+    private calculateScoreFrom2DLookup;
+    /**
+     * KpiValue의 성과 점수 계산 및 저장
+     * @param context.progressRate X13 등 2D lookup KPI에 필요한 공정률 (0~100)
+     */
+    private calculateAndSaveScore;
+    /**
+     * Leaf KPI Value를 formula로 계산합니다.
+     * 참고: recalculateProjectKpiValues에서 호출 시 기존 값이 이미 삭제되었으므로 항상 새로 생성됩니다.
+     */
+    private recalculateLeafKpiValue;
+    /**
+     * Parent KPI Value를 계산합니다.
+     * 1. formula가 있으면 자식 KPI 값들을 변수로 사용하여 formula 계산
+     * 2. formula가 없으면 자식 KPI scores의 weighted average로 계산
+     * 참고: recalculateProjectKpiValues에서 호출 시 기존 값이 이미 삭제되었으므로 항상 새로 생성됩니다.
+     */
+    private recalculateParentKpiValue;
+    /**
+     * KPIs를 계층 레벨순으로 정렬합니다 (깊은 레벨부터)
+     */
+    private sortKpisByLevel;
+    /**
+     * 자식 KPI values의 weighted average를 계산합니다.
+     */
+    private calculateWeightedAverage;
+}
+export {};