From 05128e2d493f295dc1cbb98270d78cb02bff8657 Mon Sep 17 00:00:00 2001 From: happybell80 Date: Mon, 15 Sep 2025 14:55:24 +0900 Subject: [PATCH] =?UTF-8?q?Add=20Slack=20=EB=A9=94=EC=8B=9C=EC=A7=95=20?= =?UTF-8?q?=EC=9A=B4=EC=98=81=20=EB=9F=B0=EB=B6=81=20=EB=AC=B8=EC=84=9C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 전체 Slack 메시징 아키텍처 정리 - 서비스별 역할과 토큰 전략 문서화 - 메시지 전송 경로와 플로우 정리 - 채널/스레드/DM 처리 규칙 명시 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- ...ppybell80_Slack_메시징_운영_런북.md | 73 +++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 troubleshooting/250915_happybell80_Slack_메시징_운영_런북.md diff --git a/troubleshooting/250915_happybell80_Slack_메시징_운영_런북.md b/troubleshooting/250915_happybell80_Slack_메시징_운영_런북.md new file mode 100644 index 0000000..292c3b1 --- /dev/null +++ b/troubleshooting/250915_happybell80_Slack_메시징_운영_런북.md @@ -0,0 +1,73 @@ +# Slack 메시징 운영 런북 + +## 작성일: 2025-09-15 +## 작성자: happybell80 +## 환경: rb8001, robeing-gateway, skill-slack + +--- + +## 구성요소 + +- **rb8001**: Slack 이벤트/인터랙티브 처리(app/router/slack_handler.py), DM 전송(app/skills/dm_skill.py), 뉴스 채널 게시(app/skills/news_posting_skill.py), 간단 뉴스 전송(app/skills/startup_news_skill.py). +- **robeing-gateway**: Slack Events/Interactive 프록시(POST /slack/events, POST /slack/interactive), 팀별 봇 토큰과 사용자 UUID 주입. +- **skill-slack**: 메시지 전송/수정 API 제공(POST /api/v1/messages/send, POST /api/v1/messages/update). +- **기타 서비스(skill-email, skill-news, robeing-monitor, rb10508_micro)**: Slack 메시지 전송 로직 없음. + +## 토큰/식별자 + +- **게이트웨이**: Slack 요청에서 팀 ID를 추출해 slack_workspace.bot_token 조회 후 rb8001 호출 시 헤더 X-Slack-Bot-Token로 전달. Slack 사용자 ID→내부 UUID는 user.oauth_provider='slack' AND oauth_id=slack_user_id 매핑으로 조회해 X-User-Id로 전달. +- **rb8001**: Slack 이벤트 응답 시 게이트웨이가 전달한 X-Slack-Bot-Token으로 WebClient 생성. DM 전송은 ROBEING_SLACK_BOT_TOKEN 또는 SLACK_BOT_TOKEN 사용. Company-X 뉴스 전송은 COMPANYX_SLACK_BOT_TOKEN 사용. +- **skill-slack**: 자체 SLACK_BOT_TOKEN으로 WebClient 사용. + +## 엔드포인트(I/O) + +### 게이트웨이 +- `POST /slack/events`: 요청 본문을 rb8001 `POST /api/slack/events`로 전달, 헤더 `X-Slack-Bot-Token`, `X-User-Id` 추가. +- `POST /slack/interactive`: 요청 본문을 rb8001 `POST /api/slack/interactive`로 전달, 헤더 `X-Slack-*` 및 `X-User-Id` 전달. + +### rb8001 +- `POST /api/slack/events`: Slack 이벤트 처리 후 `chat_postMessage`로 채널/스레드/DM에 응답. +- `POST /api/slack/interactive`: Slack 인터랙티브 처리, 후속 안내는 `response_url`로 전송. +- `POST /api/dm/send`: 모든 사용자 대상 DM 전송 트리거(dmskill). +- `POST /api/dm/send-to-user`: 특정 Slack 사용자 ID로 DM 전송(dmskill). + +### skill-slack +- `POST /api/v1/messages/send`: `chat_postMessage(channel, text, blocks?)` 실행. +- `POST /api/v1/messages/update`: `chat_update(channel, ts, text?, blocks?)` 실행. + +## 메시지 전송 경로(플로우) + +- **이벤트**: Slack → 게이트웨이(/slack/events) → rb8001(/api/slack/events) → rb8001이 Slack에 chat_postMessage 전송. +- **인터랙티브**: Slack → 게이트웨이(/slack/interactive) → rb8001(/api/slack/interactive) → 처리 후 response_url로 에페메럴 메시지 전송. +- **정기/수동 DM**: rb8001 스케줄러 또는 API → dm_skill → chat_postMessage(channel=슬랙 유저 ID). +- **뉴스 채널 게시**: rb8001 스케줄러 또는 명령 → news_posting_skill → chat_postMessage(channel=채널 ID, blocks). + +## 채널/스레드/DM 규칙 + +- **DM**: channel에 Slack 사용자 ID를 지정해 chat_postMessage 전송, thread_ts 미사용. +- **스레드**: event.thread_ts가 있으면 유지하여 스레드 응답. app_mention이 스레드가 아니면 원본 메시지 ts를 thread_ts로 사용해 스레드 시작. +- **채널**: 채널 ID로 전송하며, 뉴스 게시 시 Block Kit 블록 리스트를 사용. + +## 메시지 형식/옵션 + +- **텍스트**: chat_postMessage(channel, text, thread_ts?) 사용. +- **블록**: 뉴스 게시 시 Block Kit 블록 배열(blocks) 사용, 필요 시 여러 메시지로 분할. +- **링크 미리보기**: 일부 전송 경로에서 unfurl_links=False, unfurl_media=False 사용. +- **인터랙티브 업데이트**: response_url에 JSON POST로 에페메럴 메시지 전송(replace_original=False, delete_original=False). + +## 서명/검증 + +- rb8001 인터랙티브 처리 시 Slack 서명 검증(X-Slack-Request-Timestamp, X-Slack-Signature) 수행. +- 게이트웨이는 Slack 이벤트를 rb8001로 프록시하며 자체 Slack 메시지 전송 로직은 없음. + +## 관련 설정/데이터 + +- **rb8001 설정 키**: SLACK_BOT_TOKEN, ROBEING_SLACK_BOT_TOKEN, COMPANYX_SLACK_BOT_TOKEN, SLACK_SIGNING_SECRET. +- **게이트웨이 DB 테이블**: slack_workspace에서 팀별 bot_token 조회, user의 oauth_id(provider='slack')로 UUID 매핑. +- **skill-slack 설정 키**: SLACK_BOT_TOKEN. + +## 로깅 포인트 + +- **rb8001 slack_handler**: 토큰 유효성(auth_test), 채널/스레드/이벤트 타임스탬프, 전송 성공 여부를 로그로 남김. +- **rb8001 dm_skill/news_posting_skill**: 사용자별 전송 결과, Slack API 에러를 로그로 남김. +- **게이트웨이**: Slack 팀/사용자 추출, 토큰/UUID 조회 결과, 프록시 응답 코드를 로그로 남김. \ No newline at end of file