공시한입 Docs

Appearance

API 명세 ​

목적 ​

Vibe coding 컨텍스트에서 비즈니스 흐름이 흐릿해지는 걸 방지. AI 가 한 endpoint markdown 만 읽고 정확히 이해 + 변경 적용 가능하도록 자연어 + 실 예제 중심.

OpenAPI / Swagger 거부 이유:

  • AI 친화 X (YAML 보다 markdown + JSON 예제가 훨씬 잘 적용됨)
  • Swagger UI 외부 노출 risk
  • 1 인 + vibe coding 워크플로우에 안 맞음

핵심 원칙: curl 예제는 복붙 즉시 실행 가능해야 ​

  • 인증 endpoint 는 TOKEN env var 가 미리 export 되어 있다고 가정 — 매 예제마다 TOKEN=$(...) 반복 X
  • 응답 보기 좋게 | jq 파이프
  • 외부 인증 필요하면 source ~/.config/cloud-tokens/X.env 명시
  • 채워야 하는 placeholder 는 최소화 — 예: {rceptNo} 는 실 값 (20260413800802) 로 박음

세션 시작 시 1회 ​

bash
# 카카오/구글 로그인 후 받은 JWT 를 export (앱 디버그 로그에서 복사)
export TOKEN="eyJhbGciOiJIUzI1NiIs..."

이후 모든 인증 예제 -H "Authorization: Bearer $TOKEN" 만으로 동작.

작성 시점 (강제 X) ​

  • 새 endpoint 추가 → 같은 PR 에 docs 추가
  • endpoint 시그니처 / 응답 변경 → 같이 update
  • 머릿속 정리 안 될 때 — 코드 짜기 전 docs 먼저 작성하면 명확해짐

파일 명명 ​

<scope>-<endpoint>.md flat 구조.

  • ai-analyze-get.md
  • ai-analyze-reveal.md
  • auth-kakao.md
  • quota-status.md
  • disclosures-recent.md

폴더 분리 X — 검색 / grep 용이성 우선.

템플릿 ​

markdown
# GET /api/v1/ai/analyze/{rceptNo}

## 의도
한 줄 요약. 이 endpoint 가 해결하는 사용자 / 시스템 문제.

## 인증
- Bearer JWT 필수 / 선택 / 없음
- 권한 체크 (admin 등)

## 입력
- Path: `rceptNo` (14 자리 숫자)
- Query: `limit` (optional, default 10, max 50)
- Body: (POST 일 때)

## 응답

### 200 OK — 정상 케이스
\`\`\`json
{ ... 실제 응답 페이로드 ... }
\`\`\`

### 200 OK — 다른 분기 (있으면)
\`\`\`json
{ ... 다른 페이로드 ... }
\`\`\`

### 202 / 401 / 409 / 429 / 500 — 에러 분기
각 상태 코드별 응답 JSON

## curl 예제 (복붙 즉시 실행)

전제: `$TOKEN` env var 에 JWT 가 export 되어 있음.

\`\`\`bash
# 로컬 dev
curl -s -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/ai/analyze/20260413800802 | jq

# prod
curl -s -H "Authorization: Bearer $TOKEN" \
  https://api.dartbrief.com/api/v1/ai/analyze/20260413800802 | jq
\`\`\`

## 비즈니스 메모
- 임계값 / 정량 룰 (예: SHORT_DOC_THRESHOLD)
- 다른 endpoint / 테이블 의존성
- 에러 분기 의도 (예: pgx.ErrNoRows vs DB 인프라 에러)
- 캐싱 / rate limit 정책
- 향후 변경 예정 사항 (deprecation / migration)

인덱스 ​

  • auth-kakao.md — POST /api/v1/auth/kakao/token, GET /api/v1/auth/me, DELETE /api/v1/auth/withdraw
  • auth-google.md — POST /api/v1/auth/google/token
  • auth-apple.md — POST /api/v1/auth/apple/token
  • disclosures.md — GET /api/v1/disclosures/recent, GET /api/v1/disclosures/{rceptNo}, GET /api/v1/disclosures, GET /api/v1/companies/{corpCode}
  • ai-analyze-get.md — GET /api/v1/ai/analyze/{rceptNo} 분석 메타 조회
  • ai-analyze-reveal.md — POST /api/v1/ai/analyze/{rceptNo}/reveal ⚠️ App Check 필수
  • quota.md — GET /api/v1/quota, POST /api/v1/quota/ad-reward (dev only)
  • watchlist.md — watchlist CRUD + capacity + notify
  • admob-ssv.md — GET /api/v1/admob/ssv AdMob SSV 콜백 (Google → 서버 직접 호출)
  • admin.md — Admin API (X-Admin-Key 인증, App Check 제외)
  • notification-push.md — POST/DELETE /api/v1/push/fcm-token FCM 토큰 등록/해제

관련 문서 ​