Files
KART-SERVER-JAVA/docs/statistics-flow.md

21 KiB
Raw Blame History

통계 데이터와 계산 흐름

현재 구현은 문항과 응답을 요청당 한 번 준비하고, 요청한 문항별로 응답을 선택해 계산한 뒤 결과를 순서대로 전송한다.

  • 기준: 2026-10-23 소스 코드. 실제 DB 결과를 비교한 문서는 아니다.
  • 대상 API: POST /api/v1/project/{projectType}/{pkey}/statistics/result
  • index: 집계할 문항. 예: 만족도.
  • banner: 응답을 나누는 기준. 예: 성별, 연령대.
  • 그림의 클래스.메서드()는 실제 구현 이름이다. 같은 클래스의 연속 작업은 한 상자에 묶었다.
  • 1번은 간략 버전, 2번은 상세 버전이다. 상세 버전은 큰 그림 하나가 길어지지 않도록 단계별로 나눴다.

1. 간략 버전

flowchart TD
    REQ["화면에서 집계 요청<br/>StatisticsController.result()"]
    QUESTIONS[("KON 또는 KONKIWI<br/>문항 정의")]
    LOAD["문항과 응답을 한 번 준비<br/>StatisticsService.prepare()"]
    RESPONSES[("KON 또는 KONKIWI<br/>원래 응답 + 저장된 파생 응답<br/>필요한 경우 KIWI 프로필 응답")]
    FILTER["응답 JSON을 Map으로 변환하고 필터 적용<br/>StatisticsDataService.normalize()<br/>StatisticsFilterService.compile()로 만든 조건 사용"]
    CALC["요청한 문항별로 대상 응답 선택<br/>StatisticsService.calculate()"]
    TYPE{"주관식 문자 문항인가?<br/>StatisticsService.isOpenText()"}
    TABLE["전체·배너별 N / % / 통계량 계산<br/>StatisticsAggregationService.aggregate()"]
    LAYOUT["표 머리글·병합·전치 적용<br/>StatisticsTableService.table()"]
    NLP["형태소 분석과 단어 빈도 계산<br/>StatisticsTextService.analyze()"]
    DICT[("Report DB: NLP 사전·품사 설정<br/>로컬 파일: Kiwi 모델")]
    OUT["문항별 result 또는 error 전송<br/>StatisticsService.stream()<br/>StatisticsStreamService.send()"]
    END["마지막 complete 전송<br/>전체 수·성공 수·실패 수"]

    REQ --> LOAD
    QUESTIONS --> LOAD
    RESPONSES --> LOAD
    LOAD --> FILTER --> CALC --> TYPE
    TYPE -->|아니오| TABLE --> LAYOUT --> OUT
    TYPE -->|예| NLP --> OUT
    DICT --> NLP
    OUT -->|다음 문항| CALC
    OUT -->|모든 문항 처리 후| END

예를 들어 **“30대 응답자 중 성별에 따른 만족도”**를 요청하면, 나이로 응답자를 걸러 낸 다음 만족도 응답을 성별로 나눠 N·%·평균 등을 계산한다.

2. 상세 버전

2-1. 공통 준비: 어디서 데이터를 가져오는가

이 단계는 스트림을 반환하기 전에 실행한다. 문항 목록과 합집합으로 선택한 응답 데이터는 요청당 한 번 조회한다. 다만 텍스트 분석용 사전·품사 설정은 이후 텍스트 문항마다 별도로 조회한다.

flowchart TD
    API["StatisticsController.result()<br/>StatisticsBatchRequestDto.requests()<br/>indexes를 개별 요청 목록으로 변환"]
    PREP["StatisticsService.prepare()<br/>validate(): 모드·index·날짜 확인"]
    QLOAD["StatisticsService.loadQuestions()<br/>QuestionRepository.list()<br/>QuestionMapper.list()"]
    SESSION["Repository가 SurveySessionProvider.mapper() 호출<br/>forProject(): 0=KON / 1=KONKIWI"]
    QDB[("선택한 설문 DB<br/>QUESTION + DERIVED_VARIABLE<br/>KIWI이며 role=1001이면 프로필 문항 포함")]
    ORGANIZE["QuestionService.organize()<br/>expandOpen() / expandRank() / expandAttributes()<br/>입력칸·순위·속성별 문항으로 확장"]
    VALID["StatisticsService.validateDimensions()<br/>StatisticsDimensionService.resolve()<br/>모든 index와 banner의 문항 정의 확인"]
    COMPILE["StatisticsFilterService.compile()<br/>필터 구조를 응답자 판정 함수로 변환"]
    ROOTS["StatisticsService.loadResponses()<br/>storageRoots() / toStorageRoot()<br/>모든 요청의 index·banner 루트 합집합 생성"]
    RAW[("선택한 설문 DB<br/>DATA.DATJSON: 원래 응답<br/>DERIVED_DATA.DATJSON: 저장된 파생 응답")]
    PROFILE[("KIWI_SURVEY.dbo.V_PROFILE<br/>P_DATJSON: 프로필 응답")]
    QUERY["StatisticsRepository.data()<br/>StatisticsMapper.data()<br/>완료·조사 유형·날짜 조건으로 조회하고 JSON 결합"]
    DAT["StatisticsDataDto.dat<br/>집계용: 선택한 루트가 들어 있는 저장 그룹"]
    FDAT["StatisticsDataDto.filterDat<br/>필터용: 전체 응답 그룹<br/>필터가 없으면 null"]
    NORMAL["StatisticsDataService.normalize() → flatten()<br/>JSON 키를 대문자로 통일하고 Map으로 변환<br/>SurveyResponseDto 생성"]
    APPLY["StatisticsService.loadResponses()의 stream().filter(filter)<br/>판정 함수는 response.filterValues() 사용<br/>조건을 통과한 응답만 남김"]
    BATCH["StatisticsBatchDto 생성<br/>project / requests / questions / responses"]
    AUDIT["StatisticsService.prepare() → LogService.writeSiteLog()<br/>Get Report Data를 배치당 한 번 기록 시도<br/>그 후 Controller가 스트림 반환"]

    API --> PREP --> QLOAD
    SESSION -. "문항 조회와 응답 조회에 각각 적용" .-> QLOAD
    SESSION -.-> QUERY
    QDB --> QLOAD --> ORGANIZE --> VALID --> COMPILE --> ROOTS
    ROOTS --> QUERY
    RAW --> QUERY
    PROFILE -. "needsProfileResponses()가 참조 여부 확인" .-> QUERY
    QUERY --> DAT --> NORMAL
    QUERY --> FDAT --> NORMAL
    COMPILE -. "판정 함수" .-> APPLY
    NORMAL --> APPLY --> BATCH --> AUDIT
    ORGANIZE -. "questions" .-> BATCH

SQL에서 거르는 조건 — StatisticsMapper.xml의 data:

조건 실제 처리
프로젝트 DATA.PKEY = pkey
완료 상태 모든 dataScope에서 Status = 10
ACTUAL SURVEY_TYPE <> 'TEST'
TEST SURVEY_TYPE = 'TEST'
ALL 조사 유형 제한 없음. 완료 조건은 유지
날짜 FN_LAST_TIME(survey_date)를 날짜로 변환해 시작일·종료일 포함 비교. 시작일만 있으면 그 하루
파생 응답 DERIVED_DATA를 PKEY + IDKEY로 LEFT JOIN. 이 요청에서 파생값을 재계산하지 않음
프로필 응답 KIWI이며 index·banner·filter에서 PF/PS 문항을 참조하면 V_PROFILE JOIN

집계용 데이터와 필터용 데이터를 분리하는 이유: 만족도만 집계해도 나이로 필터링할 수 있어야 하기 때문이다.

데이터 사용하는 곳 의미
dat → SurveyResponseDto.values() 문항별 응답 선택, N·%·통계량, 텍스트 분석 선택한 저장 그룹의 응답. 요청한 키만 잘라 내는 방식은 아니므로 같은 그룹의 다른 키도 포함될 수 있음
filterDat → SurveyResponseDto.filterValues() StatisticsFilterService.compileCondition()이 만든 판정 함수 전체 응답을 보고 필터 판단. 필터가 없으면 normalize 단계에서 values를 함께 사용

루트는 저장된 응답 그룹을 찾는 기준이다. toStorageRoot()는 대문자로 바꾸고 #A를 제거한 뒤 첫 _ 앞부분을 사용한다. 예를 들어 q1_2#a는 Q1이 된다. TABULATION 모드에서는 index 대신 INDEX 루트를 사용한다.

2-2. 문항별 계산: 어떤 응답으로 N·%를 만드는가

준비한 배치를 StatisticsStreamService.stream()이 비동기 작업에 넘긴다. writeEvents() → StatisticsService.stream() 순서로 들어가며, 아래 계산을 indexes의 입력 순서대로 실행한다. 같은 index가 반복되어도 해당 위치마다 처리한다.

flowchart TD
    BATCH["공통 준비 결과<br/>StatisticsBatchDto"]
    LOOP["StatisticsService.stream()<br/>이번 위치의 요청 선택 → calculate()"]
    PICK["StatisticsService.withinStorageRoots()<br/>이번 index·banner의 루트에 해당하는 키가<br/>하나라도 있는 응답자만 선택"]
    DIM["StatisticsDimensionService.resolve()<br/>문항 ID → 기본 키·보기·속성·순위 범위<br/>숫자 문항 보기는 실제 응답에서 구성"]
    TYPE{"StatisticsService.isOpenText()<br/>text 문항이며 #A가 아닌가?"}
    TEXT["2-3의 텍스트 분석으로 이동<br/>StatisticsService.textAnalysis()"]
    AGG["StatisticsAggregationService.aggregate()<br/>columns()로 열별 응답 목록 생성"]
    TOTAL["StatisticsSelectionService.total() / cases()<br/>전체 응답 목록과 보기별 응답 목록"]
    BANNER["StatisticsAggregationService.addBanner()<br/>StatisticsSelectionService.bannerTotal() / bannerCases()<br/>배너 값별로 목록 분리, 중첩 배너는 재귀 처리"]
    MODE{"집계 모드"}
    NORMAL["StatisticsAggregationService<br/>totalRow() / addChoiceRows()<br/>countCell() / percentBase()<br/>N=목록 크기, %=N÷분모×100"]
    SUMMARY["StatisticsAggregationService.addSummaryRows()<br/>숫자: 평균·중앙값·표준편차 등<br/>척도: Top/Mid/Bottom·NPS 또는 평균<br/>요청한 사용자 값 그룹 추가"]
    CROSS["StatisticsAggregationService.bannerCrossTable()<br/>crossCount() / overlapCount(): 배너 간 겹침<br/>crossBase() / groupBase(): 분모 결정"]
    TABLE["StatisticsTableService.table()<br/>headers(): 머리글과 병합 정보 생성<br/>필요하면 transpose(): 행·열 교환<br/>StatisticsResponseDto, type=TABLE"]
    EVENT["StatisticsService.resultEvent() / errorEvent()<br/>문항 계산 오류는 해당 위치의 error로 변환"]
    SEND["StatisticsStreamService.send()<br/>JSON 한 줄 + 줄바꿈 전송"]
    DONE["StatisticsService.completeEvent()<br/>total / succeeded / failed"]

    BATCH --> LOOP --> PICK --> DIM --> TYPE
    TYPE -->|예| TEXT --> EVENT
    TYPE -->|아니오| AGG --> TOTAL --> BANNER --> MODE
    MODE -->|STANDARD 또는 TABULATION_0| NORMAL --> SUMMARY --> TABLE
    MODE -->|TABULATION_1| CROSS --> TABLE
    TABLE --> EVENT --> SEND
    SEND -->|다음 위치| LOOP
    SEND -->|모두 처리함| DONE

withinStorageRoots()는 응답자를 고르는 단계다. 응답자의 Map에서 다른 키를 삭제하는 단계는 아니다. 전체 배치를 한 번에 조회한 영향으로 특정 문항의 대상자가 늘어나지 않도록 다시 제한한다.

계산 도중 연결이 끊기거나 취소되면 반복과 전송을 중단한다. 공통 준비 단계의 오류는 스트림 시작 전 HTTP 오류이며, 문항별 계산 오류와 구분된다.

N과 분모가 만들어지는 위치:

항목 실제 클래스·메서드 계산 의미
전체 사례수 StatisticsSelectionService.total() 해당 문항에 응답한 목록 구성
보기별 N StatisticsSelectionService.cases() 해당 보기를 선택한 목록의 크기
배너별 사례수와 N bannerTotal() / bannerCases() 상위 단계 목록을 배너의 보기 조건으로 다시 선택
일반 비율 StatisticsAggregationService.countCell() 분모가 0이면 0%, 아니면 N ÷ 분모 × 100
일반 표의 Total 비율 totalRow() 해당 열의 보기별 비율 합. 복수응답에서는 100%를 넘을 수 있음
평균 mean() 보기 값 × 사례수의 합 ÷ 결측 사례를 뺀 분모. 역척도 처리 포함
나머지 숫자 통계 numericValues() → calculate() 응답 숫자 목록으로 Median·SD·Max·Min·Mode·선택적 Sum 계산
척도 그룹과 NPS addScaleGroups() / addGroup() / addNpsRow() 그룹에 해당하는 보기 사례 합산. NPS는 Promoters % − Detractors %
반올림·표시 문자열 StatisticsArithmetic.round() / display() 계산값과 화면 표시 문자열 구성

순위·속성 응답 선택은 StatisticsSelectionService.select()가 여러 슬롯을 순회해 목록에 추가한다. 같은 응답자가 여러 슬롯에 들어가면 여러 번 집계될 수 있으므로 N이 항상 중복 없는 사람 수인 것은 아니다. 속성 전체 문항의 요약은 columns()에서 요청 배너 대신 해당 문항의 #A 배너를 사용한다.

모드별 차이:

모드 표 구성 분모 결정 메서드와 규칙
STANDARD 집계 문항의 보기를 행으로, 배너를 열로 구성 percentBase(): 해당 열의 전체 응답 목록 크기
TABULATION_0 빈 index로 전체 표본을 놓고 배너 구성비 계산 percentBase(): Total 열은 자체 사례수, 배너 열은 형제 열 사례수의 합. 형제가 없으면 Total 사례수. 형제 판정은 실제 열 ID의 마지막 한 자리 숫자 규칙을 유지
TABULATION_1 배너를 행과 열 양쪽에 놓고 교차 계산 crossBase(): Total 열은 행의 형제 열들을 합친 고유 IDKEY 수, 나머지 열은 해당 열의 사례수

TABULATION_1의 overlapCount()는 같은 IDKEY의 좌우 목록 쌍을 센다. 모든 교차 셀이 고유 응답자 교집합 크기와 같다고 가정하면 안 된다. 빈 분모의 일반 빈도 셀은 0%이며, 정의되지 않는 그룹 비율·통계량은 null과 - 표시를 사용한다.

2-3. 텍스트 분석: 어떤 사전으로 단어를 세는가

flowchart TD
    INPUT["StatisticsService.textAnalysis()<br/>StatisticsTextService.analyze()"]
    TEXT["StatisticsTextService.answerTexts()<br/>해당 QID와 QID_ 하위 키의 문자열 수집<br/>HTML 문자 복원"]
    DICT[("Report DB<br/>REPORT_NLP_WORD (STOP 행 = 불용어, SOURCE_TEXT 행 = 치환)<br/>REPORT_NLP_TAG")]
    REPO["NlpRepository.words() / tags()<br/>NlpMapper.words() / tags()<br/>kartSqlSessionTemplate 사용"]
    MODEL[("로컬 Kiwi 모델 파일<br/>kri.kart.nlp.model-directory")]
    TOKEN["KiwiNlpService.tokenize()<br/>응답 문자열 + 사용자 사전 + 치환 → 형태소 목록<br/>오타 교정·구어체 정규화<br/>compoundNounMaxTokens에 따라 복합명사 합치기"]
    FILTER["StatisticsTextService.analyze() / isCounted()<br/>STOP 불용어 제외<br/>선택 품사 중 명사 또는 2글자 이상<br/>SL은 선택 품사·길이와 관계없이 포함"]
    COUNT["StatisticsTextService.analyze() / merge()<br/>단어+품사별 빈도 합산<br/>wordMergeMode에 따라 같은 글자 합산<br/>빈도 내림차순, 동률은 첫 등장 순서<br/>상위 100개 선택"]
    OUT["StatisticsResponseDto, type=TEXT_ANALYSIS<br/>words: 단어·품사·빈도<br/>문항별 result 이벤트로 반환"]

    INPUT --> TEXT --> TOKEN
    DICT --> REPO
    REPO -->|사전 단어·치환| TOKEN
    MODEL --> TOKEN
    TOKEN --> FILTER --> COUNT --> OUT
    REPO -->|선택 품사·불용어| FILTER

사전은 전체 공통(PKEY=ALL), 프로젝트 공통(QID=ALL), 해당 문항 범위를 합쳐 읽는다. 사용자 단어의 점수는 각각 10·50·100이며, 같은 단어는 가장 높은 점수로 한 번만 등록한다. 이 점수는 형태소 분석 사전에 사용하는 값이며 최종 빈도에 곱하는 통계 가중치가 아니다. 모델이나 native 실행 환경이 없으면 오류를 반환한다.

텍스트 분석 처리 순서는 다음과 같다.

  1. 치환: REPORT_NLP_WORD에서 SOURCE_TEXT가 있는 행은 SOURCE_TEXT를 WORD_TEXT/WORD_TAG로 바꾼다. 우선순위는 문항 > 프로젝트 > 전체이고, 사용자 사전보다 우선한다.
  2. 복합명사 합치기: compoundNounMaxTokens(기본 3)에 따라 한 어절 안에서 붙은 명사를 합친다. 사용자 사전 단어와 치환 결과는 합치지 않는다.
  3. 불용어 제외: REPORT_NLP_WORD에서 WORD_TAG가 STOP인 단어를 품사와 관계없이 제외한다. 대소문자와 공백 차이는 무시한다.
  4. 품사 합산: wordMergeMode(기본 2=명사 계열)에 따라 같은 글자의 품사별 빈도를 합친다.

기존 analyze(project, qid, responses)와 tokenize(texts, dictionary) 오버로드는 치환·불용어·합치기를 적용하지 않는 이전 동작을 유지하며, 통계 API만 새 옵션을 사용한다.

2-4. 쿼터는 어디서 갈라지는가

일반 통계 스트림과 별도인 POST /api/v1/quota/{projectType}/{pkey}/{quotaOrder}/result는 저장된 설정으로 집계한 뒤 목표 수와 결합한다. 단일 JSON 응답이다.

순서 실제 클래스·메서드 데이터 처리
1 QuotaService.result() → QuotaRepository.quotaSet() → QuotaMapper.quotaSet() 선택한 설문 DB의 QUOTASET에서 설정 조회
2 QuotaService.result() → LogService.writeSiteLog() 설정을 찾은 뒤 QUOTA VIEW 기록 시도
3 QuotaService.result() / LegacyFilterService.parse() 첫 ROW를 index로, COL을 배너로 구성. 저장된 FILTER는 AST로 해석. SQL로 실행하지 않음
4 StatisticsService.prepareQuota() 2-1의 공통 준비 재사용. 빈 STANDARD index 허용. Get Report Data는 기록하지 않음
5 StatisticsAggregationService.aggregate() 사례수 표 계산. 소계 없이 집계하며 일반 통계의 stream() / calculate()를 경유하지 않음
6 QuotaRepository.quotaEntries() → QuotaMapper.quotaEntries() 같은 설문 DB의 QUOTA에서 목표 수와 설정 조회
7 QuotaComputationService.compute() 계산된 사례수와 ORI_CNT 목표 수 결합. 0 목표 행 처리·Total 재계산·달성률 및 표시 상태 구성

3. 소스 바로가기

링크는 이 문서 기준 상대 경로다. private 메서드도 흐름 설명에 포함했다.

소스 먼저 볼 메서드
StatisticsController.java result()
StatisticsBatchRequestDto.java requests()
StatisticsService.java prepare() → loadQuestions() / loadResponses(), stream() → calculate()
SurveySessionProvider.java mapper() / forProject()
QuestionService.java organize() / expandOpen() / expandRank() / expandAttributes()
QuestionRepository.java / QuestionMapper.xml list() / statement list
StatisticsRepository.java / StatisticsMapper.xml data() / statement data
StatisticsDataService.java normalize() / flatten()
StatisticsFilterService.java compile() / compileGroup() / compileCondition()
StatisticsDimensionService.java resolve() / choices() / answeredChoices()
StatisticsSelectionService.java total() / cases() / bannerTotal() / bannerCases() / select()
StatisticsAggregationService.java aggregate() / columns() / addBanner() / percentBase() / bannerCrossTable()
StatisticsArithmetic.java round() / display()
StatisticsTableService.java table() / headers() / transpose()
StatisticsTextService.java analyze() / answerTexts() / isCounted()
KiwiNlpService.java tokenize()
NlpRepository.java / NlpMapper.xml words() / tags()
StatisticsStreamService.java stream() / writeEvents() / send()
QuotaService.java result()
QuotaRepository.java / QuotaMapper.xml quotaSet() / quotaEntries()
QuotaComputationService.java compute()

Mermaid 지원 Markdown 미리보기에서 다이어그램을 볼 수 있다. 문서의 화살표는 주요 처리·데이터 전달 관계를 나타내며 모든 화살표가 직접적인 Java 메서드 호출을 의미하지는 않는다.