ivada-infra/DOCS
3
0
Fork 0
Code Issues 1 Pull Requests 5 Actions Packages Projects Releases Wiki Activity
DOCS/troubleshooting/250915_happybell80_Slack_메시징_운영_런북.md
happybell80 05128e2d49 Add Slack 메시징 운영 런북 문서 
- 전체 Slack 메시징 아키텍처 정리
- 서비스별 역할과 토큰 전략 문서화
- 메시지 전송 경로와 플로우 정리
- 채널/스레드/DM 처리 규칙 명시

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-09-15 14:55:24 +09:00

4.6 KiB
Raw Blame History

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 조회 결과, 프록시 응답 코드를 로그로 남김.