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

237 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 통계 데이터와 계산 흐름
현재 구현은 **문항과 응답을 요청당 한 번 준비하고, 요청한 문항별로 응답을 선택해 계산한 뒤 결과를 순서대로 전송**한다.
- 기준: 2026-10-23 소스 코드. 실제 DB 결과를 비교한 문서는 아니다.
- 대상 API: `POST /api/v1/project/{projectType}/{pkey}/statistics/result`
- `index`: 집계할 문항. 예: 만족도.
- `banner`: 응답을 나누는 기준. 예: 성별, 연령대.
- 그림의 `클래스.메서드()`는 실제 구현 이름이다. 같은 클래스의 연속 작업은 한 상자에 묶었다.
- 1번은 간략 버전, 2번은 상세 버전이다. 상세 버전은 큰 그림 하나가 길어지지 않도록 단계별로 나눴다.
## 1. 간략 버전
```mermaid
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. 공통 준비: 어디서 데이터를 가져오는가
이 단계는 스트림을 반환하기 전에 실행한다. 문항 목록과 합집합으로 선택한 응답 데이터는 요청당 한 번 조회한다. 다만 텍스트 분석용 사전·품사 설정은 이후 텍스트 문항마다 별도로 조회한다.
```mermaid
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](../src/main/resources/mybatis/mapper/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가 반복되어도 해당 위치마다 처리한다.
```mermaid
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. 텍스트 분석: 어떤 사전으로 단어를 세는가
```mermaid
flowchart TD
INPUT["StatisticsService.textAnalysis()<br/>StatisticsTextService.analyze()"]
TEXT["StatisticsTextService.answerTexts()<br/>해당 QID와 QID_ 하위 키의 문자열 수집<br/>HTML 문자 복원"]
DICT[("Report DB<br/>REPORT_NLP_WORD<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/>응답 문자열 + 사용자 사전 → 형태소 목록"]
FILTER["StatisticsTextService.isCounted()<br/>선택 품사 중 명사 또는 2글자 이상<br/>SL은 선택 품사·길이와 관계없이 포함"]
COUNT["StatisticsTextService.analyze()<br/>단어+품사별 빈도 합산<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 실행 환경이 없으면 오류를 반환한다.
### 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](../src/main/java/com/kri/kart/server/controller/StatisticsController.java) | `result()` |
| [StatisticsBatchRequestDto.java](../src/main/java/com/kri/kart/server/dto/statistics/StatisticsBatchRequestDto.java) | `requests()` |
| [StatisticsService.java](../src/main/java/com/kri/kart/server/service/StatisticsService.java) | `prepare()` → `loadQuestions()` / `loadResponses()`, `stream()` → `calculate()` |
| [SurveySessionProvider.java](../src/main/java/com/kri/kart/server/persistence/SurveySessionProvider.java) | `mapper()` / `forProject()` |
| [QuestionService.java](../src/main/java/com/kri/kart/server/service/QuestionService.java) | `organize()` / `expandOpen()` / `expandRank()` / `expandAttributes()` |
| [QuestionRepository.java](../src/main/java/com/kri/kart/server/persistence/repository/QuestionRepository.java) / [QuestionMapper.xml](../src/main/resources/mybatis/mapper/QuestionMapper.xml) | `list()` / statement `list` |
| [StatisticsRepository.java](../src/main/java/com/kri/kart/server/persistence/repository/StatisticsRepository.java) / [StatisticsMapper.xml](../src/main/resources/mybatis/mapper/StatisticsMapper.xml) | `data()` / statement `data` |
| [StatisticsDataService.java](../src/main/java/com/kri/kart/server/service/statistics/StatisticsDataService.java) | `normalize()` / `flatten()` |
| [StatisticsFilterService.java](../src/main/java/com/kri/kart/server/service/statistics/StatisticsFilterService.java) | `compile()` / `compileGroup()` / `compileCondition()` |
| [StatisticsDimensionService.java](../src/main/java/com/kri/kart/server/service/statistics/StatisticsDimensionService.java) | `resolve()` / `choices()` / `answeredChoices()` |
| [StatisticsSelectionService.java](../src/main/java/com/kri/kart/server/service/statistics/StatisticsSelectionService.java) | `total()` / `cases()` / `bannerTotal()` / `bannerCases()` / `select()` |
| [StatisticsAggregationService.java](../src/main/java/com/kri/kart/server/service/statistics/StatisticsAggregationService.java) | `aggregate()` / `columns()` / `addBanner()` / `percentBase()` / `bannerCrossTable()` |
| [StatisticsArithmetic.java](../src/main/java/com/kri/kart/server/service/statistics/StatisticsArithmetic.java) | `round()` / `display()` |
| [StatisticsTableService.java](../src/main/java/com/kri/kart/server/service/statistics/StatisticsTableService.java) | `table()` / `headers()` / `transpose()` |
| [StatisticsTextService.java](../src/main/java/com/kri/kart/server/service/statistics/StatisticsTextService.java) | `analyze()` / `answerTexts()` / `isCounted()` |
| [KiwiNlpService.java](../src/main/java/com/kri/kart/server/service/statistics/KiwiNlpService.java) | `tokenize()` |
| [NlpRepository.java](../src/main/java/com/kri/kart/server/persistence/repository/NlpRepository.java) / [NlpMapper.xml](../src/main/resources/mybatis/mapper/NlpMapper.xml) | `words()` / `tags()` |
| [StatisticsStreamService.java](../src/main/java/com/kri/kart/server/service/statistics/StatisticsStreamService.java) | `stream()` / `writeEvents()` / `send()` |
| [QuotaService.java](../src/main/java/com/kri/kart/server/service/QuotaService.java) | `result()` |
| [QuotaRepository.java](../src/main/java/com/kri/kart/server/persistence/repository/QuotaRepository.java) / [QuotaMapper.xml](../src/main/resources/mybatis/mapper/QuotaMapper.xml) | `quotaSet()` / `quotaEntries()` |
| [QuotaComputationService.java](../src/main/java/com/kri/kart/server/service/quota/QuotaComputationService.java) | `compute()` |
Mermaid 지원 Markdown 미리보기에서 다이어그램을 볼 수 있다. 문서의 화살표는 주요 처리·데이터 전달 관계를 나타내며 모든 화살표가 직접적인 Java 메서드 호출을 의미하지는 않는다.