ADR 0001: 문헌 근거 워크스페이스의 병렬 구현과 route 교체¶

상태: Accepted
결정일: 2026-09-01
범위: /evidence 사용자 화면과 그 화면을 위한 UI view model
당시 설계 결정의 기록이다. 현재 구현은 frontend/src/components/evidence/와 대조한다.

Context¶

현재 src/app/evidence/page.tsx는 다음 책임을 한 파일에서 수행한다.

/api/literature-evidence fetch와 payload 검증
17개 category 선택
category 내부 검색과 field·최근 추가 filter
2~3열 evidence card grid
환자 표현, citation, 외부 link, score 표시
loading·empty·error 상태

승인된 Open Design 시안은 이 구조를 Find · Filter · Inspect 기반의 claim 목록·선택 상세 워크스페이스로 바꾼다. 변경 범위가 크고 현재 route 파일에도 사용자 변경이 있으므로, 기존 파일을 직접 누적 수정하면 시안과 구현의 차이를 추적하기 어렵고 rollback 범위도 커진다.

또한 시안의 검토 필요, 사용 가능, 출처 불일치는 현재 literature-evidence.json에 존재하지 않는 업무 상태다. 현재 확인 가능한 것은 claim, citation, 환자 표현, 일부 score와 별도 진단 문서에 기록된 식별자·taxonomy 문제다. UI가 사람의 검토 상태나 claim의 사용 가능성을 임의로 계산해서는 안 된다.

Decision¶

1. route와 화면 구현을 분리한다¶

src/app/evidence/page.tsx는 최종적으로 어떤 workspace를 렌더할지만 결정하는 얇은 route adapter가 된다. 실제 화면은 src/components/evidence/EvidenceWorkspace.tsx가 소유한다.

2. 신규 화면은 레거시 옆에서 완성한다¶

작업 시작 시 현재 route 구현을 동작 변경 없이 src/components/evidence/legacy/EvidenceWorkspaceLegacy.tsx로 이동하고, /evidence는 먼저 legacy component를 import한다. 신규 EvidenceWorkspace는 navigation에 연결하지 않은 임시 preview route에서 실제 데이터로 검증한다.

구현 중

/evidence ───────────────> EvidenceWorkspaceLegacy
/evidence-preview ───────> EvidenceWorkspace
                                  |
                                  +─ 실제 GET payload

parity 승인 후

/evidence ───────────────> EvidenceWorkspace
/evidence-preview ───────> 제거
EvidenceWorkspaceLegacy ─> 다음 승인 단위에서 제거

V2 이름이나 별도 production route는 최종 구조에 남기지 않는다.

3. 교체는 import 한 곳에서만 수행한다¶

Open Design parity, 실제 데이터, interaction, responsive, accessibility gate가 통과한 뒤 src/app/evidence/page.tsx의 import 대상만 legacy에서 신규 workspace로 바꾼다. 문제가 생기면 같은 지점에서 legacy import를 복원할 수 있다.

4. 데이터는 세 층으로 구분한다¶

Source layer
  literature-evidence.json의 원문·citation·환자 표현
        |
Integrity layer
  출처 식별자 검증, taxonomy 연결 문제처럼 확인된 감사 결과
        |
View model layer
  검색·filter·list-detail 표현을 위한 읽기 전용 조합

Governance layer (별도 후속)
  사람의 검토 상태, reviewer, 이력, 승인·문제 표시

기존 source JSON과 현재 GET payload는 UI 교체만을 위해 변경하지 않는다.
integrity 상태는 출처가 있는 audit 결과만 사용한다. 확인되지 않은 항목은 사용 가능이 아니라 검증 정보 없음으로 표현한다.
stable claim reference와 citation audit overlay가 필요하면 별도 UI registry로 만들고, 기존 외부 API에 새 field를 노출하지 않는다.
사람의 review 상태와 write action은 persistence API가 생기기 전까지 표시하지 않는다.

5. 시안과 구현의 소유권을 분리한다¶

Open Design artifact: 정보 구조, 영역 순서, 직접 진입·맥락 진입·mobile 전환의 행동 기준
design.md: typography, control size, spacing, color, responsive 수치 기준
MediKit과 src/components/ui: 실제 primitive와 공통 interaction 기준
실제 API와 검증 manifest: 화면에 표시할 사실의 기준

Open Design의 발표용 scenario bar, 가상 sidebar, 예시 의료 데이터, 독립 CSS 수치는 실제 서비스에 복제하지 않는다.

Consequences¶

Positive¶

기존 /evidence를 유지한 채 신규 화면을 실제 데이터로 비교할 수 있다.
cutover와 rollback이 route adapter의 한 import로 제한된다.
시안과 실제 구현을 같은 상태에서 screenshot으로 대조할 수 있다.
데이터 무결성과 사람의 검토 상태를 혼동하지 않는다.

Cost¶

검증 기간에는 legacy와 신규 component가 잠시 공존한다.
임시 preview route를 최종 cutover 때 반드시 제거해야 한다.
contextual entry는 stable claim reference와 upstream mapping이 준비되어야 production link를 연결할 수 있다.

Rejected alternatives¶

대안	기각 이유
현재 `page.tsx`를 직접 전면 수정	기존 동작과 신규 구조가 섞여 parity·rollback 경계가 불명확함
`/evidence-v2`를 영구 운영	navigation, URL, 상태 계약이 두 벌로 갈라짐
frontend에서 review status 계산	현재 데이터로 사람의 검토·승인 상태를 증명할 수 없음
시안의 CSS 수치를 그대로 복제	Procedure Hub의 `design.md`·MediKit 계약과 충돌함
시안의 예시 데이터를 실제 화면에 삽입	실제 source와 연결되지 않은 허위 상태·적용 범위를 만들게 됨