ROOPS RHMS 메타 척추망 4D 시각화 로딩 오류 검토 및 대응 보고서

저자 (Author): Vorno
공동 연구원: Geminy (geminy.hyperbook.com)
제출일: 2026-07-23
시스템: ROOPS Continuum / Geminy 3D Visualizer / RHMS Node

1. 개요 및 장애 현상 (Abstract)

geminy.hyperbook.com/viz/thesis-4d-meta 페이지 접속 시, 인터페이스 초기화 도중 브라우저 콘솔 및 UI 상에 SyntaxError: Unexpected token 'I', "Internal S"... is not valid JSON 오류가 출력되며 4D 메타 척추망의 렌더링이 전면 중단되는 현상이 발생했다.

본 보고서는 이 오류의 발생 경로를 추적하여 로컬 RHMS 서비스(rhms.service) 내부의 핵심 엔드포인트 누락 사실을 발견하고, 데이터베이스(rhms.db) 매핑 복구 및 핫픽스(Hotfix)를 적용하여 시각화 서비스를 정상화한 기술적 내역을 기록 및 보존한다.

2. 문제 원인 정밀 진단 (Root Cause Analysis)

2.1 예외 발생 메커니즘 추적

• 클라이언트: thesis-4d-meta 시각화 페이지 로드 시 내부 스크립트가 /layout?type=meta API를 백엔드에 쿼리함.
• 시각화 백엔드 (synapse_server.py): 메타 척추망 레이아웃 계산 함수 _layout_meta 내에서 아래와 같이 로컬 RHMS 노드의 도메인 분류 데이터를 요청함. python r_dom = requests.get("http://100.125.27.70:8090/domains?agent=moojoco", headers=headers, timeout=2) domains = r_dom.json()
• RHMS 서비스 (app.py): hb5u 로컬 서버에서 구동 중인 rhms.service(/home/moos/rhms/app.py)는 uvicorn 환경으로 포트 8090에서 실행 중이나, 코드 내에 /domains 엔드포인트가 아예 정의되어 있지 않아 404 Not Found ({"detail":"Not Found"}) JSON 데이터를 리턴함.
• 백엔드 TypeError 유발: r_dom.json()의 결과가 리스트가 아닌 단일 딕셔너리로 반환되자, synapse_server.py의 루프 구문 for d in domains가 딕셔너리의 Key 문자열("detail")을 순회하게 되었고, 이로 인해 did = d["domain_id"] (즉, "detail"["domain_id"]) 코드가 동작하면서 TypeError: string indices must be integers, not 'str' 예외가 최종 발생함.
• 최종 표출: 이 예외로 인해 synapse_server.py가 500 에러("Internal Server Error")를 텍스트로 보냈고, 브라우저가 이를 JSON으로 파싱하려다 첫 글자 'I'에 막혀 Unexpected token 'I' 에러를 표출함.

3. 대응 조치 및 핫픽스 적용 (Remediation)

3.1 SQLite DB 구조 검증

로컬 머신의 rhms.db에 테이블 구조를 파이썬을 통해 정밀 검증한 결과, sqlite3 데이터베이스에 100대 도메인 정보(C001–C100)를 온전히 보관하고 있는 domains 테이블이 정상 적재되어 있음을 발견했다: * 스키마: domain_id(TEXT), category_ko(TEXT), category_en(TEXT), parent_domain_id(TEXT), description(TEXT), keywords(TEXT)

3.2 /domains 엔드포인트 핫픽스 개발

/home/moos/rhms/app.py 소스 코드의 맨 마지막 라인에 데이터베이스의 domains 테이블을 실시간 질의하여 JSON 형태로 매핑/반환하고, auth 검증을 올바르게 통과하도록 설계된 새 엔드포인트를 핫픽스로 추가 이식했다:

@app.get("/domains")
def get_domains(agent: str = "moojoco", x_api_key: Optional[str] = Header(None)):
    auth(x_api_key, agent)
    with get_db() as conn:
        rows = conn.execute(
            "SELECT domain_id, category_ko, category_en, parent_domain_id, description, keywords FROM domains"
        ).fetchall()
    return [dict(r) for r in rows]

3.3 서비스 기동 및 실측 검증

• systemctl --user restart rhms.service 명령으로 로컬 RHMS 데몬을 재로드하여 핫픽스를 완전히 이식했습니다.
• curl을 통해 수동 쿼리를 진행한 결과, C001~C100 영역의 한글 분야명, 부모 도메인 구조 및 융합 카테고리가 JSON 데이터로 정상 서빙됨을 실측 확인했습니다.
• 이후 https://geminy.hyperbook.com/viz/thesis-4d-meta 메인 주소로 접근했을 때, 오류 차단 화면 없이 정상적으로 3D/4D 시냅스 척추망의 다차원 연결 관계가 WebGL 화면으로 원활하게 시각화됨을 확인 및 최종 종결했습니다.

4. 교훈 및 결론

• 분산 RHMS 아키텍처 환경에서는 Concept Node(도메인 정적 적재)와 Thesis Node(동적 논문 인코딩) 간의 API 프로토콜 싱크를 엄격하게 일치시키는 동기화 배포 체계가 필요합니다.
• 예기치 않은 404나 API 오류에 대비하여, 프론트엔드 및 시각화 백엔드 단에서 JSON 응답의 배열 형태 검증(isinstance(domains, list))과 같은 방어적 코드(Defensive Coding) 구조를 확립할 예정입니다.