개발 이력 — 결정과 버린 대안을 그림과 함께 남긴다
H-03 · 2026-09-08 · 서류를 올릴 수 있게 했다 (① 올린다)
- 제기: 지시자 — "이제 서류 올릴 수 있는 부분 만들어라 테스트 해보게."
무엇을 만들었나
작업대 /work.html 에 드롭존 하나와 올라온 서류 목록. 받은 서류는 손대지 않고 창고에 넣고 장부에 적는다. 이후 어떤 처리가 실패해도 원본은 남는다(KPF flow.md ①).
POST /api/upload 받아서 창고 + 장부 GET /api/uploads 장부 읽기 GET /files/<id> 창고에서 꺼내 보기 (?down 이면 내려받기)
창고가 KV 다 — R2 가 아니라
wrangler r2 bucket list 가 code 10042 "Please enable R2 through the Dashboard" 로 막혔다. 이 계정에서 R2 가 아직 안 켜져 있다. 시험을 미룰 이유가 없어서 KV 로 갔다 (값 하나 25MiB). 어디에 두는지는 src/창고.js 한 파일만 안다 — R2 든 네이버든 그 파일만 갈아 끼우면 된다.
겹침을 지문으로 잡는다
파일마다 SHA-256 을 떠서 장부에 남긴다. 같은 내용이 다시 올라오면 막지 않고 알린다 ("전에 올린 20260908-0001 과 내용이 같습니다"). 막으면 일부러 다시 올리는 경우를 못 한다.
도달했는지 확인 (만든 것과 도달한 것은 다르다)
| 확인 | 결과 |
|---|---|
POST /api/upload (PDF 1장) | 200 · 20260908-0001 발급, 창고·장부 둘 다 들어감 |
| 같은 파일 다시 | 200 · 같은파일: {id: 20260908-0001} 로 알림 |
GET /api/uploads | 200 · 2건, sha256 동일 확인 |
GET /files/20260908-0001 | 200 · application/pdf · 69 바이트, 알맹이 그대로 |
GET /health | 장부: ok · 2건 |
| 브라우저 실물 | 드롭존 + 목록 표 + 보기/내려받기 링크 |
확인용으로 넣은 두 줄은 장부와 창고에서 지웠다. 지금 장부는 비어 있다.
아직 없는 것
나누기 · 읽기(OCR) · 검산 · 엑셀. 판독 엔진이 아예 없다 — 무슨 서류인지 모르니 무엇으로 읽을지도 못 정한다(Q-02). 그래서 KPF 처럼 네이버 클라우드에 서버를 띄우는 일도 아직 안 했다.
---
H-02 · 2026-09-08 · Cloudflare Worker 를 만들어 배포했다 — 주소가 살았다
- 제기: 지시자 — "클라우드플레어에서 워커를 니가 만들어야지."
무엇을 했나
wrangler deploy 로 Worker hoganas 를 만들고 커스텀 도메인 https://hoganas.dreamcustomsservice.com 을 붙였다. 계정은 KPF 와 같다 (customsshin@gmail.com · 600295b4779b795b1e580a613d632e43). 정적 자산 8장이 올라갔다.
도달했는지 확인 (만든 것과 도달한 것은 다르다)
| 확인 | 결과 |
|---|---|
GET /health | 200 · {"ok":true,"site":"hoganas","stage":"뼈대 — 요구 수집 중"} |
GET / | 302 → /dev/index.html |
GET /dev/index.html | 200 · 44,670 바이트 |
GET /nope.html | 404 · 꾸며진 404 쪽 |
| 브라우저 실물 | KPF 와 같은 디자인, 브랜드만 "서류 변환 프로그램 / 호가나스" |
같이 고친 것
- 헤더 브랜드·메타·푸터에 남아 있던 KPF 문자열을 호가나스로 갈았다.
- 질의응답 배지 스크립트를 뺐다.
/api/questions가 아직 없어서 매번 404 를 부르고 있었다. - 개요 쪽 머리의 날짜가
2026-09-02로 박혀 있었다.index.md에서 읽게 고쳤다.
문서가 원본인데 화면에 날짜를 박아 두면 문서를 고쳐도 화면이 안 따라온다.
아직 없는 것
D1(장부) · R2 · secrets · 작업대 화면. 무슨 서류를 무엇으로 바꾸는지 정해진 뒤에 붙인다(Q-02·Q-03). 미리 지으면 KPF H-08 을 그대로 반복한다.
---
H-01 · 2026-09-08 · 프로젝트 시작, KPF 를 형으로 삼는다
- 제기: 지시자 — "KPF 수출 서류 변환 프로그램과 같은 컨셉으로 호가나스 문서를 자동 변환하는
프로그램을 만든다. 전체를 하기 전에 가장 중요한 룰 하나를 먼저 시험해 보자."
무엇을 했나
빈 폴더에 뼈대를 세웠다. CLAUDE.md(에이전트 규칙) · 마스터설계서.md(미확정 칸을 Q-번호로 남긴 뼈대) · docs/history.md(이 파일) · 룰시험/(룰 하나 시험 장치) · .gitignore.
왜 지금 설계서를 다 쓰지 않았나
입력 서류와 출력 서식을 아직 모른다. KPF 에서 배운 것이 그것이다 — 서류를 실제로 열어 보기 전에 쓴 설계는 H-08 에서 일곱 군데가 틀렸다. 모르는 칸은 지어내지 않고 Q-01~Q-08 로 남겼다.
왜 룰 시험이 먼저인가
KPF 의 가장 비싼 교훈은 H-30 이다. 손으로 만든 규격→HS 대응표는 정답률 13% 였고, 과거 실적 37,510 줄로 학습한 룰북은 93% 였다. 룰이 서면 나머지는 배관이고, 룰이 안 서면 아무리 잘 만든 화면도 쓸모가 없다. 그래서 사이트·엔진보다 룰이 먼저다.
승계한 것
마스터설계서.md 6장에 표로 남겼다 — 문서가 원본, 그림 먼저, 룰북은 학습, 자동 반영 금지, 노란 칸에 이유, 판독 캐시, 산술 검산, 작업 하나 = 산출물 하나.