Fix 312 principles & move completed plan to troubleshooting

- Move: plans/251204_emotion_based_addressing_system.md → troubleshooting/
- Update: 312 원칙 명확화 (plans vs troubleshooting 구분)
- Add: 시나리오/테스트 별도 파일 금지 명시
- Follow: 구현 완료 시 troubleshooting 이동 규칙 준수

book/300_architecture/312_문서_작성_원칙.md

@@ -41,10 +41,19 @@
 
 ### 계획 문서
 
-**경로**: `DOCS/plans/`
+**경로**: `DOCS/journey/plans/`
+**파일명**: `yymmdd_주제.md`
+**용도**: 미래 계획, 아이디어만 (아직 구현 안 됨)
+
 **규칙**:
-- 미래 계획, 아이디어
-- 구현 완료 시 troubleshooting으로 이동
+- **구현 완료 시 `journey/troubleshooting/`으로 이동** (필수)
+- **시나리오/테스트/리포트 별도 파일 금지** - 하나의 파일에 통합
+- 계획 → 구현 → 테스트 → 교훈 순서로 작성
+- 100줄 이하 유지
+
+**구분**:
+- `plans/`: 미구현 (will do)
+- `troubleshooting/`: 구현 완료 + 문제 해결 (did + learned)
 
 ---
 

journey/troubleshooting/251204_emotion_based_addressing_system.md

@@ -3,7 +3,7 @@
 **작성일**: 2025-12-04  
 **수정일**: 2025-12-04 (v2 구현 완료)  
 **작성자**: happybell80  
-**상태**: v2 구현 완료 (75% 정확도)
+**관련 파일**: `services/addressing_service.py`, `state/database.py`, `router/router.py`
 
 ---
 
@@ -72,26 +72,14 @@ state/database.py (DB CRUD만)
 - 없으면 추가: `get_recent_emotions(user_id, minutes=10)` - 감정 평균
 - DB CRUD만, 비즈니스 로직 금지
 
-### 3. router.py:264-283
-**수정**: 감정 분석 후 addressing_service 호출
-```python
-from app.services.addressing_service import get_preferred_name
-preferred_name = await get_preferred_name(user_id, user_emotion)
-context['preferred_name'] = preferred_name
-```
+### 3. router.py:282-286
+**수정**: addressing_service 호출, 현재 감정 결과 전달
 
-### 4. llm_service.py:131-132
-**수정**: system_instruction에 호칭 지시
-```python
-preferred_name = enhanced_context.get('preferred_name', '사용자')
-system_instruction += f"사용자를 '{preferred_name}'으로 호칭하세요. "
-```
+### 4. llm_service.py:134-135
+**수정**: system_instruction에 호칭 지시, 호칭 남발 방지 (첫 문장 1회만)
 
-### 5. tables.md
-**추가**: user.metadata 컬럼 문서화
-```
-| metadata | JSONB | YES | nickname, position, short_name, preferences |
-```
+### 5. tables.md:44
+**추가**: user.metadata 컬럼 (nickname, position, short_name)
 
 ## 테스트 시나리오
 
@@ -102,23 +90,9 @@ system_instruction += f"사용자를 '{preferred_name}'으로 호칭하세요. "
 
 ## 검증
 
-**로그**:
-```bash
-docker logs rb8001 --tail 100 | grep "Preferred name"
-```
-
-**DB**:
-```sql
--- 최근 10분 감정 평균
-SELECT user_id, AVG((probs->>'happiness')::float) FROM emotion_readings
-WHERE created_at > NOW() - INTERVAL '10 minutes' GROUP BY user_id;
-```
-
-**API**:
-```bash
-curl -X POST http://192.168.219.52:8001/api/message \
-  -H "Authorization: Bearer $JWT" -d '{"text": "고마워요!"}'
-```
+- 로그: `docker logs rb8001 | grep "Preferred name"`
+- DB: emotion_readings 최근 10분 평균 확률 조회
+- API: /api/message 엔드포인트로 JWT 인증 테스트
 
 ## v2 구현 완료 (복합 감정 기반)
 
@@ -149,10 +123,18 @@ v2: `84b26b6`, `52d906b`, `71806b0`, `41dcc0a`
 
 ## 교훈
 
-1. **감정 분석 정확도가 호칭 품질 결정**: 임계값 튜닝 한계, 모델 개선 필요
-2. **TDD 효과**: 10개 시나리오로 한계 조기 발견
-3. **실용적 타협**: 75% 정확도로 3단계 호칭 실사용 가능
-4. **계층 분리 원칙**: router → services → state 흐름 준수
+### 원인
+v1에서 직책 있으면 감정 무관 호칭 → UX 피드백으로 감정별 차별화 필요 발견
+
+### 교훈
+1. **모델 검증 우선**: 임계값 튜닝 전 감정 분석기 정확도 확인 필수 (증상 치료 vs 본질 해결)
+2. **TDD 효과**: 10개 시나리오로 한계 조기 발견, 75% 정확도 수용 판단
+3. **실용적 타협**: 완벽 추구보다 3단계 호칭 실사용 선택
+
+### 원칙 준수
+- ✅ 311: 계층 분리 (router → services → state)
+- ✅ 312: 문서 통합 (plans → troubleshooting 이동, 중복 문서 3개 삭제)
+- ⚠️ 311: database.py 650줄 초과 → emotion_repository.py 분리 예정
 
 ## 관련 문서