# task-1861_2.1+1 완료 보고서
> 팀: dev4-team | 팀장: 비슈누 | 일시: 2026-04-16

---

## SCQA

**S**: 인슈위키 카카오톡 정제 기능(knowledge_extractor_v2.py)에서 --month 파라미터를 통한 월별 필터링과 progress bar 표시가 구현되어 있다.

**C**: progress bar가 LLM 정제 단계(10~100%)에만 집중되어, 파일 읽기/파싱(0%)과 스레드 분리(0~10%) 단계가 사용자에게 제대로 표시되지 않는다. 전체 파이프라인 기준이 아닌 정제 단계만 반영하여 UX가 부정확하다.

**Q**: progress bar를 전체 파이프라인 기준(파일 읽기 → 파싱 → 스레드 분리 → 정제 → 저장)으로 재설계하여 사용자가 정확한 진행률을 볼 수 있는가?

**A**: progress 구간을 재설계하여 0~5% (파싱), 5~15% (스레드 분리), 15~95% (LLM 정제), 95~100% (저장)으로 변경 완료. 기존 47개 테스트 전체 통과 + 신규 5개 테스트 추가 (총 52/52 PASS). Gemini PR 리뷰 PASS (High 0건).

---

## 작업 내용

### 이슈 2: progress bar 기준 변경 (핵심 수정)
- `start_time` 변수를 함수 진입 직후로 이동 → LLM/비LLM 경로 모두 사용 가능
- 함수 진입 시 0% "파일 읽기 + 메시지 파싱 중" progress 기록 추가
- 월 필터링 직후 5% "메시지 파싱 완료" progress 기록 추가
- `_split_threads_v2()` 내부: 0~5% → 5~10% (메시지 처리), 5% → 10% (LLM 정밀분리), 10% → 15% (완료)
- LLM 배치 처리: 10+90% → 15+80% (min 95% 캡핑)
- 완료 직전 95% "결과 저장 중" 기록 추가
- 규칙 기반 경로에도 동일 패턴 적용

### 이슈 1: 월 필터링 검증
- 코드 분석 결과, `extract_knowledge_v2()` 시작에서 메시지 레벨 필터링이 정상 동작 확인
- H1(1~15일)/H2(16~31일) 필터링 로직 검증 완료
- 기존 테스트 7건(TestMonthFiltering) 모두 PASS
- 태스크 설명의 "2947개 전체 분리" 증상은 CLI 호출 시 --month 누락이 원인으로 추정

---

## 산출물 파일

- `/home/jay/projects/insuwiki/scripts/kakao_knowledge/knowledge_extractor_v2.py` — progress 구간 재설계 (81 insertions, 9 deletions)
- `/home/jay/projects/insuwiki/scripts/kakao_knowledge/tests/test_knowledge_extractor_v2.py` — progress 테스트 5건 추가 (66 insertions)

## 검증 결과

- **pytest**: 52/52 PASS (0.28초)
- **테스트 회귀**: 0건
- **Gemini PR 리뷰**: PASS (High 0건, Low 2건 — 95% intermediate progress가 redundant라는 지적은 UX 요구사항이므로 기각)

## 머지 판단
- **머지 필요**: Yes → **이미 머지 완료**
- **브랜치**: task/task-1861_2.1+1-dev4
- **PR**: https://github.com/JonghyukJeon/InsuWiki/pull/1
- **Gemini 리뷰**: PASS

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **start_time 변수 스코프 문제** — LLM 경로에서만 정의되어 비LLM 경로에서 progress 기록 시 NameError 가능 → 함수 진입 직후로 이동
2. **LLM 배치 progress 100% 초과 가능성** — 마지막 배치에서 15+80=95%를 초과할 수 있음 → `min(95, ...)` 캡핑 적용
3. **규칙 기반 경로 progress 단절** — 기존에는 100%만 기록하여 중간 단계 표시 없음 → 95% "결과 저장 중" 기록 추가

### 범위 외 미해결 (1건)
1. **"2947개 전체 분리" 재현 불가** — 코드 분석 상 월 필터링 로직은 정상. CLI 호출 시 --month 파라미터 누락이 원인으로 추정. 대시보드 프론트엔드에서 CLI 호출 코드가 프로젝트 내에 존재하지 않아 호출부 확인 불가. 범위 외 사유: 대시보드 서버 코드 미존재.

## 셀프 QC 체크리스트
- [x] 1. 영향 파일: knowledge_extractor_v2.py, test_knowledge_extractor_v2.py
- [x] 2. 엣지 케이스: 빈 메시지, 월 필터 매칭 없음, 스킵 스레드 — 모두 테스트 포함
- [x] 3. 작업 지시와 일치: progress 구간 0~5~15~95~100% 요구사항 반영 완료
- [x] 4. 에러 처리: cancelled 상태 체크, progress_file=None 방어 유지
- [x] 5. 테스트 커버리지: 52/52 전체 통과, 신규 5건 포함
- [x] 6. 발견 이슈 해결: 3건 자체 해결, 1건 범위 외
- [x] 7. 코드 아키텍처: SOLID 위반 없음
- [x] 8. 인터페이스 변경: 없음 (내부 로직만 변경)

## 모델 사용 기록
- 카르티케야(백엔드): Sonnet — progress 구간 변경 구현
- 하누만(테스터): Sonnet — progress 관련 테스트 5건 작성
- 비슈누(팀장): Opus — 코드 분석, 설계, 검증, 보고서