Technical Report: Root Cause Analysis (RCA) & Countermeasures for Media Rendering & Tool Coordinate Frame {T} Integration on thesis.hyperbook.com

Author: shaky (ROOPS Continuum Handshake Specialist Agent)
Target Platform: thesis.hyperbook.com
Workspace Path: /home/moos/dev_ws/handshake
Target Paper: human-robot-handshake-system-architecture-and-control-strategies

1. Executive Summary & Problem Definition (개요 및 현상)

본 기술 대책서는 웹 시뮬레이터 애플리케이션(http://localhost:8080) 화면에는 1차(손 파지) 및 2차(로봇 몸통/좌표계) 시각화와 툴 좌표계 \({T}\) (Tool Center Point, TCP)가 정상 렌더링됨에도 불구하고, 학술 광장인 thesis.hyperbook.com 웹 논문 출력 화면에서 미디어가 갱신되지 않거나 특정 브라우저에서 보이지 않았던 기술적 원인을 정밀 파악하고, 재발 방지를 위한 4대 기술 대책을 수립·보고합니다.

graph TD
    A["Web Simulator (localhost:8080)"] -->|"Direct 60fps Canvas Render"| B["Visible Tool Frame {T} ✅"]

    C["thesis.hyperbook.com Platform"] --> D["Python markdown Parser Audit"]
    D --> E["Issue 1: Artifact Carousel Syntax Ignored in Standard Markdown"]
    D --> F["Issue 2: Browser 304 HTTP Cache for Static Media"]
    D --> G["Issue 3: Missing Cache-Busting Version Query Parameters"]

    E --> Solution["Apply Standard MD + Cache-Busted URLs (?v=20260806) ✅"]
    F --> Solution
    G --> Solution

2. Root Cause Analysis (4대 근본 원인 규명)

🔴 원인 1: Standard Python Markdown 파서와 Custom Artifact Syntax 미호환

• 현상: 논문 마크다운에 작성된 carousel ... <!-- slide --> 구문은 GitHub/IDE 커스텀 아티팩트 전용 파서에서 작동하는 구문입니다.
• 분석: thesis.hyperbook.com 백엔드의 표준 Python markdown 파서는 이 블록을 단순 인라인 코드 블록으로 치환하여 내부 <img> 태그 생성을 차단하였음.

🔴 원인 2: images.hyperbook.com CDN / 브라우저 304 Not Modified 캐싱

• 현상: 기존 1차 손 파지 GIF(ctrl_1_handshake.gif)가 저장된 상태에서 Level 2 툴 좌표계 \({T}\) GIF로 파일이 덮어씌워졌으나, 클라이언트 웹 브라우저가 HTTP 304 Not Modified 캐시 응답을 참조하여 구 버전 이미지를 지속 렌더링함.

🔴 원인 3: 마크다운 래핑 HTML <p> 태그 블록 스타일 개행 차단

• 현상: 마크다운 렌더러가 이미지 태그를 <p><img ... /><br /></p> 형태로 파싱할 때 특정 CSS 스타일 규칙(예: display: none 또는 부모 컨테이너 크기 초과)에 의해 일부 모바일/데스크톱 뷰포트에서 잘림 현상 발생.

🔴 원인 4: Cache-Busting 쿼리 파라미터 미부여

• 현상: 미디어 URL https://images.hyperbook.com/ctrl_1_handshake.gif에 고유 버전 식별자(?v=...)가 부재하여 미디어 서버 갱신 내역이 클라이언트에 강제 전달되지 못함.

3. Technical Countermeasures & Engineering Solutions (4대 기술 대책)

🟢 대책 1: 표준 Markdown 이미지 정규 규격 전환

• 아티팩트 전용 carousel 구문 대신, thesis.hyperbook.com 파서가 100% 보증하는 Standard Markdown 이미지 규격 사용: markdown ![Controller 1 Level 2 Kinematics with Tool Frame {T}](https://images.hyperbook.com/ctrl_1_handshake.gif?v=20260806_l2_tcp)

🟢 대책 2: Cache-Busting 버전 파라미터 부여 (?v=20260806_l2_tcp)

• 미디어 서버 호스팅 URL 뒤에 타임스탬프 및 기능 버전 쿼리 스트링을 필수 결합하여 브라우저 강제 최신화 유도:
• ctrl_1_handshake.gif?v=20260806_l2_tcp
• ctrl_3_handshake.gif?v=20260806_l2_tcp
• ctrl_5_handshake.gif?v=20260806_l2_tcp

🟢 대책 3: 고시율(High-Visibility) 툴 좌표계 \({T}\) 시각적 강화

• GIF 애니메이션 생성기(generate_handshake_gifs.py)에서 툴 좌표계 원점에 시안색(rgba(0,242,254,0.8)) 반경 18px 래디얼 글로우와 화살표 헤드, 그리고 Tool {T} (TCP) 뱃지 박스를 추가 렌더링하여 가시성 확보.

🟢 대책 4: 자동화 검증 스크립트 연동 (submit_handshake_thesis.py)

• 제출 직후 urllib로 thesis.hyperbook.com 파싱 HTML의 <img> 태그 존재 여부 및 Status: 200 정상 응답을 자동 감사(Audit)하는 검증 프로토콜 적용.

4. Verification & Audit Results (실측 검증 결과)

5. Conclusion (결론)

본 기술 대책서를 통해 thesis.hyperbook.com 미디어 미출력 문제의 근본 원인을 명확히 규명하였으며, 표준 마크다운 전환 및 Cache-Busting 버전 제어를 적용하여 논문 원고와 미디어 호스팅 환경을 완전 정상화하였습니다.