Google Drive 모듈 — 워크허브 ↔ 드라이브 통합
워크허브의 모든 첨부 / 파일 / 명함 / 미팅 트랜스크립트를 Google Drive 원본으로 다룰 수 있게 해주는 모듈입니다. 워크허브가 파일을 자기 스토리지에 복사하지 않고, Drive 의 webViewLink 와 권한으로 직접 연결합니다.
왜 Drive 인가: 회사가 이미 Workspace 를 쓰고 있으면 파일을 두 곳에 복제하지 않고 원본 한 곳에서 관리할 수 있습니다. 권한·검색·버전관리·외부 공유가 모두 Drive 기준.
1. 동작 그림
워크허브 화면 Google Drive
───────────── ──────────────
메시지/태스크/명함/미팅
│
│ ① "Drive 첨부" 클릭
▼
Google Picker 팝업 ◀─── 본인 Drive 마이/공유 드라이브
│
│ ② 파일 선택
▼
워크허브 첨부 행 생성 ─────▶ external_id = drive_file_id
│ (워크허브 안에 파일 본체 복사 X)
│
│ ③ 수신자에게 자동 권한 부여 (선택 — grant_on_send=true)
▼
gdrive_grants 테이블 ──────▶ Drive permissions API
(수신자가 "구글에서 열기" 클릭 시 열림)핵심:
- 워크허브 DB 에는 파일 본체가 들어가지 않음 — Drive ID + 미리보기 메타만
- "구글에서 열기" 클릭 시 워크허브 백엔드가 Drive
webViewLink로 302 redirect - 메시지 삭제 / 멤버 변동 시 Drive 권한도 자동 회수
2. 사전 준비
기관관리자가 먼저 Google 모듈 + Drive 모듈 을 활성화하고 Picker API Key 를 등록해야 합니다 — 기관관리자 가이드 — Drive 모듈 참고.
활성화가 끝나면 메시지 첨부 / CRM 명함 인박스 / 미팅 트랜스크립트 등의 진입점이 노출됩니다.
본인 사용자 — 한 번만
기관관리자가 Drive 모듈을 활성한 후, 본인이 처음 Drive 첨부를 누르면:
- "Google 계정 연결" 안내 팝업 → 클릭
- Google 동의 화면에서 본인 Gmail 계정 선택 + "드라이브 파일 보기/관리" 권한 동의
- 워크허브에 본인 OAuth 토큰 (AES-GCM 암호화) 저장 → 이후 모든 Drive 흐름이 본인 계정 권한으로 동작
본인 계정 vs 공용 계정: 공유 드라이브를 쓰면 본인 계정이 공유 드라이브 멤버여야 첨부 가능. 마이드라이브 모드면 본인 드라이브 안의 파일만 접근.
3. 메시지 / DM / 토픽 — Drive 파일 첨부
3.1 첨부하기
메시지 입력창 우하단 📎 Drive 버튼 클릭:
┌──────────────────────────────────────────────┐
│ Google Picker (Google 가 제공하는 표준 팝업) │
│ ┌──────────────┬─────────────────────────┐ │
│ │ 📁 내 드라이브 │ 📁 공유 드라이브 │ │
│ └──────────────┴─────────────────────────┘ │
│ 최근 파일 / 검색 / 폴더 탐색 │
└──────────────────────────────────────────────┘- 내 드라이브 탭: 본인 마이드라이브
- 공유 드라이브 탭: 본인이 멤버인 공유 드라이브들
- 업로드 탭: 로컬 파일을 Drive 의 이 채널 폴더 (자동 생성됨) 로 즉시 업로드 후 첨부
파일 선택 → 워크허브 메시지에 칩으로 표시:
📄 견적서_2026Q2.xlsx [구글에서 열기]3.2 수신자 입장에서
수신자가 칩의 [구글에서 열기] 클릭 시:
- 백엔드
/files/{id}/open가 호출됨 - 워크허브가 본인 (작성자) Drive 권한을 자동 부여 (
grant_on_send=ON인 경우) - 302 redirect 로 Drive
webViewLink이동 - Drive 에서 본인 권한으로 열림
3.3 자동 권한 회수
다음 이벤트 시 워크허브가 부여한 Drive 권한을 자동 해제:
| 이벤트 | 회수 동작 |
|---|---|
| 메시지/DM 삭제 | 해당 첨부의 모든 grantee 권한 회수 |
| 채널/프로젝트에서 멤버 제외 | 그 멤버의 모든 첨부 권한 일괄 회수 |
| 사용자 비활성화 (퇴사) | 해당 사용자가 받은 모든 권한 회수 |
→ gdrive_grants 테이블에 audit 기록 + Drive permissions API delete 호출.
본인이 직접 부여한 권한은 회수 안됨: 본인이 Drive 콘솔에서 직접 "공유" 한 권한은 워크허브가 만지지 않습니다. 워크허브가 자동 부여한 것만 추적.
4. CRM — Drive 인박스 / 트랜스크립트
4.1 명함 — Drive 인박스 (자동 OCR)
기관관리자가 모듈관리 → CRM 설정에서 명함 Drive 폴더 를 설정해두면:
- 본인이 폰으로 명함 사진을 찍어 그 Drive 폴더에 업로드 (Drive 앱 / Workspace 동기화 등)
- 워크허브 고객관리 → 명함 화면에 Drive 인박스 영역에 자동으로 나타남
- [OCR 처리] 클릭 → Gemini Vision 으로 명함 자동 인식
- [확정] → 워크허브 명함 행 생성 + Drive 원본은 폴더 이동 + 파일명에 고객사명 자동 prefix
이 흐름의 장점:
- 폰 카메라 → Drive 업로드 → 워크허브 인식 → 고객 등록 = 한 동선
- 원본 명함 사진은 Drive 에 영구 보관 (워크허브가 카피하지 않음)
- 여러 사용자가 같은 폴더에 업로드하면 자동으로 인박스 공유
4.2 미팅 트랜스크립트 — Drive 가져오기
회의 녹음을 Otter/Plaud 같은 도구로 트랜스크립트 (.txt/.md/.srt/.vtt) 만들어 Drive 에 저장한 후:
- 워크허브 고객관리 → 미팅 → [트랜스크립트로 자동 생성]
- [Drive 에서 가져오기] 클릭 → Google Picker → 텍스트 파일 선택
- 백엔드가 1MB 까지 텍스트 가져옴 + LLM 으로 요약 + 미팅 행 자동 생성
Drive 모듈 비활성 기관: 위 버튼이 [파일에서 가져오기] (로컬 업로드) 로 자동 전환.
4.3 미팅 첨부
미팅 행에서 [첨부] → Drive Picker → 녹음 원본 / 회의 자료 등 첨부. 메시지 첨부와 동일하게 Drive 권한 자동 부여 / 회수.
5. Gmail 첨부 → Drive 저장
Gmail 모듈에서 받은 메일의 첨부 (영수증 / 견적서 / 인보이스 등) 를 Drive 로 영구 보관:
- 메일 본문 우상단 [첨부 보기]
- 첨부 행 우측 [Drive 로 저장] (명시적 동의 — 자동 import 금지)
- 워크허브 미리 정의된 Drive 폴더 (
/Workhub/Gmail-imports/) 에 저장 - 저장 후:
- 워크허브 첨부 행 생성 → 메일에서 역참조
- 경비 생성 시 receipt 로 자동 연결 가능 (
create_expense_from_email)
본인 명시 동의가 필요: 워크허브가 받은편지함 자동 스캔하면서 첨부를 Drive 로 옮기지 않습니다. 사용자가 그 메일에서 직접 누른 경우에만.
6. 파일 탭 — Drive 출처 메시징
채널/토픽/프로젝트의 파일 탭은 모든 첨부를 통합 표시합니다.
| 컬럼 | 표시 |
|---|---|
| 출처 배지 | 🟢 Drive / ⚪ 워크허브 업로드 |
| 이름 | 클릭 시 미리보기 (Drive 파일은 webViewLink) |
| 소유자 | Drive 파일은 Drive 의 원본 소유자, 아니면 업로드 사용자 |
| 액션 | 🔗 구글에서 열기 / ⬇ 다운로드 / 🗑 삭제 |
→ 워크허브 안에서 일관된 파일 관리 흐름. Drive 원본의 권한·소유는 그대로 유지.
7. FAQ
Q. 공유 드라이브 안 쓰고 본인 마이드라이브로만 운영해도 되나요?
가능합니다. 단점:
- 본인이 퇴사하면 본인 드라이브 자료가 사라짐 (회사가 백업할 수 없음)
- 같은 채널의 다른 사람이 본인 드라이브 파일을 보려면 grant 가 필요 (Drive 모듈이 자동 처리하지만)
회사 자료의 영속성/공유성을 위해 공유 드라이브 권장 — 기관관리자가 모듈 설정에서 지정.
Q. Drive 콘솔에서 직접 권한 추가하면 워크허브에 영향이 있나요?
영향 없음. 워크허브는 본인이 자동 부여한 권한만 추적 (gdrive_grants 테이블). Drive 콘솔에서 직접 부여한 권한은 회수 대상이 아니고, 그대로 유지됩니다.
Q. 파일 첨부 한도가 있나요?
Drive 첨부는 파일 본체를 워크허브가 보관하지 않으므로 워크허브 스토리지 한도와 무관. Drive 자체 한도 (Workspace 플랜에 따른 GB) 만 적용.
Q. 모바일 (Flutter) 앱에서도 Drive 첨부 되나요?
현재 Drive Picker 는 웹 화면 전용. 모바일에서는 카메라/갤러리 → 일반 업로드만. 단:
- Drive 모바일 앱에서 파일을 워크허브 첨부로 공유는 가능 (운영체제의 "공유" 메뉴)
- CRM 명함 인박스 흐름은 폰 카메라 → Drive 앱 업로드 → 워크허브 자동 인식으로 사실상 모바일 지원
Q. 본인이 Drive 권한 회수했는데 워크허브 화면에는 칩이 남아있어요.
워크허브가 알지 못함 (Drive 측 외부 변경은 watch 하지 않음). 클릭 시 Drive 가 403 → 워크허브가 "권한 없음" 안내. 시각적 정리는 별도 cron 으로 검토 예정 (현재는 즉시 반영 안됨).
Q. 공유 드라이브 멤버가 아닌 사람이 첨부 클릭하면?
grant_on_send=ON인 경우: 워크허브가 자동으로 read 권한 부여 → 열림grant_on_send=OFF인 경우: Drive 가 "접근 권한 없음" → 사용자가 본인 Drive 콘솔에서 요청 필요
Q. Drive 모듈을 켰는데 메시지에 Drive 버튼이 안 보여요.
체크:
- 기관관리자가 Drive 모듈 을 실제로 ON 했는지 (
/app/admin/modules) - 본인이 Drive OAuth 연결을 했는지 (메시지 첨부 화면에 "Google 계정 연결" 안내가 떴어야 함)
- 기관관리자가 Google Picker API Key 를 입력했는지 — 없으면 Picker 가 안 뜸
8. 트러블슈팅
"본인 Google 계정 권한 만료"
본인이 https://myaccount.google.com/permissions 에서 워크허브 권한을 회수했거나 토큰이 만료된 경우. 워크허브에서 다시 Drive 첨부 클릭 시 자동으로 재연결 안내.
"Drive 첨부 후 칩이 빨갛게 표시됨"
gdrive_grants 의 상태가 error — Drive permissions API 호출 실패. 원인:
- 본인이 그 파일의 소유자가 아니라 권한 부여 못함 (공유 드라이브 사용 권장)
- Drive 측 quota 초과
- 파일이 이미 삭제됨
칩 클릭 시 에러 메시지 노출. 본인 Drive 콘솔에서 직접 권한 부여로 우회 가능.
"공유 드라이브의 파일인데 워크허브 첨부 시 본인 권한이 회수되더라"
워크허브는 본인이 자동 부여한 grant 만 회수합니다. 본인이 공유 드라이브 멤버 자격으로 갖고 있던 원래 권한은 절대 회수 안 함. 회수 대상이 아닌데 그렇게 보이면 우연한 다른 원인.
9. 보안 / 개인정보
- OAuth refresh token 은 AES-GCM 으로 암호화돼 DB 저장 — 시스템관리자도 평문 조회 불가
- 워크허브는 본인 Drive 파일을 복사하지 않음 — Drive ID 와 미리보기 메타만 보관
- 워크허브가 부여한 권한은 모두
gdrive_grants에 audit 기록 — 누가 / 언제 / 어떤 파일 / 누구에게 - 본인이 언제든 https://myaccount.google.com/permissions 에서 워크허브 권한 회수 → 즉시 sync 중단
- 권한 회수 시 워크허브가 부여한 grant 도 자동 정리 (다음 호출에서 403 → 상태 갱신)
관련 가이드
- Gmail 모듈 — 메일 첨부를 Drive 로 저장
- 메시지 — 채널/토픽 메시징 (Drive 첨부 포함)
- 파일 — 파일 탭 일반 사용법
- Claude / MCP 클라이언트 연결 — Claude 에서 Drive 첨부 자동화
- 기관관리자 가이드 — Drive 모듈 — 모듈 활성화 / Picker API Key / 공유 드라이브