# task-927.1 완료 보고 메시지 포맷 개선 (코드화)

**담당**: 헤르메스 (dev1-team 팀장)

---

## SCQA

**S**: 팀장봇의 완료 알림 메시지(`format_notification_message()`)가 plain text + 이모지로 생성되어, 텔레그램에서 가독성이 떨어지고 핵심 정보(작업 제목, 이슈 해결 내역)가 누락되는 상태였다.

**C**: 제이회장님이 승인한 마크다운 포맷(볼드 헤더, 핵심 결과, 이슈 섹션)으로 출력되도록 코드 수정이 필요했으며, Telegram에서 마크다운 렌더링을 위해 `parse_mode` 설정과 파싱 에러 fallback이 추가되어야 했다.

**Q**: 기존 86개 테스트를 깨뜨리지 않으면서 새 마크다운 포맷을 적용하고 Telegram 호환성을 확보할 수 있는가?

**A**: `report_utils.py`에 3개 메타데이터 필드(title, issues_resolved, issues_unresolved) 추가 및 `format_notification_message()` 전면 교체, `notify-completion.py`에 `parse_mode: "Markdown"` + 400 fallback 로직 구현. pytest 102건 전건 통과(기존 86 + 신규 16), pyright 0 에러.

---

## 생성/수정 파일 목록

- `scripts/report_utils.py` — `extract_report_metadata()` 보강(title/issues_resolved/issues_unresolved 필드 추가), `format_notification_message()` 마크다운 포맷으로 전면 교체
- `scripts/notify-completion.py` — `send_telegram_notification()`에 `parse_mode: "Markdown"` 추가 + 400 에러 시 plain text fallback
- `scripts/tests/test_report_utils.py` — 신규 13개 테스트 추가 (metadata 5개 + format 8개)
- `scripts/tests/test_notify_completion.py` — 신규 3개 테스트 추가 (parse_mode/fallback)

---

## 변경 상세

### 1. `extract_report_metadata()` 보강

신규 필드 3개:
- `title`: 보고서 첫 `# ` 헤더에서 `task-XXX.X ` 제거 후 추출
- `issues_resolved`: `### 자체 해결` 섹션 파싱 → `[{"summary": str, "resolution": str}]`
- `issues_unresolved`: `### 범위 외 미해결` 섹션 파싱 → `[{"summary": str, "resolution": str}]`

기존 필드(test_summary, files_count, unresolved_count, unresolved_items, team_id, duration) 변경 없음.

### 2. `format_notification_message()` 전면 교체

이전 포맷:
```
✅ task-924.1 완료 (dev1-team, 6분 12초)
[요약] prioritize_results() 함수를...
📁 생성/수정: 4개 파일
🧪 테스트: pyright 0 errors
⚠️ 미해결: 2건 (...)
📄 상세: memory/reports/task-924.1.md
```

새 포맷:
```
**task-924.1 완료 보고** (dev1-team)
**InfoKeyword 키워드 우선순위 평가 기능 추가** (6분 12초)

**핵심 결과**
`prioritize_results()` 함수를 추가하여...
생성/수정: 4개 파일, 테스트: pytest 28건 통과, pyright 0 에러

**발견/해결 이슈 3건**
1. **black/isort 일부 불일치** — 재실행으로 해결
2. **total_blogs 미존재 가능성** — .get() 기본값 처리
3. **priority=0 falsy 문제** — 해당 없음 확인
```

핵심 변경점:
- 이모지(✅📁🧪⚠️📄) 완전 제거 → 볼드 마크다운으로 대체
- 작업 제목 + 소요시간 표시 추가
- "핵심 결과" 섹션으로 SCQA Answer 활용
- "발견/해결 이슈 N건" 번호 리스트
- chain 관련 replace 패턴도 새 포맷에 맞게 업데이트

### 3. `send_telegram_notification()` 수정

- payload에 `"parse_mode": "Markdown"` 추가
- 400 응답 시 `parse_mode` 없는 fallback payload로 재전송
- fallback 성공(200) → True 반환, 실패 → False 반환

---

## 테스트 결과 (정량적 증거)

**test_report_utils.py**: 66/66 passed (0.14s)
- 기존 53개 PASS + 신규 13개 PASS

**test_notify_completion.py**: 36/36 passed (0.16s)
- 기존 33개 PASS + 신규 3개 PASS

**pyright**: 0 errors, 0 warnings, 0 informations

**black/isort**: 포매팅 준수 확인

---

## 검증 기준 달성 여부

1. 출력 포맷이 목표 포맷과 일치 (볼드 헤더, 번호 리스트, 이슈 섹션) — 달성
2. Telegram `parse_mode: "Markdown"` 적용됨 — 달성
3. Markdown 파싱 에러 시 plain text fallback 동작 — 달성 (test_markdown_parse_error_fallback PASS)
4. 기존 테스트 전체 통과 + 신규 테스트 추가 — 달성 (86→102, 0 FAIL)
5. 4096자 제한 준수 유지 — 달성 (test_new_format_telegram_limit, test_long_report_message_within_telegram_limit PASS)
6. pyright/black/isort 통과 — 달성

---

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **chain replace 패턴 불일치** — `notify-completion.py` line 423의 `.replace()` 패턴이 이전 포맷(`✅ task-id 완료`)을 참조하고 있어 새 포맷(`**task-id 완료 보고**`)으로 업데이트
2. **기존 테스트 이모지 의존** — `test_files_count_marked_in_message`, `test_unresolved_issues_marked_in_message` 등이 이모지(`📁`, `⚠️`) OR 텍스트(`파일`, `미해결`) 형태로 검증하므로, 새 포맷에서 텍스트 대안을 반드시 포함하도록 구현
3. **issues_unresolved 키 네이밍** — task 지시서에는 `"reason"` 키로 명시되어 있었으나, 테스트 코드에서 `"resolution"` 키로 작성됨. 테스트 기준에 맞춰 `"resolution"` 키로 통일

### 범위 외 미해결 (0건)
없음