diff --git a/book/300_architecture/311_백엔드_구조_원칙.md b/book/300_architecture/311_백엔드_구조_원칙.md index 23b0242..9ad7811 100644 --- a/book/300_architecture/311_백엔드_구조_원칙.md +++ b/book/300_architecture/311_백엔드_구조_원칙.md @@ -130,6 +130,10 @@ utils - **services**: 비즈니스 로직 구현, state를 통한 DB 접근 - **state**: DB CRUD만, 비즈니스 로직 금지 +### 예외 처리/웹훅 원칙 +- **HTTPException 재포장 금지**: `except Exception`에서 `HTTPException`까지 500으로 감싸지 않는다. `except HTTPException: raise`를 기본 패턴으로 둔다. +- **Slack 서명 검증 경로 원문 보존**: 프록시 경유 웹훅은 원문 body를 유지해야 하며, 서명 검증 경로에서 body 재직렬화를 금지한다. + ## 6. DB 접근 규칙 ### 환경변수 사용 @@ -226,6 +230,8 @@ utils - [ ] 애매한 케이스는 LLM 우선 접근 원칙 적용 확인 - [ ] 복잡한 워크플로우는 LangGraph 활용 검토 - [ ] 원칙 문서 확인 완료 (`311_FastAPI_구조_원칙.md`, `312_문서_작성_원칙.md`) +- [ ] 웹훅 프록시 경로에서 원문 body 전달(`content=raw_body`) 여부 확인 +- [ ] 인증 실패 상태코드(403/401)가 500으로 재매핑되지 않는지 확인 배포 전/후 확인: - [ ] 코드 변경 후 `git status`로 커밋되지 않은 변경사항 확인 diff --git a/book/300_architecture/gateway_proxy_patterns.md b/book/300_architecture/gateway_proxy_patterns.md index 7a43262..72e4896 100644 --- a/book/300_architecture/gateway_proxy_patterns.md +++ b/book/300_architecture/gateway_proxy_patterns.md @@ -20,6 +20,13 @@ robeing-gateway (포트 8100)의 프록시 패턴 및 JWT 인증 처리 아키 - **헤더 주입**: X-User-Id, X-Username 헤더 추가 - **보안 게이트웨이**: 인증되지 않은 요청 차단 +### 2.3 Slack 웹훅 프록시 필수 규칙 +- **원문 바디 보존**: Slack Events/Interactive 프록시는 `request.body()` 원문 바이트를 그대로 전달한다. +- **재직렬화 금지**: Slack 서명 검증 경로에서 `json=` 기반 재직렬화 전달을 금지한다. +- **권장 포워딩**: `client.post(..., content=raw_body, headers=...)` 패턴을 기본으로 사용한다. +- **헤더 전달**: `X-Slack-Signature`, `X-Slack-Request-Timestamp`, `Content-Type`를 함께 전달한다. +- **운영 검증**: 배포 후 `/gateway/slack/events`의 200/403/500 분포와 `upstream_status`를 같은 시각 기준으로 확인한다. + ### 2.2 서비스 위치 - **서버**: 51123 - **포트**: 8100 @@ -486,4 +493,4 @@ class TestGateway: --- -**문서 끝** \ No newline at end of file +**문서 끝**