문서 안내¶

실행·검증은 Frontend와 Backend, 전체 프로젝트 소개는 내부 매뉴얼을 따른다. 기획자·개발자는 아래 문서 사이트에서 소개·사용법·FAQ와 상세 기술 문서를 함께 읽는다.

문서 사이트 실행¶

저장소 루트에서 실행한다. 앱 서버나 DB는 필요하지 않다.

uv tool run --from mkdocs==1.6.1 --with mkdocs-material==9.6.20 mkdocs serve

로컬 주소는 http://127.0.0.1:3025다. 포트가 사용 중이면 -a 127.0.0.1:3026처럼 빈 포트를 지정한다. 전체 HTML 빌드는 다음 명령으로 검증한다.

uv tool run --from mkdocs==1.6.1 --with mkdocs-material==9.6.20 mkdocs build --strict

Thready와 같은 MkDocs Material 버전을 사용하며 한국어 검색·목차·이전/다음 장을 제공한다.
원문은 이 저장소의 Markdown이다. FE·BE·ops README는 빌드 시 포함하며 복제하지 않는다.
site/는 생성된 HTML이며 Git에서 제외한다. 별도 수작업 HTML 원본은 유지하지 않는다.
PHub 사이드바의 ‘사용 가이드’에서 같은 사이트의 /manual/index.html로 접근한다. Frontend 빌드 시 문서를 포함한다. 별도 문서 서버는 작성 중 미리보기용이다. 매뉴얼 자체 로그인은 없으며 배포 시 PHub의 접근 보호 범위를 따른다.
기존 Mermaid 설계도는 고정 버전의 CDN 스크립트로 렌더링한다. 오프라인에서는 도식이 원문 코드로 보일 수 있다.

폴더	역할	문서
`guides/`	사용법과 개발·연동·운영 기준	화면 사용법 · FAQ · API · 검색 API · 디자인 · 배포
`architecture/`	도메인 책임과 데이터·검색 구조	도메인 계약 · 데이터 모델 · 검색 구조
`adr/`	선택한 설계와 그 이유	문헌 화면 · Canonical 게시 · 안전 규칙 · STG 전환 · FE 구조
`reviews/`	남은 승인·검토 조건과 진행 근거	Canonical 전환 · 임상 검토 · 미반영 지적
`references/`	출처·조사 시점이 있는 외부 참고자료	의료 코드

운영 SQL과 설치 안내는 ops/README.md에 둔다.

실행 명령은 영역별 README, 공개 계약은 guides, 결정 이유는 ADR에서 관리한다.
구조 문서의 목표 설계와 실제 구현을 구분한다. 현재 schema와 동작은 코드와 대조한다.
검토 문서는 미완료 조건을 보존하되, 과거 상태를 현재 완료·승인 근거로 사용하지 않는다.
새 문서보다 기존 문서의 해당 절을 먼저 갱신한다. 같은 내용을 여러 문서에 복제하지 않는다.
완료 보고서·중복 초안은 별도 archive에 쌓지 않고 Git 이력으로 남긴다. 삭제 전 자료는 예를 들어 git show b9aae70:docs/local-db-load-proof.md로 확인한다.