diff --git a/.env.example b/.env.example index e0e56b5..ac2791e 100644 --- a/.env.example +++ b/.env.example @@ -30,6 +30,16 @@ CUSTOMER_ORDER_LIST_URL=/orderlist/ # - 대상 문서는 반드시 "Google 스프레드시트" 형식(업로드한 .xlsx 는 파일>Google 스프레드시트로 저장) # - 서비스 계정 이메일(client_email)에 해당 문서를 편집자로 공유해야 한다 # CUPANG_SHEET_ID=1J74op7lBZOgE27p4R28I3RWsv0EtXdii +# +# [방식 A] 사용자 OAuth 리프레시 토큰 — 조직 정책으로 서비스 계정 키를 못 만들 때 +# 토큰 발급: python scripts/google_sheets_authorize.py --client-id .. --client-secret .. +# (Cloud Console 에서 "데스크톱 앱" 유형 OAuth 클라이언트 ID 발급 후 사용) +# client id/secret 을 생략하면 로그인용 GOOGLE_CLIENT_ID/SECRET 을 쓴다. +# GOOGLE_SHEETS_OAUTH_CLIENT_ID=xxx.apps.googleusercontent.com +# GOOGLE_SHEETS_OAUTH_CLIENT_SECRET=replace-me +# GOOGLE_SHEETS_OAUTH_REFRESH_TOKEN=replace-me +# +# [방식 B] 서비스 계정 JSON (문서를 client_email 에 편집자로 공유해야 함) # GOOGLE_SHEETS_CREDENTIALS=/opt/www/main/secrets/google-sheets-sa.json # 또는 파일 대신 JSON 본문을 통째로 (한 줄): # GOOGLE_SHEETS_CREDENTIALS_JSON={"type":"service_account", ...} diff --git a/CLAUDE.md b/CLAUDE.md index e6f3d16..2c3cd21 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -31,7 +31,7 @@ Claude Code는 이 저장소에서 작업을 시작하기 전에 **반드시 아 - 반품관리 - 외부 쇼핑몰 API 연동 (카페24, 네이버 스마트스토어, 사방넷 등) - 개인경비 (`app/modules/expense/`, `expense_db`) -- 쿠팡 밀크런 (`app/modules/cupang/`, `cupang_db`) — 출고 달력/박스 계산/입고센터 관리, 상품은 `itemcode_db` 읽기 전용. 출고 묶음은 **박스 계산 화면의 [분배 확정] 으로만** 만든다(신규 등록 폼 없음, `/cupang/new` 는 박스 계산으로 리다이렉트). 확정 조건: 미배분 박스 0 + 담긴 센터마다 출고방식(택배/파렛트) 선택. 확정 시 센터마다 출고 묶음 1건(`status=출고준비`, 센터입고일=출고일+1일) + 출고리스트 엑셀 자동 다운로드(`GET /cupang/export.xlsx?date=`, 시트명 YYYYMMDD). 양식 생성은 `app/modules/cupang/export.py` 한 곳에서 만들어 xlsx·구글시트가 공유. `CUPANG_SHEET_ID` + 서비스 계정(`GOOGLE_SHEETS_CREDENTIALS[_JSON]`) 설정 시 확정과 동시에 Google 스프레드시트에 출고일 시트를 생성/덮어쓰기(`app/integrations/google_sheets.py`, 미설정이면 조용히 skip). 작업 중 상태는 `cupang_box_calc_drafts` 에 이름 붙여 임시 저장/불러오기. 쿠팡 발주 엑셀(xlsx) 다중 업로드 지원(`POST /cupang/api/box-calc/upload`, openpyxl) — F13 입고예정일의 하루 전 = 출고일, 22행부터 B=쿠팡상품코드·F=센터명·G=수량을 읽어 `cupang_products.coupang_item_code` 로 제품 매칭 후 센터별 합산 → 센터 단위로 박스 계산·자동 배분 +- 쿠팡 밀크런 (`app/modules/cupang/`, `cupang_db`) — 출고 달력/박스 계산/입고센터 관리, 상품은 `itemcode_db` 읽기 전용. 출고 묶음은 **박스 계산 화면의 [분배 확정] 으로만** 만든다(신규 등록 폼 없음, `/cupang/new` 는 박스 계산으로 리다이렉트). 확정 조건: 미배분 박스 0 + 담긴 센터마다 출고방식(택배/파렛트) 선택. 확정 시 센터마다 출고 묶음 1건(`status=출고준비`, 센터입고일=출고일+1일) + 출고리스트 엑셀 자동 다운로드(`GET /cupang/export.xlsx?date=`, 시트명 YYYYMMDD). 양식 생성은 `app/modules/cupang/export.py` 한 곳에서 만들어 xlsx·구글시트가 공유. `CUPANG_SHEET_ID` + 인증(사용자 OAuth `GOOGLE_SHEETS_OAUTH_REFRESH_TOKEN` 또는 서비스 계정 `GOOGLE_SHEETS_CREDENTIALS[_JSON]`) 설정 시 확정과 동시에 Google 스프레드시트에 출고일 시트를 생성/덮어쓰기(`app/integrations/google_sheets.py`, 미설정이면 조용히 skip). 작업 중 상태는 `cupang_box_calc_drafts` 에 이름 붙여 임시 저장/불러오기. 쿠팡 발주 엑셀(xlsx) 다중 업로드 지원(`POST /cupang/api/box-calc/upload`, openpyxl) — F13 입고예정일의 하루 전 = 출고일, 22행부터 B=쿠팡상품코드·F=센터명·G=수량을 읽어 `cupang_products.coupang_item_code` 로 제품 매칭 후 센터별 합산 → 센터 단위로 박스 계산·자동 배분 - 휴가 관리 (`app/modules/vacation/`, `vacation_db`) — 월간 달력(구글식 bar)/연차·반차 신청/승인 워크플로/공휴일·연차 설정. 권한키 `vacation`·`vacation_approver` - 말레이시아 창고 재고관리 (`app/modules/malaysia/`, `malaysia_stock_db`) — 낱개(MT/MX/MZ) 입출고·조정, 세트(MY) BOM, 일일 재고조사(세트→낱개 자동 분해), 현재고 현황. 뚜껑(MD-)은 재고 집계 제외 — 단, 창고 랙에는 위치 확인용으로 배치 가능(`store.LID_ITEMS`). 상품은 `itemcode_db` 읽기 전용. 권한키 `malaysia` - 말레이시아 배송 (`app/modules/dispatch/`, `dispatch_db`) — TikTok·Shopee 출고관리. 플랫폼별 데이터 엑셀 업로드(TikTok=03_TikTok_Order_Export.xlsx, Shopee=Packing List.Doorstep Delivery.xlsx) → 1박스=1카드 출고 작업 리스트·SKU 피킹 요약·Kagayaku 전달표 자동 생성. 1박스 묶음 기준 Package ID > Tracking ID > Order ID, 같은 박스 같은 SKU 합산. 작업 상태 토글(`dispatch_logs` 기록). 받는 사람 이름/전화/주소는 박스 단위로 저장(작업 카드 표시 + 출고 엑셀 생성용 — 개인정보). 배치 다운로드 zip 에 업로드 원본 + 취합 출고 엑셀(`YYYY.MM.DD(Ddd)_tictoc|shopee.xlsx`) 포함. 엑셀은 openpyxl 파싱/생성. 권한키 `dispatch`. 상세는 `docs/DISPATCH_MODULE.md` diff --git a/app/integrations/google_sheets.py b/app/integrations/google_sheets.py index 6e4c100..cf9e844 100644 --- a/app/integrations/google_sheets.py +++ b/app/integrations/google_sheets.py @@ -1,11 +1,21 @@ -"""Google 스프레드시트 쓰기 공통 계층 (서비스 계정). +"""Google 스프레드시트 쓰기 공통 계층. -- 다른 모듈에서도 쓸 수 있게 `app/integrations/` 에 둔다. -- 인증: 구글 클라우드 **서비스 계정** JSON. +인증 방식 두 가지를 지원한다(설정된 쪽을 자동 선택, 서비스 계정 우선). + +1) 사용자 OAuth 리프레시 토큰 — 조직 정책으로 서비스 계정 **키 발급이 막힌** 경우 + · `GOOGLE_SHEETS_OAUTH_REFRESH_TOKEN` 1회 동의로 받은 refresh token + · `GOOGLE_SHEETS_OAUTH_CLIENT_ID` / `..._SECRET` + (없으면 로그인용 `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` 사용) + 토큰 발급: `python scripts/google_sheets_authorize.py` + 이 방식은 토큰을 발급한 **사용자 권한**으로 동작하므로, 그 사용자가 이미 + 편집할 수 있는 문서면 별도 공유가 필요 없다. + +2) 서비스 계정 JSON · `GOOGLE_SHEETS_CREDENTIALS` 서비스 계정 JSON 파일 경로 - · `GOOGLE_SHEETS_CREDENTIALS_JSON` JSON 본문(파일 대신 환경변수로 넣을 때) - 대상 스프레드시트를 서비스 계정 이메일(client_email)에 **편집자로 공유**해야 한다. -- 비밀값(키)은 로그·화면에 절대 출력하지 않는다. + · `GOOGLE_SHEETS_CREDENTIALS_JSON` JSON 본문(파일 대신 환경변수로) + 대상 문서를 서비스 계정 이메일(client_email)에 **편집자로 공유**해야 한다. + +- 비밀값(키/토큰)은 로그·화면에 절대 출력하지 않는다. - 라이브러리(google-api-python-client)가 없거나 설정이 비어 있으면 `enabled = False` 로 조용히 비활성화되고, 호출부는 건너뛴다. """ @@ -17,6 +27,7 @@ import os from typing import Any SCOPES = ["https://www.googleapis.com/auth/spreadsheets"] +TOKEN_URI = "https://oauth2.googleapis.com/token" class GoogleSheetsWriter: @@ -25,39 +36,91 @@ class GoogleSheetsWriter: def __init__(self) -> None: self.enabled = False self.reason = "" + self.auth_mode = "" # "service_account" | "oauth" self._service: Any = None self._client_email = "" + try: + from googleapiclient.discovery import build + except ImportError: + self.reason = "google-api-python-client 미설치" + return + + creds = self._service_account_creds() + if creds is None: + creds = self._oauth_creds() + if creds is None: + if not self.reason: + self.reason = ( + "GOOGLE_SHEETS_OAUTH_REFRESH_TOKEN 또는 " + "GOOGLE_SHEETS_CREDENTIALS(_JSON) 미설정" + ) + return + + try: + self._service = build("sheets", "v4", credentials=creds, cache_discovery=False) + except Exception as exc: # noqa: BLE001 - 사유만 남긴다(비밀값 미출력) + self.reason = f"Sheets 클라이언트 생성 실패: {type(exc).__name__}" + return + self.enabled = True + + # ── 인증 ───────────────────────────────────────── + def _service_account_creds(self) -> Any: raw = (os.getenv("GOOGLE_SHEETS_CREDENTIALS_JSON") or "").strip() path = (os.getenv("GOOGLE_SHEETS_CREDENTIALS") or "").strip() if not raw and not path: - self.reason = "GOOGLE_SHEETS_CREDENTIALS(_JSON) 미설정" - return - + return None try: info = json.loads(raw) if raw else json.loads( open(path, encoding="utf-8").read() ) except (OSError, ValueError): self.reason = "서비스 계정 JSON 을 읽지 못했습니다." - return - + return None try: from google.oauth2.service_account import Credentials - from googleapiclient.discovery import build - except ImportError: - self.reason = "google-api-python-client 미설치" - return - try: creds = Credentials.from_service_account_info(info, scopes=SCOPES) - self._service = build("sheets", "v4", credentials=creds, cache_discovery=False) - except Exception as exc: # noqa: BLE001 - 인증 실패 사유만 남긴다 + except Exception as exc: # noqa: BLE001 self.reason = f"서비스 계정 인증 실패: {type(exc).__name__}" - return - + return None self._client_email = str(info.get("client_email") or "") - self.enabled = True + self.auth_mode = "service_account" + return creds + + def _oauth_creds(self) -> Any: + refresh_token = (os.getenv("GOOGLE_SHEETS_OAUTH_REFRESH_TOKEN") or "").strip() + if not refresh_token: + return None + client_id = ( + os.getenv("GOOGLE_SHEETS_OAUTH_CLIENT_ID") + or os.getenv("GOOGLE_CLIENT_ID") + or "" + ).strip() + client_secret = ( + os.getenv("GOOGLE_SHEETS_OAUTH_CLIENT_SECRET") + or os.getenv("GOOGLE_CLIENT_SECRET") + or "" + ).strip() + if not client_id or not client_secret: + self.reason = "GOOGLE_SHEETS_OAUTH_CLIENT_ID/SECRET 미설정" + return None + try: + from google.oauth2.credentials import Credentials + + creds = Credentials( + token=None, + refresh_token=refresh_token, + token_uri=TOKEN_URI, + client_id=client_id, + client_secret=client_secret, + scopes=SCOPES, + ) + except Exception as exc: # noqa: BLE001 + self.reason = f"OAuth 자격 생성 실패: {type(exc).__name__}" + return None + self.auth_mode = "oauth" + return creds @property def client_email(self) -> str: diff --git a/requirements.txt b/requirements.txt index b68d6d6..2a3092e 100644 --- a/requirements.txt +++ b/requirements.txt @@ -14,3 +14,5 @@ pillow>=10.0 cryptography>=42.0 google-api-python-client>=2.100 google-auth>=2.30 +# refresh token 발급 스크립트(scripts/google_sheets_authorize.py) 전용 +google-auth-oauthlib>=1.2 diff --git a/scripts/google_sheets_authorize.py b/scripts/google_sheets_authorize.py new file mode 100644 index 0000000..a329ed5 --- /dev/null +++ b/scripts/google_sheets_authorize.py @@ -0,0 +1,90 @@ +"""Google 스프레드시트 쓰기용 refresh token 1회 발급 스크립트. + +조직 정책(`iam.disableServiceAccountKeyCreation`)으로 서비스 계정 키를 만들 수 없을 때 +사용자 계정 OAuth 로 서버가 시트에 기록하도록 하기 위한 토큰을 받는다. + +사전 준비 (Google Cloud Console) + 1. API 및 서비스 → 라이브러리 → "Google Sheets API" 사용 + 2. API 및 서비스 → OAuth 동의 화면 구성(내부 또는 외부) + 3. 사용자 인증 정보 → 사용자 인증 정보 만들기 → **OAuth 클라이언트 ID** + → 애플리케이션 유형 **데스크톱 앱** → 클라이언트 ID / 보안 비밀 확인 + +실행 (개발 PC, 브라우저 있는 환경에서) + python scripts/google_sheets_authorize.py --client-id --client-secret + 또는 환경변수로: + GOOGLE_SHEETS_OAUTH_CLIENT_ID / GOOGLE_SHEETS_OAUTH_CLIENT_SECRET + + 브라우저가 열리면 **시트를 편집할 수 있는 계정**으로 로그인·동의한다. + 마지막에 출력되는 refresh token 을 서버 `.env` 의 + `GOOGLE_SHEETS_OAUTH_REFRESH_TOKEN` 에 넣는다. + +주의 + - 출력된 refresh token 은 비밀값이다. Git·메신저에 남기지 말 것. + - 토큰은 발급한 사용자 권한으로 동작한다. 그 사용자가 대상 문서를 편집할 수 + 있어야 하며, 계정 비밀번호 변경·토큰 폐기 시 다시 발급해야 한다. +""" + +from __future__ import annotations + +import argparse +import os +import sys + +SCOPES = ["https://www.googleapis.com/auth/spreadsheets"] + + +def main() -> int: + parser = argparse.ArgumentParser(description="Google Sheets refresh token 발급") + parser.add_argument("--client-id", default=os.getenv("GOOGLE_SHEETS_OAUTH_CLIENT_ID", "")) + parser.add_argument( + "--client-secret", default=os.getenv("GOOGLE_SHEETS_OAUTH_CLIENT_SECRET", "") + ) + parser.add_argument( + "--port", type=int, default=0, help="로컬 콜백 포트(기본: 임의 포트)" + ) + args = parser.parse_args() + + client_id = (args.client_id or "").strip() + client_secret = (args.client_secret or "").strip() + if not client_id or not client_secret: + print("client id / secret 이 필요합니다. --client-id / --client-secret 또는 환경변수로 넣으세요.") + return 2 + + try: + from google_auth_oauthlib.flow import InstalledAppFlow + except ImportError: + print("google-auth-oauthlib 가 필요합니다: pip install google-auth-oauthlib") + return 2 + + flow = InstalledAppFlow.from_client_config( + { + "installed": { + "client_id": client_id, + "client_secret": client_secret, + "auth_uri": "https://accounts.google.com/o/oauth2/auth", + "token_uri": "https://oauth2.googleapis.com/token", + "redirect_uris": ["http://localhost"], + } + }, + scopes=SCOPES, + ) + # prompt=consent 를 줘야 refresh token 이 항상 내려온다. + creds = flow.run_local_server(port=args.port, prompt="consent", access_type="offline") + + if not creds.refresh_token: + print("refresh token 을 받지 못했습니다. 계정의 기존 권한을 해제하고 다시 시도하세요.") + return 1 + + print() + print("=" * 70) + print("서버 .env 에 아래 값을 넣으세요 (비밀값 — 공유 금지)") + print("=" * 70) + print(f"GOOGLE_SHEETS_OAUTH_CLIENT_ID={client_id}") + print("GOOGLE_SHEETS_OAUTH_CLIENT_SECRET=<위에서 쓴 보안 비밀>") + print(f"GOOGLE_SHEETS_OAUTH_REFRESH_TOKEN={creds.refresh_token}") + print("=" * 70) + return 0 + + +if __name__ == "__main__": + sys.exit(main())