3/12 응 결국 수정

MedExplain 서버 개발 진행 보고서

1. 작업 개요
이번 작업에서는 MedExplain 프로젝트의 서버(B) 파트에서 모바일(A)와 연결 가능한 1차 API 뼈대를 구축하였다.  
기존에는 STT 연결 및 WebSocket 기반 텍스트 수신 구조가 중심이었다면, 이번 작업에서는 STT 이후 결과를 사용자가 실제로 활용할 수 있는 형태로 가공하고 저장하는 기능을 우선 구현하는 방향으로 범위를 확장하였다.

2. 변경 배경 및 이유
초기 구상에서는 음성 입력 이후 STT 결과를 얻는 것 자체에 초점이 맞춰져 있었다.  
하지만 프로젝트 방향이 점차 “환자/보호자가 진료 내용을 이해하고 다시 확인할 수 있도록 돕는 앱” 쪽으로 구체화되면서, 단순 전사 결과만으로는 사용자 가치가 부족하다는 문제가 있었다.

또한 교수님 피드백 및 팀 논의 과정에서 다음과 같은 점이 중요해졌다.

- 단순 음성 인식 기능만으로는 프로젝트 차별성이 약함
- 사용자가 실제로 필요로 하는 것은 긴 진료 내용을 이해 가능한 형태로 정리해주는 기능임
- 모바일 화면 구현을 위해서는 서버가 정리된 데이터 구조를 먼저 제공해야 함
- STT 고도화보다 요약, 용어 설명, 기록 저장 같은 후속 처리 구조를 먼저 만드는 것이 전체 구현 흐름상 더 효율적임

이러한 이유로 이번 단계에서는 STT 이후 파이프라인 중에서도 모바일과 직접 연결되는 기능을 우선 구현하였다.

3. 이번 작업 목표
이번 작업의 목표는 다음과 같았다.

- summary API 구현
- explain API 구현
- records 저장 및 조회 API 구현
- A가 Flutter에서 바로 붙일 수 있는 요청/응답 구조 확정
- Swagger에서 각 기능 정상 동작 확인

4. 구현 내용

4-1. 데이터 구조 통일
A와 B가 동일한 형식으로 데이터를 주고받을 수 있도록 API 응답 구조를 먼저 확정하였다.

- summary 응답: 배열(list)
- terms 응답: {term, description} 객체 배열
- records 저장 필드: record_id, date, department, clean_text, summary, terms
- records 목록 조회: summary_preview 포함
- records 상세 조회: clean_text, summary, terms 전체 포함

이 과정을 통해 모바일과 서버가 같은 기준으로 개발될 수 있도록 하였다.

4-2. 스키마 파일 작성
app/models/schemas.py를 생성하여 요청 및 응답 형식을 Pydantic 모델로 정의하였다.

구현한 모델
- TextRequest
- TermItem
- SummaryResponse
- ExplainResponse
- RecordCreateRequest
- RecordListItem
- RecordListResponse
- RecordDetailResponse

이를 통해 서버 응답 형식을 일관되게 유지할 수 있도록 하였다.

4-3. summary 기능 구현
app/services/summarizer.py를 생성하여 입력 텍스트를 문장 단위로 분리하고 최대 3문장까지 배열로 반환하는 1차 더미 요약 기능을 구현하였다.

app/routes/summary.py를 생성하여 POST /summary 엔드포인트를 연결하였다.

Swagger 테스트 결과
- 요청 성공
- summary 배열 형식으로 응답 확인 완료

4-4. explain 기능 구현
app/services/term_extractor.py를 생성하여 내부 dictionary 기반 의료 용어 추출 기능을 구현하였다.

현재는
- CRP
- 내시경
- 염증
- 검사
등 일부 용어를 예시로 등록해두고, 입력 텍스트에 포함된 용어를 탐지하여 설명과 함께 반환하도록 하였다.

app/routes/explain.py를 생성하여 POST /explain 엔드포인트를 연결하였다.

Swagger 테스트 결과
- 요청 성공
- terms 배열 형식으로 응답 확인 완료

4-5. records 기능 구현
app/data/records.json 파일을 생성하여 로컬 JSON 기반 저장소를 마련하였다.  
app/routes/records.py를 생성하여 다음 기능을 구현하였다.

- POST /records : 기록 저장
- GET /records : 기록 목록 조회
- GET /records/{record_id} : 기록 상세 조회

Swagger 테스트 결과
- 기록 저장 성공
- 목록 조회 성공
- 상세 조회 성공

5. 테스트 결과
Swagger를 이용해 직접 엔드포인트를 테스트한 결과, 아래 기능이 모두 정상 동작함을 확인하였다.

- POST /summary
- POST /explain
- POST /records
- GET /records
- GET /records/{record_id}

6. 현재 단계의 의미
이번 작업으로 서버는 단순 STT 처리 수준을 넘어서, 모바일 앱이 바로 활용할 수 있는 구조화된 데이터 제공이 가능해졌다.  
특히 A 파트에서는 현재 구현된 API를 바탕으로 다음 기능을 바로 연결할 수 있다.

- 진료 요약 화면 표시
- 의료 용어 설명 UI 표시
- 기록 저장 기능
- 기록 목록 화면
- 기록 상세 화면

7. 한계점
이번 단계는 1차 뼈대 구현이므로 다음과 같은 한계가 있다.

- summary는 실제 AI 요약 모델이 아닌 단순 분리 기반 더미 로직임
- explain은 외부 의료 용어 API가 아닌 내부 dictionary 기반임
- records는 DB가 아닌 JSON 파일 로컬 저장 방식임
- STT 결과와 summary/explain/records가 자동 연동된 상태는 아님

8. 향후 계획
다음 단계에서는 아래 항목들을 순차적으로 개선할 예정이다.

- STT 결과 후처리용 text_cleaner 추가
- summary를 실제 요약 모델 또는 LLM과 연결
- explain 기능을 의료 용어 API 또는 확장 사전과 연결
- records 저장 구조를 DB 기반으로 전환
- STT 결과가 생성되면 summary/explain/records로 자연스럽게 이어지는 서버 흐름 구성
- Flutter(A)와의 실제 연결 및 UI 테스트 진행

9. 결론
이번 작업에서는 MedExplain 서버 파트에서 모바일과 연동 가능한 핵심 API 뼈대를 우선 구현하였다.  
이를 통해 프로젝트의 방향을 단순 음성 인식 중심에서, 환자/보호자가 진료 내용을 이해하고 다시 확인할 수 있도록 돕는 구조로 구체화하였다.  
현재는 더미 및 로컬 저장 기반이지만, 전체 시스템 연결의 출발점이 되는 핵심 구조는 확보한 상태이며, 이후에는 이를 실제 모델 및 저장 구조와 연결하여 기능을 고도화할 예정이다.