{"openapi":"3.1.0","info":{"title":"복붙 API","version":"1.0.0","description":"복붙 시드 회원 데이터(이름·주소·휴대폰·이메일·직업) 및 배치 관리 API. PII는 기본 마스킹되며, unmask=true 사용 시 Bearer 토큰이 필수입니다."},"servers":[{"url":"/api/public/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"SEEDKIT_API_TOKEN 또는 로그인 사용자 JWT"},"apiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"EXTERNAL_API_KEY (외부 트리거·감시·내부 크론)"},"supabaseApiKey":{"type":"apiKey","in":"header","name":"apikey","description":"pg_cron 표준 호출용 백엔드 anon 키"}},"schemas":{"Member":{"type":"object","properties":{"id":{"type":"integer"},"batch_id":{"type":"string","nullable":true},"name":{"type":"string"},"address":{"type":"string"},"region_code":{"type":"string"},"region_name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"occupation":{"type":"string"},"gender":{"type":"string","enum":["M","F"]},"birth_year":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"Batch":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"label":{"type":"string"},"target_count":{"type":"integer"},"generated_count":{"type":"integer"},"status":{"type":"string","enum":["running","paused","done","cancelled"]},"started_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/stats/summary":{"get":{"summary":"전체 통계 요약 (anonymous OK)","responses":{"200":{"description":"OK"}}}},"/members":{"get":{"summary":"회원 목록 (Bearer 필수)","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":500}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"region","in":"query","schema":{"type":"string"},"description":"시도 코드 (예: 11)"},{"name":"gender","in":"query","schema":{"type":"string","enum":["M","F"]}},{"name":"occupation","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"이름 부분일치"},{"name":"unmask","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"}}}},"/members/{id}":{"get":{"summary":"회원 단건 조회 (Bearer 필수)","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"unmask","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Not Found"}}}},"/batches":{"get":{"summary":"배치 목록","responses":{"200":{"description":"OK"}}},"post":{"summary":"새 배치 생성 (Bearer 필수)","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["label","targetCount"],"properties":{"label":{"type":"string","maxLength":80},"targetCount":{"type":"integer","maximum":1000000}}}}}},"responses":{"201":{"description":"Created"}}}},"/batches/{id}":{"get":{"summary":"배치 단건 조회","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}},"delete":{"summary":"배치 + 회원 삭제 (Bearer 필수)","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/batches/{id}/generate":{"post":{"summary":"청크 단위 회원 생성 트리거 (Bearer 필수)","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/batches/{id}/stats":{"get":{"summary":"배치 생성 요약 통계 (성별/생애주기/티어/상위 지역·직업)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/occupations":{"get":{"summary":"직업 목록 (기본 is_legacy=false)","parameters":[{"name":"tier","in":"query","schema":{"type":"string","enum":["T1","T2","T3","T4","T5","T6"]}},{"name":"employment_type","in":"query","schema":{"type":"string"}},{"name":"include_legacy","in":"query","schema":{"type":"boolean"}},{"name":"limit","in":"query","schema":{"type":"integer","default":200,"maximum":1000}}],"responses":{"200":{"description":"OK"}}}},"/occupations/{id}":{"get":{"summary":"직업 단건","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Not Found"}}}},"/occupations/tier/{tier}":{"get":{"summary":"티어별 직업 목록 (T1~T6)","parameters":[{"name":"tier","in":"path","required":true,"schema":{"type":"string","enum":["T1","T2","T3","T4","T5","T6"]}}],"responses":{"200":{"description":"OK"}}}},"/generate":{"post":{"summary":"필터 조건으로 페르소나 배치 즉시 생성 (Bearer 필수, count ≤ 10000)","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["count"],"properties":{"count":{"type":"integer","maximum":10000},"label":{"type":"string"},"filters":{"type":"object","properties":{"life_stage":{"type":"string","enum":["student","military_service","employed","unemployed","retired"]},"region":{"type":"string","description":"시도 코드 (예: 11, 41, 47)"},"income_tier":{"type":"string","enum":["T1","T2","T3","T4","T5","T6"]},"occupation_id":{"type":"integer"}}}}}}}},"responses":{"201":{"description":"Created"}}}},"/simulation-report/{id}":{"get":{"summary":"시뮬레이션 리포트 HTML (PDF 인쇄용). 접근: ?t= 리포트 토큰 / 소유자 Bearer / 공개 쇼케이스","security":[{"bearerAuth":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"t","in":"query","schema":{"type":"string"},"description":"HMAC 리포트 토큰"},{"name":"unlocked","in":"query","schema":{"type":"string","enum":["0","1"]}}],"responses":{"200":{"description":"text/html"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/showcase-report/{id}":{"get":{"summary":"공개 쇼케이스 리포트 HTML. 접근: 공개 쇼케이스 또는 ?t= 리포트 토큰","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"t","in":"query","schema":{"type":"string"},"description":"HMAC 리포트 토큰"}],"responses":{"200":{"description":"text/html"},"403":{"description":"Forbidden"}}}},"/competitor-report/{id}":{"get":{"summary":"경쟁사 비교 리포트 HTML. 접근: ?t= 리포트 토큰 / 소유자 Bearer / 공개 쇼케이스","security":[{"bearerAuth":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"t","in":"query","schema":{"type":"string"}},{"name":"print","in":"query","schema":{"type":"string","enum":["0","1"]},"description":"0 이면 자동 인쇄 비활성"}],"responses":{"200":{"description":"text/html"},"403":{"description":"Forbidden"}}}},"/complete-package/{id}":{"get":{"summary":"패키지 전체(리포트·후기·FGI) 통합 HTML. 접근: 공개 쇼케이스 / ?t= 토큰 / 소유자 Bearer","security":[{"bearerAuth":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"t","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"text/html"},"403":{"description":"Forbidden"}}}},"/external-simulate-trigger":{"post":{"summary":"외부 서비스에서 상품 등록 시 시장조사 파이프라인 트리거 (즉시 report_id 반환, 완료 시 callback_url 로 POST)","security":[{"apiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product_name","image_url","external_source","external_ref_id"],"properties":{"product_name":{"type":"string","maxLength":200},"category":{"type":"string","maxLength":80},"price":{"type":"integer","minimum":0},"image_url":{"type":"string","format":"uri"},"description":{"type":"string","maxLength":2000},"external_source":{"type":"string","maxLength":80},"external_ref_id":{"type":"string","maxLength":120},"callback_url":{"type":"string","format":"uri"},"panel_size":{"type":"integer","minimum":20,"maximum":500}}}}}},"responses":{"200":{"description":"{ report_id, status: processing }"},"401":{"description":"Unauthorized"}}}},"/admin-health":{"get":{"summary":"운영 감시용 헬스 체크 (적체 파이프라인 탐지)","security":[{"apiKeyAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"}}}},"/cron-cleanup-stuck":{"post":{"summary":"[내부] 멈춘 파이프라인 정리 크론. 인증: X-API-KEY 또는 apikey 헤더","x-internal":true,"security":[{"apiKeyAuth":[]},{"supabaseApiKey":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"}}}},"/admin-cleanup-stuck":{"post":{"summary":"[내부] 관리자 수동 적체 정리","x-internal":true,"security":[{"apiKeyAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"}}}},"/retry-rejected-personas":{"post":{"summary":"[내부] 품질 게이트 rejected 페르소나 재생성. 인증: X-API-KEY 또는 apikey 헤더","x-internal":true,"security":[{"apiKeyAuth":[]},{"supabaseApiKey":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"}}}},"/simulation-demo":{"post":{"summary":"[내부] 관리자 전용 데모 시뮬레이션 실행 (로그인 + admin 역할 필수)","x-internal":true,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"403":{"description":"Forbidden"}}}},"/openapi":{"get":{"summary":"이 OpenAPI 3.1 스펙 (anonymous OK)","responses":{"200":{"description":"OK"}}}},"/docs":{"get":{"summary":"사람이 읽는 HTML 문서 (anonymous OK)","responses":{"200":{"description":"text/html"}}}},"/webhooks/n8n/generate":{"post":{"summary":"n8n HTTP Request 노드 전용 — 생성 완료 시 callback URL로 결과 POST","tags":["n8n"],"servers":[{"url":"/api/public"}],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["count"],"properties":{"count":{"type":"integer","maximum":10000},"label":{"type":"string"},"filters":{"type":"object"},"webhook_callback_url":{"type":"string","format":"uri"},"callback_headers":{"type":"object","additionalProperties":{"type":"string"}}}}}}},"responses":{"200":{"description":"OK"}}}}}}