# task-2058: 카카오톡 정제 프로세스 실시간 모니터링 개선

## S — Situation
카카오톡 정제 대시보드에서 프로세스 세부 상태(현재 스레드, LLM 호출 횟수, CPU/메모리)를 확인할 수 없어 모니터링이 불충분했다.

## C — Complication
- 현재 처리 중인 스레드 번호/이름이 구조화되지 않아 정확한 진행 파악 불가
- LLM API 호출 횟수와 마지막 성공 시각 미표시로 stuck 여부 판단 어려움
- 프로세스 CPU/메모리 사용량 미표시로 alive/dead만 확인 가능

## Q — Question
progress 데이터와 API 응답을 확장하여 세부 모니터링 정보를 대시보드에 표시할 수 있는가?

## A — Answer

### 백엔드 변경 (knowledge_extractor_v2.py + models_v2.py)

| 파일 | 변경 내용 | grep 검증 | 상태 |
|------|-----------|-----------|------|
| `/home/jay/projects/insuwiki/.worktrees/task-2058-dev5/scripts/kakao_knowledge/models_v2.py:105` | BatchProgress에 `llm_call_count` 필드 추가 | grep "llm_call_count" OK | verified |
| `/home/jay/projects/insuwiki/.worktrees/task-2058-dev5/scripts/kakao_knowledge/knowledge_extractor_v2.py:33-34` | 모듈 레벨 `_llm_call_count`, `_last_success_at` 변수 추가 | grep "_llm_call_count" OK | verified |
| `/home/jay/projects/insuwiki/.worktrees/task-2058-dev5/scripts/kakao_knowledge/knowledge_extractor_v2.py:225-227` | `_call_claude`에서 LLM 호출 카운터 증가 + 성공 시각 기록 | grep "global _llm_call_count" OK | verified |
| `/home/jay/projects/insuwiki/.worktrees/task-2058-dev5/scripts/kakao_knowledge/knowledge_extractor_v2.py:1026-1027` | `_write_progress`에 `llmCallCount`, `lastSuccessAt` 필드 추가 | grep "llmCallCount" OK | verified |
| `/home/jay/projects/insuwiki/.worktrees/task-2058-dev5/scripts/kakao_knowledge/knowledge_extractor_v2.py:1070-1072` | `extract_knowledge_v2` 시작 시 카운터 초기화 | grep "global _llm_call_count" OK (2건) | verified |
| `/home/jay/projects/insuwiki/.worktrees/task-2058-dev5/scripts/kakao_knowledge/knowledge_extractor_v2.py:1220` | 배치 시작 시 `_cur_thread_name` 캐시 | grep "_cur_thread_name" OK | verified |
| `/home/jay/projects/insuwiki/.worktrees/task-2058-dev5/scripts/kakao_knowledge/knowledge_extractor_v2.py:1256,1357` | `currentThreadName` 필드를 `_cur_thread_name`으로 참조 | grep "currentThreadName" OK (2건) | verified |

### API 확장 (routes_get.py)

| 파일 | 변경 내용 | grep 검증 | 상태 |
|------|-----------|-----------|------|
| `/home/jay/workspace/dashboard/routes_get.py:113-116` | psutil try/except import + `_HAS_PSUTIL` 플래그 | grep "_HAS_PSUTIL" OK | verified |
| `/home/jay/workspace/dashboard/routes_get.py:1967-1975` | running+pidAlive 시 `cpuPercent`, `memoryMB`, `processStatus` 추가 | grep "cpuPercent" OK | verified |

### 프론트엔드 (InsuWikiView.js)

| 파일 | 변경 내용 | grep 검증 | 상태 |
|------|-----------|-----------|------|
| `/home/jay/workspace/dashboard/components/InsuWikiView.js:1348-1359` | PID 영역에 CPU%, MEM MB, processStatus 표시 | grep "cpuPercent" OK | verified |
| `/home/jay/workspace/dashboard/components/InsuWikiView.js:1339` | LLM 호출 횟수 표시 (`· LLM N회`) | grep "llmCallCount" OK | verified |
| `/home/jay/workspace/dashboard/components/InsuWikiView.js:1378-1382` | 마지막 LLM 성공 시각 표시 | grep "lastSuccessAt" OK | verified |
| `/home/jay/workspace/dashboard/components/InsuWikiView.js:1383-1387` | 현재 스레드 이름 표시 (`▶ 현재: ...`) | grep "currentThreadName" OK | verified |

## 발견 이슈 및 해결

### 이슈 1: batch_threads unbound 버그 (해결됨)
- **원인**: `del batch_threads` (라인 1305) 이후에 `_write_progress`에서 `batch_threads[0]`를 참조하여 pyright reportUnboundVariable 에러
- **해결**: 배치 시작 시 `_cur_thread_name`에 미리 캐시하고 이후 참조에서 이 변수를 사용
- **커밋**: `8975dd6` (마르둑)

### 이슈 2: InsuWiki 탭 React error #130 (기존 이슈)
- **현상**: InsuWiki 탭 클릭 시 "Element type is undefined" React 에러로 빈 화면
- **원인 분석**: 변경 전 버전에서도 동일 에러 발생 → 본 작업 범위 외 기존 이슈
- **조치**: 보고서에 기록, 코드 회귀 없음 확인 완료

### 이슈 3: 폴링 간격 이미 적절 (설계 변경)
- **태스크 설명**: "갱신 간격이 너무 김 (30~60초)" → 실제 코드: running 시 3초, idle 시 10초
- **결론**: 폴링 간격 변경 불필요. 대신 데이터 풍부화에 집중

## L1 스모크테스트 결과
- 서버 재시작: 성공 (port 8000)
- API 응답 확인: `curl http://localhost:8000/api/wiki/refine/status` → 200 OK, 기존 필드 정상
  - 새 필드(`cpuPercent`, `memoryMB`, `processStatus`)는 running+alive 시에만 추가됨 — 현재 failed 상태이므로 미포함 정상
  - `llmCallCount`, `lastSuccessAt`, `currentThreadName`은 다음 정제 실행 시 progress 파일에 기록됨
- 스크린샷: InsuWiki 탭 자체가 기존 이슈로 빈 화면 (React error #130, 본 작업 범위 외)
- psutil 테스트: `python3 -c "import psutil; ..."` → cpuPercent/memoryMB/processStatus 정상 동작

## 모델 사용 기록
- 엔키(백엔드): sonnet — progress 데이터 확장 + API psutil 추가
- 이쉬타르(프론트엔드): sonnet — UI 표시 확장
- 마르둑(팀장): opus — 설계/검토/버그 수정/통합

## 머지 판단
- **머지 필요**: Yes
- **브랜치**: task/task-2058-dev5 (insuwiki worktree)
- **워크트리 경로**: /home/jay/projects/insuwiki/.worktrees/task-2058-dev5
- **dashboard 변경**: main에 직접 커밋됨 (routes_get.py, InsuWikiView.js)
- **머지 의견**: 코드 변경 범위 최소, API 정상 동작, 기존 기능 회귀 없음 확인. InsuWiki 탭 빈 화면은 기존 이슈.

## 커밋 이력
1. `c59709d` - [task-2058] 엔키: progress 데이터 확장 (worktree)
2. `101ec3a5` - [task-2058] 엔키: API에 psutil CPU/메모리 정보 추가 (dashboard)
3. `95bbbcc3` - [task-2058] 이쉬타르: 프론트엔드 모니터링 UI 확장 (dashboard)
4. `8975dd6` - [task-2058] 마르둑: batch_threads unbound 버그 수정 (worktree)

## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회