---
task_id: task-1932
type: context
scope: task
created: 2026-04-17
updated: 2026-04-17
status: in-progress
---

# 맥락 노트: task-1932

**task**: task-1932

---

## 결정 근거

### 1. 좀비 감지 시 "failed" vs "cancelled"
- 현재: 프로세스가 죽으면 "cancelled"로 전환 → 사용자 의도 취소와 구분 불가
- 변경: "failed"로 전환 + "프로세스 비정상 종료" 메시지 → 명확한 상태 구분
- 기각 대안: 새 status 값 "crashed" 도입 → 프론트엔드 모든 곳에 새 상태 분기 필요, 과도함

### 2. kill vs cancel 엔드포인트 분리
- `/api/wiki/refine/cancel`: 기존. 메타데이터 보존 + 이어서 작업 가능
- `/api/wiki/refine/kill`: 신규. lock PID만 kill 가능 (보안), running 상태만 허용
- 기각 대안: cancel에 force 파라미터 추가 → API 의미 혼란

### 3. 폴링 주기 2초 → 3초
- 태스크 지시에 명시된 요구사항
- 현재 2초도 잘 동작하나, 서버 부하 감소 + 정제가 수분~수십분 소요 → 1초 차이 체감 없음

## 3 Step Why 자문

1st Why: "왜 이 설계가 필요한가?"
→ A: 프로세스 좀비 상태를 정확히 감지하고, 사용자가 서버 터미널 없이 직접 프로세스를 제어해야 한다.

2nd Why: "왜 A가 최선의 접근인가?"
→ B: PID 기반 실시간 생존 확인 + 전용 kill 엔드포인트는 기존 코드에 최소 변경으로 구현 가능하며, lock 파일 PID 제한으로 보안 위험도 차단된다.

3rd Why: "왜 B가 다른 대안보다 나은가?"
→ C: 대안1(WebSocket 실시간 통신)은 서버 아키텍처 변경 필요, 대안2(systemd 서비스 관리)는 인프라 의존성 증가. 현재 HTTP 폴링 + PID 제어는 기존 패턴과 일관되고 구현/유지보수 비용 최소.

→ A-B-C 논리적 일관성: PASS (최소 변경 + 보안 + 기존 패턴 활용)

## 참조 자료

- 기존 코드: `/home/jay/workspace/dashboard/routes_get.py:1871-1958` (status 핸들러)
- 기존 코드: `/home/jay/workspace/dashboard/routes_post.py:934-973` (cancel 핸들러)
- 테스트: `/home/jay/workspace/dashboard/tests/test_refine_status_pid.py`

## 주의사항

- kill 엔드포인트에서 임의 PID kill 방지 (lock 파일 PID만 허용)
- running 상태가 아니면 kill 거부 (400)
- 좀비 감지 시 lock 파일 정리 필요