Skip to content
geniuskeyPublic

About

Resources

Stars

8 stars

Watchers

0 watching

Forks

Latest commit

 

History

236 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Books

books.euiyun.com — 인터랙티브 웹 교과서 시리즈를 소개하는 사이트입니다. 시리즈는 두 갈래로 자랍니다: 일하는 지식(반도체·SW·AI·기기)과 살아가는 지식(돈·집·건강·취미).

페이지

파일 내용
index.html 홈. 첫 화면에 GA4 방문 통계, 아래로 내리며 보는 서가: 분야별 서가(조회수가 많은 분야부터, 분야마다 인기 상위 4권, 데스크톱에서는 두 서가씩 한 줄, ‘모두 보기’는 그 분야의 전체 책장). 질문으로 고른 대표 실험 6개와 저자 노트
/field/, /field/<분야 id>/ 예전 주소. 해당 지식 지도로 자동 이동
/library/ 전체 책장. 상단 즉시 검색, 분야 선택, 책별 즐겨찾기와 간결한 목록 (?field=life&q=전세처럼 주소로도 지정 가능)
/roadmap/ 로드맵. 전체·분야별 진행률, 다음 차례와 후속 후보, 만들고 싶은 시뮬레이터. 아이디어는 진행률에서 제외
/simulators/ 출간된 책의 전체 실험 검색. 일부 실험의 학습 질문·한영 동의어, 분야·교과서·난이도 열의 복수 선택 필터와 공유 가능한 검색 URL
/paths/ 지식 지도. 분야를 고르면 바로 탐색. ?field=semiconductor처럼 공유하며, 읽는 순서는 지도 아래에서 선택적으로 펼침
/feedback/ 전권 공통 독자 의견 창구. 오류 제보·건의·저자 응원을 로그인 없이 받고, GitHub 접수도 제공
/admin/ Google 로그인과 전체·비공개 글 조회를 위한 관리 화면. 기존 ?admin=1 주소도 이곳으로 이동

독자 의견 접수

모든 책의 상단 아이콘과 바닥글은 /feedback/?book=<책 id>&page=<현재 URL>로 연결됩니다. 로그인 없는 폼에서 오류 제보·의견·저자 응원을 받고, 닉네임은 선택 사항입니다. 공개 범위의 기본값은 비공개이며 공개를 선택한 글만 페이지의 독자 목록에 바로 표시합니다. 기존 접수 글과 공개 범위가 없는 구형 폼의 글은 비공개로 저장합니다. 책 ID와 URL의 출처는 브라우저와 Worker 양쪽에서 검증합니다. 전송에 실패하면 입력을 유지하고 같은 글의 재전송에는 같은 접수 ID를 사용합니다.

게시판의 ‘내 글 · 비공개 포함’에서 작성한 브라우저의 글을 다시 확인할 수 있습니다. 브라우저의 localStorage에 별도의 256비트 확인 키를 먼저 저장하고, 서버에는 SHA-256 해시만 기록합니다. 키는 조회 URL 대신 X-Feedback-Owner 헤더로 전달합니다. 공개 좋아요의 visitor ID와는 별개이며, 새로 작성한 글에만 적용됩니다. 브라우저 데이터 삭제·다른 기기·기능 도입 전 글은 복구할 수 없습니다. 저장소가 차단된 경우 현재 페이지에서만 조회할 수 있음을 접수 완료 시 안내합니다. DB에 0005_feedback_owner.sql을 적용한 뒤 Worker와 사이트를 배포합니다.

의견 작성 시 선택 이메일을 남길 수 있습니다. 이메일은 관리자 인증을 통과한 목록에만 포함되며 공개 목록과 내 글 응답에는 포함되지 않습니다. 자동 메일 발송은 하지 않으며, 관리자가 답장 이메일 링크로 연락할 수 있습니다. 0006_feedback_email.sql을 먼저 적용한 뒤 Worker, 정적 사이트 순서로 배포합니다.

게시판 상단에는 공개·비공개를 합친 전체 글 수를 표시합니다. 필터·페이지에 관계없는 누적 수이며 비공개 글의 내용이나 작성자는 공개하지 않습니다.

공개 글에는 로그인 없이 댓글(최대 1,000자, 닉네임 선택)과 좋아요를 남깁니다. 댓글은 최신순으로 20개씩 불러오며 실패한 댓글을 다시 보내도 중복 저장하지 않습니다. 좋아요는 브라우저의 localStorage에 보관하는 임의 UUID별로 한 번 누르거나 취소합니다. 계정 인증이 아니므로 브라우저 변경·저장소 삭제에 따른 중복까지 막지는 않으며, 저장소를 사용할 수 없으면 현재 페이지에서만 식별자가 유지됩니다. IP는 저장하지 않습니다. 비공개·숨김 글은 댓글·좋아요 API에서도 차단합니다. 댓글·좋아요 쓰기 요청에도 기존 접수 빈도 제한을 함께 적용합니다.

관리자는 /admin/의 ‘관리자 로그인’에서 Google 로그인하고 전체·비공개·공개 글을 조회합니다. 글과 댓글의 HTTP(S) URL 및 www 주소는 자동으로 링크로 표시합니다. 관리자가 비공개 글을 공개로 바꾸는 기능은 제공하지 않습니다. 공개 조회 API는 페이지 URL과 관리자 상태를 반환하지 않습니다. 관리자용 API는 모든 조회마다 Google 서명·발급자·클라이언트 ID·만료·검증된 이메일을 서버에서 확인합니다. geniuskey@gmail.com만 허용합니다. 토큰은 sessionStorage에 보관해 /admin/을 새로고침하면 서버 검증을 거쳐 복원합니다. Google 토큰의 실제 만료 시각에 해제하며 로그아웃하면 저장된 토큰도 삭제합니다. 저장소를 사용할 수 없으면 현재 페이지에서만 유지됩니다. 관리는 /admin/에서만 하며, 이 페이지에는 Google 애널리틱스를 넣지 않습니다. 애널리틱스가 있는 다른 페이지는 GA보다 먼저 저장된 관리자 토큰을 삭제하므로, 같은 탭에서 다른 페이지로 이동하면 관리자 로그인이 해제됩니다. /feedback/에서는 관리자 로그인과 세션 복원을 하지 않으며 관리자 이름으로 글을 쓰려면 /admin/을 이용합니다. 관리 화면 HTML은 python3 tools/build-admin.py로 독자 의견 화면에서 생성합니다.

관리자로 로그인해 작성한 글과 댓글은 서버에서 Google 인증을 확인해 is_admin을 저장하고, 닉네임 대신 색상 배지 ‘관리자’를 표시합니다. 일반 독자가 같은 닉네임을 입력해도 배지는 붙지 않습니다. 0004_admin_authors.sql은 작성자가 확인한 기존 Edwin 글 한 건도 고유 ID로 지정해 관리자 표시를 적용합니다.

관리자 Google 로그인 설정

Google Identity Services 설정 안내에 따라 웹 애플리케이션 OAuth 클라이언트를 생성하거나 기존 클라이언트를 사용합니다. 승인된 JavaScript 원본에 https://books.euiyun.com을 등록합니다. 팝업 콜백 방식을 사용하므로 리디렉션 URI와 클라이언트 보안 비밀번호는 필요하지 않습니다. 동의 화면이 테스트 상태이면 관리자 계정을 테스트 사용자로 추가합니다.

같은 클라이언트 ID를 data/feedback-config.json의 googleClientId와 worker/wrangler.jsonc의 GOOGLE_CLIENT_ID에 설정하고 Worker와 정적 사이트를 함께 배포합니다. 도메인 등록만으로는 클라이언트 ID가 만들어지지 않습니다. ID 미설정 시 관리자 API는 503을 반환하고 로그인 UI는 준비 중 안내를 표시합니다. Google ID 토큰 검증은 공식 검증 지침을 따르며 jose로 Google JWKS를 검증합니다. 프런트엔드에서 이메일을 읽어 권한을 결정하지 않습니다.

기존 GitHub 창구도 유지합니다. 중앙 geniuskey/books의 .github/ISSUE_TEMPLATE/ 양식에 책·페이지 입력란을 미리 채웁니다. GitHub 접수는 로그인과 공개 글 작성이 필요합니다. 개별 답변은 약속하지 않습니다.

Cloudflare D1 접수 API

정적 사이트는 GitHub Pages에 두고, worker/의 Cloudflare Worker가 POST /api/feedback을 처리합니다. D1 바인딩·마이그레이션은 Cloudflare 문서, 연속 제출 제한은 Rate Limiting 문서를 따릅니다. 제한은 Cloudflare 위치별로 IP당 5회/분, 전체 100회/분이며 완전한 봇 차단을 보장하지 않습니다. IP는 접수 DB에 저장하지 않습니다. SQL 매개변수 바인딩, 요청 크기·필드 길이 제한, 허용 출처 검사와 숨겨진 스팸 입력란을 사용합니다.

초기 설정 (Node.js 24 이상 권장):

cd worker
npm ci
npx wrangler login
npx wrangler d1 create books-feedback

현재 설정은 운영 D1 books-feedback에 연결되어 있습니다. 다른 계정에서 처음 설정할 때는 생성 결과의 database_id를 worker/wrangler.jsonc에 넣습니다. 이미 같은 이름의 DB가 있으면 npx wrangler d1 list로 확인하고 해당 ID를 사용하세요. 계정 내 다른 Rate Limiting 바인딩과 namespace ID가 겹치지 않는지도 확인합니다.

# 댓글·좋아요 테이블(0003_reactions.sql)을 포함해 먼저 적용
npm run migrate:remote
npm run deploy

배포 출력의 Worker URL에 /api/feedback을 붙여 data/feedback-config.json의 endpoint를 채웁니다. 사이트 변경을 배포하기 전에 실제 접수와 D1 저장을 확인하세요. endpoint가 비어 있거나 설정을 불러오지 못하면 폼은 전송을 막고 GitHub 창구를 안내합니다. API는 https://books.euiyun.com에서의 요청만 허용합니다. 토큰·비밀 키를 프런트엔드나 저장소에 넣지 않습니다.

로컬 개발:

cd worker
npm test
npm run migrate:local
npm run dev -- --var ALLOWED_ORIGINS:http://localhost:8000

정적 사이트는 별도 터미널에서 python3 -m http.server 8000으로 실행합니다. 로컬에서만 endpoint를 http://localhost:8787/api/feedback으로 바꿔 사용하고 배포 전 실제 Worker 주소로 복원합니다. 테스트는 저장·중복 방지·필드/출처 검증·요청 크기·연속 제출 제한·DB 장애를 확인합니다.

저자는 Cloudflare 대시보드의 D1 books-feedback에서 feedback 테이블을 확인하거나 다음 명령을 사용합니다. 조회 결과에는 독자가 남긴 비공개 글이 포함되므로 공개 이슈 등에 그대로 옮기지 않습니다.

cd worker
npx wrangler d1 execute DB --remote --command "SELECT type, nickname, message, book_id, page_url, created_at FROM feedback ORDER BY created_at DESC LIMIT 50"

실행

빌드 과정이 없는 정적 사이트입니다. fetch로 JSON을 읽으므로 로컬에서는 서버로 띄웁니다.

python3 -m http.server 8000   # → http://localhost:8000

코드 구조

  • js/core.js — 데이터 로딩, 머리말·꼬리말, 책 카드, 진행률 막대 (모든 페이지 공통)
  • js/wafer.js — 웨이퍼 맵 (분야 하나 / 전체 부채꼴 모드)과 분야 카드용 작은 웨이퍼
  • js/covers.js — 책 표지 일러스트
  • js/home.js, js/field.js, js/library.js, js/roadmap.js — 페이지별 렌더링
  • js/field-maps.js — 분야별 지도 제목·대분류·책 배치·연결 설명. 반도체 분류는 books.json의 stages를 사용하며, 새 책은 분류 지정 전에도 탐색 그룹에 표시됩니다.
  • css/style.css — 각 교과서와 같은 디자인 토큰을 쓰는 공통 스타일

데이터: data/books.json

사이트가 읽는 책 목록입니다. 실험 탐색과 학습 경로는 아래의 편집 데이터도 사용합니다.

서가에서 가져오기: tools/sync-books.py

서가 저장소(../<서가>)에 있는 책의 사실은 서가가 원본입니다. 제목·부제·소개·상태·주소·장과 시뮬레이터 수·색·주제·표지 무늬·코드가 여기에 해당합니다. 서가에서 바꾼 뒤 python3 tools/sync-books.py로 books.json에 옮기고, --check로 어긋난 값만 볼 수 있습니다. 책은 checkout(<서가>/<slug>)으로, 없으면 ID로 맞춥니다. 서가는 catalog.json(format: euiyun-shelf/1)을 읽고, 아직 없으면 catalog.js를 읽습니다.

  • 허브 전용 값(field, featured, en, legacyUrls, level, checkout)은 건드리지 않습니다.
  • 이 사이트에서만 다르게 쓰는 값은 책의 keepLocal에 적습니다. 예: 코드가 겹치는 AnatomyBook ANT, MaterialsBook CMT.
  • 집필 예정 책에는 주소와 장·시뮬레이터 수를 옮기지 않습니다.
  • 서가 카탈로그에 map이 있으면 그 분야의 묶음(fields[].stages), 지도 연결(fields[].map)과 책의 stage도 서가에서 가져옵니다. 지금은 모든 분야가 이 방식입니다. 한 분야에 서가가 여럿이면(culture = music + art, electronics = system) 묶음을 서가의 첫 책 순서대로 잇고 연결을 합칩니다. 제목·설명은 서가가 하나일 때만 서가에서 오고, 여럿이면 js/field-maps.js에 둡니다. 서가 밖 책(ElectricBook)은 fields[].hubStages의 허브 묶음을 쓰고 책의 stage를 허브에서 정합니다. 연결의 책 ID가 허브와 다르면(SciBook color → colorbook) 허브 ID로 바꿉니다. js/field-maps.js에는 배치 좌표(regions), 여러 서가를 아우르는 제목·설명, 서가 밖 책의 연결만 남습니다.
  • science-books는 자기 catalog.json을 따로 쓰므로 빌드(python3.12 tools/build.py)가 만드는 shelf.json을 읽습니다. 과목명·설명·상태·주소·장과 시뮬레이터 수, 분야별 묶음과 지도(catalog.json의 map)가 오고, 코드·표지는 허브가 관리합니다. art-books는 tools/sync-catalog.py가 각 책 book.json(이름·설명·표지 값)에서 catalog.json을 만듭니다.

서가 홈 공통 코드: tools/shelf-kit/

아홉 서가(medical·math·construction·money·computing·semi·music·system·art)의 첫 화면은 같은 코드를 씁니다. 원본과 서가 안 사본은 다음과 같습니다.

원본(books) 서가 안 사본
tools/shelf-kit/shelf.js shared/js/shelf.js
tools/shelf-kit/shelf.css shelf.css
js/covers.js(허브 표지) shared/js/covers.js
css/cover-animations.css(허브 표지 움직임) shared/css/cover-animations.css

고친 뒤 python3 tools/sync-shelf-kit.py로 형제 폴더에 복사하고 서가마다 커밋합니다. --check는 어긋난 사본만 보여 줍니다. 서가마다 다른 값은 각 서가 catalog.js의 window.SHELF(book.json의 제목·주소·coverTitles·map·themeKey·readLink)로 받고, 서가 고유 스타일은 shelf-local.css에 둡니다(semi: 본문 검색·7열 책장, music: 2열 실험, art: 전시실 벽·7열 책장). 본문 검색이 있는 서가는 SHELF_SEARCH_HITS·ShelfSearch·shelf:search로 공통 코드와 이어집니다. 테마 저장 키는 서가 주소의 첫 이름(medical-theme 등)이고 art는 ab-theme입니다. science-books는 첫 화면 디자인이 달라 공통 코드를 쓰지 않습니다.

  • 매일 KST 05:41에 .github/workflows/sync-books.yml이 --remote --hold-publish로 공개된 서가 카탈로그(https://<서가>/catalog.json, 없으면 catalog.js)를 읽어 바뀐 값을 커밋합니다. 출간 상태로 바뀌는 책은 실험 수집·읽기 경로·OG 이미지가 함께 필요하므로 상태·주소·장 수를 그대로 두고 실행 요약에 알립니다. 그 책은 형제 폴더를 받아 python3 tools/sync-books.py로 직접 출간 처리합니다.

  • wings — 두 갈래 (work, life)

  • fieldAliases — 이전 분야 ID를 통합 분야로 연결 (ai → computing, housing → money, art → culture).

  • fields — 분야. id, wing, name, en, desc, color, colorDark, 선택적으로 stages(지도 묶음. 반도체는 직접, 서가 지도가 있는 분야는 sync-books.py가 채움)와 map(서가 지도의 제목·설명·연결)

  • books — 책. 같은 분야 안에서는 배열 순서가 추천 읽기 순서이자 웨이퍼를 채우는 순서입니다.

  • phases — 로드맵 단계 (1 다음 차례, 2 후속 후보). 집필 중인 책을 포함해 다음 차례는 최대 3권

  • statusLabels — 상태 표시 문구 (published 출간, writing 집필 중, planned 집필 예정)

  • tools, author — 도구·데이터 목록, 저자 노트

책 필드

필드 설명
id, code 저장소 이름, 웨이퍼 다이에 표시할 3글자 코드 (겹치지 않게)
title, subtitle, description 이름, 부제, 소개
en 출간된 책의 영문 title·description. euiyun.com 영문 페이지가 빌드할 때 읽으므로 출간할 때 함께 채웁니다
field, stage 분야 id, (단계가 있는 분야라면) 단계 id
status, phase 상태, 로드맵 단계
ideas 집필 예정 책에서 만들고 싶은 시뮬레이터
headline, url, repo 출간·집필 중인 책의 한 줄 문구, 사이트 주소, GitHub 주소
legacyUrls 서가를 옮기기 전의 옛 사이트 주소. 조회수 집계(tools/build-analytics.py)에서 같은 책으로 합칩니다. 책 주소를 바꾸면 이전 url을 여기에 추가하세요
chapters, simulators, level, topics 출간된 책의 챕터 수, 시뮬레이터 수, 난이도, 주제어
color, colorDark 책 대표색 (없으면 분야 색). 기본은 각 책 사이트의 --accent지만, 같은 분야에서 비슷한 색이 겹치면 이 사이트에서만 다른 색으로 바꿔 씁니다
motif 표지 일러스트 (memory, pixel, layers, attention, aperture, logic, circuit, package, car, wafermap, litho, probe, soc, subpixel, shmoo, lens, network, matrix, umbrella, house, ripple, transform, brackets, digital, fab, process, etch, guitar, piano, drums, bass, linear, calculus, ode, numerical, beam, concrete, soil, tower, rebar, bridge, crane, bim; 과목 ID와 같은 SciBook 표지; 없으면 기본 격자). 새 그림은 js/covers.js에 추가하고 움직임은 css/style.css의 표지 애니메이션에 둡니다. fab·process·etch는 SemiBooks, guitar·piano·drums·bass는 MusicBooks, linear·calculus·ode·numerical은 MathBooks, beam·concrete·soil·tower·rebar·bridge·crane·bim은 ConstructionBooks와 같은 코드를 씁니다
featured 대표 시뮬레이터: title, desc, link(책 주소 기준 상대 경로, 예: chapters/hbm.html#sim-h3), image(img/sims/ 아래 캡처)

새 주제는 먼저 data/editorial-backlog.json에 아이디어로 보관합니다. 독자 한 유형, 기존 책으로 해결되지 않는 질문, 차별화된 대표 실험을 정한 뒤 books.json에 status: "planned"로 올립니다. 쓰기 시작하면 writing, 출간하면 published로 바꾸며 주소와 숫자를 채웁니다.

data/editorial-backlog.json은 공개 책장·분야 지도·진행률에 포함하지 않는 편집 자료입니다. 원래 책 정보와 통합 대상·이유, 제거한 분야를 보관합니다. merge는 통합 방향이며 본문 반영 완료를 뜻하지 않습니다. idea는 보류 아이디어, removed-field는 제거한 세금·법 분야의 주제입니다. GPUBook은 GPU 실행 구조와 병렬 컴퓨팅으로 범위를 좁혔고, NPU는 SoCBook 심화 섹션으로 계획합니다.

상단 검색창은 입력 즉시 책 이름·분야·주제에서 관련 검색어를 최대 8개까지 드롭다운으로 제안합니다. 클릭하거나 ↑·↓로 고른 뒤 Enter를 누르면 해당 검색어로 검색하며, Esc나 바깥 클릭으로 닫습니다. 한글 조합 중에는 Enter로 검색하지 않습니다. 검색은 /library/?q=검색어로 연결하며, 전체 책장에서는 입력 즉시 현재 필터 안에서 검색합니다.

분야는 반도체, 기초과학·공학, 수학, 건설·건축, 컴퓨터·AI, 기기·시스템, 돈·부동산, 건강, 예술·교양의 9개로 구성합니다. 기존 주제는 지식 지도의 내부 분류로 유지하며, 이전 분야 URL은 통합 분야로 연결합니다.

홈은 사전 지식 없이 시작하기 좋은 출간 도서 10권을 js/home.js의 starterPicks 순서로 소개합니다. PC에서는 5권씩 두 줄로, 작은 화면에서는 같은 두 줄을 좌우로 넘기며 볼 수 있습니다. 책마다 짧은 추천 문구를 표시합니다. 분야 선택은 /paths/?field=<id> 지식 지도로 연결합니다. 전체 책장 상단에도 선택한 분야의 지도 링크를 표시합니다. 홈에서는 분야별 전권 목록을 따로 펼치지 않습니다.

전체 책장이 책의 전체 목록과 상세 정보를 모아 제공하는 곳입니다. 한글 제목이 있는 세로 표지를 화면 너비에 따라 6·4·3·2열로 진열하고 책 이름과 짧은 소개를 표시합니다. ‘상세 보기’에서 책 소개·주제 태그·챕터 정보와 집필 예정 책의 실험 아이디어를 펼칩니다. 표지에 마우스를 올리거나 키보드로 초점을 맞춰도 소개를 볼 수 있습니다. 분야 버튼, 갈래·상태 필터와 즐겨찾기를 제공합니다. 표지를 우클릭하면 즐겨찾기를 추가·해제할 수 있습니다. 키보드는 Shift+F10, 터치는 길게 누르기를 지원하며 기존 즐겨찾기 저장 키를 유지합니다.

상단 메뉴는 교과서 찾기·지식 지도·실험 찾기·독자 의견으로 구성합니다. /paths/는 지도를 기본 화면으로 바로 보여 줍니다. 상단은 제목과 분야 선택만 두며, 반복되는 소개·진행률·보기 전환 탭은 표시하지 않습니다. 분야는 ?field=<id>로 공유하고 새로고침·뒤로 가기에도 유지합니다. 이전 ?view=map&field=<id> 주소도 지원합니다.

지식 아틀라스는 주제별 영역과 책을 2차원 공간에 배치하고, 함께 살펴볼 책을 곡선으로 연결합니다. 선은 필수 학습 순서를 뜻하지 않습니다. 책을 선택한 뒤에만 지도 아래에 소개·연결 이유·읽기 링크를 표시하며, 상단의 선택한 책 링크로 소개에 이동할 수 있습니다. Tab과 방향키로 책 사이를 이동하고 Enter로 선택하며 Esc로 선택을 해제합니다. 확대·축소·전체 보기, 마우스로 빈 공간 끌기, 터치·스크롤 이동을 지원합니다. 모바일에서도 지도 좌표를 유지합니다. 조작법은 지도 아래 ‘지도 보는 법’에 접어 둡니다. 기존 #card-<book-id> 링크는 해당 책을 선택해 보여줍니다.

추천 읽기 경로는 지도 아래 ‘읽는 순서도 보고 싶다면’에 접어 두고 선택한 분야에 관련된 경로만 표시합니다. 각 경로는 짧은 질문과 한글 책 이름을 잇는 시각적인 순서로 요약하며, 자세한 연결 이유는 경로를 펼치면 볼 수 있습니다. 이전 읽기·실험 경로 해시 주소는 해당 분야를 선택하고 필요한 접힌 영역을 자동으로 엽니다. 지도는 읽기 경로 데이터 응답을 기다리지 않고 표시하며, 경로 로딩에 실패해도 지도는 사용할 수 있습니다.

지도 분류와 책 사이의 연결 이유는 js/field-maps.js에서 관리합니다. links는 [책 ID, 책 ID, 연결 이유] 배열이며, 지도 선은 현재 분야 안의 연결을 표시합니다. 분야를 넘는 관계는 같은 파일의 FIELD_MAP_CROSS_LINKS에 한 번만 등록하며 양쪽 책의 ‘함께 살펴볼 책’에 표시합니다. 다른 분야의 책을 누르면 해당 지도로 이동해 그 책을 선택합니다. 연결 목록에는 집필 상태를 표시하고, 기본적으로 PC 6권·모바일 2권 이후는 펼쳐 봅니다.

연결은 두 책의 목차·소개에 공통 개념, 구체적인 구현 관계, 또는 기술과 산업·활용의 접점이 있을 때 추가합니다. 단순히 같은 분야이거나 일반적인 수학·경제 지식이 도움이 된다는 이유만으로 연결하지 않습니다. 필수 선수 과목이나 집필 순서가 아닌 양방향 탐색 관계입니다. 출간 전 책은 공개된 기획 범위까지만 연결합니다. 2026-10-17 검토에서는 메모리–산업, 설계–공정, 테스트–불량 분석 등 누락을 보강하고, ‘비율과 함수’만을 근거로 한 수학–카메라 연결은 제외했습니다. 테스트–산업 등 기존 연결은 실제 공통 주제가 드러나도록 설명을 구체화했습니다. node tools/check-field-maps.cjs로 책 ID, 분야, 중복·자기 연결, 분류 누락을 검사합니다.

regions는 선택적인 [왼쪽 좌표, 위쪽 좌표, 책 열 수] 배열로 분류 순서에 대응합니다. 지정하지 않으면 분류 개수에 맞춘 기본 배치를 사용합니다. 반도체 분류는 계속 books.json의 stages를 따릅니다. 책을 추가하면 주변 영역과 겹치지 않는지도 확인해 주세요.

‘이 분야 책 전체 보기’는 /library/?field=<id>&status=all로 연결합니다. 아직 읽을 수 없는 책은 해당 분야와 책 이름으로 필터한 전체 책장으로 연결합니다. 홈의 별도 분야 카드와 상단 분야 드롭다운은 제거했습니다. 분야 분류는 책장·실험 필터와 지도 선택에 사용합니다.

OpticsBook을 출간해 반도체 분야의 기초 물리로 분류했습니다. 이미지 센서 개발에 필요한 회절·PSF·MTF, 박막, 마이크로렌즈·픽셀 광학 스택·입사각·광학 크로스토크를 다루며, SensorBook의 센서 구조·회로·신호 처리 설명을 광학 원리와 설계 변수로 보완합니다. 읽기 경로 lens-to-pixel은 OpticsBook에서 SensorBook으로 이어집니다. 현재 다음 차례(1단계)에는 책이 없고, ElectricBook·StatBook 등은 후속 후보입니다.

og.png(공유 미리보기 이미지)는 tools/og.html을 python3 tools/build-og.py(Playwright 필요)로 캡처한 것입니다. 책장과 숫자를 data/books.json·data/experiment-catalog.json에서 읽으므로 책을 출간한 뒤 다시 실행해 주세요. img/sims/의 시뮬레이터 화면은 캡처 이미지라 시뮬레이터가 바뀌면 다시 캡처해 주세요. 시뮬레이터 캡처는 각 책 페이지에서 #sim-… .sim-view 영역을 가로 720px JPEG로 저장한 것입니다.

실험 탐색 데이터

책장은 출간·집필 중·집필 예정 책을 함께 표시하며, 분야와 검색어로 목록을 좁힐 수 있습니다. 일하는 지식·살아가는 지식은 책장의 갈래 필터로 유지하고, 실험에는 분야를 가로지르는 개념 태그를 여러 개 붙입니다.

  • data/experiment-catalog.json: 형제 폴더의 출간된 책에서 실험 앵커와 제목을 수집한 스냅샷입니다. 각 책의 HTML이 바뀌면 다시 수집합니다.
  • data/learning.json: 개념 ID·한영 동의어, 일부 실험의 학습 질문·개념 연결, 명시적인 학습 경로. 책 배열의 진열 순서와 경로의 순서는 독립입니다.
  • data/model-validation.json: 기준 사례를 실제 책의 계산 함수에 실행한 기록입니다. 확인 날짜·범위·담당 방식·소스 해시·입출력 사례를 보관합니다.
  • data/discovery.json, data/paths.json: tools/build-discovery.py가 만드는 생성 파일. 직접 수정하지 않습니다. discovery.json은 /simulators/의 검색용 실험 목록이고, paths.json은 /paths/의 읽기·실험 경로입니다. 페이지마다 필요한 파일만 받도록 나눴습니다.
    • 내려받는 크기를 줄이려고 공백 없이 저장하고, 페이지가 books.json으로 복원할 수 있는 값은 뺍니다. 빼는 값은 bookId(ID 앞부분), url(책 URL + chapters/<chapter>.html#<anchor>, 다른 형태일 때만 link를 남김), level(책 난이도), 그리고 빈 값과 기본값(reviewStatus: unreviewed)입니다.
  • 실험 ID는 bookId/chapterName/anchorId입니다. 기존 앵커를 바꾸면 연결된 메타데이터와 외부 링크도 함께 마이그레이션해야 합니다.
  • reviewStatus: unreviewed는 계산 모델의 검증을 완료하지 않았다는 내부 상태입니다. reference-checked는 기록된 입력과 경계값의 계산만 통과했다는 뜻이며, 실제 현상에 대한 예측력이나 전체 화면 조작을 보증하지 않습니다. 검색 등록이나 링크 확인만으로 상태를 변경하지 않습니다.
  • 검색은 전체 실험의 제목·책 이름과, 보강된 일부 실험의 설명·질문·개념 동의어를 대상으로 합니다. 모든 챕터 본문을 검색하는 기능은 아직 없습니다. 난이도는 개별 실험 평가가 아닌 책 메타데이터입니다.
python tools/collect-experiments.py  # 형제 폴더에 출간된 책 저장소가 있을 때
python tools/build-discovery.py
python tools/check-discovery.py
node tools/check-models.cjs

검사기는 ID 중복, 참조, 이미지, 생성 데이터 동기화와 등록된 기준 사례를 확인합니다. 형제 폴더에 책 저장소가 있으면 챕터·앵커·계산 함수·함수별 해시를 확인하고, 없는 책은 미확인 개수를 보고합니다. check-models.cjs 실행에는 Node.js가 필요합니다. 책 메타데이터의 시뮬레이터 수는 기존 수기 숫자이며 검색 결과 개수는 실제 앵커 수입니다. 실제 배포 URL 가용성과 모델의 물리적 정확성은 별도 확인 대상입니다.

새 계산 모델을 reference-checked로 표시하려면 model-validation.json에 실험의 전체 ID, 확인 날짜, 검증 범위와 한계, 검토 당시 파일의 SHA-256(sourceSha256), 함수별 SHA-256(functionSha256), 알려진 기준값과 경계 조건을 기록하고 check-models.cjs에 해당 함수 실행 경로를 연결합니다. 함수별 해시는 CRLF를 LF로 정규화하여 소스를 로드한 뒤 Function.prototype.toString.call(함수)의 UTF-8 SHA-256으로 계산합니다. 등록된 계산 함수가 바뀌면 검사가 실패하므로 사례를 다시 검토한 뒤 함수 해시와 확인 날짜, 파일 해시를 갱신합니다. 파일 전체 해시는 검토 이력으로 보관하며 메뉴·툴팁 등 화면 코드 변경만으로 검사를 실패시키지 않습니다. 현재 등록 함수는 외부 상태나 별도 헬퍼에 의존하지 않습니다. 의존성이 있는 모델을 추가할 때는 의존 함수와 상수의 변경도 검증하도록 범위를 확장해야 합니다. 학습 질문과 간단한 실험 설명은 learning.json에 추가하고 생성 파일을 다시 만듭니다. 현재 2개 실험의 계산 기준 사례를 확인했으며 나머지는 미검증 상태입니다.

.github/workflows/check-discovery.yml은 포털 데이터 변경과 주간 일정에 실행됩니다. 확인 대상인 YieldBook과 ComputerBook을 체크아웃해 해시와 기준 사례를 검사합니다. 다른 책의 앵커 전체 수집 검사는 모든 형제 저장소가 있는 로컬 작업 공간에서 실행합니다.

집필·실험 품질 기준

새 주제는 내부 상태를 보여 줄 수 있는지, 인과관계를 조작할 수 있는지, 트레이드오프나 흔한 오해를 드러내는지를 기준으로 선정합니다. 실험 수 자체를 학습 성과로 삼지 않습니다.

대표 실험은 질문 → 예측 → 조작 → 비교 → 설명 → 다른 조건에 적용 순서로 설계합니다. 모델 가정·생략한 현상·유효 입력 범위·단위·출처를 실험 가까이 밝힙니다. 초기화와 기준 시나리오를 제공하고 확률 실험에는 재현 가능한 시드를 둡니다. 매개변수 공유 기능을 추가할 때는 모델 버전도 보존합니다.

모델 검증에는 알려진 기준값, 경계 조건, 보존 법칙 또는 예상되는 경향, 확률 모델의 반복 시행 결과를 사용합니다. 화면이 잘 나온다는 사실과 계산이 올바르다는 사실을 구분합니다. reviewed 상태를 도입하려면 검토자·날짜·모델 버전·검증 사례·출처를 함께 기록해야 합니다.

학습 품질은 새 조건의 결과를 예측하는지, 이유를 설명하는지, 다른 문제에 적용하는지로 확인합니다. 실험 카드에 질문을 추가한 것만으로 학습 효과가 검증된 것은 아닙니다.

다음 아키텍처 단계

현재 구현은 전체 실험의 제목과 링크, 일부 실험의 학습 정보, 명시적인 학습 경로를 연결합니다. 다음 작업은 아래 순서로 진행합니다.

  1. 서로 다른 책 2~3권에서 초기화·비교·상태 공유·접근성 인터페이스를 실제 적용하고 공통 규약을 확정합니다.
  2. 검증된 반복 기능만 버전이 고정된 공통 코어로 추출합니다. 책별 repo와 노광·소자·패키지·신경망 계산 엔진은 독립적으로 유지합니다. 템플릿만 복사해서 배포한 뒤 방치하지 않고 업데이트 검증 절차를 둡니다.
  3. 각 책이 schemaVersion, bookId, revision, 챕터·실험의 안정적인 ID와 상대 URL, 개념 참조를 담은 manifest를 생성하게 합니다. 중앙은 해당 버전의 manifest를 수집·검증해 정적 검색 데이터를 만듭니다. 수집 실패 시 이전 정상 인덱스를 유지합니다.
  4. 중앙 편집 데이터는 분야·동의어·큐레이션·학습 경로를 소유하고, 개별 책은 챕터·실험·모델 설명을 소유합니다. 동일 정보를 양쪽에서 수동 편집하지 않습니다.
  5. 실험·챕터 검색의 실제 사용 사례가 쌓이면 본문 인덱스와 검색 순위를 확장합니다. 의미 검색과 그래프 DB는 요구가 확인된 뒤 도입합니다.

개념 ID와 출처는 공유하되, 독자의 배경과 목적에 맞춘 본문 설명의 반복은 허용합니다. 외부 검색이나 전체 책의 자동 수집·공통 코어 전환은 현재 구현에 포함되지 않습니다.

페이지 주소

하위 페이지는 <이름>/index.html에서 제공하며 공개 주소는 /<이름>/입니다. CSS·JavaScript·데이터 경로는 사이트 루트 기준으로 작성합니다. 기존 *.html 파일은 북마크와 다른 책의 링크를 위해 유지하며 검색 조건과 해시를 새 주소에 전달합니다. GitHub Pages 정적 호스팅에서는 이 이동이 HTTP 301이 아닌 브라우저 이동으로 처리됩니다.

주소 변경 후 python3 tools/check-routes.py로 내부 파일 경로와 기존 주소의 검색 조건·해시 보존을 검사합니다.

python3 tools/build-fields.py는 tools/templates/field.html과 data/books.json으로 예전 분야 주소의 이동 페이지와 사이트맵을 생성합니다. /field/, /field/?f=<id>, /field/<id>/는 /paths/?view=map&field=<id>로 연결하며 기존 검색 조건·해시를 보존합니다. 분야를 추가하면 이 명령도 실행하세요. 지도의 분류·연결은 js/field-maps.js, 지도 렌더링과 보기 전환은 js/field.js에서 관리합니다.

독자 요청

2026-10-18 독자 요청으로 전자기학·열역학·재료공학·플라즈마공학, 산화·박막 증착·CMP·세정·팹 인프라, 기타·피아노·드럼을 다루는 교과서 10권을 후속 집필 예정에 추가했습니다. 확정 출간일은 없으며 기존 공정 전문 교과서와 연결합니다.

서가 저장소와 허브의 약속

책은 서가 저장소(형제 폴더)에서 쓰고, 사실 값은 tools/sync-books.py가 가져옵니다(위 ‘서가에서 가져오기’). 허브에는 서가가 모르는 값만 둡니다.

  • 책 주소는 https://<서가>/<slug>/, checkout은 <서가 저장소>/<slug>입니다. 실험 목록(collect-experiments.py)도 이 경로에서 수집합니다. 일부 책만 갱신할 때는 --book infrabook처럼 반복 지정합니다.
  • 책 ID는 서가로 옮겨도 바꾸지 않습니다. 독자 의견·통계가 ID로 이어지기 때문입니다. SciBook 과목은 독자 의견 링크가 과목 ID를 보내므로 과목 ID(electromagnetics 등)를 씁니다.
  • 옛 개별 사이트 주소는 legacyUrls에 남겨 조회수를 합칩니다.
  • 서가 전체 의견용 ID(science, mathbooks, constructionbooks, musicbooks, moneybooks, systembooks, computingbooks, medicalbooks)는 sisterBooks에 둡니다.
  • 표지 그림은 서가와 같은 motif 코드를 js/covers.js에 둡니다.
  • 아직 공개하지 않은 책에는 주소를 추측해 넣지 않습니다.
  • 허브에서만 다르게 쓰는 값은 keepLocal로 지킵니다. 코드가 겹치는 AnatomyBook ANT(AnalogBook ANA), MaterialsBook CMT(재료과학 MAT), FabInfraBook의 이름·코드, ColorBook의 영문 이름·소개입니다.
서가 저장소 허브 분야 지도 메모
SemiBooks semi-books semiconductor 서가 제조·인프라 묶음은 process+infra. PlasmaBook은 공정 장비 책이라 반도체 분야
SciBook science-books science 서가 shelf.json을 읽음. 색채공학(colorbook, color/)은 ID를 유지한 채 이 서가로 옴
MathBooks math-books math 서가 장 수에 용어집 포함. 확률과 통계는 SciBook에서 옮겨 옴
ConstructionBooks construction-books construction 서가 장 수에 용어집 포함
ComputingBooks computing-books computing 서가 예정 4권은 서가 roadmap.json에도 둠. 모델 검사 CI가 이 저장소를 체크아웃
MoneyBooks money-books money 서가
MedicalBooks medical-books health 서가
SystemBooks system-books electronics 서가 분야에 서가 밖 ElectricBook(허브 묶음 circuits)이 함께 있음. CameraBook은 culture에서 옮겨 옴
MusicBooks music-books culture 서가 분야를 ArtBooks와 나눠 씀
ArtBooks art-books culture 서가 이름·설명은 각 책 book.json, 책 안의 이름(ColorBook 등)은 각 책 book.js

지난 이전·출간 경위는 git log -- data/books.json에서 볼 수 있습니다.

GA4 통계와 인기순 서가

홈의 책 링크는 클릭할 때 GA4 open_book 이벤트(book_id, link_url, placement)를 보냅니다(홈 서가별 클릭 분석용). .github/workflows/analytics.yml이 매일 KST 06:17에 tools/build-analytics.py로 집계해 data/analytics.json을 커밋합니다.

  • stats: 2026-10-30(GA4 도입)부터 오늘(KST)까지 *.euiyun.com 책 사이트의 다녀간 분·다시 찾아온 분·페이지 본 횟수. 홈 첫 화면에 표시
  • opens: 최근 28일 동안 책별 페이지 조회수(각 책 사이트의 hostName+pagePath를 책 URL 접두사로 묶음, GA4 '페이지 및 화면'의 조회수와 같은 기준). 옛 주소(legacyUrls)의 조회수도 같은 책으로 합칩니다. 홈의 분야별 서가는 분야에 속한 책 조회수의 합이 많은 분야부터 놓고(분야 바로 가기도 같은 순서), 분야 안에서는 책 조회수 순서로 놓습니다. 같으면 books.json 순서를 따릅니다.

설정은 Repository 수준(환경 Secret은 읽지 않음)에 둡니다. Secret GA4_CREDENTIALS(Books 속성 뷰어 권한이 있는 서비스 계정 JSON), Variable 또는 Secret GA4_PROPERTY_ID(숫자 속성 ID). 설정이 없으면 예약 실행은 건너뛰고 직접 실행은 실패로 표시합니다.

About

Resources

Stars

8 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages