DOCS/journey/ideas/250916_슬랙_캔버스_API_활용_방안.md

로빙(RO-BEING)의 슬랙 캔버스(Canvas) 활용 방안

Slack API 문서를 기반으로, 로빙이 캔버스를 읽고 쓰기 위해 필요한 스코프, 구현 흐름, 제약 사항을 3가지 시나리오로 나누어 구체적으로 정리한 문서입니다.

---

공통 이해 요약

[현재 프로젝트 상태] 캔버스 API 미사용 (canvases.create/edit/sections.lookup 호출 없음). canvases:read/write 스코프 미설정. files.list?types=canvas 탐색 미구현. canvases.access.set/delete 권한 관리 없음.

• 캔버스 종류: 독립 문서(standalone) 또는 채널에 붙은 문서(channel canvas)로 존재합니다.
• 주요 API:
  • 생성: canvases.create
  • 수정: canvases.edit
  • 섹션 조회: canvases.sections.lookup
  • 접근 권한: canvases.access.set / delete
• 콘텐츠 포맷: document_content 객체에 type: "markdown"과 markdown 문자열만 지원합니다. Block Kit은 지원하지 않습니다.
• 탐색 및 읽기: files.list API에 types=canvas 파라미터를 주어 검색하고, 반환된 파일 객체의 url_private를 Authorization: Bearer <token> 헤더와 함께 호출하여 본문을 다운로드합니다.
• 필수 권한 (스코프):
  • canvases:write: 생성/편집/삭제/공유
  • canvases:read: 섹션 조회 등 읽기 작업
  • files:read: 파일/캔버스 목록 조회 및 다운로드
• 제약 사항:
  • 유료 플랜 전용: 캔버스 관련 API는 유료 플랜에서만 사용할 수 있습니다.
  • DM/다인 DM 공유: 채널 ID가 아닌 사용자 ID(user_ids) 기준으로만 공유 가능하며, 사전에 해당 사용자에게 캔버스 링크가 공유된 이력이 있어야 합니다.
  • 전용 마크다운: 사용자(![](@U123)), 채널(![](#C123)) 멘션 문법이 일반 메시지와 다릅니다.

---

시나리오 1: 프로젝트별 위키 (독립 캔버스)

목표: 프로젝트 시작 시 독립적인 위키 캔버스를 만들고, 섹션별로 내용을 추가/교체하며, 필요시 특정 인원이나 채널에 공유합니다.

필요 스코프

• 필수: canvases:write, canvases:read, files:read
• 선택: conversations:read (채널 ID 탐색용), chat:write (안내 메시지 전송용)

구현 흐름

1. 생성: canvases.create를 호출하여 title과 document_content (markdown)를 포함한 캔버스를 생성하고, 반환된 canvas_id를 저장합니다.
2. 공유 (선택): canvases.access.set을 사용하여 user_ids 또는 channel_ids로 접근 권한을 부여합니다.
3. 편집:
   • 문단 추가: canvases.edit의 changes 배열에 {operation: "insert_at_end", ...}를 포함하여 호출합니다.
   • 특정 위치 삽입: canvases.sections.lookup으로 section_id를 찾은 뒤, insert_after / insert_before / replace operation을 사용합니다.
4. 목록화/탐색: files.list?types=canvas로 워크스페이스의 캔버스 목록을 조회하고, url_private로 본문을 다운로드합니다.

---

시나리오 2: 채널 온보딩/FAQ 자동화 (채널 캔버스)

목표: 새 채널이 생성되거나 로빙이 채널에 초대될 때, 해당 채널의 캔버스 탭에 "가이드/FAQ" 문서를 자동으로 생성하고 주기적으로 갱신합니다.

필요 스코프

• 필수: canvases:write, canvases:read
• 선택: conversations:read (채널 ID 탐색), chat:write (갱신 알림), files:read (내부 파일/이미지 링크 삽입)

구현 흐름

1. 채널 식별: conversations.list 또는 채널 생성 이벤트를 통해 channel_id를 확보합니다.
2. 채널 탭에 캔버스 생성: canvases.create 호출 시 channel_id를 함께 전달하면 해당 채널 탭에 캔버스가 자동으로 추가됩니다.
3. 접근 제어: canvases.access.set으로 채널 단위 접근 권한을 설정합니다.
4. 주기적 갱신: 캔버스 내 헤더(예: ## FAQ)를 앵커로 삼아 canvases.sections.lookup으로 위치를 찾고, canvases.edit으로 해당 섹션만 교체합니다.

---

시나리오 3: 회의록/인시던트 문서화

목표: 회의나 인시던트 종료 후, 대화 요약본을 캔버스의 정해진 서식(체크리스트, 테이블 등)에 맞춰 구조화하여 반영하고 관련 스크린샷을 첨부합니다.

필요 스코프

• 필수: canvases:write, canvases:read
• 선택: files:read (이미지 퍼멀링크 조회), chat:write (완료 알림), conversations:read (관련 채널 탐색)

구현 흐름

1. 서식 정의: 캔버스 내에 헤더(예: # Summary, ## Action items)를 앵커로 미리 정의합니다.
2. 섹션 위치 탐색: canvases.sections.lookup에 section_types:["h1","h2"]와 contains_text:"Action items" 같은 조건을 주어 삽입할 위치의 section_id를 찾습니다.
3. 내용 반영: canvases.edit을 사용하여 insert_after 또는 replace operation을 수행합니다. 체크리스트(- [ ]), 테이블(파이프 | 문법) 등 캔버스 전용 마크다운을 사용합니다.
4. 이미지 삽입: 슬랙에 업로드된 파일은 files.info로 permalink를 얻은 뒤, 마크다운 ![alt](permalink) 형식으로 본문에 삽입합니다.
5. 완료 알림 (선택): chat.postMessage를 통해 관련 채널에 캔버스 링크와 변경 요약 내용을 알립니다.

---

앱 매니페스트 및 스코프 설정 (예시)

display_information:
  name: RO-BEING
features:
  bot_user:
    display_name: RO-BEING
    always_online: true
oauth_config:
  scopes:
    bot:
      - canvases:write
      - canvases:read
      - files:read
      - conversations:read       # 채널 탐색/확인 용도
      - chat:write               # 안내/알림 메시지 포스팅 시
settings:
  interactivity:
    is_enabled: true

중요: 스코프 추가 후에는 앱을 워크스페이스에 재설치해야 합니다.

최소 구현 체크리스트

• 스코프 추가: 매니페스트에 canvases:write, canvases:read, files:read 추가 후 앱 재설치.
• 생성: canvases.create로 캔버스 생성 및 canvas_id 저장. (채널 탭 연동 시 channel_id 포함)
• 편집: canvases.sections.lookup → canvases.edit 조합으로 위치 기반 편집 구현.
• 공유: canvases.access.set으로 채널/사용자 접근 수준 설정. (DM/MPDM 제약 준수)
• 탐색: files.list?types=canvas로 캔버스 검색 및 url_private로 본문 다운로드.