docs(S15P11A705-54): API 명세에 공통 응답 봉투 형식 반영

[minyongP]

요약

모든 응답을 공통 봉투로 감싸는 계약으로 명세를 개정합니다. 성공은 {success:true, data}, 오류는 {success:false, error}이며 클라이언트는 success 하나로 분기합니다.

⚠️ 프론트엔드 영향 (Breaking)

응답 파싱이 전부 바뀝니다. 기존 res.items → res.data.items, 기존 res.code → res.error.code. FE와 동시 배포가 필요합니다.

변경 내용

• §1.6 공통 응답 형식 신설 — 봉투 정의, null 필드 생략(성공에 error 키·오류에 data 키 없음), 204는 본문 없음, success가 HTTP 상태 코드를 대체하지 않음
• §1.3·§1.4 예시를 data 안으로. 커서 규칙(Base64(정렬키+id), size 기본 20)은 불변
• §1.5 오류 형식 → {success:false, error:{code, message, fieldErrors, traceId}}
  • traceId 추가 — 기존 명세엔 없었으나 백엔드가 이미 반환하며(운영 로그 상관관계), 문의·장애 대응 시 이 값으로 로그를 추적합니다. 클라이언트는 해석하지 않고 노출·전달만 합니다.
  • DELETE_CONFIRMATION_REQUIRED의 impact를 error.impact 로 이동(§5.6·§5.7)
• §3~§10 응답 예시 전부 봉투 적용. 요청 body 예시는 변경하지 않음
• §11.0 ApiResponse<T>·ApiError 타입 추가 — success로 좁히면 data/error가 타입 수준에서 배타적으로 갈립니다

섹션 번호를 재배치하지 않은 이유

봉투는 논리적으로 §1.3 자리가 자연스럽지만, 다른 파트 문서가 §1.4·§1.5를 인용하고 있어 재번호는 기존 참조를 깨뜨립니다. 그래서 §1.6으로 덧붙이고, 문서 상단 개요와 §1.4에 §1.6으로의 참조를 넣었습니다.

검증

• JSON 블록 38개 = 원래 37개 + §1.6 신설 1개
• 봉투가 없는 블록 14개는 전부 요청 body임을 기계적으로 확인(응답 누락 0)
• 산문 속 인라인 응답 예시(§3.4) 1건도 갱신
• static/의 다른 문서에는 JSON 응답 예시가 없어 정합성 영향 없음

범위 밖

• 05_AI_설계.md(AI 파트 소유)는 수정하지 않았습니다. 봉투 영향이 있으면 AI 파트가 자체 갱신해야 합니다.
• 백엔드 구현(ApiResponse + ResponseBodyAdvice + 전역 핸들러 수정)과 결정 기록(ADR)은 S15P11A705-53에서 진행합니다.
• ⚠️ 백엔드의 현재 ErrorResponse는 닫힌 record라 error.impact를 담을 수 없습니다 — 확장점 도입이 -53의 선결 과제입니다.

[colosair]

AI 파트 관점에서 확인했습니다. 승인합니다.

05_AI_설계.md는 갱신 불필요하다고 판단했습니다. 봉투 적용 대상이 Client API(/api/core/v1)인 반면, AI 파트 계약은 내부 전용(/internal/v1, Spring ↔ FastAPI)이라 다른 계약입니다.

내부 API에 봉투를 적용하지 않는 근거:

봉투의 목적이 클라이언트 편의("success 하나로 분기")
  → Spring은 HTTP 상태 코드·예외로 이미 분기하므로 이득이 없음
/context/process는 202 + 본문 없음
  → 봉투를 씌우면 {success:true, data:null} 형태가 되어 무의미
파싱 계층 추가
  → FastAPI가 감싸고 Spring이 벗기는 왕복. 순 이득 0

계약의 소비자가 다르면 형식이 달라도 무방하고, 오히려 내부/외부 경계가 형식으로 드러나는 이점이 있다고 봅니다.

AI 파트 데이터는 Spring이 조립하는 시점에 봉투 안으로 들어갑니다. /search 결과(recordId·contextId·similarity)를 Spring이 matchedContext로 조립해 반환하므로, FastAPI 응답이 클라이언트에 직접 노출되는 경로가 없습니다. ResponseBodyAdvice로 자동 처리되면 AI 파트 쪽 조치는 0건입니다.

§1.6을 신설해 기존 참조를 보존한 판단에도 동의합니다. static/05와 back/docs/ai/spec이 §1.4·§1.5를 인용하고 있어, 재번호했다면 AI 파트 문서도 함께 고쳐야 했습니다. 논리적 위치보다 참조 안정성을 택한 게 맞습니다.

traceId 추가는 유용해 보입니다. AI 파트도 향후 Spring↔FastAPI 상관추적이 필요해지면 같은 값을 전파하는 방향을 검토할 수 있겠습니다(현재는 미결·후순위).