feat(extraction): 컷오버 Phase 2 — marker-service 제거 (MinerU 단독)

읽기뷰 회귀 0 확인(doc 39464 재처리 → engine=mineru success, 71 imgs, docimg ref/NAS persist
정상) 후 marker 제거. compose 에서 marker-service 블록 + fastapi depends_on + marker_models
볼륨 + services/marker/ 소스 삭제. 롤백 = git history + ~/.local/share/marker-decommission-backups.
마크다운 엔진 = mineru-service 단독.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

app/services/hier_decomp/builder.py

@@ -26,7 +26,16 @@ _ATX = re.compile(r'^(#{1,6})\s+(?P<title>\S.*?)\s*#*\s*$')
 _KO_JANG = re.compile(r'^\s*(?P<title>제\s*\d+\s*장\b.*)$')
 _KO_JEOL = re.compile(r'^\s*(?P<title>제\s*\d+\s*절\b.*)$')
 _KO_JO = re.compile(r'^\s*(?P<title>제\s*\d+\s*조\b.*)$')
-_ENG = re.compile(r'^\s*(?P<title>(?:Chapter|Section|Article|Part|PART)\s+[\dIVXLA-Z]+\b.*)$')
+# _ENG: 영문 구조 헤딩(ATX 미사용 문서용). ASME 파트는 보통 ATX(`# PART PG`)로 잡혀 _ENG 의존 낮음.
+# D1: 식별자 뒤가 소문자 문장연속이면("Part III to demonstrate to the satisfaction…") 본문이므로
+# 미탐지 — 가짜 절 차단. 선택 제목은 대문자/괄호/숫자로 시작해야 헤딩 인정(소문자 시작=문장으로 봄).
+# 식별자는 번호/PG/3.31/UHX/A-1 등 (.·- 소수·하이픈 확장 허용).
+_ENG = re.compile(
+    r'^\s*(?P<title>(?:Chapter|Section|Article|Part|PART)\s+'
+    r'[\dIVXLA-Z]+(?:[.\-][\dA-Za-z]+)*'
+    r'(?:\s+[A-Z(\d][^\n]*)?'
+    r')\s*$'
+)
 
 # 코드펜스 경계 (FE outlineAnchors.ts:60 `/^\s{0,3}(```|~~~)/` 와 동일). 펜스 내부 라인은
 # heading 미탐지 — 코드블록 안 '# foo' 가 가짜 절을 만들지 않게(O3).

app/workers/marker_worker.py

@@ -39,7 +39,11 @@ from models.queue import ProcessingQueue
 
 logger = logging.getLogger(__name__)
 
-MARKER_ENDPOINT = "http://marker-service:3300/convert"
+# 마크다운 추출 엔드포인트. compose env `MARKER_ENDPOINT`(base URL)에서 읽는다 —
+# 기본=marker(무변), 컷오버=`http://mineru-service:3301` 로 env 플립만으로 전환.
+# marker/mineru 가 동일 /convert 계약(file_path·start/end·md+base64 images)이라 워커 무변.
+_MARKDOWN_BASE = os.getenv("MARKER_ENDPOINT", "http://marker-service:3300").rstrip("/")
+MARKER_ENDPOINT = _MARKDOWN_BASE if _MARKDOWN_BASE.endswith("/convert") else _MARKDOWN_BASE + "/convert"
 MARKER_TIMEOUT = 300                    # 큰 PDF 5 분 한도
 MAX_PAGES = 200                         # 소형 1-shot 경로 /convert max_pages 안전장치
 

config.yaml

@@ -1,8 +1,6 @@
 # hyungi_Document_Server 설정
 
 ai:
-  gateway:
-    endpoint: "http://ai-gateway:8080"
 
   models:
     # ─── 단일 generation 호스트 routing (2026-05-14 GPU LLM 제거) ───

docker-compose.yml

@@ -54,24 +54,27 @@ services:
       start_period: 180s
     restart: unless-stopped
 
-  # Phase 1B (2026-05-01): PDF → markdown 변환. ocr-service 와 별도 컨테이너 (deps 충돌 회피).
-  marker-service:
-    build: ./services/marker
+  # MinerU 2.5 VLM PDF→markdown 추출 — ★ marker-service 대체(컷오버 2026-06-18, A/B 8/8 PASS).
+  # 단일카드 markdown VRAM ~10GB(marker)→~5.9GB 고정. fastapi 가 MARKER_ENDPOINT 로 호출.
+  # 동기 do_parse 버그 회피 위해 server.py 는 async aio_do_parse 사용. 포트 3301.
+  mineru-service:
+    build: ./services/mineru
     ports:
-      - "127.0.0.1:3300:3300"
+      - "127.0.0.1:3301:3301"
     expose:
-      - "3300"
+      - "3301"
     environment:
-      - HF_HOME=/models/huggingface
-      - TORCH_HOME=/models/torch
-      # D-1 (crawl-24x7): idle-unload 전환 — 영구 점유(~3.5GB) 해제가 90% 봉투의 전제.
-      # /ready 는 idle 에서도 200 (fastapi depends_on service_healthy 유지).
-      # 롤백 = MARKER_PRELOAD=1 + MARKER_IDLE_UNLOAD_MINUTES=0.
-      - MARKER_PRELOAD=0
-      - MARKER_IDLE_UNLOAD_MINUTES=${MARKER_IDLE_UNLOAD_MINUTES:-30}
+      # vlm-engine = 순수 VLM 단일모델. 기본 hybrid-engine 은 다중모델 로드 = OOM(반드시 명시).
+      - MINERU_BACKEND=vlm-engine
+      - MINERU_LANG=${MINERU_LANG:-korean}
+      # 공유 16GB 카드 공존: 절대 VRAM 캡(GB, 공유카드 robust) + vLLM 분율 캡 병용.
+      - MINERU_VIRTUAL_VRAM_SIZE=${MINERU_VIRTUAL_VRAM_SIZE:-6}
+      - MINERU_GPU_MEMORY_UTILIZATION=${MINERU_GPU_MEMORY_UTILIZATION:-0.40}
+      - MINERU_PRELOAD=${MINERU_PRELOAD:-1}
     volumes:
       - ${NAS_NFS_PATH:-/mnt/nas/Document_Server}:/documents:ro
-      - marker_models:/models
+      - mineru_models:/root/.cache
+    ipc: host                      # vLLM 공유메모리 — 공식 run 의 --ipc=host 대응.
     deploy:
       resources:
         reservations:
@@ -80,11 +83,11 @@ services:
               count: 1
               capabilities: [gpu]
     healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:3300/ready"]
+      test: ["CMD", "curl", "-f", "http://localhost:3301/ready"]
       interval: 30s
       timeout: 10s
       retries: 3
-      start_period: 300s
+      start_period: 900s           # VLM 모델 lazy 다운로드(~2.4GB)+엔진 로드 여유.
     restart: unless-stopped
 
   stt-service:
@@ -149,7 +152,7 @@ services:
       #       → 32 한도 초과 → 413. 64 로 늘림.
       # GPU VRAM free 6199MiB 충분. baseline path (MAX_RERANK_INPUT=200) 영향 0.
       - MAX_BATCH_TOKENS=16384
-      - MAX_CLIENT_BATCH_SIZE=64
+      - MAX_CLIENT_BATCH_SIZE=256  # 2026-06-18 fix: 64→256, MAX_RERANK_INPUT=200 커버 (batch>64 ERROR=RRF silent fallback 해소; MAX_BATCH_TOKENS가 VRAM 상한이라 entries 증가는 VRAM 무관)
       - MAX_CONCURRENT_REQUESTS=4
     volumes:
       - reranker_cache:/data
@@ -168,19 +171,6 @@ services:
       start_period: 120s
     restart: unless-stopped
 
-  ai-gateway:
-    build: ./gpu-server/services/ai-gateway
-    ports:
-      - "127.0.0.1:8081:8080"
-    environment:
-      - PRIMARY_ENDPOINT=http://100.76.254.116:8801/v1/chat/completions
-      - FALLBACK_ENDPOINT=http://ollama:11434/v1/chat/completions
-      - CLAUDE_API_KEY=${CLAUDE_API_KEY:-}
-      - DAILY_BUDGET_USD=${DAILY_BUDGET_USD:-5.00}
-    # depends_on: ollama 제거 (2026-06-08) — ollama 서비스가 standalone 으로 이관됨.
-    # FALLBACK_ENDPOINT 의 ollama:11434 는 standalone(동일 hostname, DS 망 부착)으로 해소.
-    restart: unless-stopped
-
   fastapi:
     build: ./app
     ports:
@@ -197,7 +187,8 @@ services:
         condition: service_healthy
       kordoc-service:
         condition: service_healthy
-      marker-service:
+      # 마크다운 엔진 = mineru-service (marker-service 제거 2026-06-18, 롤백=git history).
+      mineru-service:
         condition: service_healthy
     env_file:
       - credentials.env
@@ -205,7 +196,8 @@ services:
       - DATABASE_URL=postgresql+asyncpg://pkm:${POSTGRES_PASSWORD}@postgres:5432/pkm
       - KORDOC_ENDPOINT=http://kordoc-service:3100
       - OCR_ENDPOINT=http://ocr-service:3200
-      - MARKER_ENDPOINT=http://marker-service:3300
+      # ★ 컷오버 2026-06-18: marker-service:3300 → mineru-service:3301 (동일 /convert 계약).
+      - MARKER_ENDPOINT=http://mineru-service:3301
       - MARKER_CONTAINER_PATH_PREFIX=/documents
       # 2026-05-08 (D9 Track B revised): GPU stt-service 정식 승격, 내부 DNS 사용.
       - STT_ENDPOINT=http://stt-service:3300
@@ -283,4 +275,4 @@ volumes:
   reranker_cache:
   ocr_models:
   stt_models:
-  marker_models:
+  mineru_models:

frontend/src/lib/components/SectionOutline.svelte

@@ -1,13 +1,18 @@
 <script lang="ts">
   // 문서 상세 좌측 절(section) 목차 (PR-DocSrv-Hier-Section-UI-1).
-  // - groupOrFlat 로 per-doc 동적 (top-segment 1단 그룹 vs flat).
+  // - ASME 등 구조화 코드(buildPartOutline.hasParts): front-matter 단일 접이그룹 + PART 접이
+  //   (기본 접힘, 1030 flat → ~14 top-level). scroll-spy/딥링크 진입 시 조상 PART auto-expand. (D8)
+  // - 그 외(per-doc): groupOrFlat 폴백 — top-segment 1단 그룹 vs flat(5140/5186/비-ASME 무회귀).
   // - 항목 클릭 → 인라인 아코디언으로 요약/section_type/heading_path breadcrumb 표시.
-  // - 본문 스크롤 점프 없음(§Q2, deep-link 는 follow-up). summary=NULL 은 "요약 없음" 문구.
+  import { untrack } from 'svelte';
   import Badge from '$lib/components/ui/Badge.svelte';
   import {
     cleanHeading,
     pathSegments,
     groupOrFlat,
+    buildPartOutline,
+    partGroupViews,
+    groupKeyByChunkId,
     sectionTypeLabel,
     type DocumentSection,
     type OutlineItem,
@@ -17,14 +22,38 @@
     sections: DocumentSection[];
     /** 항목 클릭 시 본문 점프 콜백(부모가 #sec-{chunkId} scrollIntoView). 없으면 아코디언만. */
     onJump?: (chunkId: number) => void;
-    /** scroll-spy 현재 절(chunk_id) — 강조용. */
+    /** scroll-spy 현재 절(chunk_id) — 강조 + Part auto-expand. */
     activeKey?: number | null;
   }
   let { sections, onJump, activeKey = null }: Props = $props();
 
-  let layout = $derived(groupOrFlat(sections));
+  let partOutline = $derived(buildPartOutline(sections));
+  // hasParts(ASME 등): Part 접이 모드. 아니면 partViews=null → groupOrFlat 폴백.
+  let partViews = $derived(partOutline.hasParts ? partGroupViews(partOutline) : null);
+  let layout = $derived.by(() => (partOutline.hasParts ? null : groupOrFlat(sections)));
+  let groupIndex = $derived(partViews ? groupKeyByChunkId(partViews) : null);
   let total = $derived(sections.length);
+
   let selectedId = $state<number | null>(null);
+  // Part 그룹 접이 상태: key 없으면 접힘(기본 전부 접힘). $state Record = Svelte5 deep-proxy 반응형.
+  let expanded = $state<Record<string, boolean>>({});
+  function toggleGroup(key: string) {
+    expanded[key] = !expanded[key];
+  }
+  // 문서 전환(DocumentViewer 가 sections prop 교체) 시 접이/선택 리셋 — 문서 간 PART 라벨/chunk_id 가
+  // 우연히 겹쳐 이전 펼침/선택이 이월되는 것 차단(기본 전부 접힘 불변식 보존). untrack=쓰기 자기재발화 차단.
+  $effect(() => {
+    void sections;
+    untrack(() => { expanded = {}; selectedId = null; });
+  });
+  // scroll-spy/딥링크 활성 절의 조상 Part 를 펼침(다른 그룹은 건드리지 않음). untrack=쓰기 자기재발화 차단.
+  $effect(() => {
+    const ak = activeKey;
+    const idx = groupIndex;
+    if (ak == null || !idx) return;
+    const gk = idx.get(ak);
+    if (gk) untrack(() => { expanded[gk] = true; });
+  });
 
   function toggle(item: OutlineItem) {
     const id = item.section.chunk_id;
@@ -95,7 +124,37 @@
     <span class="text-faint font-normal">{total}</span>
   </h3>
 
-  {#if layout.mode === 'group'}
+  {#if partViews}
+    <!-- Part 접이 모드 (ASME 등): front-matter 단일 그룹 + PART 접이, 기본 접힘 -->
+    <div class="space-y-1">
+      {#each partViews as g (g.key)}
+        {@const isOpen = !!expanded[g.key]}
+        <div>
+          <button
+            type="button"
+            onclick={() => toggleGroup(g.key)}
+            aria-expanded={isOpen}
+            class={[
+              'w-full flex items-center gap-1.5 px-2 py-1.5 rounded-md text-[11px] font-semibold uppercase tracking-wide transition-colors',
+              g.isFrontMatter ? 'text-faint' : 'text-dim',
+              'hover:bg-surface hover:text-text',
+            ].join(' ')}
+          >
+            <span class="shrink-0 transition-transform duration-150 {isOpen ? 'rotate-90' : ''}">›</span>
+            <span class="flex-1 min-w-0 text-left truncate normal-case">{g.label}</span>
+            <span class="font-normal text-faint">{g.items.length}</span>
+          </button>
+          {#if isOpen}
+            <ul class="space-y-0.5 mt-0.5">
+              {#each g.items as item (item.section.chunk_id)}
+                {@render itemRow(item)}
+              {/each}
+            </ul>
+          {/if}
+        </div>
+      {/each}
+    </div>
+  {:else if layout?.mode === 'group'}
     <div class="space-y-3">
       {#each layout.groups as g (g.key)}
         <div>
@@ -118,7 +177,7 @@
     </div>
   {:else}
     <ul class="space-y-0.5">
-      {#each layout.items as item (item.section.chunk_id)}
+      {#each layout?.items ?? [] as item (item.section.chunk_id)}
         {@render itemRow(item)}
       {/each}
     </ul>

frontend/src/lib/utils/headingPath.test.ts

@@ -7,6 +7,12 @@ import {
   pathSegments,
   collapseWindows,
   groupOrFlat,
+  buildPartOutline,
+  partitionOutlineItems,
+  partGroupViews,
+  groupKeyByChunkId,
+  FRONT_MATTER_KEY,
+  FRONT_MATTER_LABEL,
   sectionTypeLabel,
   type DocumentSection,
 } from './headingPath.ts';
@@ -190,3 +196,211 @@ test('groupOrFlat: 빈 입력 → flat, 항목 0', () => {
   assert.equal(layout.mode, 'flat');
   assert.equal(layout.items.length, 0);
 });
+
+// ── D9: cleanHeading ASME 개정바 ðNÞ strip ──
+test('cleanHeading: ASME 개정바 ðNÞ 통째 제거 (가운데 25 안 남김)', () => {
+  assert.equal(
+    cleanHeading('<sup>ð</sup>**25**<sup>Þ</sup> **PG-5.4 Size Limits**'),
+    'PG-5.4 Size Limits',
+  );
+  // 개정바 없는 일반 제목은 그대로 (회귀)
+  assert.equal(cleanHeading('#### **PG-2 SERVICE LIMITATIONS**'.replace(/^#+\s*/, '')), 'PG-2 SERVICE LIMITATIONS');
+});
+
+// ── D7: buildPartOutline — front-matter 분리 + PART 그룹 ──
+test('buildPartOutline: front-matter 분리 + PART 그룹', () => {
+  const sections = [
+    sec({ heading_path: 'TABLE OF CONTENTS', section_title: 'TABLE OF CONTENTS' }),
+    sec({ heading_path: 'Honors and Awards Committee', section_title: 'Honors and Awards Committee' }),
+    sec({ heading_path: 'PART PG GENERAL > PG-1 SCOPE', section_title: 'PG-1 SCOPE' }),
+    sec({ heading_path: 'PART PG GENERAL > PG-2 SERVICE', section_title: 'PG-2 SERVICE' }),
+    sec({ heading_path: 'PART PW > PW-1 SCOPE', section_title: 'PW-1 SCOPE' }),
+  ];
+  const o = buildPartOutline(sections);
+  assert.equal(o.hasParts, true);
+  assert.equal(o.frontMatter.length, 2); // TOC + Committee
+  assert.equal(o.groups.length, 2); // PART PG, PART PW
+  assert.equal(o.groups[0].key, 'PART PG GENERAL');
+  assert.equal(o.groups[0].items.length, 2); // PG-1, PG-2
+  assert.equal(o.groups[1].key, 'PART PW');
+  assert.equal(o.groups[1].items.length, 1);
+});
+
+test('buildPartOutline: split-parent + window 가 같은 PART 그룹에서 1항목으로 흡수', () => {
+  const sections = [
+    sec({ heading_path: 'PART PG GENERAL > PG-27 CYL', section_title: 'PG-27 CYL', node_type: 'section_split', chunk_id: 100, text: 'PG-27 CYL' }),
+    sec({ heading_path: 'PART PG GENERAL > PG-27 CYL', section_title: 'PG-27 CYL', node_type: 'window', parent_id: 100, text: 'body part 1' }),
+    sec({ heading_path: 'PART PG GENERAL > PG-27 CYL', section_title: 'PG-27 CYL', node_type: 'window', parent_id: 100, text: 'body part 2' }),
+  ];
+  const o = buildPartOutline(sections);
+  assert.equal(o.hasParts, true);
+  assert.equal(o.groups.length, 1);
+  assert.equal(o.groups[0].items.length, 1); // split-parent + 2 window → 1 항목
+  assert.equal(o.groups[0].items[0].fragmentCount, 2);
+});
+
+test('buildPartOutline: content part 없으면 hasParts=false (폴백 신호)', () => {
+  const o = buildPartOutline([sec({ heading_path: 'Intro', section_title: 'Intro' })]);
+  assert.equal(o.hasParts, false);
+  assert.equal(o.groups.length, 0);
+});
+
+test('buildPartOutline: PART/SUBSECTION 마커 없으면(항목코드만) hasParts=false → 폴백', () => {
+  // 실 ASME 코드(5180/5210)는 PART/SUBSECTION 마커를 갖는다. PART 가 0 인 문서(항목코드만)는
+  // 접을 PART 가 없으므로 hasParts=false → 호출자가 groupOrFlat/flat 으로 폴백.
+  const o = buildPartOutline([
+    sec({ heading_path: 'FOREWORD', section_title: 'FOREWORD' }),
+    sec({ heading_path: null, section_title: 'U-1 적용범위' }),
+  ]);
+  assert.equal(o.hasParts, false);
+  assert.equal(o.groups.length, 0);
+});
+
+test('buildPartOutline: (NON)MANDATORY APPENDIX 도 최상위 섹션 경계 — 마지막 PART 흡수 방지', () => {
+  // 5180 실측: 부록을 마커로 안 잡으면 마지막 PART(PHRSG)가 부록 289항목을 carry-forward 흡수(=300).
+  const o = buildPartOutline([
+    sec({ heading_path: 'PART PHRSG REQUIREMENTS > PHRSG-1', section_title: 'PHRSG-1' }),
+    sec({ heading_path: 'PHRSG-2 SCOPE', section_title: 'PHRSG-2' }), // PHRSG 로 carry
+    sec({ heading_path: 'MANDATORY APPENDIX IV LOCAL THIN AREAS', section_title: '...' }),
+    sec({ heading_path: 'IV-1 GENERAL', section_title: 'IV-1' }), // APPENDIX IV 로 carry
+    sec({ heading_path: 'NONMANDATORY APPENDIX A EXPLANATION', section_title: '...' }),
+  ]);
+  assert.deepEqual(o.groups.map((g) => [g.key.slice(0, 24), g.items.length]), [
+    ['PART PHRSG REQUIREMENTS', 2],          // PHRSG-1 + PHRSG-2(carry), 부록 안 섞임
+    ['MANDATORY APPENDIX IV LO', 2],         // 부록 헤딩 + IV-1(carry)
+    ['NONMANDATORY APPENDIX A ', 1],
+  ]);
+});
+
+test('buildPartOutline: 본문 cross-ref/문장 false PART 차단 (5210 stale 패턴)', () => {
+  // 혼합대소문자 'Part D…' · 코드 뒤 비대문자(한글) 문장 'PART UW 규정은…' · 비대문자 코드 'PART 층이…'
+  // = 전부 본문이라 PART 아님. 깨끗한 PART 0 → hasParts=false → flat 폴백(가짜 그룹 0).
+  const o = buildPartOutline([
+    sec({ heading_path: 'Part D, Subpart 3의 해당 재료', section_title: 'Part D…' }),
+    sec({ heading_path: 'PART UW 규정은 용접에 의해 제작되는', section_title: 'PART UW 규정은…' }),
+    sec({ heading_path: 'PART 층이 진 구조로 조립되는', section_title: 'PART 층이…' }),
+  ]);
+  assert.equal(o.hasParts, false);
+});
+
+test('buildPartOutline: SUBSECTION 마커도 PART 경계로 인식(Sec VIII)', () => {
+  const o = buildPartOutline([
+    sec({ heading_path: 'TOC', section_title: 'TOC' }),
+    sec({ heading_path: 'SUBSECTION A GENERAL > UG-1', section_title: 'UG-1' }),
+    sec({ heading_path: 'SUBSECTION B > UW-1', section_title: 'UW-1' }),
+  ]);
+  assert.equal(o.hasParts, true);
+  assert.equal(o.frontMatter.length, 1);
+  assert.deepEqual(o.groups.map((g) => g.key), ['SUBSECTION A GENERAL', 'SUBSECTION B']);
+});
+
+// ── D8: partitionOutlineItems — 이미 collapse 된 OutlineItem 재배치(인스턴스 보존) ──
+test('partitionOutlineItems: flat outline 의 인스턴스를 그대로 재배치(재-collapse 없음)', () => {
+  const sections = [
+    sec({ heading_path: 'TABLE OF CONTENTS', section_title: 'TABLE OF CONTENTS' }),
+    sec({ heading_path: 'PART PG GENERAL > PG-1 SCOPE', section_title: 'PG-1 SCOPE' }),
+    sec({ heading_path: 'PART PG GENERAL > PG-2 SERVICE', section_title: 'PG-2 SERVICE' }),
+    sec({ heading_path: 'PART PW > PW-1 SCOPE', section_title: 'PW-1 SCOPE' }),
+  ];
+  const flat = collapseWindows(sections); // 컴포넌트의 outline 과 동일 경로
+  const o = partitionOutlineItems(flat);
+  assert.equal(o.hasParts, true);
+  assert.equal(o.frontMatter.length, 1);
+  assert.equal(o.groups.length, 2);
+  // ★ 인스턴스 동일성: 재배치된 item 이 flat outline 의 바로 그 객체여야 selectedSectionId 정합.
+  assert.ok(o.frontMatter[0] === flat[0], 'front-matter item = flat[0] 인스턴스');
+  assert.ok(o.groups[0].items[0] === flat[1], 'PART PG 첫 item = flat[1] 인스턴스');
+  assert.ok(o.groups[1].items[0] === flat[3], 'PART PW item = flat[3] 인스턴스');
+  // chunk_id 집합이 flat 과 정확히 일치(클릭→selectedSectionId 조회 실패 없음).
+  const flatIds = flat.map((it) => it.section.chunk_id).sort();
+  const partIds = [...o.frontMatter, ...o.groups.flatMap((g) => g.items)]
+    .map((it) => it.section.chunk_id).sort();
+  assert.deepEqual(partIds, flatIds);
+});
+
+test('partitionOutlineItems: 비-PART top-segment 항목은 직전 PART 로 carry-forward (marker 트리 불규칙 흡수)', () => {
+  // ★ 5180 실측 패턴: PART 아래 직접 중첩 안 된 항목('PG-28'·'GENERAL')의 top-segment 가 PART 가
+  //   아니다 → 단순 segs[0] 그룹핑이면 가짜 그룹 폭발. carry-forward 가 직전 PART 로 흡수해야 한다.
+  const items = collapseWindows([
+    sec({ heading_path: 'TOC', section_title: 'TOC' }),
+    sec({ heading_path: 'PART PG GENERAL > PG-1', section_title: 'PG-1' }),
+    sec({ heading_path: 'PG-28 EXTERNAL PRESSURE', section_title: 'PG-28' }), // top-seg ≠ PART → carry
+    sec({ heading_path: 'OPENINGS AND COMPENSATION', section_title: 'OPENINGS' }), // carry
+    sec({ heading_path: 'PART PW > PW-1', section_title: 'PW-1' }),
+    sec({ heading_path: 'GENERAL', section_title: 'GENERAL' }), // PART PW 로 carry
+  ]);
+  const o = partitionOutlineItems(items);
+  assert.equal(o.hasParts, true);
+  assert.equal(o.frontMatter.length, 1);
+  assert.equal(o.groups.length, 2, 'PART PG / PART PW 단 2그룹(가짜 그룹 0)');
+  assert.equal(o.groups[0].key, 'PART PG GENERAL');
+  assert.equal(o.groups[0].items.length, 3, 'PG-1 + PG-28 + OPENINGS carry');
+  assert.equal(o.groups[1].key, 'PART PW');
+  assert.equal(o.groups[1].items.length, 2, 'PW-1 + GENERAL carry');
+  // carry 된 항목도 인스턴스 보존(클릭 정합)
+  assert.ok(o.groups[0].items[1].section.section_title === 'PG-28');
+});
+
+test('partitionOutlineItems: buildPartOutline 과 그룹 구조 동치(collapse→partition == partition∘collapse)', () => {
+  const sections = [
+    sec({ heading_path: 'PART PG > PG-27 CYL', section_title: 'PG-27 CYL', node_type: 'section_split', chunk_id: 100, text: 'PG-27 CYL' }),
+    sec({ heading_path: 'PART PG > PG-27 CYL', section_title: 'PG-27 CYL', node_type: 'window', parent_id: 100, text: 'b1' }),
+    sec({ heading_path: 'PART PG > PG-27 CYL', section_title: 'PG-27 CYL', node_type: 'window', parent_id: 100, text: 'b2' }),
+    sec({ heading_path: 'PART PW > PW-1', section_title: 'PW-1' }),
+  ];
+  const viaBuild = buildPartOutline(sections);
+  const viaPartition = partitionOutlineItems(collapseWindows(sections));
+  assert.equal(viaBuild.hasParts, viaPartition.hasParts);
+  assert.deepEqual(viaBuild.groups.map((g) => [g.key, g.items.length]), viaPartition.groups.map((g) => [g.key, g.items.length]));
+  // window 흡수 후 PART PG 는 1 항목(fragmentCount 2).
+  assert.equal(viaPartition.groups[0].items.length, 1);
+  assert.equal(viaPartition.groups[0].items[0].fragmentCount, 2);
+});
+
+// ── D8: partGroupViews / groupKeyByChunkId — 렌더 그룹 평탄화 + auto-expand 역인덱스 ──
+test('partGroupViews: front-matter 를 첫 그룹(sentinel key)으로, 이어 PART 그룹', () => {
+  const sections = [
+    sec({ heading_path: 'TOC', section_title: 'TOC' }),
+    sec({ heading_path: 'PART PG > PG-1', section_title: 'PG-1' }),
+    sec({ heading_path: 'PART PW > PW-1', section_title: 'PW-1' }),
+  ];
+  const views = partGroupViews(buildPartOutline(sections));
+  assert.equal(views.length, 3);
+  assert.equal(views[0].key, FRONT_MATTER_KEY);
+  assert.equal(views[0].label, FRONT_MATTER_LABEL);
+  assert.equal(views[0].isFrontMatter, true);
+  assert.equal(views[1].key, 'PART PG');
+  assert.equal(views[1].label, 'PART PG');
+  assert.equal(views[1].isFrontMatter, false);
+  assert.equal(views[2].key, 'PART PW');
+  // 모든 key 유일(Svelte each key 안전)
+  const keys = views.map((v) => v.key);
+  assert.equal(new Set(keys).size, keys.length);
+});
+
+test('partGroupViews: front-matter 없으면 PART 그룹만(첫 그룹 sentinel 없음)', () => {
+  const sections = [
+    sec({ heading_path: 'PART PG > PG-1', section_title: 'PG-1' }),
+    sec({ heading_path: 'PART PW > PW-1', section_title: 'PW-1' }),
+  ];
+  const views = partGroupViews(buildPartOutline(sections));
+  assert.equal(views.length, 2);
+  assert.ok(views.every((v) => !v.isFrontMatter));
+  assert.equal(views[0].key, 'PART PG');
+});
+
+test('groupKeyByChunkId: 대표 chunk_id → 소속 group key (auto-expand 역인덱스)', () => {
+  const sections = [
+    sec({ chunk_id: 1, heading_path: 'TOC', section_title: 'TOC' }),
+    sec({ chunk_id: 2, heading_path: 'PART PG > PG-1', section_title: 'PG-1' }),
+    sec({ chunk_id: 3, heading_path: 'PART PG > PG-2', section_title: 'PG-2' }),
+    sec({ chunk_id: 4, heading_path: 'PART PW > PW-1', section_title: 'PW-1' }),
+  ];
+  const views = partGroupViews(buildPartOutline(sections));
+  const idx = groupKeyByChunkId(views);
+  assert.equal(idx.get(1), FRONT_MATTER_KEY);
+  assert.equal(idx.get(2), 'PART PG');
+  assert.equal(idx.get(3), 'PART PG');
+  assert.equal(idx.get(4), 'PART PW');
+  assert.equal(idx.get(999), undefined);
+});

frontend/src/lib/utils/headingPath.ts

@@ -84,6 +84,9 @@ export function sectionTypeLabel(t: string | null | undefined): string | null {
 export function cleanHeading(raw: string | null | undefined): string {
   if (!raw) return '';
   return raw
+    // D9(read-time): ASME 개정바 ðNÞ(`<sup>ð</sup>**25**<sup>Þ</sup>`) 통째 제거 — 개별 sup strip 전에.
+    //   (일반 sup strip 이 먼저면 가운데 '25'(개정 연도)만 남아 'ð25Þ PG-5.4' → '25 PG-5.4' 오염)
+    .replace(/<sup>\s*ð\s*<\/sup>.*?<sup>\s*Þ\s*<\/sup>/gi, '')
     .replace(/<sup>.*?<\/sup>/gi, '') // 각주 위첨자
     .replace(/<sub>.*?<\/sub>/gi, '')
     .replace(/<[^>]+>/g, '') // 잔여 HTML 태그
@@ -231,3 +234,129 @@ export function groupOrFlat(sections: DocumentSection[]): OutlineLayout {
   }));
   return { mode: 'group', items: [], groups };
 }
+
+// ── D7/D8 (asme-item-decomp read-time): front-matter 억제 + Part 계층 그룹 ──
+// 긴 구조화 코드(ASME)의 절뷰가 flat 1030 으로 길어지는 문제(front-matter 240 + 다중 PART)를
+// 표현 계층에서 해결. 빌더/재분해 무접촉 — sections 엔드포인트가 주는 heading_path 만으로 산출.
+
+/**
+ * 최상위 섹션 경계 top-segment 패턴: 대문자 'PART'/'SUBSECTION'/'(MANDATORY|NONMANDATORY) APPENDIX'
+ * + 대문자 코드(PG/UW/IV/A) + 선택 제목(대문자/숫자/괄호 시작).
+ *   예: 'PART PG GENERAL REQUIREMENTS…', 'SUBSECTION A GENERAL', 'NONMANDATORY APPENDIX A EXPLANATION…'.
+ * 부록(APPENDIX)도 ASME 최상위 섹션(파트와 동격)이라 별 그룹으로 — 안 그러면 마지막 PART 가 부록 전체를
+ * carry-forward 로 흡수(5180 실측: PART PHRSG 11항목 → 부록 289 흡수 = 300).
+ *
+ * ★ case-sensitive + 제목-대문자 가드 = 본문 cross-ref/문장 false match 차단(5210 실측):
+ *   'Part D, Subpart 3의 …'(혼합대소문자) · 'PART UW 규정은 용접에 …'(코드 뒤 한글 문장) · 'PART 층이 진 …'
+ *   (코드 비대문자) 전부 거부. D1 빌더 _ENG 가드의 read-time 대응([[feedback_docstring_invariant_swap_audit]]).
+ * ⚠ 알려진 트레이드오프(D3 재검토): 제목-대문자 가드는 비영문(한글) 제목으로 시작하는 PART 도 거부한다
+ *   (예: 'PART PG 일반 요건'). false-negative(→flat 폴백)는 false-positive(→가짜 그룹)보다 안전한 방향이라
+ *   파일럿(5180 영문)엔 옳고 5210(D3 재분해 전 한글 stale)은 flat 폴백된다. **5210 D3 재분해 후 실 PART
+ *   제목 형태(영문/한글/코드만)를 보고 가드를 정련** — read-time 라 마이그 0. [[project_hierarchical_decomposition]] D3.
+ */
+const PART_MARKER_RE = /^((MANDATORY |NONMANDATORY )?APPENDIX|PART|SUBSECTION)\s+[A-Z][A-Z0-9.\-]*(\s+[A-Z0-9(].*)?$/;
+
+/** top-segment 문자열이 PART/SUBSECTION/APPENDIX 헤딩인가 (마커 판정 단일 소스 — 경계·carry 공용). */
+function isPartMarkerSeg(seg0: string): boolean {
+  return PART_MARKER_RE.test(seg0);
+}
+
+/** 절의 heading_path 첫 세그먼트가 PART/SUBSECTION/APPENDIX 헤딩 = 새 최상위 섹션 경계. */
+function isPartMarker(s: DocumentSection): boolean {
+  const segs = pathSegments(s.heading_path);
+  return segs.length > 0 && isPartMarkerSeg(segs[0]);
+}
+
+export interface PartOutline {
+  /** PART PG / PART PW … 전(前) front-matter(TOC·위원회·인명) — 단일 접이 그룹용. */
+  frontMatter: OutlineItem[];
+  /** 본문 Part 그룹들(heading_path 첫 세그먼트 = PART 기준). 기본 접힘은 렌더(D8)에서. */
+  groups: OutlineGroup[];
+  /** content part 경계를 못 찾으면 false → 기존 groupOrFlat 폴백 권장. */
+  hasParts: boolean;
+}
+
+/**
+ * 이미 collapseWindows 된 OutlineItem[] 를 front-matter(첫 PART 마커 전) 분리 + 본문을 PART 로
+ * **순서 기반 carry-forward** 그룹. 정렬(chunk_index) 유지.
+ *
+ * ★ carry-forward 가 핵심: 실 ASME md 는 marker 추출 트리가 불규칙해 'PG-28'·'GENERAL' 등 다수
+ *   항목의 heading_path 첫 세그먼트가 PART 가 아니다(자기 자신/중간 헤딩). 단순 segs[0] 그룹핑은
+ *   250+ 가짜 그룹을 낳는다(5180 실측). → PART/SUBSECTION 마커를 만나면 새 그룹을 열고, 비-마커
+ *   항목은 직전 PART 로 흡수 = 실제 ~13 PART 로 수렴.
+ * ★ 같은 OutlineItem 인스턴스를 재배치만 한다(재-collapse 없음) → 호출자의 flat outline 과
+ *   chunk_id·인스턴스가 1:1 일치(상세페이지 treeNav 가 selectedSectionId/focusView 와 정합).
+ * PART 마커가 0 이면 hasParts=false → 호출자가 groupOrFlat/flat 으로 폴백.
+ */
+export function partitionOutlineItems(items: OutlineItem[]): PartOutline {
+  let boundary = -1;
+  for (let i = 0; i < items.length; i++) {
+    if (isPartMarker(items[i].section)) { boundary = i; break; }
+  }
+  if (boundary < 0) {
+    return { frontMatter: [], groups: [], hasParts: false };
+  }
+  const frontMatter = items.slice(0, boundary);
+
+  const order: string[] = [];
+  const map = new Map<string, OutlineItem[]>();
+  let current = ''; // 현재 PART 키 — boundary 가 PART 마커라 첫 본문 항목에서 즉시 설정됨.
+  for (let i = boundary; i < items.length; i++) {
+    const it = items[i];
+    const segs = pathSegments(it.section.heading_path);
+    if (segs.length && isPartMarkerSeg(segs[0])) current = segs[0]; // 새 PART 경계(경계 루프와 동일 판정 = '' 누출 불가)
+    if (!map.has(current)) { map.set(current, []); order.push(current); }
+    map.get(current)!.push(it);
+  }
+  const groups: OutlineGroup[] = order.map((key) => ({ key, isOther: false, items: map.get(key)! }));
+  return { frontMatter, groups, hasParts: true };
+}
+
+/**
+ * front-matter 경계(첫 content part) 분리 + 본문을 PART(heading_path 첫 세그먼트)로 그룹.
+ * = collapseWindows 후 partitionOutlineItems (절뷰 rail/treeNav 공용 진입점, sections 기반).
+ */
+export function buildPartOutline(sections: DocumentSection[]): PartOutline {
+  return partitionOutlineItems(collapseWindows(sections));
+}
+
+// ── D8: Part 접이 렌더용 — front-matter 를 첫 그룹으로 평탄화 + auto-expand 역인덱스 ──
+
+/** front-matter 접이 그룹의 안정 key/라벨(실 PART 키와 충돌 불가능한 sentinel). */
+export const FRONT_MATTER_KEY = '__front_matter__';
+export const FRONT_MATTER_LABEL = '문서 정보·서문';
+
+/** 접이 그룹 1개(front-matter 또는 PART) 의 렌더 뷰. */
+export interface PartGroupView {
+  /** Svelte each key + 접이 상태 key. front-matter = FRONT_MATTER_KEY. */
+  key: string;
+  /** 헤더 표시 라벨. */
+  label: string;
+  isFrontMatter: boolean;
+  items: OutlineItem[];
+}
+
+/**
+ * PartOutline → 렌더 그룹 배열. front-matter(있으면)를 항상 첫 그룹으로,
+ * 이어서 PART 그룹들. 기본 접힘/auto-expand 는 컴포넌트가 key 로 관리.
+ */
+export function partGroupViews(outline: PartOutline): PartGroupView[] {
+  const views: PartGroupView[] = [];
+  if (outline.frontMatter.length) {
+    views.push({ key: FRONT_MATTER_KEY, label: FRONT_MATTER_LABEL, isFrontMatter: true, items: outline.frontMatter });
+  }
+  for (const g of outline.groups) {
+    views.push({ key: g.key, label: g.key, isFrontMatter: false, items: g.items });
+  }
+  return views;
+}
+
+/**
+ * 대표 OutlineItem 의 chunk_id → 소속 group key 역인덱스(딥링크/스크롤스파이 진입 시
+ * 조상 그룹 auto-expand 용). activeKey/selectedSectionId 는 대표 chunk_id 라 대표만 매핑.
+ */
+export function groupKeyByChunkId(views: PartGroupView[]): Map<number, string> {
+  const m = new Map<number, string>();
+  for (const v of views) for (const it of v.items) m.set(it.section.chunk_id, v.key);
+  return m;
+}

frontend/src/routes/documents/[id]/+page.svelte

@@ -24,7 +24,8 @@
   import AIClassificationEditor from '$lib/components/editors/AIClassificationEditor.svelte';
   import LibraryPathEditor from '$lib/components/editors/LibraryPathEditor.svelte';
   import DocumentDangerZone from '$lib/components/editors/DocumentDangerZone.svelte';
-  import { cleanHeading, pathSegments, sectionTypeLabel, collapseWindows } from '$lib/utils/headingPath';
+  import { untrack } from 'svelte';
+  import { cleanHeading, pathSegments, sectionTypeLabel, collapseWindows, partitionOutlineItems, partGroupViews, groupKeyByChunkId } from '$lib/utils/headingPath';
   import { domainLabel } from '$lib/utils/domainSlug';
 
   marked.use({ mangle: false, headerIds: false });
@@ -69,10 +70,21 @@
   // 강등한다(예: 5180 = 27개 논리 절 → 562 window). raw sections 를 그대로 그리면 동일 제목 수백 행으로
   // 파편화되므로, collapseWindows 로 논리 절 1개(대표=split-parent, bodyText=window 본문 합본)로 합친다.
   let outline = $derived(collapseWindows(sections));
+  // Part 접이 트리(ASME 등 hasParts): 같은 outline 인스턴스를 front-matter/PART 로 재배치(재-collapse 없음
+  // → selectedSectionId/focusView 정합). flat 1030 → front-matter 단일그룹 + ~14 PART 접이. (D8)
+  let treePart = $derived(partitionOutlineItems(outline));
+  let treeGroups = $derived(treePart.hasParts ? partGroupViews(treePart) : null);
+  let treeGroupIndex = $derived(treeGroups ? groupKeyByChunkId(treeGroups) : null);
+  let treeExpanded = $state({}); // key 없으면 접힘(기본 전부 접힘). Svelte5 deep-proxy 반응형.
+  function toggleTreeGroup(key) { treeExpanded[key] = !treeExpanded[key]; }
+  // sections 로딩 완료 플래그 — 미완 동안 fallback 풀-문서 뷰어를 띄우면, 곧 절뷰로 교체되며
+  // 풀-문서 이미지가 '살짝 보였다 사라지는' 플래시가 난다(절 보유 문서). 로딩 중엔 skeleton.
+  let sectionsLoaded = $state(false);
   async function loadSections() {
     const reqId = docId;
     try { const r = await api(`/documents/${reqId}/sections`); if (reqId === docId) sections = r?.sections ?? []; }
     catch { if (reqId === docId) sections = []; }
+    finally { if (reqId === docId) sectionsLoaded = true; }
   }
 
   onMount(async () => {
@@ -116,8 +128,34 @@
   let mTree = $state(false);
   let mIns = $state(false);
   let manageOpen = $state(false);
-  $effect(() => { if (outline.length && !outline.some((it) => it.section.chunk_id === selectedSectionId)) selectedSectionId = outline[0].section.chunk_id; });
-  let selectedItem = $derived(outline.find((it) => it.section.chunk_id === selectedSectionId) ?? outline[0] ?? null);
+  // 기본 선택 = 첫 본문 Part 의 첫 절(front-matter TOC 가 아니라 실제 내용으로 진입, front-matter 접힘 유지).
+  let defaultSelId = $derived.by(() => {
+    if (treeGroups) {
+      const body = treeGroups.find((g) => !g.isFrontMatter);
+      if (body && body.items.length) return body.items[0].section.chunk_id;
+    }
+    return outline[0]?.section.chunk_id ?? null;
+  });
+  $effect(() => { if (outline.length && !outline.some((it) => it.section.chunk_id === selectedSectionId)) selectedSectionId = defaultSelId; });
+  // 문서가 바뀌면(sections 교체) Part 접이·모바일 본문 펼침 상태 리셋 — 문서 간 PART 라벨/chunk_id 가
+  // 겹쳐 이전 상태가 이월되는 것 차단(기본 전부 접힘 보존). ※ 같은 컴포넌트 인스턴스로 client 네비 시
+  // sections 가 재로딩될 때만 발화 — 현재 [id] 페이지는 onMount 1회 로딩이라 SPA prev/next 미reload 는
+  // 선존 별도 이슈(D8 범위 밖, 사용자 보고 대상).
+  $effect(() => {
+    void sections;
+    untrack(() => { treeExpanded = {}; mBodyOpen = {}; });
+  });
+  // 선택 절의 조상 Part 를 펼침(prev/next·딥링크 진입 시 트리에서 자동 노출). untrack=쓰기 자기재발화 차단.
+  $effect(() => {
+    const sel = selectedSectionId;
+    const idx = treeGroupIndex;
+    if (sel == null || !idx) return;
+    const gk = idx.get(sel);
+    if (gk) untrack(() => { treeExpanded[gk] = true; });
+  });
+  // selectedSectionId 미설정(초기) 시 defaultSelId(첫 본문 Part)로 바로 해석 — outline[0](표지/front-matter)
+  // 를 잠깐 렌더했다 effect 가 defaultSelId 로 바꾸는 절뷰 내부 플래시 차단.
+  let selectedItem = $derived(outline.find((it) => it.section.chunk_id === (selectedSectionId ?? defaultSelId)) ?? outline[0] ?? null);
   let selectedSection = $derived(selectedItem?.section ?? null);
   let selIdx = $derived(outline.findIndex((it) => it.section.chunk_id === selectedItem?.section?.chunk_id));
   // 절 본문 = 청크 원문(it.bodyText, window 조각 합본) 직접 렌더. 과거 char_start 로 md_content 를
@@ -168,13 +206,14 @@
       <span style="display:inline-flex;align-items:center;gap:4px;font-size:10px;color:#697061;"><span style="width:8px;height:8px;border-radius:2px;background:#7a8b3f;"></span>절차</span>
       <span style="display:inline-flex;align-items:center;gap:4px;font-size:10px;color:#697061;"><span style="width:8px;height:8px;border-radius:2px;background:#b5840a;"></span>요건</span>
     </div>
-    {#each outline as it (it.section.chunk_id)}
+    {#snippet treeNode(it)}
       {@const s = it.section}
       {@const tm = typeMeta(it.sectionType)}
       {@const active = !jumpMode && s.chunk_id === selectedSection?.chunk_id}
       {@const child = secDepth(s) > 0}
       {@const low = isMidLow(it.confidence)}
-      <svelte:element this={jumpMode ? 'a' : 'div'} href={jumpMode ? `#m-sec-${s.chunk_id}` : undefined} role="button" tabindex="0"
+      <svelte:element this={jumpMode ? 'a' : 'div'} href={jumpMode ? `#m-sec-${s.chunk_id}` : undefined}
+        role={jumpMode ? undefined : 'button'} tabindex={jumpMode ? undefined : 0}
         onclick={() => !jumpMode && (selectedSectionId = s.chunk_id)}
         onkeydown={(e) => { if (!jumpMode && (e.key === 'Enter' || e.key === ' ')) { e.preventDefault(); selectedSectionId = s.chunk_id; } }}
         class="d3node {child ? 'd3child' : ''} {active ? 'd3active' : ''}"
@@ -189,7 +228,25 @@
           {/if}
         </div>
       </svelte:element>
-    {/each}
+    {/snippet}
+
+    {#if treeGroups}
+      <!-- Part 접이(ASME 등): front-matter 단일그룹 + PART 접이, 기본 접힘. 선택/딥링크 시 조상 Part auto-expand. -->
+      {#each treeGroups as g (g.key)}
+        {@const isOpen = !!treeExpanded[g.key]}
+        <button type="button" class="d3grp" aria-expanded={isOpen} onclick={() => toggleTreeGroup(g.key)}
+          style="display:flex;align-items:center;gap:7px;width:100%;text-align:left;background:none;border:none;cursor:pointer;border-radius:8px;padding:6px 8px;margin:4px 0 1px;">
+          <span style="transition:transform .16s;transform:rotate({isOpen ? 90 : 0}deg);color:#9aa090;font-weight:700;font-size:12px;flex-shrink:0;">›</span>
+          <span style="flex:1;min-width:0;font-size:11px;font-weight:700;color:{g.isFrontMatter ? '#9aa090' : '#697061'};letter-spacing:.3px;text-transform:uppercase;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;">{g.label}</span>
+          <span style="font-size:10px;color:#9aa090;font-variant-numeric:tabular-nums;flex-shrink:0;">{g.items.length}</span>
+        </button>
+        {#if isOpen}
+          {#each g.items as it (it.section.chunk_id)}{@render treeNode(it)}{/each}
+        {/if}
+      {/each}
+    {:else}
+      {#each outline as it (it.section.chunk_id)}{@render treeNode(it)}{/each}
+    {/if}
     {#if quality}
       <div style="margin-top:12px;padding-top:10px;border-top:1px solid #dde3d6;">
         <div style="font-size:10.5px;font-weight:700;color:#697061;margin-bottom:7px;letter-spacing:.3px;">추출 품질</div>
@@ -239,8 +296,8 @@
         {/if}
       </div>
     {/if}
-    {#if selectedBodyHtml}
-      <div class="prose prose-base max-w-none text-text">{@html selectedBodyHtml}</div>
+    {#if selectedItem?.bodyText}
+      <MarkdownDoc documentId={doc.id} mdContent={selectedItem.bodyText} mdStatus={null} class="prose prose-base max-w-none text-text" />
     {:else}
       <p style="color:#9aa090;font-size:14px;font-style:italic;">이 절의 본문은 추출되지 않았습니다. 헤더의 '원본'에서 확인하세요.</p>
     {/if}
@@ -339,7 +396,7 @@
     {#if it.bodyText}
       <details class="m-secbody" ontoggle={(e) => { if (e.currentTarget.open) mBodyOpen[s.chunk_id] = true; }}>
         <summary style="cursor:pointer;list-style:none;font-size:12px;color:#697061;padding:5px 0;user-select:none;display:flex;align-items:center;gap:5px;">본문 보기 <span class="m-chev" style="transition:transform .16s;color:#9aa090;">›</span></summary>
-        {#if mBodyOpen[s.chunk_id]}<div class="prose prose-sm max-w-none text-text" style="margin-top:6px;">{@html bodyHtml(it)}</div>{/if}
+        {#if mBodyOpen[s.chunk_id]}<div style="margin-top:6px;"><MarkdownDoc documentId={doc.id} mdContent={it.bodyText} mdStatus={null} class="prose prose-sm max-w-none text-text" /></div>{/if}
       </details>
     {/if}
   </div>
@@ -384,10 +441,13 @@
       </div>
     </div>
 
-    {#if useSectionView}
+    {#if !sectionsLoaded}
+      <!-- sections 로딩 중: fallback 풀-문서(이미지)→절뷰 교체 플래시 방지용 skeleton -->
+      <Skeleton h="h-96" rounded="card" />
+    {:else if useSectionView}
       <!-- 데스크탑(xl+): 3영역 -->
       <div class="hidden xl:grid" style="grid-template-columns:252px minmax(0,1fr) 336px;gap:13px;align-items:start;">
-        <div style="background:#f4f7f1;border:1px solid #dde3d6;border-radius:14px;padding:13px 11px;position:sticky;top:14px;max-height:calc(100vh-2rem);overflow-y:auto;">{@render treeNav(false)}</div>
+        <div style="background:#f4f7f1;border:1px solid #dde3d6;border-radius:14px;padding:13px 11px;position:sticky;top:14px;max-height:calc(100vh - 2rem);overflow-y:auto;">{@render treeNav(false)}</div>
         <div style="min-width:0;"><div style="background:#f4f7f1;border:1px solid #dde3d6;border-radius:14px;padding:20px 22px;">{@render focusView()}</div></div>
         <div style="position:sticky;top:14px;">{@render rail()}</div>
       </div>
@@ -400,6 +460,9 @@
         </div>
         {#if mTree}<div style="background:#f4f7f1;border:1px solid #dde3d6;border-radius:12px;padding:6px;margin-bottom:10px;">{@render treeNav(true)}</div>{/if}
         {#if mIns}<div style="background:#f4f7f1;border:1px solid #dde3d6;border-radius:12px;padding:13px 14px;margin-bottom:10px;">{@render rail()}</div>{/if}
+        <!-- D8 스코프 한계(의도적): 모바일 본문은 전체 outline(~1030)을 연속 카드로 eager 마운트한다.
+             Part 접이는 위 treeNav(앵커 점프 네비)에만 적용 — 본문 롱스크롤은 줄이지 않는다. 데스크탑은
+             focusView 가 단일 절만 렌더하므로 무관. 모바일 본문 분할/가상화는 별 follow-up. -->
         <div style="display:flex;flex-direction:column;gap:10px;">{#each outline as it (it.section.chunk_id)}{@render sectionCard(it)}{/each}</div>
       </div>
     {:else}
@@ -474,6 +537,7 @@
 <style>
   .d3node:hover { background: #ecf0e8; }
   .d3active:hover { background: #e3ebdf; }
+  .d3grp:hover { background: #ecf0e8; }
   .d3child { position: relative; }
   .d3child::before { content: ""; position: absolute; left: 2px; top: -3px; bottom: 50%; width: 1px; background: #cdd6c4; }
   .d3child::after { content: ""; position: absolute; left: 2px; top: 50%; width: 7px; height: 1px; background: #cdd6c4; }

services/marker/Dockerfile

@@ -1,22 +0,0 @@
-FROM python:3.12-slim
-
-WORKDIR /app
-
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    libgl1 libglib2.0-0 curl \
-    && apt-get clean && rm -rf /var/lib/apt/lists/*
-
-COPY requirements.txt .
-RUN pip install --no-cache-dir \
-    --extra-index-url https://download.pytorch.org/whl/cu126 \
-    -r requirements.txt
-
-# 모델 미다운로드 (HF cache volume → 첫 호출/warmup 시 적재).
-
-COPY server.py .
-
-EXPOSE 3300
-HEALTHCHECK --start-period=300s --interval=30s --timeout=10s --retries=3 \
-    CMD curl -f http://localhost:3300/ready || exit 1
-
-CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "3300"]

services/marker/requirements.txt

@@ -1,9 +0,0 @@
-torch==2.11.0+cu126
-torchvision==0.26.0+cu126
-transformers==4.57.6
-surya-ocr==0.17.1
-marker-pdf==1.10.2
-pymupdf>=1.24.0,<2.0.0
-fastapi>=0.110.0,<1.0.0
-uvicorn[standard]>=0.27.0,<1.0.0
-pillow>=10.0.0,<12.0.0

services/marker/server.py

@@ -1,325 +0,0 @@
-"""marker-service — POST /convert: PDF → markdown + 추출 이미지 base64.
-
-Phase 1B   (2026-05-01) — 텍스트만 응답, 이미지 폐기.
-Phase 1B.5             — `_images` 직렬화해서 base64 응답에 포함. NAS write 권한이
-                         없는 stateless 변환기 유지 (fastapi 가 NAS persist 담당).
-D-1 (plan crawl-24x7-1, 2026-06-10) — idle-unload 운영 전환:
-  MARKER_PRELOAD=0           : startup warmup 끔 (첫 /convert 시 lazy load)
-  MARKER_IDLE_UNLOAD_MINUTES : N분 유휴 시 모델 해제 (0=비활성, 기존 동작)
-  /ready 는 idle(미적재)에서도 200 — fastapi 의 depends_on service_healthy 가
-  lazy 모드에서 영구 미기동으로 굳는 것 방지. 503 은 warmup_failed 한정.
-
-plan: ~/.claude/plans/piped-humming-crystal.md
-"""
-import base64
-import gc
-import hashlib
-import io
-import logging
-import os
-import threading
-import time
-from pathlib import Path
-
-from fastapi import FastAPI, HTTPException, Response
-from pydantic import BaseModel, Field
-
-from marker.converters.pdf import PdfConverter
-from marker.models import create_model_dict
-from marker.output import text_from_rendered
-import marker as marker_module
-
-logger = logging.getLogger(__name__)
-app = FastAPI()
-
-os.environ.setdefault("HF_HOME", "/models/huggingface")
-os.environ.setdefault("TORCH_HOME", "/models/torch")
-
-_models = None
-_converter = None
-try:
-    import importlib.metadata
-    _engine_version = importlib.metadata.version("marker-pdf")
-except Exception:
-    _engine_version = "unknown"
-_warmup_done = False
-_warmup_error: str | None = None
-_warmup_lock = threading.Lock()
-
-# D-1 idle-unload 상태 — 전이는 전부 _warmup_lock 아래
-_PRELOAD = os.getenv("MARKER_PRELOAD", "1") != "0"
-_IDLE_UNLOAD_MINUTES = int(os.getenv("MARKER_IDLE_UNLOAD_MINUTES", "0"))
-_inflight = 0
-_last_used = time.monotonic()
-
-# 이미지 응답 cap. base64 응답 크기 폭주 방지. 사용자 PDF 풀 측정 (Phase 1D) 시
-# 가장 이미지 많은 문서가 ~30건 수준 → 200 은 안전 마진. 초과 시 truncate flag 응답.
-MAX_IMAGES_PER_DOC = int(os.getenv("MARKER_MAX_IMAGES_PER_DOC", "200"))
-# per-image 최대 raw bytes (base64 전). 그래픽이 많은 풀페이지 스캔 회피.
-MAX_BYTES_PER_IMAGE = int(os.getenv("MARKER_MAX_BYTES_PER_IMAGE", str(10 * 1024 * 1024)))
-
-
-def _ensure_warmup() -> None:
-    """첫 /convert 또는 startup hook 시 모델 로드. HF cache volume 활용."""
-    global _models, _converter, _warmup_done, _warmup_error
-    if _warmup_done:
-        return
-    with _warmup_lock:
-        if _warmup_done:
-            return
-        try:
-            logger.info("[marker-service] warmup start")
-            _models = create_model_dict()
-            _converter = PdfConverter(artifact_dict=_models)
-            _warmup_done = True
-            _warmup_error = None
-            logger.info(f"[marker-service] warmup done engine_version={_engine_version}")
-        except Exception as exc:
-            _warmup_error = f"{type(exc).__name__}: {exc}"
-            logger.exception("[marker-service] warmup failed")
-            raise
-
-
-def _acquire_models():
-    """warmup 보장 + inflight 진입을 원자적으로 — ensure 직후 reaper 가 해제하는 경합 차단."""
-    global _inflight
-    while True:
-        _ensure_warmup()
-        with _warmup_lock:
-            if _warmup_done:
-                _inflight += 1
-                return
-        # ensure 와 lock 재진입 사이에 unload 가 끼어든 희귀 경합 — 재시도
-
-
-def _release_models():
-    global _inflight, _last_used
-    with _warmup_lock:
-        _inflight -= 1
-        _last_used = time.monotonic()
-
-
-def _maybe_unload() -> None:
-    """유휴 시 모델 해제. 변환 중(inflight>0)이면 절대 해제하지 않는다.
-
-    split 변환의 배치 사이 간격은 초 단위 — N>=1분 임계면 배치 사이 해제 없음.
-    """
-    global _models, _converter, _warmup_done
-    with _warmup_lock:
-        if not _warmup_done or _inflight > 0:
-            return
-        if time.monotonic() - _last_used < _IDLE_UNLOAD_MINUTES * 60:
-            return
-        _models = None
-        _converter = None
-        _warmup_done = False
-    gc.collect()
-    try:
-        import torch
-        torch.cuda.empty_cache()
-    except Exception:
-        pass
-    logger.info(f"[marker-service] idle-unload: 모델 해제 (유휴 {_IDLE_UNLOAD_MINUTES}분 초과)")
-
-
-async def _idle_reaper():
-    import asyncio
-    while True:
-        await asyncio.sleep(60)
-        try:
-            _maybe_unload()
-        except Exception:
-            logger.exception("[marker-service] idle reaper 오류")
-
-
-@app.on_event("startup")
-async def startup():
-    """startup hook — warmup 은 MARKER_PRELOAD 게이트 (D-1: lazy 기본 전환은 compose 가)."""
-    import asyncio
-    if _PRELOAD:
-        asyncio.create_task(asyncio.to_thread(_ensure_warmup))
-    if _IDLE_UNLOAD_MINUTES > 0:
-        asyncio.create_task(_idle_reaper())
-        logger.info(f"[marker-service] idle-unload 활성: {_IDLE_UNLOAD_MINUTES}분")
-
-
-class ConvertRequest(BaseModel):
-    file_path: str
-    max_pages: int | None = None
-    # page range (1-based inclusive) — LargeDoc split 변환용. marker 내부 0-based 변환은
-    # convert() 에 격리 (page numbering invariant: DB/API=1-based, marker=0-based).
-    start_page: int | None = None
-    end_page: int | None = None
-
-
-class ConvertImage(BaseModel):
-    """marker 추출 이미지 1건. fastapi 가 NAS 에 쓰고 docimg:img_NNN 으로 ref 정규화."""
-    slug: str           # marker 원본 slug (예: '_page_0_Picture_3.jpeg')
-    format: str         # 'png' | 'jpeg' | 'webp' | 'gif'
-    width: int | None = None
-    height: int | None = None
-    bytes_b64: str      # base64-encoded raw bytes
-
-
-class ConvertResponse(BaseModel):
-    md_content: str
-    md_content_hash: str
-    engine: str
-    engine_version: str
-    elapsed_ms: int
-    raw_metrics: dict
-    images: list[ConvertImage] = Field(default_factory=list)
-    images_truncated: bool = False
-
-
-@app.get("/health")
-def health():
-    return {"status": "ok", "service": "marker-service"}
-
-
-@app.get("/ready")
-async def ready(response: Response):
-    """Round 4 #1+#2: Response.status_code 명시 + warmup_error 노출.
-
-    D-1: idle(미적재) = 200. 503 은 warmup_failed 한정 — lazy 모드에서 fastapi
-    depends_on service_healthy 가 영구 미기동으로 굳지 않게. 배포 검증에서
-    'status=ready' 단언하던 runbook 은 강제 warm 호출(/convert 1건)로 대체.
-    """
-    if _warmup_error:
-        response.status_code = 503
-        return {
-            "status": "warmup_failed",
-            "engine": "marker",
-            "engine_version": _engine_version,
-            "error": _warmup_error,
-        }
-    if not _warmup_done:
-        return {
-            "status": "warming_up" if _PRELOAD else "idle",
-            "engine": "marker",
-            "engine_version": _engine_version,
-            "models_loaded": False,
-            "idle_unload_minutes": _IDLE_UNLOAD_MINUTES,
-        }
-    return {
-        "status": "ready",
-        "engine": "marker",
-        "engine_version": _engine_version,
-        "models_loaded": True,
-        "inflight": _inflight,
-        "idle_unload_minutes": _IDLE_UNLOAD_MINUTES,
-    }
-
-
-@app.post("/convert", response_model=ConvertResponse)
-async def convert(req: ConvertRequest):
-    p = Path(req.file_path)
-    if not p.is_file():
-        raise HTTPException(404, detail={"code": "file_not_found", "message": str(p)})
-    if req.start_page is not None and req.end_page is not None:
-        if req.start_page < 1 or req.end_page < req.start_page:
-            raise HTTPException(
-                422,
-                detail={
-                    "code": "bad_page_range",
-                    "message": f"start_page={req.start_page} end_page={req.end_page}",
-                },
-            )
-
-    # D-1: warmup 보장 + inflight 진입 원자화 — 변환 중 reaper 해제 차단. 해제는 finally.
-    _acquire_models()
-    try:
-        start = time.monotonic()
-        # page range 지정 시 per-request converter (모델 _models 재사용 → reload 없음).
-        # invariant: req.start_page/end_page = 1-based inclusive → marker 0-based 로 변환.
-        converter = _converter
-        if req.start_page is not None and req.end_page is not None:
-            page_range = list(range(req.start_page - 1, req.end_page))  # 0-based inclusive
-            converter = PdfConverter(artifact_dict=_models, config={"page_range": page_range})
-        try:
-            rendered = converter(str(p))
-        except Exception as exc:
-            logger.exception(f"[marker-service] conversion failed path={p}: {exc}")
-            raise HTTPException(
-                status_code=422,
-                detail={
-                    "code": "conversion_failed",
-                    "message": f"{type(exc).__name__}: {exc}",
-                },
-            ) from exc
-
-        md_text, _meta, raw_images = text_from_rendered(rendered)
-        elapsed_ms = int((time.monotonic() - start) * 1000)
-    finally:
-        _release_models()
-
-    images_payload, truncated = _serialize_images(raw_images, str(p))
-
-    return ConvertResponse(
-        md_content=md_text,
-        md_content_hash=hashlib.sha256(md_text.encode("utf-8")).hexdigest(),
-        engine="marker",
-        engine_version=_engine_version,
-        elapsed_ms=elapsed_ms,
-        raw_metrics={
-            "page_count": getattr(rendered, "page_count", None),
-            "image_count_extracted": len(raw_images) if raw_images else 0,
-            "image_count_returned": len(images_payload),
-        },
-        images=images_payload,
-        images_truncated=truncated,
-    )
-
-
-def _serialize_images(raw_images, src_path: str) -> tuple[list[ConvertImage], bool]:
-    """marker 의 `_images` (dict[slug, PIL.Image]) → base64 ConvertImage 리스트.
-
-    가드:
-      - MAX_IMAGES_PER_DOC 초과 시 head 만 반환 + truncated=True
-      - per-image 직렬화 실패 시 해당 이미지만 skip + warn (전체 fail 안 함)
-      - per-image 결과 byte 크기가 MAX_BYTES_PER_IMAGE 초과 시 skip + warn
-    """
-    if not raw_images:
-        return [], False
-
-    items = list(raw_images.items())
-    truncated = len(items) > MAX_IMAGES_PER_DOC
-    if truncated:
-        logger.warning(
-            f"[marker-service] images truncated path={src_path} "
-            f"total={len(items)} cap={MAX_IMAGES_PER_DOC}"
-        )
-        items = items[:MAX_IMAGES_PER_DOC]
-
-    out: list[ConvertImage] = []
-    for slug, pil_img in items:
-        try:
-            fmt_raw = (pil_img.format or "PNG").upper()
-            # WebP/GIF 도 marker 가 emit 가능하지만 본 1B.5 기준은 PNG/JPEG 우선.
-            # 알 수 없는 포맷이면 PNG 로 강제 (lossless re-encode).
-            fmt = fmt_raw if fmt_raw in {"PNG", "JPEG", "WEBP", "GIF"} else "PNG"
-            buf = io.BytesIO()
-            pil_img.save(buf, format=fmt)
-            raw_bytes = buf.getvalue()
-            if len(raw_bytes) > MAX_BYTES_PER_IMAGE:
-                logger.warning(
-                    f"[marker-service] image too large skipped path={src_path} "
-                    f"slug={slug} bytes={len(raw_bytes)} cap={MAX_BYTES_PER_IMAGE}"
-                )
-                continue
-            out.append(
-                ConvertImage(
-                    slug=slug,
-                    format=fmt.lower(),
-                    width=pil_img.width,
-                    height=pil_img.height,
-                    bytes_b64=base64.b64encode(raw_bytes).decode("ascii"),
-                )
-            )
-        except Exception as exc:
-            logger.warning(
-                f"[marker-service] image serialize failed path={src_path} "
-                f"slug={slug}: {type(exc).__name__}: {exc}"
-            )
-            continue
-    return out, truncated

services/mineru/Dockerfile

@@ -0,0 +1,45 @@
+# mineru-service — MinerU 2.5 VLM 기반 PDF→markdown 추출기. marker-service 대체.
+# 단일카드(RTX 4070 Ti S 16GB→PRO 4000 24GB) markdown VRAM ~10GB(marker)→~5GB(MinerU VLM).
+#
+# 공식 opendatalab/MinerU global Dockerfile 기반:
+#   FROM vllm/vllm-openai:v0.21.0 (CUDA 13.0). GPU 호스트 드라이버 595.71.05 / CUDA 13.2 가
+#   13.0 런타임 지원 → cu129 폴백 불필요. vLLM 은 base 이미지가 제공하므로 mineru 는 [core] 만.
+#
+# 모델은 이미지에 굽지 않고 런타임 warmup 시 HF cache 볼륨으로 lazy 다운로드 (marker/ocr 선례 =
+#   서버 .cache 볼륨). 이미지 슬림 유지 + server.py 반복 빌드 빠름 + 모델 볼륨 영속.
+FROM vllm/vllm-openai:v0.21.0
+
+# base 이미지의 ENTRYPOINT(vLLM OpenAI 서버)를 제거 — 우리는 uvicorn 으로 자체 FastAPI 기동.
+ENTRYPOINT []
+
+# opencv(libgl) + CJK 폰트(레이아웃/렌더 안전) + curl(healthcheck). 공식 Dockerfile 동일.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        fonts-noto-core fonts-noto-cjk fontconfig libgl1 curl \
+    && fc-cache -fv \
+    && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# mineru[core] — 공식 설치 라인. vLLM(vlm-engine 백엔드)은 base 가 이미 제공.
+RUN python3 -m pip install -U 'mineru[core]>=3.2.1' --break-system-packages \
+    && python3 -m pip cache purge
+
+# 서비스 wrapper 의존성. base(vllm-openai)+mineru 가 fastapi/uvicorn/pillow 를 이미 제공 →
+# pymupdf 만 추가(나머지 명시 핀은 base 의 pillow 12.x 를 불필요하게 다운그레이드해서 제거).
+RUN python3 -m pip install --no-cache-dir --break-system-packages \
+        'pymupdf>=1.24.0,<2.0.0'
+
+# MINERU_MODEL_SOURCE=huggingface = warmup 시 lazy 다운로드 (HF cache 볼륨에 영속).
+# PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True = 단편화 완화(연구 권고, 거대 입력 OOM 완충).
+ENV MINERU_MODEL_SOURCE=huggingface \
+    HF_HOME=/root/.cache/huggingface \
+    PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
+
+WORKDIR /app
+# server.py = 무거운 pip 레이어 뒤에 COPY → 반복 빌드 시 캐시 적중(빠른 재빌드).
+COPY server.py /app/server.py
+
+EXPOSE 3301
+# VLM 모델 lazy 다운로드(~2.4GB)+엔진 로드 여유로 start-period 길게.
+HEALTHCHECK --start-period=900s --interval=30s --timeout=10s --retries=3 \
+    CMD curl -f http://localhost:3301/ready || exit 1
+
+CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "3301"]

services/mineru/server.py

@@ -0,0 +1,315 @@
+"""mineru-service — POST /convert: PDF → markdown + 추출 이미지 base64.
+
+marker-service 대체(MinerU 2.5 VLM). **marker 의 /convert 계약을 그대로 복제**해서
+marker_worker 가 엔드포인트만 바꾸면 되도록 한다(요청/응답 동일 shape):
+
+  요청:  {file_path, max_pages?, start_page?, end_page?}   (page = 1-based inclusive)
+  응답:  {md_content, md_content_hash, engine, engine_version, elapsed_ms,
+          raw_metrics, images:[{slug, format, width, height, bytes_b64}], images_truncated}
+
+설계 노트:
+- **page range 는 PyMuPDF 로 직접 슬라이스**해서 MinerU 에 넘긴다(start_page..end_page →
+  0-based [a,b] 페이지만 담은 새 PDF bytes). MinerU 의 `end_page_id=0 falsy 무시` 버그 회피.
+  40p 윈도우 분할은 marker_worker 가 그대로 담당. (검증: fitz 슬라이스 렌더 = 원본과 동일 품질.)
+- **★ 반드시 async 엔진(`aio_do_parse`) 사용.** 동기 `do_parse`(vllm-engine sync)는 본 모델
+  (MinerU2.5-Pro-2605-1.2B)에서 layout 토큰 malformed → 빈 md 산출(실측 G1-2). async
+  (`aio_do_parse` = vllm-async-engine, mineru CLI 가 쓰는 정상 경로) = 정상 출력.
+- **이미지 = stateless**: marker 처럼 NAS write 안 함. MinerU 가 md 에 박는 `![](images/<sha>.jpg)`
+  href 를 그대로 slug 으로 반환 → fastapi(marker_worker)의 `_rewrite_image_refs` 가 basename
+  매칭으로 `docimg:img_NNN` 정규화 + NAS persist. (계약 무변)
+- **VRAM 캡**: `MINERU_GPU_MEMORY_UTILIZATION`(vLLM 분율, 0.40→~6GB 실측). compose 의
+  `MINERU_VIRTUAL_VRAM_SIZE` 도 무해(실측 정상)하나 출력엔 무관 — 캡은 분율로 충분.
+  backend=`vlm-engine`(기본 hybrid-engine 은 다중모델 로드 OOM, 반드시 명시).
+
+엔진은 첫 변환(또는 startup warmup) 시 1회 로드 — MinerU ModelSingleton 캐시. 단일 GPU 라
+변환은 _engine_lock 으로 직렬화.
+"""
+import asyncio
+import base64
+import hashlib
+import inspect
+import io
+import logging
+import os
+import time
+import unicodedata
+from pathlib import Path
+
+import fitz  # PyMuPDF — page 슬라이스 + 페이지수
+from fastapi import FastAPI, HTTPException, Response
+from PIL import Image
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger("mineru-service")
+logging.basicConfig(level=logging.INFO)
+app = FastAPI()
+
+try:
+    import importlib.metadata
+    _engine_version = importlib.metadata.version("mineru")
+except Exception:
+    _engine_version = "unknown"
+
+# ---- 설정 (compose env 로 override) -----------------------------------------
+MINERU_BACKEND = os.getenv("MINERU_BACKEND", "vlm-engine")
+MINERU_LANG = os.getenv("MINERU_LANG", "korean")
+GPU_MEM_UTIL = float(os.getenv("MINERU_GPU_MEMORY_UTILIZATION", "0.40"))
+
+MAX_IMAGES_PER_DOC = int(os.getenv("MINERU_MAX_IMAGES_PER_DOC", "200"))
+MAX_BYTES_PER_IMAGE = int(os.getenv("MINERU_MAX_BYTES_PER_IMAGE", str(10 * 1024 * 1024)))
+MAX_PAGES_HARD = int(os.getenv("MINERU_MAX_PAGES_HARD", "200"))  # 1-shot max_pages 안전장치
+
+_PRELOAD = os.getenv("MINERU_PRELOAD", "1") != "0"
+
+# ---- 엔진 상태 ---------------------------------------------------------------
+_warmup_done = False
+_warmup_error: str | None = None
+# 단일 GPU async 엔진 — warmup + convert 직렬화(엔진 1개, 임시디렉토리/싱글톤 경합 차단).
+_engine_lock = asyncio.Lock()
+
+
+async def _run_mineru(pdf_bytes: bytes, lang: str) -> tuple[str, list[dict]]:
+    """슬라이스된 PDF bytes → (markdown, 이미지 dict 리스트). **async 엔진 경로.**
+
+    호출자(_ensure_warmup / convert)가 _engine_lock 을 잡은 상태로 호출한다.
+    이미지 dict: {slug, format, width, height, raw_bytes}. slug = md href 그대로.
+    """
+    import glob
+    import tempfile
+
+    from mineru.cli.common import aio_do_parse
+
+    with tempfile.TemporaryDirectory(prefix="mineru_") as td:
+        candidate = {
+            "output_dir": td,
+            "pdf_file_names": ["doc"],
+            "pdf_bytes_list": [pdf_bytes],
+            "p_lang_list": [lang],
+            "backend": MINERU_BACKEND,
+            "formula_enable": True,
+            "table_enable": True,
+            "f_dump_md": True,
+            "f_dump_content_list": True,
+            "f_dump_middle_json": False,
+            "f_dump_model_output": False,
+            "f_dump_orig_pdf": False,
+            "f_draw_layout_bbox": False,
+            "f_draw_span_bbox": False,
+            "gpu_memory_utilization": GPU_MEM_UTIL,
+        }
+        sig = inspect.signature(aio_do_parse)
+        has_var_kw = any(
+            p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
+        )
+        kwargs = candidate if has_var_kw else {
+            k: v for k, v in candidate.items() if k in sig.parameters
+        }
+        await aio_do_parse(**kwargs)
+
+        md_files = sorted(glob.glob(f"{td}/**/*.md", recursive=True))
+        if not md_files:
+            raise RuntimeError("mineru produced no markdown output")
+        md_path = Path(md_files[0])
+        md_text = md_path.read_text(encoding="utf-8", errors="replace")
+
+        images: list[dict] = []
+        img_dir = md_path.parent / "images"
+        if img_dir.is_dir():
+            for img_file in sorted(img_dir.iterdir()):
+                if not img_file.is_file():
+                    continue
+                raw = img_file.read_bytes()
+                slug = f"images/{img_file.name}"  # md href 와 정확히 일치
+                w = h = None
+                try:
+                    with Image.open(io.BytesIO(raw)) as im:
+                        w, h = im.width, im.height
+                        fmt = (im.format or "JPEG").lower()
+                except Exception:
+                    fmt = img_file.suffix.lstrip(".").lower() or "jpeg"
+                images.append(
+                    {"slug": slug, "format": fmt, "width": w, "height": h, "raw_bytes": raw}
+                )
+        return md_text, images
+
+
+async def _ensure_warmup() -> None:
+    """첫 /convert 또는 startup hook 시 1-page 합성 PDF 로 엔진+모델 적재."""
+    global _warmup_done, _warmup_error
+    if _warmup_done:
+        return
+    async with _engine_lock:
+        if _warmup_done:
+            return
+        try:
+            logger.info("[mineru-service] warmup start (async engine load + model fetch)")
+            doc = fitz.open()
+            page = doc.new_page()
+            page.insert_text((72, 72), "MinerU warmup.")
+            warmup_bytes = doc.tobytes()
+            doc.close()
+            await _run_mineru(warmup_bytes, MINERU_LANG)
+            _warmup_done = True
+            _warmup_error = None
+            logger.info(f"[mineru-service] warmup done engine_version={_engine_version}")
+        except Exception as exc:
+            _warmup_error = f"{type(exc).__name__}: {exc}"
+            logger.exception("[mineru-service] warmup failed")
+            raise
+
+
+@app.on_event("startup")
+async def startup():
+    if _PRELOAD:
+        asyncio.create_task(_ensure_warmup())
+
+
+# ---- 계약 모델 (marker 와 동일 shape) ----------------------------------------
+class ConvertRequest(BaseModel):
+    file_path: str
+    max_pages: int | None = None
+    start_page: int | None = None   # 1-based inclusive
+    end_page: int | None = None     # 1-based inclusive
+
+
+class ConvertImage(BaseModel):
+    slug: str
+    format: str
+    width: int | None = None
+    height: int | None = None
+    bytes_b64: str
+
+
+class ConvertResponse(BaseModel):
+    md_content: str
+    md_content_hash: str
+    engine: str
+    engine_version: str
+    elapsed_ms: int
+    raw_metrics: dict
+    images: list[ConvertImage] = Field(default_factory=list)
+    images_truncated: bool = False
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "service": "mineru-service"}
+
+
+@app.get("/ready")
+async def ready(response: Response):
+    """marker /ready 의미 복제: warmup_failed 만 503, idle/warming=200(depends_on 굳음 방지)."""
+    if _warmup_error:
+        response.status_code = 503
+        return {"status": "warmup_failed", "engine": "mineru",
+                "engine_version": _engine_version, "error": _warmup_error}
+    if not _warmup_done:
+        return {"status": "warming_up" if _PRELOAD else "idle", "engine": "mineru",
+                "engine_version": _engine_version, "models_loaded": False}
+    return {"status": "ready", "engine": "mineru",
+            "engine_version": _engine_version, "models_loaded": True}
+
+
+def _resolve_path(file_path: str) -> Path | None:
+    """NFC(DB) vs NFD(NFS) 한글 경로 정규화 차이 흡수. ocr/server.py 와 동일 패턴
+    (필수 — 한글명 파일은 NFS=NFD 저장이라 DB 의 NFC 경로로는 is_file=False)."""
+    for c in (file_path,
+              unicodedata.normalize("NFD", file_path),
+              unicodedata.normalize("NFC", file_path)):
+        p = Path(c)
+        if p.exists():
+            return p
+    parent = Path(file_path).parent
+    if parent.exists():
+        target = unicodedata.normalize("NFC", Path(file_path).name)
+        for child in parent.iterdir():
+            if unicodedata.normalize("NFC", child.name) == target:
+                return child
+    return None
+
+
+def _slice_pdf(src_path: Path, start_page: int | None, end_page: int | None,
+               max_pages: int | None) -> tuple[bytes, int]:
+    """요청 page 범위(1-based inclusive)만 담은 새 PDF bytes + 변환 페이지수 반환."""
+    with fitz.open(src_path) as src:
+        n = src.page_count
+        if start_page is not None and end_page is not None:
+            a = max(0, start_page - 1)
+            b = min(n - 1, end_page - 1)
+        else:
+            a = 0
+            cap = max_pages if max_pages is not None else MAX_PAGES_HARD
+            b = min(n - 1, cap - 1)
+        if b < a:
+            raise HTTPException(422, detail={"code": "bad_page_range",
+                                             "message": f"a={a} b={b} n={n}"})
+        out = fitz.open()
+        out.insert_pdf(src, from_page=a, to_page=b)
+        pdf_bytes = out.tobytes()
+        out.close()
+        return pdf_bytes, (b - a + 1)
+
+
+def _serialize_images(images: list[dict], src_path: str) -> tuple[list[ConvertImage], bool]:
+    """이미지 dict 리스트 → base64 ConvertImage 리스트 (marker 가드 동일)."""
+    truncated = len(images) > MAX_IMAGES_PER_DOC
+    if truncated:
+        logger.warning(f"[mineru-service] images truncated path={src_path} "
+                       f"total={len(images)} cap={MAX_IMAGES_PER_DOC}")
+        images = images[:MAX_IMAGES_PER_DOC]
+    out: list[ConvertImage] = []
+    for img in images:
+        raw = img["raw_bytes"]
+        if len(raw) > MAX_BYTES_PER_IMAGE:
+            logger.warning(f"[mineru-service] image too large skipped path={src_path} "
+                           f"slug={img['slug']} bytes={len(raw)} cap={MAX_BYTES_PER_IMAGE}")
+            continue
+        out.append(ConvertImage(
+            slug=img["slug"], format=img["format"],
+            width=img.get("width"), height=img.get("height"),
+            bytes_b64=base64.b64encode(raw).decode("ascii"),
+        ))
+    return out, truncated
+
+
+@app.post("/convert", response_model=ConvertResponse)
+async def convert(req: ConvertRequest):
+    p = _resolve_path(req.file_path)
+    if p is None or not p.is_file():
+        raise HTTPException(404, detail={"code": "file_not_found", "message": req.file_path})
+    if req.start_page is not None and req.end_page is not None:
+        if req.start_page < 1 or req.end_page < req.start_page:
+            raise HTTPException(422, detail={"code": "bad_page_range",
+                "message": f"start_page={req.start_page} end_page={req.end_page}"})
+
+    pdf_bytes, page_count = _slice_pdf(p, req.start_page, req.end_page, req.max_pages)
+
+    await _ensure_warmup()                  # 엔진 로드 보장(내부에서 _engine_lock 잡았다 놓음)
+    async with _engine_lock:                # 실제 변환 직렬화(단일 GPU)
+        start = time.monotonic()
+        try:
+            md_text, raw_images = await _run_mineru(pdf_bytes, MINERU_LANG)
+        except HTTPException:
+            raise
+        except Exception as exc:
+            logger.exception(f"[mineru-service] conversion failed path={p}: {exc}")
+            raise HTTPException(422, detail={"code": "conversion_failed",
+                "message": f"{type(exc).__name__}: {exc}"}) from exc
+        elapsed_ms = int((time.monotonic() - start) * 1000)
+
+    images_payload, truncated = _serialize_images(raw_images, str(p))
+
+    return ConvertResponse(
+        md_content=md_text,
+        md_content_hash=hashlib.sha256(md_text.encode("utf-8")).hexdigest(),
+        engine="mineru",
+        engine_version=_engine_version,
+        elapsed_ms=elapsed_ms,
+        raw_metrics={
+            "page_count": page_count,
+            "image_count_extracted": len(raw_images),
+            "image_count_returned": len(images_payload),
+        },
+        images=images_payload,
+        images_truncated=truncated,
+    )

tests/hier_decomp/test_eng_matcher.py

@@ -0,0 +1,106 @@
+"""_ENG 매처 노이즈 차단 단위테스트 (asme-item-decomp-1 D1).
+
+핵심 불변식: 영문 구조 헤딩 매처(_ENG)가
+  - (음성) 본문 중간 'Part III to demonstrate…' 같은 소문자 문장연속을 가짜 절로 잡지 않고,
+  - (양성) 진짜 영문 구조 헤딩(PART PG / Part 1 / Section 3.31 / Part UHX …)은 탐지하며,
+  - (ATX 보존) _ENG 축소가 ATX 파트(`# PART PG`)·항목(`#### PG-1`)을 떨구지 않는다(ATX 우선).
+
+pytest + 단독 실행 양쪽 지원:
+  PYTHONPATH=. python3 tests/hier_decomp/test_eng_matcher.py
+"""
+from __future__ import annotations
+
+try:  # pytest 경로 (앱 패키지)
+    from app.services.hier_decomp.builder import _detect_heading, build_hier_tree
+except Exception:  # 단독 실행 (앱 deps 없이 builder.py 직접 로드 — stdlib only)
+    import importlib.util
+    import pathlib
+    import sys
+
+    _bp = pathlib.Path(__file__).resolve().parents[2] / "app/services/hier_decomp/builder.py"
+    _spec = importlib.util.spec_from_file_location("_hier_builder_t", _bp)
+    _m = importlib.util.module_from_spec(_spec)
+    sys.modules[_spec.name] = _m  # dataclass __module__ 해소
+    _spec.loader.exec_module(_m)
+    _detect_heading, build_hier_tree = _m._detect_heading, _m.build_hier_tree
+
+
+# ── 음성: 본문 문장은 헤딩 아님 (가짜 절 차단 — D1 회귀의 핵심) ──
+NEG = [
+    "Part III to demonstrate to the satisfaction of the represen-",
+    "Section V of the agreement applies to all parties",
+    "Part IV is hereby amended as follows",
+    "Article II shall be interpreted broadly",
+    "Chapter 3 describes the general method used here",
+]
+
+# ── 양성: 진짜 영문 구조 헤딩 ──
+POS = [
+    "PART PG GENERAL REQUIREMENTS FOR ALL METHODS OF CONSTRUCTION",
+    "Part 1",
+    "Part PFH",
+    "Part UHX (TUBESHEET CALCULATION)",
+    "Section 3.31",
+    "Chapter 1 Introduction",
+    "Article 5 Definitions",
+]
+
+
+def test_eng_negatives_not_detected():
+    for line in NEG:
+        assert _detect_heading(line) is None, f"가짜 절로 잡힘: {line!r}"
+
+
+def test_eng_positives_detected_as_chapter():
+    for line in POS:
+        r = _detect_heading(line)
+        assert r is not None, f"진짜 헤딩 미탐지: {line!r}"
+        _lvl, _title, nt = r
+        assert nt == "chapter", f"{line!r} node_type={nt}"
+
+
+def test_atx_part_and_item_still_detected():
+    # _ENG 축소가 진짜 ATX 파트/항목을 떨구지 않음 (ATX 우선 탐지)
+    r = _detect_heading("# PART PG GENERAL REQUIREMENTS FOR ALL METHODS OF CONSTRUCTION")
+    assert r is not None
+    lvl, title, nt = r
+    assert lvl == 1 and nt is None, r  # ATX = level(# 수), node_type None
+    assert title.startswith("PART PG")
+    r2 = _detect_heading("#### PG-1 SCOPE")
+    assert r2 is not None and r2[0] == 4 and r2[2] is None, r2
+
+
+def test_build_hier_tree_drops_false_part_section():
+    # 본문에 'Part III to demonstrate…' 가 섞여도 가짜 절이 생기지 않음
+    md = (
+        "# PART PG GENERAL REQUIREMENTS\n"
+        "#### PG-1 SCOPE\n"
+        "The rules cover power boilers.\n"
+        "Part III to demonstrate to the satisfaction of the representative\n"
+        "that the requirements are met, the manufacturer shall proceed...\n"
+        "#### PG-2 SERVICE LIMITATIONS\n"
+        "body of pg-2 here.\n"
+    )
+    titles = [n.section_title for n in build_hier_tree(md) if n.section_title]
+    assert any(t.startswith("PART PG") for t in titles), titles
+    assert any(t.startswith("PG-1") for t in titles), titles
+    assert any(t.startswith("PG-2") for t in titles), titles
+    assert not any("demonstrate" in (t or "") for t in titles), f"가짜 절 누출: {titles}"
+
+
+if __name__ == "__main__":
+    import sys
+    import traceback
+
+    fns = [(k, v) for k, v in sorted(globals().items()) if k.startswith("test_") and callable(v)]
+    failed = 0
+    for name, fn in fns:
+        try:
+            fn()
+            print(f"PASS {name}")
+        except Exception as e:
+            failed += 1
+            print(f"FAIL {name}: {e}")
+            traceback.print_exc()
+    print(f"\n{len(fns) - failed}/{len(fns)} passed")
+    sys.exit(1 if failed else 0)