# Task 270.1 완료 보고서
## group_chat.py — 세션 중 자연어 인원/설정 제어 기능 추가

**팀**: dev1-team (헤르메스)
**작업일**: 2026-03-06
**레벨**: Lv.2

---

## 작업 내용

group_chat.py에 세션 중 자연어로 인원/설정을 제어하는 기능을 추가했습니다.

### 추가된 기능
1. **detect_intent() 확장**: "control" 의도 감지 (6가지 제어 타입)
   - limit_personas: "10명만 얘기해", "5명까지만"
   - remove_persona: "로키 빠져", "아테나 나가"
   - add_persona: "비너스 불러", "로키 합류시켜"
   - filter_by_role: "백엔드만 남아", "팀장들만"
   - filter_by_team: "1팀만", "개발2팀만 남아"
   - set_auto_turns: "3턴까지만 자동으로", "계속 얘기해"

2. **handle_control()**: 제어 명령 처리 메서드 (GroupChatSession)
   - 인원 제한/퇴장/합류/역할필터/팀필터/자동발화수 변경
   - 최소 1명 유지 보장, speak_counts 동기화

3. **send_system_message()**: ⚙️ 아이콘 시스템 메시지 전송

4. **시작 시 자연어 인원 지정**: "전원 집합", "백엔드만 모여", "1팀 모여", "5명만 모여" 등

5. **모듈 레벨 상수 추가**: CONTROL_TYPES, ROLE_FILTERS, TEAM_FILTERS, _PERSONA_NAMES

6. **run_one_turn() 수정**: max_auto_turns 인스턴스 변수 지원 (getattr 폴백)

7. **main() 루프 확장**: control 의도 처리 분기 추가

---

## 생성/수정 파일 목록

| 파일 | 변경 유형 | 설명 |
|------|-----------|------|
| `/home/jay/workspace/group_chat.py` | 수정 | 제어 기능 추가 (상수, detect_intent, handle_control, send_system_message 등) |
| `/home/jay/workspace/tests/test_group_chat.py` | 수정 | 신규 테스트 29개 추가 (4개 클래스) |

---

## 테스트 결과

- **전체 테스트**: 156개 PASS (기존 127 + 신규 29)
- **전체 프로젝트 테스트**: 599개 PASS

### 신규 테스트 클래스
- TestDetectIntentControl (12개): 제어 명령 감지 테스트
- TestDetectIntentStartPersonas (6개): 시작 시 자연어 인원 지정 테스트
- TestHandleControl (10개): 제어 명령 처리 테스트
- TestSendSystemMessage (1개): 시스템 메시지 전송 테스트

### 검증 항목 커버리지
1. "10명만 얘기해" → 10명 축소 ✅
2. "로키 빠져" → 퇴장 메시지 + 참여자 제거 ✅
3. "비너스 불러" → 합류 메시지 + 참여자 추가 ✅
4. "백엔드만 남아" → 백엔드 3명만 ✅
5. "1팀만" → 개발1팀 5명만 ✅
6. "3턴까지만 자동으로" → max_auto_turns 변경 ✅
7. "백엔드만 모여" → 시작 시 백엔드만 소집 ✅
8. "전원 집합" → 19명 소집 ✅
9. 기존 기능 유지 (입장/퇴장, 타임아웃, user_input) ✅
10. 전체 테스트 PASS ✅

---

## 셀프 QC

### 1-A 기본 체크리스트
- [x] 1. 영향 파일: group_chat.py, test_group_chat.py. 다른 파일에 영향 없음
- [x] 2. 엣지 케이스: 0명 제한 무시, 1명 남은 상태 제거 무시, 중복 추가 무시, 키워드 우선순위(END→control→user_input)
- [x] 3. 작업 지시와 정확히 일치
- [x] 4. 에러 처리: handle_control 각 분기에서 유효성 검증, 최소 1명 보장
- [x] 5. 테스트: 29개 신규 테스트가 10개 검증 항목 전체 커버

### 1-B 데이터 계약 체크리스트
- 해당 없음 (workers/, src/types/, shared/schemas/ 변경 없음)

---

## 자동 검증 (qc_verify.py)

```json
{
  "task_id": "task-270.1",
  "verified_at": "2026-03-06T00:18:22",
  "overall": "PASS",
  "checks": {
    "api_health": {"status": "SKIP", "details": ["서버 작업 아님"]},
    "file_check": {"status": "PASS", "details": ["group_chat.py (47320 bytes)", "test_group_chat.py (97295 bytes)"]},
    "data_integrity": {"status": "PASS"},
    "test_runner": {"status": "PASS", "details": ["599 passed in 5.07s"]},
    "schema_contract": {"status": "SKIP", "details": ["workers 변경 없음"]}
  }
}
```

---

## 버그 유무
- 발견된 버그 없음

## 비고
- 제어 명령은 Claude 호출 없이 키워드 매칭만으로 즉시 반응 (지연 없음)
- 기존 기능 127개 테스트 모두 유지 (하위 호환성 보장)
- max_auto_turns는 getattr 폴백으로 기존 세션 복구 호환성 유지