diff --git a/docs/statistics-flow.md b/docs/statistics-flow.md
new file mode 100644
index 0000000..12d2caf
--- /dev/null
+++ b/docs/statistics-flow.md
@@ -0,0 +1,236 @@
+# 통계 데이터와 계산 흐름
+
+현재 구현은 **문항과 응답을 요청당 한 번 준비하고, 요청한 문항별로 응답을 선택해 계산한 뒤 결과를 순서대로 전송**한다.
+
+- 기준: 2026-10-23 소스 코드. 실제 DB 결과를 비교한 문서는 아니다.
+- 대상 API: `POST /api/v1/project/{projectType}/{pkey}/statistics/result`
+- `index`: 집계할 문항. 예: 만족도.
+- `banner`: 응답을 나누는 기준. 예: 성별, 연령대.
+- 그림의 `클래스.메서드()`는 실제 구현 이름이다. 같은 클래스의 연속 작업은 한 상자에 묶었다.
+- 1번은 간략 버전, 2번은 상세 버전이다. 상세 버전은 큰 그림 하나가 길어지지 않도록 단계별로 나눴다.
+
+## 1. 간략 버전
+
+```mermaid
+flowchart TD
+ REQ["화면에서 집계 요청
StatisticsController.result()"]
+ QUESTIONS[("KON 또는 KONKIWI
문항 정의")]
+ LOAD["문항과 응답을 한 번 준비
StatisticsService.prepare()"]
+ RESPONSES[("KON 또는 KONKIWI
원래 응답 + 저장된 파생 응답
필요한 경우 KIWI 프로필 응답")]
+ FILTER["응답 JSON을 Map으로 변환하고 필터 적용
StatisticsDataService.normalize()
StatisticsFilterService.compile()로 만든 조건 사용"]
+ CALC["요청한 문항별로 대상 응답 선택
StatisticsService.calculate()"]
+ TYPE{"주관식 문자 문항인가?
StatisticsService.isOpenText()"}
+ TABLE["전체·배너별 N / % / 통계량 계산
StatisticsAggregationService.aggregate()"]
+ LAYOUT["표 머리글·병합·전치 적용
StatisticsTableService.table()"]
+ NLP["형태소 분석과 단어 빈도 계산
StatisticsTextService.analyze()"]
+ DICT[("Report DB: NLP 사전·품사 설정
로컬 파일: Kiwi 모델")]
+ OUT["문항별 result 또는 error 전송
StatisticsService.stream()
StatisticsStreamService.send()"]
+ END["마지막 complete 전송
전체 수·성공 수·실패 수"]
+
+ 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()
StatisticsBatchRequestDto.requests()
indexes를 개별 요청 목록으로 변환"]
+ PREP["StatisticsService.prepare()
validate(): 모드·index·날짜 확인"]
+ QLOAD["StatisticsService.loadQuestions()
QuestionRepository.list()
QuestionMapper.list()"]
+ SESSION["Repository가 SurveySessionProvider.mapper() 호출
forProject(): 0=KON / 1=KONKIWI"]
+ QDB[("선택한 설문 DB
QUESTION + DERIVED_VARIABLE
KIWI이며 role=1001이면 프로필 문항 포함")]
+ ORGANIZE["QuestionService.organize()
expandOpen() / expandRank() / expandAttributes()
입력칸·순위·속성별 문항으로 확장"]
+ VALID["StatisticsService.validateDimensions()
StatisticsDimensionService.resolve()
모든 index와 banner의 문항 정의 확인"]
+ COMPILE["StatisticsFilterService.compile()
필터 구조를 응답자 판정 함수로 변환"]
+ ROOTS["StatisticsService.loadResponses()
storageRoots() / toStorageRoot()
모든 요청의 index·banner 루트 합집합 생성"]
+ RAW[("선택한 설문 DB
DATA.DATJSON: 원래 응답
DERIVED_DATA.DATJSON: 저장된 파생 응답")]
+ PROFILE[("KIWI_SURVEY.dbo.V_PROFILE
P_DATJSON: 프로필 응답")]
+ QUERY["StatisticsRepository.data()
StatisticsMapper.data()
완료·조사 유형·날짜 조건으로 조회하고 JSON 결합"]
+ DAT["StatisticsDataDto.dat
집계용: 선택한 루트가 들어 있는 저장 그룹"]
+ FDAT["StatisticsDataDto.filterDat
필터용: 전체 응답 그룹
필터가 없으면 null"]
+ NORMAL["StatisticsDataService.normalize() → flatten()
JSON 키를 대문자로 통일하고 Map으로 변환
SurveyResponseDto 생성"]
+ APPLY["StatisticsService.loadResponses()의 stream().filter(filter)
판정 함수는 response.filterValues() 사용
조건을 통과한 응답만 남김"]
+ BATCH["StatisticsBatchDto 생성
project / requests / questions / responses"]
+ AUDIT["StatisticsService.prepare() → LogService.writeSiteLog()
Get Report Data를 배치당 한 번 기록 시도
그 후 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["공통 준비 결과
StatisticsBatchDto"]
+ LOOP["StatisticsService.stream()
이번 위치의 요청 선택 → calculate()"]
+ PICK["StatisticsService.withinStorageRoots()
이번 index·banner의 루트에 해당하는 키가
하나라도 있는 응답자만 선택"]
+ DIM["StatisticsDimensionService.resolve()
문항 ID → 기본 키·보기·속성·순위 범위
숫자 문항 보기는 실제 응답에서 구성"]
+ TYPE{"StatisticsService.isOpenText()
text 문항이며 #A가 아닌가?"}
+ TEXT["2-3의 텍스트 분석으로 이동
StatisticsService.textAnalysis()"]
+ AGG["StatisticsAggregationService.aggregate()
columns()로 열별 응답 목록 생성"]
+ TOTAL["StatisticsSelectionService.total() / cases()
전체 응답 목록과 보기별 응답 목록"]
+ BANNER["StatisticsAggregationService.addBanner()
StatisticsSelectionService.bannerTotal() / bannerCases()
배너 값별로 목록 분리, 중첩 배너는 재귀 처리"]
+ MODE{"집계 모드"}
+ NORMAL["StatisticsAggregationService
totalRow() / addChoiceRows()
countCell() / percentBase()
N=목록 크기, %=N÷분모×100"]
+ SUMMARY["StatisticsAggregationService.addSummaryRows()
숫자: 평균·중앙값·표준편차 등
척도: Top/Mid/Bottom·NPS 또는 평균
요청한 사용자 값 그룹 추가"]
+ CROSS["StatisticsAggregationService.bannerCrossTable()
crossCount() / overlapCount(): 배너 간 겹침
crossBase() / groupBase(): 분모 결정"]
+ TABLE["StatisticsTableService.table()
headers(): 머리글과 병합 정보 생성
필요하면 transpose(): 행·열 교환
StatisticsResponseDto, type=TABLE"]
+ EVENT["StatisticsService.resultEvent() / errorEvent()
문항 계산 오류는 해당 위치의 error로 변환"]
+ SEND["StatisticsStreamService.send()
JSON 한 줄 + 줄바꿈 전송"]
+ DONE["StatisticsService.completeEvent()
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()
StatisticsTextService.analyze()"]
+ TEXT["StatisticsTextService.answerTexts()
해당 QID와 QID_ 하위 키의 문자열 수집
HTML 문자 복원"]
+ DICT[("Report DB
REPORT_NLP_WORD
REPORT_NLP_TAG")]
+ REPO["NlpRepository.words() / tags()
NlpMapper.words() / tags()
kartSqlSessionTemplate 사용"]
+ MODEL[("로컬 Kiwi 모델 파일
kri.kart.nlp.model-directory")]
+ TOKEN["KiwiNlpService.tokenize()
응답 문자열 + 사용자 사전 → 형태소 목록"]
+ FILTER["StatisticsTextService.isCounted()
선택 품사 중 명사 또는 2글자 이상
SL은 선택 품사·길이와 관계없이 포함"]
+ COUNT["StatisticsTextService.analyze()
단어+품사별 빈도 합산
빈도 내림차순, 동률은 첫 등장 순서
상위 100개 선택"]
+ OUT["StatisticsResponseDto, type=TEXT_ANALYSIS
words: 단어·품사·빈도
문항별 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 메서드 호출을 의미하지는 않는다.