[gpffh20]

Summary

근거 기반 임상 인사이트맵 기능의 백엔드 부분을 구현했다. 온톨로지 개념/관계 그래프, 환자 지표 추이, SOAP Case Index를 저장하는 데이터 모델과 이를 조회/검색하는 Graph API를 추가한다.

Changes

• ontology_concepts, ontology_edges, soap_case_indexes, patient_metric_trends 4개 테이블 및 alembic 마이그레이션 추가
• scripts/seed_ontology.py + scripts/ontology_seed.yaml: 기존 RAG 온톨로지(UtterAI_AI/app/rag/ontology.yaml)를 기반으로 concept 38개, 관계(edge) 55개 시드 (idempotent upsert)
• Graph API 3종: GET /api/v1/insight-map, POST /api/v1/insight-map/search, GET /api/v1/soap-case-indexes/{id}/source-link
• app/core/authorization.py: report/session/patient_ref/case_index 소유권 검증 공용 헬퍼 (기존 서비스마다 중복돼 있던 로직을 재사용 가능하게 추출)
• Report가 FINALIZED로 전환될 때 soap_case_indexes를 자동 생성 (app/services/case_index_builder.py) — SOAP 원문은 저장하지 않고 concept 태깅 + 라벨 조합 요약만 저장

Why

03. 온톨로지맵 별도 창 설계서에 따라, 리포트 수정 챗봇에서 링크만 걸려 있던 인사이트맵(create_ontology_map_link 툴)의 실제 백엔드 구현체가 필요했다. AgentCore/Strands agent가 아니라 그래프 데이터 모델 + API가 메인 구현체여야 한다는 설계 원칙에 따라 이 레포에 핵심 로직을 둔다.

Impact

• API: 신규 엔드포인트 3개 추가 (기존 엔드포인트 변경 없음)
• DB: 신규 테이블 4개 추가 (기존 테이블 스키마 변경 없음)
• Permissions: soap_case_indexes 조회는 항상 therapist_id == current_user.id로 강제 필터링 (본인 SOAP 기록만 노출, IDOR 방지)
• Operations: python scripts/seed_ontology.py를 배포 후 1회 실행해야 온톨로지 데이터가 채워짐

Test

• 로컬 테스트 수행 (pytest tests/unit 126개 전부 통과)
• 수동 검증 수행 (로컬 DB에 마이그레이션 적용 + seed 실행 + FE 연동 확인)

Checklist

• base branch가 main이다 (레포의 실질 통합 브랜치, dev는 방치 상태)
• 관련 이슈를 연결했다
• 민감 정보가 포함되지 않았다
• 상태 전이/권한/멱등성 규칙을 확인했다 (case index upsert는 report_id 기준 idempotent)
• 문서가 필요하면 함께 수정했다

References

• 03. 인사이트용 온톨로지맵: 별도 창 구현 설계서
• UtterAI_AI/docs/ADR-003-insight-map-agent-runtime.md