GFF 서버 구축 00 -- GFF 서버란 무엇이고 왜 만드는가

0. 한 줄 요약

GFF 서버는 “문서 변환 + 포인트 관리 + 결과 검증”을 서버에서 한 기준으로 처리하기 위한 백엔드다.

---

1. 먼저 용어부터 정리: SSOT(단일 기준)이란?

SSOT는 “Single Source of Truth”의 약자다.
블로그에서는 이렇게 이해하면 된다.

단일 기준(SSOT) = 정답을 하나로 정해두고, 최종 판단은 그 기준만 따른다.

예를 들어 포인트가 있다면,

• 앱 화면에 보이는 숫자(캐시)는 참고일 수 있지만
• 최종으로 믿는 숫자는 서버 DB에 있는 값 하나로 고정한다

이렇게 해야:

• 기기마다 값이 달라지는 일이 줄고
• 실수/오류/분쟁이 줄고
• 장기 운영이 가능해진다

이 시리즈에서 “단일 기준”은 주로 다음을 의미한다.

• 포인트의 최종 값은 서버가 가진다
• 포인트 변동 기록(원장)은 서버가 가진다

---

2. GFF 서버란 무엇인가

2.1 GFF(글틀공방)의 핵심은 “문서 자동화”

GFF는 사용자가 작성해야 하는 문서를 더 쉽고 정확하게 만들기 위한 앱(들)이다.
사용자는 입력(텍스트/체크/메모/사진 등)을 제공하고, 앱은 이를 구조화해서 결과 문서를 만든다.

하지만 “문서 변환”은 단순 UI 기능이 아니다.

• 비용이 드는 AI 호출이 포함될 수 있고
• 변환 결과는 반드시 규칙/정책에 맞게 검증되어야 하며
• 기록(히스토리), 근거(evidence), 누락 질문(missingQuestions) 같은 구조가 필요하다

이 일을 안정적으로 처리하려면 “서버”가 필요해진다.

2.2 GFF 서버가 하는 일(정의)

GFF 서버는 크게 3가지를 한다.

1) 변환 실행

• 텍스트 변환(예: 기록지/일지/보고서 문장 정리)
• 이미지 기반 템플릿 스키마 생성(양식 사진 → JSON 스키마)

2) 결과 검증

• 금지: 실행 코드 생성/해석 같은 위험한 출력
• 허용: 스키마(JSON)만 수용
• 출력 구조 검증: 필수 키, 섹션 구조, 길이 제한, 허용 타입 등

3) 포인트 관리(단일 기준) + 기록

• 무료 광고 포인트(ad_points)와 유료 포인트(paid_points)를 서버에서만 최종 관리
• 성공 후 차감(실패 시 차감 없음)
• 같은 요청이 여러 번 들어와도 중복으로 적립/차감되지 않도록 “기록”을 남기고 확인한다

4) 저장(최소)

• 업로드된 프리뷰 이미지를 서버에서 처리(업로드/검증)할 수 있다
• 단, 템플릿은 서버에 저장하지 않는다
  • 템플릿(스키마/정의)은 개별 앱 내부에 저장
  • 서버에는 템플릿을 모아두거나 재사용하는 저장소를 두지 않는다

---

3. 왜 서버가 필요한가

3.1 비용 문제: AI 호출은 “사용량 기반 비용”이다

AI 호출 비용은 사용량에 비례한다.
클라이언트(앱)에서 직접 호출하면:

• 키 관리가 어렵고(유출 위험)
• 비용 통제가 어렵고
• 호출 정책을 통일하기 어렵다

서버에서 호출하면:

• 비용 상한/토큰 제한 같은 정책을 강제할 수 있고
• 사용자별 사용량/포인트를 서버 단일 기준으로 통제할 수 있다

3.2 보안 문제: 앱에서 “실행 코드”를 받으면 위험하다

이미지 템플릿 생성 같은 기능에서,
모델이 실행 가능한 코드를 만들어 보내고 앱이 실행하면 위험/불안정이 커진다.

그래서 GFF는:

• “실행 코드 수용”을 기본 정책에서 제외하고
• 서버에서 스키마(JSON) 만 수용/검증한 뒤
• 앱은 렌더러로만 동작하게 만든다

3.3 운영 문제: 포인트는 서버 단일 기준이 아니면 무너진다

GFF는 사용량 기반 포인트 구조를 가진다.

• 광고로 얻는 무료 포인트
• 결제로 얻는 유료 포인트
• 변환/템플릿 생성 시 차감

여기서 가장 큰 위험은 “중복 처리”다.

• 네트워크 재시도
• 버튼 중복 클릭
• 서버 응답 지연으로 재전송

이런 상황에서 적립/차감이 두 번 반영되면 운영이 바로 무너진다.
그래서 서버는:

• 처리 요청마다 고유 번호(요청 ID, 광고 보상 번호, 결제 토큰 등)를 받고
• 이미 처리한 번호인지 확인한 다음
• 한 번만 반영하고 “기록(원장)”을 남긴다

---

4. GFF 서버가 해결하려는 문제(정리)

• [문제] 앱에서 AI 호출 → 키 유출/비용 통제 불가/정책 통일 불가

  • [해결] 서버에서만 호출 + 정책 강제

• [문제] 포인트가 기기 기준(로컬) → 조작/중복/분쟁

  • [해결] 포인트를 서버 단일 기준으로 관리 + 중복 처리 방지 기록 유지

• [문제] 이미지 템플릿 생성 결과의 안정성/보안

  • [해결] 실행 코드 금지 + 스키마(JSON)만 수용 + 서버 검증

• [문제] 장기 운영 인프라가 없으면 유지가 불가능

  • [해결] Cloud Run + Firestore + Storage 중심으로 단순하게 고정

---

5. 전체 구성(큰 그림)

5.1 서버 스택(현재 방향)

• API 서버: FastAPI (로컬에서 개발 후 Cloud Run 배포)
• DB: Firestore (포인트/기록 저장)
• 이미지 업로드: 서버가 업로드/검증을 담당(저장은 단계에 따라 local 또는 GCS)
• 인증: Google 로그인(idToken) → server verify → user_key=(iss, sub)

5.2 데이터 핵심(단일 기준)

• users/{user_key}
  • ad_points (0..10)
  • paid_points (0..N)
• ledger/{event_id}
  • type / delta / balance(AD|PAID) / status / createdAt
  • “중복 처리 방지”를 위한 고유 번호(광고 보상 번호/결제 토큰/요청 ID 등)

정책 고정: 템플릿(스키마/정의)은 서버 저장 대상이 아니다.
템플릿은 개별 앱 로컬 저장을 원칙으로 한다.

---

6. 마무리

이 글의 목적은 “GFF 서버가 왜 필요한지”를 먼저 설명하는 것이다.
다음 글부터는 실제로 서버 운영 기반(GCP 프로젝트, Billing, Firestore 등)을 하나씩 세팅하고, FastAPI 서버와 연결해 나갈 것이다.

---

(끝)