Files
dbx-main/app/integrations/google_sheets.py
T
king e63734c984 feat(cupang): 밀크런 출고리스트 작성 팝업 — 구글 시트 출고일 시트 아래에 덧붙임
- 첫 화면 "+ 신규 등록" 옆 엑셀색 버튼 → 작성일·출고일·센터입고일(프로젝트 날짜 팝업),
  입고센터(시트 F열 + 등록 센터, 직접 입력), 출고방식(파렛트/택배), 코드표 검색 제품·수량, 출고, 작업자(기본 핫프렌즈)
- POST /cupang/api/outbound-sheet: 출고일 시트 YYYYMMDD(요일) 맨 아래에 기존 양식으로 추가
  (순번 이어짐·파렛트 배경색), 시트가 없으면 5행 양식째 생성. cupang_db 에는 저장하지 않음
- GET /cupang/api/outbound-sheet/centers: 입고센터 후보(10분 캐시)
- export.build_block 분리(기존 build_table 결과 동일), google_sheets 에 sheet_titles·read_ranges·append_block 추가
- 테스트: pytest(양식·입력 검사·덧붙일 위치·Sheets 요청·실제 앱), Playwright 화면 테스트

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-23 14:57:43 +09:00

530 lines
21 KiB
Python

"""Google 스프레드시트 쓰기 공통 계층.
인증 방식 두 가지를 지원한다(설정된 쪽을 자동 선택, 서비스 계정 우선).
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-api-python-client)가 없거나 설정이 비어 있으면
`enabled = False` 로 조용히 비활성화되고, 호출부는 건너뛴다.
"""
from __future__ import annotations
import functools
import json
import os
import threading
from typing import Any
SCOPES = ["https://www.googleapis.com/auth/spreadsheets"]
TOKEN_URI = "https://oauth2.googleapis.com/token"
def _hex_color(value: str) -> dict[str, float]:
""""RRGGBB" → Sheets API 색상."""
v = (value or "").lstrip("#")
return {
"red": int(v[0:2], 16) / 255.0,
"green": int(v[2:4], 16) / 255.0,
"blue": int(v[4:6], 16) / 255.0,
}
def a1_sheet(title: str) -> str:
"""A1 표기용 시트 이름 — 작은따옴표로 감싸고 안의 ' 는 '' 로."""
return "'" + title.replace("'", "''") + "'"
def col_letter(col: int) -> str:
"""1-based 열 번호 → 열 문자(A, B, …, AA)."""
letters = ""
while col > 0:
col, rem = divmod(col - 1, 26)
letters = chr(65 + rem) + letters
return letters
def _repeat_cell(
sheet_id: int, r1: int, c1: int, r2: int, c2: int, fmt: dict[str, Any], fields: str
) -> dict[str, Any]:
"""1-based 양끝 포함 범위에 같은 서식을 입히는 요청."""
return {
"repeatCell": {
"range": {
"sheetId": sheet_id,
"startRowIndex": r1 - 1, "endRowIndex": r2,
"startColumnIndex": c1 - 1, "endColumnIndex": c2,
},
"cell": {"userEnteredFormat": fmt},
"fields": fields,
}
}
# 웹 핸들러가 sync def(스레드풀)라 여러 요청이 동시에 이 writer 를 쓸 수 있다.
# googleapiclient 의 HTTP 클라이언트(httplib2)는 스레드 안전하지 않고, 같은 날짜
# 시트를 동시에 지우고/쓰면 내용이 섞이므로 시트 작업은 한 번에 하나씩만 한다.
_LOCK = threading.RLock()
def _serialized(fn: Any) -> Any:
@functools.wraps(fn)
def wrapper(*args: Any, **kwargs: Any) -> Any:
with _LOCK:
return fn(*args, **kwargs)
return wrapper
class GoogleSheetsWriter:
"""시트 1장을 통째로 다시 쓰는 용도의 얇은 래퍼."""
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:
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 None
try:
from google.oauth2.service_account import Credentials
creds = Credentials.from_service_account_info(info, scopes=SCOPES)
except Exception as exc: # noqa: BLE001
self.reason = f"서비스 계정 인증 실패: {type(exc).__name__}"
return None
self._client_email = str(info.get("client_email") or "")
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:
"""공유 대상 확인용(비밀값 아님)."""
return self._client_email
# ────────────────────────────────────────────────
def _sheet_id(self, spreadsheet_id: str, title: str) -> int | None:
meta = self._service.spreadsheets().get(spreadsheetId=spreadsheet_id).execute()
for sh in meta.get("sheets", []):
props = sh.get("properties", {})
if props.get("title") == title:
return int(props.get("sheetId"))
return None
def _create_sheet(self, spreadsheet_id: str, title: str) -> int:
res = self._service.spreadsheets().batchUpdate(
spreadsheetId=spreadsheet_id,
body={"requests": [{"addSheet": {"properties": {"title": title}}}]},
).execute()
return int(res["replies"][0]["addSheet"]["properties"]["sheetId"])
@property
def lock(self) -> Any:
"""읽고 → 쓰기를 한 덩어리로 묶을 때 쓰는 잠금(같은 시트에 동시에 덧붙이지 않게).
RLock 이라 잡은 채로 이 writer 의 다른 메서드를 불러도 된다."""
return _LOCK
@_serialized
def sheet_titles(self, *, spreadsheet_id: str) -> list[str]:
"""문서의 시트 이름 목록(탭 순서)."""
if not self.enabled:
raise RuntimeError(self.reason or "Google Sheets 미설정")
meta = self._service.spreadsheets().get(
spreadsheetId=spreadsheet_id, fields="sheets.properties.title"
).execute()
return [str(sh.get("properties", {}).get("title") or "") for sh in meta.get("sheets", [])]
@_serialized
def read_ranges(
self, *, spreadsheet_id: str, ranges: list[str], chunk: int = 50
) -> list[list[list[Any]]]:
"""A1 범위 여러 개의 값(범위마다 2차원 목록). 요청 하나가 너무 길지 않게 나눠 읽는다."""
if not self.enabled:
raise RuntimeError(self.reason or "Google Sheets 미설정")
out: list[list[list[Any]]] = []
for i in range(0, len(ranges), chunk):
part = ranges[i:i + chunk]
res = self._service.spreadsheets().values().batchGet(
spreadsheetId=spreadsheet_id, ranges=part
).execute()
got = res.get("valueRanges", [])
out.extend(vr.get("values", []) for vr in got)
out.extend([] for _ in range(len(part) - len(got)))
return out
@_serialized
def append_block(
self,
*,
spreadsheet_id: str,
title: str,
cells: dict[tuple[int, int], Any],
merges: list[tuple[int, int, int, int]],
first_row: int,
last_row: int,
first_col: int,
last_col: int,
left_cols: tuple[int, ...] = (9,),
highlight: str = "",
) -> dict[str, Any]:
"""이미 있는 시트의 first_row~last_row 에 표 한 덩어리를 쓴다(위쪽 내용은 그대로).
서식은 write_table 의 데이터 행과 같다 — 가운데 정렬·줄바꿈·테두리, left_cols 만 왼쪽 정렬,
highlight("RRGGBB")가 있으면 그 덩어리 배경색. 좌표는 1-based."""
if not self.enabled:
raise RuntimeError(self.reason or "Google Sheets 미설정")
meta = self._service.spreadsheets().get(
spreadsheetId=spreadsheet_id,
fields="sheets.properties(sheetId,title,gridProperties.rowCount)",
).execute()
props = next(
(sh.get("properties", {}) for sh in meta.get("sheets", [])
if sh.get("properties", {}).get("title") == title),
None,
)
if props is None:
raise LookupError(f"시트를 찾을 수 없습니다: {title}")
sheet_id = int(props.get("sheetId"))
row_count = int(props.get("gridProperties", {}).get("rowCount") or 0)
requests: list[dict[str, Any]] = []
if row_count < last_row:
# 격자보다 아래에는 값을 쓸 수 없으므로 행을 먼저 늘린다
requests.append({"appendDimension": {
"sheetId": sheet_id, "dimension": "ROWS", "length": last_row - row_count,
}})
for (r1, c1, r2, c2) in merges:
requests.append({
"mergeCells": {
"mergeType": "MERGE_ALL",
"range": {
"sheetId": sheet_id,
"startRowIndex": r1 - 1, "endRowIndex": r2,
"startColumnIndex": c1 - 1, "endColumnIndex": c2,
},
}
})
requests.append(_repeat_cell(
sheet_id, first_row, first_col, last_row, last_col,
{"horizontalAlignment": "CENTER", "verticalAlignment": "MIDDLE", "wrapStrategy": "WRAP"},
"userEnteredFormat(horizontalAlignment,verticalAlignment,wrapStrategy)",
))
for col in left_cols:
requests.append(_repeat_cell(
sheet_id, first_row, col, last_row, col,
{"horizontalAlignment": "LEFT"}, "userEnteredFormat(horizontalAlignment)",
))
if highlight:
requests.append(_repeat_cell(
sheet_id, first_row, first_col, last_row, last_col,
{"backgroundColor": _hex_color(highlight)}, "userEnteredFormat(backgroundColor)",
))
border = {"style": "SOLID", "color": {"red": 0, "green": 0, "blue": 0}}
requests.append({
"updateBorders": {
"range": {
"sheetId": sheet_id,
"startRowIndex": first_row - 1, "endRowIndex": last_row,
"startColumnIndex": first_col - 1, "endColumnIndex": last_col,
},
"top": border, "bottom": border, "left": border, "right": border,
"innerHorizontal": border, "innerVertical": border,
}
})
self._service.spreadsheets().batchUpdate(
spreadsheetId=spreadsheet_id, body={"requests": requests}
).execute()
matrix = [
[cells.get((r, c), "") for c in range(first_col, last_col + 1)]
for r in range(first_row, last_row + 1)
]
self._service.spreadsheets().values().update(
spreadsheetId=spreadsheet_id,
range=f"{a1_sheet(title)}!{col_letter(first_col)}{first_row}",
valueInputOption="USER_ENTERED",
body={"values": matrix},
).execute()
return {
"created": False,
"title": title,
"first_row": first_row,
"last_row": last_row,
"url": f"https://docs.google.com/spreadsheets/d/{spreadsheet_id}/edit#gid={sheet_id}",
}
@_serialized
def delete_sheet(self, *, spreadsheet_id: str, title: str) -> dict[str, Any]:
"""이름이 정확히 일치하는 시트 1장을 삭제한다.
- 없으면 아무것도 하지 않는다(missing).
- 문서에 시트가 그 하나뿐이면 구글이 삭제를 거부하므로,
대신 내용을 비운다(cleared).
"""
if not self.enabled:
raise RuntimeError(self.reason or "Google Sheets 미설정")
meta = self._service.spreadsheets().get(spreadsheetId=spreadsheet_id).execute()
sheets = meta.get("sheets", [])
target = None
for sh in sheets:
props = sh.get("properties", {})
if props.get("title") == title:
target = int(props.get("sheetId"))
break
if target is None:
return {"ok": True, "action": "missing", "title": title}
if len(sheets) <= 1:
self._service.spreadsheets().batchUpdate(
spreadsheetId=spreadsheet_id,
body={"requests": [
{"unmergeCells": {"range": {"sheetId": target}}},
{"updateCells": {"range": {"sheetId": target}, "fields": "*"}},
]},
).execute()
return {"ok": True, "action": "cleared", "title": title}
self._service.spreadsheets().batchUpdate(
spreadsheetId=spreadsheet_id,
body={"requests": [{"deleteSheet": {"sheetId": target}}]},
).execute()
return {"ok": True, "action": "deleted", "title": title}
@_serialized
def write_table(
self,
*,
spreadsheet_id: str,
title: str,
cells: dict[tuple[int, int], Any],
merges: list[tuple[int, int, int, int]],
header_row: int,
first_data_row: int,
last_row: int,
first_col: int,
last_col: int,
title_row: int,
widths: dict[int, int], # 열 번호(1-based) -> 픽셀
header_bg: str = "",
row_highlights: list[tuple[int, int, str]] | None = None,
) -> dict[str, Any]:
"""시트를 만들고(있으면 비우고) 표를 통째로 기록한다.
좌표는 모두 1-based(엑셀과 동일). 반환값에 시트 URL 을 담는다.
header_bg / row_highlights 의 색은 "RRGGBB" 16진 문자열.
"""
if not self.enabled:
raise RuntimeError(self.reason or "Google Sheets 미설정")
sheet_id = self._sheet_id(spreadsheet_id, title)
created = sheet_id is None
if created:
sheet_id = self._create_sheet(spreadsheet_id, title)
rows_n = max([r for (r, _c) in cells] or [1])
cols_n = last_col
matrix: list[list[Any]] = [["" for _ in range(cols_n)] for _ in range(rows_n)]
for (r, c), value in cells.items():
matrix[r - 1][c - 1] = value
requests: list[dict[str, Any]] = [
# 기존 내용/서식/병합 초기화 → 같은 날짜로 다시 확정해도 깨끗하게 덮어쓴다
{"unmergeCells": {"range": {"sheetId": sheet_id}}},
{"updateCells": {"range": {"sheetId": sheet_id}, "fields": "*"}},
]
for (r1, c1, r2, c2) in merges:
requests.append({
"mergeCells": {
"mergeType": "MERGE_ALL",
"range": {
"sheetId": sheet_id,
"startRowIndex": r1 - 1, "endRowIndex": r2,
"startColumnIndex": c1 - 1, "endColumnIndex": c2,
},
}
})
def _fmt(r1: int, c1: int, r2: int, c2: int, fmt: dict[str, Any], fields: str) -> dict[str, Any]:
return _repeat_cell(sheet_id, r1, c1, r2, c2, fmt, fields)
requests.append(_fmt(
title_row, first_col, title_row, last_col,
{"horizontalAlignment": "CENTER", "verticalAlignment": "MIDDLE",
"textFormat": {"bold": True, "fontSize": 16}},
"userEnteredFormat(horizontalAlignment,verticalAlignment,textFormat)",
))
header_fmt: dict[str, Any] = {
"horizontalAlignment": "CENTER", "verticalAlignment": "MIDDLE",
"textFormat": {"bold": True},
}
header_fields = "userEnteredFormat(horizontalAlignment,verticalAlignment,textFormat)"
if header_bg:
header_fmt["backgroundColor"] = _hex_color(header_bg)
header_fields = (
"userEnteredFormat(horizontalAlignment,verticalAlignment,"
"textFormat,backgroundColor)"
)
requests.append(_fmt(header_row, first_col, header_row, last_col,
header_fmt, header_fields))
if last_row >= first_data_row:
requests.append(_fmt(
first_data_row, first_col, last_row, last_col,
{"horizontalAlignment": "CENTER", "verticalAlignment": "MIDDLE",
"wrapStrategy": "WRAP"},
"userEnteredFormat(horizontalAlignment,verticalAlignment,wrapStrategy)",
))
# 제품명 칸만 왼쪽 정렬
requests.append(_fmt(
first_data_row, 9, last_row, 9,
{"horizontalAlignment": "LEFT"},
"userEnteredFormat(horizontalAlignment)",
))
border = {"style": "SOLID", "color": {"red": 0, "green": 0, "blue": 0}}
requests.append({
"updateBorders": {
"range": {
"sheetId": sheet_id,
"startRowIndex": header_row - 1, "endRowIndex": last_row,
"startColumnIndex": first_col - 1, "endColumnIndex": last_col,
},
"top": border, "bottom": border, "left": border, "right": border,
"innerHorizontal": border, "innerVertical": border,
}
})
# 특정 행 구간 배경색(예: 파렛트 출고 블록)
for (r1, r2, color) in (row_highlights or []):
requests.append(_fmt(
r1, first_col, r2, last_col,
{"backgroundColor": _hex_color(color)},
"userEnteredFormat(backgroundColor)",
))
for col, width in widths.items():
requests.append({
"updateDimensionProperties": {
"range": {
"sheetId": sheet_id, "dimension": "COLUMNS",
"startIndex": col - 1, "endIndex": col,
},
"properties": {"pixelSize": int(width)},
"fields": "pixelSize",
}
})
self._service.spreadsheets().batchUpdate(
spreadsheetId=spreadsheet_id, body={"requests": requests}
).execute()
self._service.spreadsheets().values().update(
spreadsheetId=spreadsheet_id,
range=f"'{title}'!A1",
valueInputOption="USER_ENTERED",
body={"values": matrix},
).execute()
return {
"created": created,
"title": title,
"url": f"https://docs.google.com/spreadsheets/d/{spreadsheet_id}/edit#gid={sheet_id}",
}
_writer: GoogleSheetsWriter | None = None
def get_writer() -> GoogleSheetsWriter:
"""프로세스 1개당 1회 초기화."""
global _writer # noqa: PLW0603
with _LOCK:
if _writer is None:
_writer = GoogleSheetsWriter()
return _writer