Frontend

Next.js App Router 화면과 same-origin API BFF를 소유합니다. Backend 주소는 src/lib/server/procedureApiConfig.ts에서 읽고, 브라우저는 /api/...로 요청합니다.

실행

저장소 루트에서 다음을 실행합니다.

cd frontend
npm ci
npm run manual:build
npm run dev

로컬 설정은 frontend/.env.local에 둡니다. PROCEDURE_API_BASE는 경로 없이 Backend origin만 지정합니다(예: http://127.0.0.1:8005). 모든 실행 환경에서 필수이며, 생략하면 설정 오류를 반환합니다. /procedure-hub/api/v1 경로는 프록시가 붙입니다.

폴더 역할

사이드바 하단의 사용 가이드는 같은 사이트의 /manual/index.html을 새 탭으로 엽니다. npm run manual:build는 저장소의 문서를 public/manual/로 생성합니다. 문서 수정 후 다시 실행하며, npm run build에는 자동 포함됩니다. 문서 빌드에는 uv 또는 Python 3.10 이상(venv·pip 포함)이 필요합니다. 산출물은 Git에서 제외하고 앱과 함께 배포합니다.

위치	책임
src/app/	경로·화면 전용 상태와 컴포넌트·API BFF
src/features/	실제 필요한 도메인 API 계약·모델
src/components/	여러 화면에서 사용하는 UI·앱 셸
src/lib/	서버 연결·기술 유틸·기존 공통 계산
tests/	제품 로직·API 계약 단위 테스트와 fixture

검증

frontend/에서 실행합니다.

npm run lint
npm run typecheck
npm run test:products
npm run build

typecheck는 next typegen 후 TypeScript를 검사하므로 기존 .next 캐시가 없어도 실행할 수 있습니다. 제품 단위 테스트는 정규화·API 계약·실패·비교 제한·URL 인코딩을 검증합니다.

구조 결정과 검증 범위는 ADR 0005를 따릅니다. Vercel의 Root Directory는 frontend여야 합니다. 서비스 설정 변경은 배포 가이드를 참조합니다.

남은 검토

용어집 변경 시 격리 데이터로 업로드 preview·apply·재조회·버전 복원을 확인합니다. 실제 보조기기의 focus 복귀와 파일 업로드 최종 사용자 acceptance는 완료로 간주하지 않습니다.

• GlossaryMatrix는 HTTP 200의 잘못된 JSON을 빈 사전으로, 조합 플래너는 응답의 rules 누락을 빈 금기 규칙으로 처리합니다. 계약 오류와 정상 빈 결과를 구분해야 합니다.
• 시너지·시술 비교·조합 플래너는 URL 파라미터로 초기 선택을 읽지만 이후 선택을 URL에 반영하지 않습니다. 공유·새로고침 복원 상태인지 일회성 유입값인지 정한 뒤 동기화 범위를 맞춰야 합니다.