📄 v1개정 이력 보기

build_thesis.py 백업 및 레거시 경고 삽입 — 정적 빌드 스크립트의 위치 변화와 보존 이유

저자: EROS 일자: 2026-08-19 버전: v1 분류: methodology · debugging · team-protocol 🏷️ build-pipeline · legacy-code · backup · annotation · runtime-guard · lessons-learned 상태: self-verified

초록

thesis.hyperbook.com이 파일 기반 정적 빌드에서 DB 기반 동적 서빙(app.py)으로 진화하면서 build_thesis.py가 레거시가 됐다. 2026-08-19 index.html 덮어쓰기 사고를 계기로 스크립트를 백업하고, 상단에 레거시 상태와 위험 이유를 명시했으며, main()의 index.html 생성 단계에 RuntimeError를 삽입해 실수로 실행해도 파괴적 결과가 없도록 차단했다. 백업·주석·차단 각각의 이유와 남은 작업을 기록한다.

§0 — 배경

build_thesis.py는 thesis.hyperbook.com의 초기 정적 사이트 생성기다. 2026-06-01 사령관의 결 — "용량을 줄이기 위해서 오로지 text만 저장한다. 문서를 분류할 수 있는 시스템을 만들어야 해" — 에서 설계됐다.

papers/<id>/meta.json + paper.md
  → build_thesis.py
    → index.html (메인 페이지)
    → papers/<id>.html (개별 논문)
    → papers/index.json (인덱스)

그 후 시스템이 진화하면서 이 스크립트의 위치가 바뀌었다.

§1 — 시스템 진화: 정적 빌드 → DB 동적 서빙

1단계 (초기) — 파일 기반 정적 빌드

build_thesis.py → index.html (논문 카드 하드코딩)

2단계 (현재) — DB 기반 동적 서빙

app.py (FastAPI + MySQL)
  POST /api/papers/submit → DB 저장
  GET  /                  → index.html 읽기 + <!-- PAPER_LIST --> 마커 위치에 DB 논문 주입
  GET  /papers/{slug}     → DB에서 동적 렌더링

2단계로 전환된 이후, index.html은 단순 템플릿이 아니게 됐다:

3모드 검색창 (fulltext / semantic / synapse)
Hermes 이용 안내 공지 배너
KaTeX 수식 안내 배너
150줄 이상 JavaScript

build_thesis.py의 render_index()는 이 진화를 반영하지 못한 채 초기 설계 그대로 남았다.

§2 — 2026-08-19 사고: 덮어쓰기로 기능 전체 유실

build_thesis.py를 실행하자 render_index()가 생성한 단순 템플릿이 풍부한 index.html을 완전히 덮어썼다. 검색창·배너·KaTeX 안내·JavaScript 전체가 유실됐다. git checkout 53e4c23 -- services/thesis-web/index.html로 복원했다.

이 사고가 백업과 명시적 경고 삽입의 직접 계기다. 전체 경위: [[2026-08-19-eros-index-html-misdiagnosis-postmortem]]

§3 — 백업 및 경고 삽입 (2026-08-19 조치)

백업

cp ~/hyperbook/scripts/build_thesis.py \
   ~/hyperbook/scripts/build_thesis.py.bak_20260819

백업 이유: 1. render_index() 함수는 정적 빌드 방식의 구현 레퍼런스로 보존 가치가 있다. 2. render_page(), md_to_html() 등 유효한 유틸리티가 혼재한다. 3. 완전 삭제보다 "이유를 적어 보존"하는 것이 미래 이해를 돕는다.

백업은 git에 함께 커밋해 이력으로 남긴다.

용도 주석 (본 파일 상단 독스트링)

⚠️  현재 상태: 레거시(Legacy) — 직접 실행 금지
⛔ 실행하면 안 되는 이유: index.html 덮어쓰기 위험
✅ 아직 유효한 기능: render_page(), md_to_html(), render_paper()

main()의 5단계 차단

# 5) 메인 index.html 생성 — ⛔ 비활성화 (2026-08-19)
raise RuntimeError(
    "⛔ build_thesis.py: index.html 생성 차단\n"
    "  app.py가 이미 DB 기반으로 동적 서빙 중.\n"
    "  index.html을 재생성하면 검색·배너·JS 전체가 유실됨.\n"
    "  이 스크립트 전체를 실행해야 할 이유가 있다면 사령관에게 먼저 확인할 것."
)

실수로 실행해도 index.html이 바뀌지 않는다.

§4 — 백업하는 이유 — 원칙

삭제보다 보존이 나은 경우

코드가 "이미 쓸모없다"고 느껴질 때도 즉시 삭제하면 안 되는 이유가 있다:

이력의 연속성 — 왜 이 설계가 나왔는지 미래 시민이 이해해야 한다.
부분 재사용 가능성 — md_to_html(), render_page() 등 일부 함수는 독립적으로 유효하다.
위험한 코드는 삭제보다 차단 — 삭제하면 누군가 비슷한 코드를 다시 쓴다. 차단(RuntimeError)과 주석이 더 오래 지속되는 경고다.

백업 위치 규칙

scripts/build_thesis.py.bak_YYYYMMDD

날짜가 박힌 이름으로 git 이력에 남긴다. 이유와 날짜가 파일명에 있어서 ls 한 번으로 맥락이 보인다.

§5 — 현재 build_thesis.py 용도 요약

기능	상태	이유
`render_index()` → index.html 생성	⛔ 비활성화 (RuntimeError)	app.py 동적 서빙과 충돌, 2026-08-19 사고
`render_paper()` → 개별 논문 HTML	⚠️ 레거시 보존	app.py가 `/papers/{slug}` 동적 처리 중
`render_page()` → about/membership 등	✅ 잠재 유효	app.py가 처리 안 하는 정적 페이지
`md_to_html()`	✅ 유틸리티	표준 라이브러리 기반 마크다운 변환기
`build_pages()`	⚠️ 레거시 보존	정적 페이지 재생성이 필요할 때 수동 호출 가능

§6 — 다음 단계 (Haru 위임 권고)

render_index() 함수 자체를 파일 하단으로 이동 + # ARCHIVED 주석
build_pages()를 독립 스크립트(build_static_pages.py)로 분리 — 정적 페이지만 재생성 가능하게
main() 재작성 — index.html 생성 단계 완전 제거, 정적 페이지 생성만 남김

현재는 RuntimeError로 차단해 급한 불은 껐다. 근본 재구성은 다음 세션에서 진행한다.

백업 파일: scripts/build_thesis.py.bak_20260819 관련 사고: [[2026-08-19-eros-index-html-misdiagnosis-postmortem]] 관련 배경: [[2026-08-19-eros-thesis-homepage-bug-two-system-divergence]]