[FEAT] Ouch Guide, Visit Guide, 자가진단 알고리즘 API 구현 및 구조화 조회 기능 추가 (#58)

[99hyuk]

📌 관련 이슈

• closed: [FEAT] QnA, 진료 가이드, 자가 진단 알고리즘 API 구현 #58

✨ PR 세부 내용

📌 작업 개요
Ouch Guide / Visit Guide / 자가진단 알고리즘 API 전반에 대해 다음과 같은 개선 및 기능 추가 작업을 진행하였습니다.

✅ 공통 개선 사항

1. Swagger 문서화 정비

• 모든 Controller에 @tag, @operation, @parameter, @ExampleObject 등 Swagger 어노테이션 상세 적용
• Swagger UI에서 요청 파라미터 및 응답 구조를 예시 기반으로 명확하게 확인 가능하도록 개선
• 요청 DTO에는 @Schema(example=...) 사용하여 Swagger 요청 예시 추가

2. languageCode 다국어 파라미터 예외 처리 강화

• 지원되지 않는 언어코드(ko, en 외)가 전달될 경우 LANGUAGE_NOT_SUPPORTED 예외 발생
• 모든 API에서 언어 파라미터 유효성 일관되게 검증

3. 공통 예외 코드 확장 및 통일

• CommonErrorCode에 다음 항목 추가:

1. LANGUAGE_NOT_SUPPORTED
2. SYSTEM_SYMPTOM_NOT_FOUND
3. CONDITION_NOT_AVAILABLE

• OuchException으로 통합되어 JSON 형태 에러 응답 (code + message) 반환
• 상태코드는 400/404 등 명확한 실패 상태로 반환 (이전 204 문제 해결)

📂 Ouch Guide API 개선 사항 (/guide/ouch)

기능 추가

• 전체 가이드 문항 조회: GET /guide/ouch
• 카테고리별 문항 조회: POST /guide/ouch/category → GET /guide/ouch/filter?category=...&languageCode=... 방식으로 수정
• 카테고리 목록 조회: GET /guide/ouch/categories?languageCode=...

기타 개선

• Swagger 예시 값 적용 (category, languageCode)
• DTO (OuchGuideCategoryRequest)에 @Schema 추가
• 응답 언어 일관성 유지 (ko, en 기준)

📂 Visit Guide API (/guide)

기능 추가

• 전체 병원 방문 단계별 안내 단계 조회: GET /guide
• 특정 스텝만 조회: GET /guide/{step}

기타 개선

• VisitGuide DTO 구성 단순화 (LocalizedText 구조 유지)
• 스텝별 필드 (purpose, whatToExpect, keyPhrases, actionGuide, tips) 정리

📂 자가진단 알고리즘 API (/diagnosis-algorithm)

기능 추가

• 전체 알고리즘 목록 조회: GET /diagnosis-algorithm
• 진료과 추천: POST /diagnosis-algorithm (system + symptom + optional condition)
• 1차 system 리스트 조회: GET /diagnosis-algorithm/systems?languageCode=...
• 2차 symptom 리스트 조회: GET /diagnosis-algorithm/symptoms?system=...&languageCode=...
• 3차 condition 리스트 조회: GET /diagnosis-algorithm/conditions?system=...&symptom=...&languageCode=...

예외 처리

• 존재하지 않는 system+symptom 조합 요청 시: SYSTEM_SYMPTOM_NOT_FOUND (404)
• condition이 없는 two-step 항목 요청 시: CONDITION_NOT_AVAILABLE (404)
• 지원되지 않는 언어 요청 시: LANGUAGE_NOT_SUPPORTED (400)

💡 테스트 및 확인 사항

• Swagger UI에서 모든 API 정상 표시 및 예시 값 반영 확인
• 예외 발생 시 {"code": "...", "message": "..."} 형태로 반환되는지 확인 완료

🙋‍♀️ 예정 사항

• languageCode를 향후 다국어 확장(zh, vi 등) 시 Map<String, String> 구조로 리팩토링할 예정입니다.

💬 리뷰 요청 사항