diff --git a/docs/superpowers/specs/2026-06-21-pdf-page-split-design.md b/docs/superpowers/specs/2026-06-21-pdf-page-split-design.md new file mode 100644 index 00000000..51bf4019 --- /dev/null +++ b/docs/superpowers/specs/2026-06-21-pdf-page-split-design.md @@ -0,0 +1,99 @@ +# PDF 도면 임포트 — 지정 페이지 분할 + 인라인 전송 설계 + +- 날짜: 2026-06-21 +- 브랜치: feature/pv-btob +- 상태: 승인됨 (구현 대기) +- 관련 파일: `src/app/api/gemini/floor-plan/route.js`, `src/components/floor-plan/modal/placementShape/PlacementShapeSetting.jsx` + +## 배경 / 문제 + +배치면 초기설정의 "읽기 페이지 설정"에서 평면도/입면도 페이지를 지정할 수 있으나, 현재 페이지 번호는 **프롬프트 텍스트 힌트로만** 쓰이고 PDF 는 **전체가 Gemini 에 전송**된다(`buildPrompt` 에만 사용, `file` 버퍼 전체를 `uploadFile`). 따라서: + +- Gemini 가 전 페이지를 비전 토큰화 → 입력 토큰·추론 시간·비용이 페이지 수에 비례(`mediaResolution: HIGH` 로 페이지당 토큰이 큼). +- 페이지 지정은 정확도엔 도움이 되나 속도엔 거의 효과가 없다. + +## 목표 + +지정한 페이지만 실제로 잘라서 전송하여 분석 속도·비용을 절감한다. 추가로 Files API 업로드 + 처리 폴링(최대 60초 대기) 단계를 인라인 전송으로 제거한다. + +## 범위 + +### In scope +- `specify` 모드에서 지정한 평면도 + 입면도 페이지만 `pdf-lib` 로 추출한 새 PDF 생성. +- 분할본을 `inlineData`(base64) 로 Gemini 에 전송 — Files API 업로드·폴링·`deleteFile` 제거. +- 페이지 번호 파싱(`"1,3-5"`, 1-based) 및 PDF 범위 검증. +- 분할 시 프롬프트를 "페이지 번호 힌트" → "평면도/입면도 순서 매핑"으로 전환. + +### Out of scope (후속 작업) +- **입면도를 지붕 형상 판별에 실제 활용** — 응답 스키마에 높이/지붕형태 필드 추가, 프롬프트 재설계, 결과를 캔버스 지붕형상에 연결하는 별도 작업. 이번엔 입면도 **페이지를 전송**하는 데까지만(토대 마련). +- 서버 에러 메시지 i18n (기존 잔여 과제, 기존 한국어 하드코딩 패턴 유지). +- 클라이언트 측 PDF 가공/미리보기. + +## 설계 + +### 데이터 흐름 + +클라이언트(`PlacementShapeSetting.jsx`) — **변경 없음**: 기존대로 `pageMode`/`floorPages`/`facadePages` 텍스트 + 원본 PDF 전체를 multipart 로 전송. + +서버(`route.js`): + +``` +formData 수신 (file, pageMode, floorPages, facadePages) + │ + ├─ pageMode === 'specify' AND (floorPages 또는 facadePages 비어있지 않음) + │ ├─ pdf-lib 로 원본 로드, getPageCount() + │ ├─ floorPages/facadePages 파싱 → 1-based → 0-based 인덱스 + │ ├─ PDF 범위로 검증, 유효 인덱스만 (평면도 먼저, 입면도 뒤, 그룹 내 오름차순·중복제거) + │ ├─ 유효 페이지 0개 → 422 INVALID_PAGE_RANGE + │ ├─ 분할 중 예외(손상 PDF 등) → 422 PDF_SPLIT_FAILED + │ └─ 유효 페이지 ≥1 → copyPages 로 새 PDF 생성 → splitBuffer + │ + └─ else (all 모드 또는 입력 둘 다 빈값) → 원본 buffer 사용 + +전송 PDF(splitBuffer 또는 원본) 크기 판정: + ├─ raw 크기 ≤ INLINE_MAX_BYTES → inlineData(base64) 경로 + └─ 초과 → Files API 경로 (기존: uploadFile → waitForFileActive → fileData) + +generateContent([ , { text: prompt } ]) +``` + +### 페이지 번호 파싱 +- 형식: 쉼표 구분 + 하이픈 범위. 예) `"1,3-5"` → `[1,3,4,5]`. **1-based**. +- 공백/빈 토큰/숫자 아닌 토큰은 무시. +- `floorPages`, `facadePages` 각각 파싱 → PDF 총 페이지 수로 필터 → 0-based 변환. +- 분할본 페이지 순서: `[...floorIdx, ...facadeIdx]`(평면도 먼저). 각 그룹 내 오름차순·중복 제거, 그룹 간 동일 페이지가 겹치면 평면도 우선. + +### 인라인 / Files API 분기 +- `INLINE_MAX_BYTES` 상수: 요청 총 20MB 한도 + base64 약 +33% 를 감안해 보수적으로 raw 기준 약 12MB. +- 분할본은 거의 항상 한도 이하 → 대부분 인라인. 초과(고해상도 스캔 등) 시 Files API 로 자동 fallback(기존 경로 재사용). +- 인라인 경로: `waitForFileActive`/`deleteFile` 불필요(임시 파일 없음). + +### 프롬프트 보정 +- `buildPrompt` 에 분할 컨텍스트 전달: `{ splitMode: true, floorCount, facadeCount }`. +- 분할 시: 페이지 번호 힌트 대신 순서 매핑 안내. 예) + > "첨부 PDF 는 평면도/지붕평면도 {floorCount}장과 입면도 {facadeCount}장으로 구성됩니다(평면도가 앞). 외곽선은 평면도/지붕평면도에서만 추출하고 입면도는 사용하지 마세요." + - `facadeCount === 0` 이면 입면도 문구 생략. +- 비분할(all/fallback) 경로는 기존 `buildPrompt` 동작 유지. + +### 에러 처리 (정책 A — 명시적 에러) +- 유효 페이지 0개(범위 밖 번호만 입력) → `422 { code: 'INVALID_PAGE_RANGE' }`. 클라이언트는 기존 `payload.error.message` 분기로 표시. +- 분할 단계 예외 → `422 { code: 'PDF_SPLIT_FAILED' }`. 조용한 전체 fallback 하지 않음(A 정책 일관). +- 입력 둘 다 빈값 + `specify` → `all` 처럼 전체 전송(자연스러운 기본값, 에러 아님). + +### 의존성 +- `pdf-lib` 추가(`yarn add pdf-lib`). 서버 라우트에서만 import. 순수 JS → `next.config.mjs` externals 수정 불필요. + +## 변경 파일 +- `src/app/api/gemini/floor-plan/route.js` — 분할·인라인·프롬프트 분기(핵심). +- `package.json` — `pdf-lib` 의존성. +- 클라이언트 변경 없음. + +## 검증 (테스트 러너 없음 → 수동) +- `NEXT_PUBLIC_ENABLE_LOGGING=true` 로 `timing`(fileReady/generate) 로그 확인 — 인라인 경로에서 fileReady 단계 소멸 확인. +- 시나리오: (a) 평면도 1p 지정 (b) 평면도+입면도 지정 (c) 범위 밖 페이지 → 422 (d) all 모드 회귀 (e) 대용량 → Files API fallback. +- `yarn lint`, `yarn build` 통과(eslint 미설치 시 build 가 lint 를 스킵하는 점 주의). + +## 위험 / 완화 +- 인라인 한도 초과 → Files API fallback 으로 흡수. +- 분할본 순서와 프롬프트 매핑 불일치 → 순서를 `[평면도, 입면도]` 로 고정하고 프롬프트도 동일 순서로 명시. +- 입면도가 외곽선 추출을 오염 → 프롬프트에서 "입면도 미사용" 명시(기존 `BASE_PROMPT` 에도 존재). diff --git a/package.json b/package.json index 0fc4da32..81c5c75b 100644 --- a/package.json +++ b/package.json @@ -37,6 +37,7 @@ "mssql": "^11.0.1", "next": "14.2.28", "next-international": "^1.2.4", + "pdf-lib": "^1.17.1", "react": "^18", "react-chartjs-2": "^5.2.0", "react-colorful": "^5.6.1", diff --git a/src/app/api/gemini/floor-plan/route.js b/src/app/api/gemini/floor-plan/route.js index c8e09ca4..877629c3 100644 --- a/src/app/api/gemini/floor-plan/route.js +++ b/src/app/api/gemini/floor-plan/route.js @@ -3,6 +3,7 @@ import { cookies } from 'next/headers' import { getIronSession } from 'iron-session' import { GoogleGenerativeAI, SchemaType } from '@google/generative-ai' import { GoogleAIFileManager, FileState } from '@google/generative-ai/server' +import { PDFDocument } from 'pdf-lib' import { sessionOptions } from '@/lib/session' import { logger } from '@/util/logger' @@ -10,6 +11,9 @@ import { logger } from '@/util/logger' const MAX_FILE_BYTES = 20 * 1024 * 1024 // 20MB const MAX_VERTICES = 500 const DEFAULT_MODEL = 'gemini-3.1-pro-preview' +// 인라인 전송 한도 — Gemini 요청 총 20MB 한도에서 base64(+~33%) 를 감안한 보수값. +// 초과 시 Files API 경로로 자동 fallback 한다. +const INLINE_MAX_BYTES = 12 * 1024 * 1024 // 12MB (raw) // Gemini 호출은 건당 과금이므로 사용자별 호출 빈도를 제한한다(프로세스 단위 in-memory). const RATE_LIMIT_WINDOW_MS = 60 * 1000 @@ -92,7 +96,15 @@ const BASE_PROMPT = `당신은 일본 주택 건축 도면에서 "지붕 투영 "selectedDrawingType": string (선택) }` -const buildPrompt = ({ pageMode, facadePages, floorPages } = {}) => { +const buildPrompt = ({ pageMode, facadePages, floorPages, splitInfo } = {}) => { + // 분할 전송: 잘린 PDF 는 페이지가 1,2,3… 으로 재번호되므로 원본 페이지 번호 힌트 대신 순서 매핑을 안내한다. + if (splitInfo) { + const segs = [] + if (splitInfo.floorCount > 0) segs.push(`평면도/지붕평면도 ${splitInfo.floorCount}장`) + if (splitInfo.facadeCount > 0) segs.push(`입면도 ${splitInfo.facadeCount}장`) + const compo = `첨부 PDF 는 ${segs.join('과 ')}으로 구성됩니다(평면도가 앞).` + return `${BASE_PROMPT}\n\n${compo} 외곽선은 평면도/지붕평면도 페이지에서만 추출하고, 입면도 페이지는 외곽선 추출에 쓰지 말고 높이·층수 참고로만 사용하세요.` + } if (pageMode === 'specify' && (facadePages || floorPages)) { const hints = [] if (floorPages) hints.push(`평면도(平面図)·지붕평면도(屋根伏図) 페이지: ${floorPages}`) @@ -133,6 +145,37 @@ const validateOuterline = (outerline) => { return { ok: true, empty: false } } +// "1,3-5" → [1,3,4,5] (1-based). 공백·빈 토큰·숫자 아닌 토큰은 무시한다. +const parsePageList = (str) => { + const out = [] + if (!str) return out + for (const token of String(str).split(',')) { + const t = token.trim() + if (!t) continue + const range = t.split('-') + if (range.length === 2) { + const a = parseInt(range[0], 10) + const b = parseInt(range[1], 10) + if (Number.isInteger(a) && Number.isInteger(b)) { + for (let i = Math.min(a, b); i <= Math.max(a, b); i++) out.push(i) + } + } else { + const n = parseInt(t, 10) + if (Number.isInteger(n)) out.push(n) + } + } + return out +} + +// 1-based 페이지 번호 배열을 PDF 범위 내 0-based 인덱스로. 범위 밖 제거, 오름차순·중복 제거. +const toValidIndices = (pages, total) => { + const set = new Set() + for (const p of pages) { + if (Number.isInteger(p) && p >= 1 && p <= total) set.add(p - 1) + } + return [...set].sort((a, b) => a - b) +} + const waitForFileActive = async (fileManager, fileName, { timeoutMs = 60000, intervalMs = 1500 } = {}) => { const started = Date.now() let file = await fileManager.getFile(fileName) @@ -195,15 +238,54 @@ export async function POST(req) { const buffer = Buffer.from(await file.arrayBuffer()) - const uploadStarted = Date.now() - const uploadResult = await fileManager.uploadFile(buffer, { - mimeType: 'application/pdf', - displayName: file.name || 'floor-plan.pdf', - }) - uploadedFileName = uploadResult.file.name + // 지정 페이지만 잘라낸다(specify + 페이지 입력 시). 입력이 둘 다 비어있으면 원본 전체를 그대로 보낸다. + let sendBuffer = buffer + let splitInfo = null + if (pageMode === 'specify' && (floorPages || facadePages)) { + let src + try { + src = await PDFDocument.load(buffer) + } catch (e) { + return NextResponse.json({ error: { code: 'PDF_SPLIT_FAILED', message: 'PDF 를 읽지 못했습니다.' } }, { status: 422 }) + } + const total = src.getPageCount() + const floorIdx = toValidIndices(parsePageList(floorPages), total) + const floorSet = new Set(floorIdx) + // 평면도가 앞, 입면도는 뒤. 그룹 간 동일 페이지가 겹치면 평면도 우선. + const facadeIdx = toValidIndices(parsePageList(facadePages), total).filter((i) => !floorSet.has(i)) + const order = [...floorIdx, ...facadeIdx] + if (order.length === 0) { + return NextResponse.json( + { error: { code: 'INVALID_PAGE_RANGE', message: '지정한 페이지 번호가 PDF 범위를 벗어났습니다. 페이지 번호를 확인해주세요.' } }, + { status: 422 }, + ) + } + try { + const out = await PDFDocument.create() + const copied = await out.copyPages(src, order) + copied.forEach((p) => out.addPage(p)) + sendBuffer = Buffer.from(await out.save()) + } catch (e) { + return NextResponse.json({ error: { code: 'PDF_SPLIT_FAILED', message: 'PDF 페이지 분할에 실패했습니다.' } }, { status: 422 }) + } + splitInfo = { floorCount: floorIdx.length, facadeCount: facadeIdx.length } + } - await waitForFileActive(fileManager, uploadedFileName) - const fileReadyMs = Date.now() - uploadStarted + // 분할본은 대부분 인라인 한도 이하 → 업로드·폴링 없이 즉시 전송. 초과 시에만 Files API 로 fallback. + const fileStarted = Date.now() + let pdfPart + if (sendBuffer.length <= INLINE_MAX_BYTES) { + pdfPart = { inlineData: { data: sendBuffer.toString('base64'), mimeType: 'application/pdf' } } + } else { + const uploadResult = await fileManager.uploadFile(sendBuffer, { + mimeType: 'application/pdf', + displayName: file.name || 'floor-plan.pdf', + }) + uploadedFileName = uploadResult.file.name + await waitForFileActive(fileManager, uploadedFileName) + pdfPart = { fileData: { fileUri: uploadResult.file.uri, mimeType: uploadResult.file.mimeType } } + } + const fileReadyMs = Date.now() - fileStarted const genAI = new GoogleGenerativeAI(apiKey) const model = genAI.getGenerativeModel({ @@ -217,18 +299,10 @@ export async function POST(req) { }, }) - const prompt = buildPrompt({ pageMode, facadePages, floorPages }) + const prompt = buildPrompt({ pageMode, facadePages, floorPages, splitInfo }) const generateStarted = Date.now() - const result = await model.generateContent([ - { - fileData: { - fileUri: uploadResult.file.uri, - mimeType: uploadResult.file.mimeType, - }, - }, - { text: prompt }, - ]) + const result = await model.generateContent([pdfPart, { text: prompt }]) const raw = result.response.text() logger.debug('[gemini/floor-plan] timing(ms)', { fileReady: fileReadyMs, generate: Date.now() - generateStarted })