diff --git a/book/300_architecture/311_FastAPI_구조_원칙.md b/book/300_architecture/311_FastAPI_구조_원칙.md index 763e5cc..e9f90ea 100644 --- a/book/300_architecture/311_FastAPI_구조_원칙.md +++ b/book/300_architecture/311_FastAPI_구조_원칙.md @@ -279,7 +279,47 @@ utils - 프로덕션 환경에서 표준적인 배포 방식 - 백엔드와 웹서버의 명확한 역할 분리 -## 16. 모범 사례 참고 +## 16. Slack API 호출 원칙 + +### 필수 원칙 +- **skill-slack API 사용**: rb8001에서 Slack API 호출 시 반드시 skill-slack HTTP API 사용 +- **WebClient 직접 호출 금지**: `slack_sdk.WebClient`를 rb8001 코드에서 직접 사용하지 않음 +- **아키텍처 준수**: rb8001(brain) → skill-slack(hand) 위임 구조 유지 + +### thread_ts 처리 규칙 +- **조건부 포함**: `thread_ts`는 유효한 값(truthy)일 때만 payload에 포함 +- **None/빈 문자열 제외**: `None`, `""` 등 falsy 값일 때는 payload에 포함하지 않음 (invalid_thread_ts 에러 방지) +- **올바른 예시**: + ```python + payload = {"channel": channel, "text": text} + if message_ts: # None이나 빈 문자열이면 포함 안 함 + payload["thread_ts"] = message_ts + ``` +- **잘못된 예시**: + ```python + payload = {"channel": channel, "text": text, "thread_ts": message_ts} # message_ts가 None이면 에러 + ``` + +### Slack 메시지 업데이트 vs 새 메시지 +- **원본 메시지 업데이트**: 인터랙티브 버튼 응답 등 기존 메시지를 수정해야 할 때는 `/api/v1/update` 사용 +- **새 메시지**: 별도의 새 메시지를 보낼 때는 `/api/v1/send` 사용 +- **예시**: "예/아니오" 버튼에 대한 응답은 원본 메시지를 업데이트하여 버튼을 제거하고 결과 표시 + +## 17. 테스트 원칙 + +### 실제 테스트 필수 +- **코드 수정 후 실제 테스트**: 코드만 수정하고 실제 테스트를 수행하지 않으면 안 됨 +- **추측 금지**: "아마 작동할 것이다" 같은 추측 대신 실제 실행으로 검증 +- **테스트 방법**: + - API: `curl`로 직접 호출하여 응답 확인 + - Slack 기능: 실제 Slack에서 버튼 클릭, 메시지 전송 등 직접 테스트 + - DB 저장: API 응답뿐만 아니라 DB 직접 조회로 최종 확인 + +### Git 작업 규칙 +- **각 폴더별 확인**: Git 커밋 히스토리는 각 프로젝트 폴더에서 개별적으로 확인 +- **루트에서 확인 금지**: 루트 디렉토리에서 git log를 확인하려고 하지 않음 (각 폴더는 별도 리포지토리) + +## 18. 모범 사례 참고 본 문서는 FastAPI 커뮤니티의 다음 모범 사례를 반영하였습니다: