1/25 API 계약 최종 고정,JSON 깨짐 방어 로직

1. 담당 역할 개요 (B 담당)

본 프로젝트에서 B 담당은 FastAPI 기반 서버를 구축하고,

STT 결과 텍스트를 입력받아 환자 친화적 요약 JSON으로 변환하는 /summarize API를 구현하였다.

특히 프론트엔드와의 안정적인 연동을 위해 API 계약 고정 및 JSON 안정성 확보를 핵심 목표로 두었다.

---

2. API 설계 및 구현

(1) API 계약 고정

shared/schema.md를 단일 기준으로 삼아, 요청·응답 구조를 변경하지 않고 구현하였다.

요청

POST /summarize
{
"raw_text":"string"
}

응답

{
"summary_3sent":"string",
"easy_terms":[
{"term":"string","easy":"string"}
],
"next_actions":[
{"title":"string","detail":"string"}
],
"warnings":["string"]
}

FastAPI의 Pydantic 모델을 활용하여 필드 누락이나 타입 오류가 발생하지 않도록 강제하였다.

---

(2) 요약 로직 및 방어 설계

• 요약 결과는 항상 3문장이 되도록 보정 로직을 적용하였다.
• 어떤 입력이 들어와도 응답 JSON 구조가 깨지지 않도록 설계하였다.
• 실제 LLM 연동 이전 단계로, 현재는 더미 요약 결과를 사용하되
• 구조와 흐름은 그대로 유지되도록 구현하였다.

---

(3) 서버 안정성 확보

• /health 엔드포인트를 통해 서버 상태를 즉시 확인할 수 있도록 구성하였다.
• Swagger UI(/docs)를 통해 프론트엔드 및 팀원들이 직접 API 테스트 가능하도록 하였다.
• curl / Swagger 테스트 결과, 여러 차례 호출에서도 모두 200 OK 응답을 반환함을 확인하였다.

---

3. 테스트 결과

• Swagger UI 및 curl을 이용해 다양한 의료 텍스트 입력 테스트 수행
• 모든 테스트에서 JSON 구조가 유지됨
• 프론트엔드에서 바로 사용 가능한 형태의 응답 확인

---

4. 한계점 및 향후 개선 방향

• 현재 의료 용어 설명(easy_terms)은 더미 데이터 수준으로 제한적임
• 의료 용어 사전 API 연동 또는 LLM 기반 동적 설명 생성이 필요함
• 추후 프롬프트 설계를 통해 의료 표현의 정확성과 범용성을 개선할 예정

---

5. 결론

본 단계에서는 서버의 구조적 안정성과 계약 준수를 최우선으로 구현을 완료하였다.

의료 내용의 품질 개선은 다음 단계에서 확장 가능하도록 설계되어 있으며,

현재 상태로 프론트엔드 연동 및 데모 시연이 가능한 수준임을 확인하였다.