K-Law 개발자 문서 — 2026-09-15 ~ 09-18 작업 정리

이 기간 동안 klaw.hondi.net(Openhash-Gopang/klaw)과 hondi-proxy 백엔드(Openhash-Gopang/hondi worker.js)에 이뤄진 모든 변경사항을 정리합니다. PR 번호는 각 저장소 기준입니다.

1. hondi 인증 · 과금 연동 2. 토큰 예산 · 안정성 3. 이력 기능 확장 (1차) 4. UI/UX 변경 이력 5. 인프라 · 기타 6. 이력 탭 즉시 닫힘 버그 7. 일치도 평가 기능 신설 8. 이력 시스템 전면 개편 (게시판화) 9. 공개 게시판 신설 + 레거시 제거 10. 표시 다듬기 (제목·일치도·항목별 평가) 11. 사고실험으로 발견한 문제들 12. 알려진 제약 · 남은 과제

1. hondi 인증 · 과금 연동 FEATURE

klaw #17, #20, #21 · hondi #274

배경 원칙(주피터 지시): "혼디 가입자는 혼디 시스템의 모든 모듈에 자유로이 접근할 수 있어야 한다 — hondi.net에 전화번호 인증하면 다른 모든 K-서비스에 자유로이 접근하고, hondi.net과 동일한 방식으로 사용량에 따른 GDC 차감이 이뤄져야 한다."

DeepSeek 무료 이용 경로 신설 — API Key를 직접 입력하지 않고 DeepSeek을 선택하면, K-서비스 공용 인증 모듈(k-service-auth-client.js, phone_verify_token 기반)로 로그인 후 /klaw/relay(K-Law 공유 계정)를 통해 이용. 본인 API Key 입력 시(BYOK)는 기존처럼 브라우저에서 각 제공사 API로 직접 호출 — relay를 거치지 않음.
인증 필수화 — _klawCall이 요청 전 반드시 KAuth.ensureLogin()을 거치도록 변경. 이전엔 401을 받은 뒤에야 재로그인하는 반응형 구조였음.
실제 로그인 상태 배지 — 헤더의 "게스트" 표시가 2026-07-23 제거된 구 고팡 지갑 SSO 콜백(_onGopangAuth) 잔재라 실제 상태와 무관하게 고정 표시되던 문제를 발견, KAuth.hasValidLogin() 기반 실시간 배지(_klawRefreshAuthBadge)로 교체.

2. 토큰 예산 · 안정성 FIX

klaw #18, #22, #25, #31, #32

핵심 발견: klaw-pro 티어는 DeepSeek의 "thinking"(추론) 모드가 항상 켜져 있고 (hondi worker.js payload.thinking), 추론 토큰도 max_tokens 예산에서 함께 소모된다. 예산이 부족하면 모델이 추론만 하다 실제 답변은 한 글자도 못 쓰고 끝나는 사례가 반복 발견됨.

토큰 예산 변경 이력

항목	최초	최종
사건 분석 (단순)	1400	2400
사건 분석 (복잡, pro)	2400	10000
STEP 0	3000	9000
STEP A	3000	14000
STEP B (최종 판결문)	3000	16000
STEP C	3000	9000

STEP A·B가 특히 높은 이유: 각 STEP은 이전 STEP 전체 출력을 컨텍스트로 이어받아 갈수록 입력이 커지고, 요구되는 실제 출력 분량도 STEP C(확신도 숫자+짧은 요약)보다 훨씬 길다.

자동 복구 로직

_klawCaseIsComplex() — 글자 수(900자) 또는 당사자 키워드 빈도(12개 초과) 기준으로 복잡한 사건을 판정해 klaw-flash 대신 klaw-pro로 자동 승격.
flash→pro 자동 재시도 — klaw-flash 응답이 finish_reason:'length'로 잘리면, klaw-pro로 한 번 자동 재시도(사전 복잡도 판정을 놓친 사례 사후 구제).
빈 결과 안전장치 — 사건 분석 핵심 3필드(사건의 개요/원고 주장/피고 주장)가 전부 비거나, STEP 결과가 완전히 빈 문자열이면, 더 큰 예산으로 1회 자동 재시도 → 그래도 비면 "성공한 것처럼 보이는 빈 결과"를 조용히 넘기지 않고 명확한 오류 + "다시 시도" 버튼 표시.
종합 확신도 파싱 견고화 — 모델이 [종합 확신도: min(8,9)=8/10]처럼 계산식을 적어도 마지막 숫자를 정확히 추출하도록 정규식 보완.

3. 이력 기능 확장 (1차) FEATURE SECURITY

klaw #21, #34, #35 · hondi #274, #278, #280

3-1. 본인 전용 + 프라이버시 (#21)

기존 이력 기능은 currentUser?.ipv6(2026-07-23 제거된 죽은 코드가 채워야 하는 값)에 의존해 저장·조회가 항상 조용히 실패하고 있었다. 게다가 백엔드가 클라이언트가 보내는 user_id를 그대로 신뢰해, 값만 바꾸면 남의 이력을 보거나 남의 이름으로 기록을 남길 수 있는 취약점 발견.

hondi worker.js: /klaw/sessions/*가 phone_verify_token으로 서버가 guid를 직접 재확인 — 클라이언트가 보내는 user_id는 완전히 무시.
klaw: 이력 목록을 일치도 % + 시각 두 항목만 표시하도록 단순화(주피터 지시 — "일치도 점수만 표시").
PocketBase klaw_sessions에 match_rate 필드 신설(마이그레이션/Admin API로 무중단 반영).

3-2. 전문 저장 · 열람 (#34, #35)

"일치도만 표시"에서 한 발 나아가, STEP 0~C 판결문 전문을 저장하고 이력 목록 클릭 시 모달로 다시 열람하는 기능 추가.

GitHub 저장 방식은 채택하지 않음 — klaw 저장소가 공개 저장소라 인증 없이 전 세계에 노출되고, 매 시뮬레이션마다 커밋이 쌓여 GitHub Pages가 재배포되는 문제가 있어 기각. 대신 이미 인증 구조가 갖춰진 PocketBase에 필드만 추가하는 방식 채택.
hondi worker.js: /klaw/sessions 저장 시 verdict_full 함께 저장. /klaw/sessions/detail(신규) — record id + phone_verify_token으로 조회, 레코드의 user_id가 요청자 guid와 정확히 일치할 때만 반환(안 맞으면 404 — 존재 여부조차 안 알려줌).
PocketBase에 verdict_full 텍스트 필드(최대 200,000자) 신설.
klaw: 이력 행 클릭 → 모달에 사건 종류·사건 개요·주문·판결 요약 메타 정보 + 전문 표시. 토큰 만료 시 _klawCall과 동일한 재로그인 자동복구 로직 적용.

4. UI/UX 변경 이력 STYLE

klaw #14, #16, #19, #23, #24, #26, #27, #29, #33

디자인 방향이 세션 내내 여러 번 전환되었다 — 각 결정은 그 시점 지시를 반영한 것으로, 이후 지시가 이전 방향을 대체한다.

단계	내용
자료 다운로드 카드	Material Design 카드(#19) → 법원 문서풍 무장식 고지문(미채택) → 헤더 우측 여백으로 이동, 카드/문구 삭제(#29, 최종)
안내 박스 배경색	제각각(주황/초록/파랑) → 청색으로 통일(#14) → 2곳(면책 고지·표 강조행)만 남기고 플레인 텍스트化(#16, 최종)
AI 모델 카드	빈 선택 표시등·제각각 아이콘 모양·3줄 텍스트 → 체크 배지·통일 아바타·2줄 압축, API Key 버튼 간소화(#33, 최종 — 사전에 목업 승인 절차 거침)
진행 표시	dot 4개 → 막대 바(#23) → 실제 DeepSeek 스트리밍 원문 미리보기 + 경과시간 기반 바(#24, 최종)
입력 제출	Enter 키 제출은 다문단 사건 개요 작성과 충돌 — Ctrl+Enter로 제출, 일반 Enter는 줄바꿈 유지(#23)

접이식 섹션 신설

"K-Law는 어떻게 동작하나요" — 기본 숨김, 제목 클릭 시 슬라이드 아웃/인(#26)
"시뮬레이션 절차와 방법" — 판례 선택→타 LLM으로 사실관계만 추출→붙여넣기 3단계 안내, 이후 "예시" 링크 2개(대법원 판례 예시, 사건 요약 예시 페이지) 및 "원심 판결문 활용법" 항목 추가(#27, #30)

5. 인프라 · 기타 CHORE

klaw #15

줄바꿈 CRLF→LF 정규화 + .gitattributes — Python 스크립트로 파일을 열고 저장하는 과정에서 Windows 텍스트 모드가 파일 전체 줄바꿈을 CRLF로 바꿔버려, 다음 patch들이 매번 컨텍스트 불일치로 실패하는 원인이 됨. 정규화 커밋(내용 변경 없음, 재현 확인)으로 해결하고 재발 방지용 설정 추가.
Windows PowerShell 관련 팁 — 줄바꿈에 \가 아닌 백틱(`) 사용, git am 대용량 patch 실패 시 git apply로 대체 가능.

6. 이력 탭 즉시 닫힘 버그 FIX

klaw #37

"이력" 탭을 클릭해도 반응이 없다는 제보. 재현해보니 실제로는 한 클릭 안에서 두 가지가 동시에 일어나고 있었다: ① 탭의 onclick="toggleHistoryPanel()"이 실행되어 패널이 열리고, ② 같은 클릭 이벤트가 document까지 계속 버블링되며 "패널 바깥 클릭 시 닫기" 리스너가 발동해 곧바로 닫혀버렸다. 같은 패널을 여는 우측 상단 아바타 버튼(#user-info-bar)은 그 리스너의 예외 목록에 들어있어 정상 작동했지만, 나중에 추가된 "이력" 탭 버튼은 예외 목록에서 빠져 있던 게 원인.

탭 버튼에 id="history-tab-btn"을 부여하고 리스너 조건에 추가해 해결. Playwright로 "아바타는 정상, 탭은 열렸다 즉시 닫힘" 상태를 직접 재현해 원인을 확정한 뒤 수정했다.

7. 일치도 평가 기능 신설 FEATURE

klaw #38

"사건의 개요" 입력란 아래에 "일치도 평가" 패널을 신설. 사용자가 실제 대법원 판결문 전문을 붙여넣으면, 방금 생성된 K-Law 가상 판결문과 비교하여 "일치도 평가 기준" 방법론에 따른 평가 보고서를 생성한다.

mammoth.js 도입 — K-Law 방법론(.md)·출력형식(.txt)과 달리 "일치도 평가 기준" 원문은 .docx라 그대로 프롬프트에 넣을 수 없다. mammoth.browser.min.js로 클라이언트에서 텍스트만 추출.
버전 자동 감지 — loadKlawVersion()과 동일한 패턴으로 저장소 파일 목록을 스캔해 일치도_평가_기준_v[숫자].docx 중 가장 높은 버전을 자동 선택. 문서가 새 버전으로 교체되기만 하면 코드 수정 없이 반영됨.
빈 결과 안전장치 재사용 — 이 호출도 klaw-pro(thinking 모드)를 타므로, 앞서 STEP 0~C에 적용한 것과 동일하게 결과가 비면 더 큰 예산(24000)으로 자동 재시도 후 명확한 오류를 표시하도록 처음부터 구현.

8. 이력 시스템 전면 개편 — 팝업 → 게시판 페이지 FEATURE

klaw #39, #41, #42 · hondi #278, #280, #301, board-detail

"팝업이 아니라 게시판 형식의 이력 페이지를 보여달라"는 지시로, 작은 플라이아웃 패널을 완전히 걷어내고 my-history.html 신규 페이지로 교체.

8-1. 판결문 전문 저장 · 열람

STEP 0~C 완료 시 이미 클라이언트에 조립되어 있던 window._verdictText 전문을 verdict_full 필드로 저장(최대 200,000자, 초과 시 무음 절단 대신 [⚠ 저장 용량 한도로 잘림] 명시).
/klaw/sessions/detail — record id + phone_verify_token으로 조회, 레코드의 user_id가 요청자 guid와 정확히 일치할 때만 반환.

8-2. 항목별 일치도 점수

일치도 평가 프롬프트가 방법론 원문에서 자동 추출한 실제 항목명(결론 방향 일치도/핵심 법리 일치도/세부 논증 일치도)으로 [항목: X] [점수: Y%] 태그를 출력하도록 지정. 항목명을 코드에 하드코딩하지 않고 정규식으로 파싱해 match_items(JSON)에 저장 — 방법론 문서가 버전업되어 항목 구성이 바뀌어도 코드 수정이 필요 없다.

실제 문서로 파싱 로직 검증 — 주피터님이 실제 "일치도_평가_기준_v1.6.docx" 파일을 첨부해주셔서, mammoth.js가 그 표(항목/배점/설명 3열)를 어떻게 텍스트로 풀어내는지 직접 확인 후 파싱 정규식을 작성 — 추측이 아니라 실측 기반으로 구현.

8-3. 사건명 자동 생성

분석 프롬프트에 【사건명】 태그를 추가해 "건축인허가 처분 취소 청구"처럼 실제 법원 사건명 형태의 짧은 제목을 K-Law가 직접 생성하도록 함. 날짜는 이미 별도 칼럼에 있으므로 제목에는 절대 포함하지 않음. 이 필드 도입 이전에 생성된 레코드는 소급 적용되지 않아, case_type+case_summary 기반 대체 제목으로 폴백.

9. 공개 게시판 신설 + 레거시 제거 FEATURE SECURITY

klaw #40 · hondi board-detail

public-board.html 신설 — is_public=true인 이력만 인증 없이 볼 수 있는 게시판. 작성자는 이용자-xxxx 형태로 익명화(guid 뒷자리 일부만 노출).

옛 자동 게시 시스템이 여전히 살아있었음 — "기본 비공개, 선택적 공개"를 설계·구현하는 도중, 사실은 _sendCaseToKlaw()가 모든 시뮬레이션 결과를 예외 없이 옛 klaw_cases 컬렉션(공개 옵션 자체가 없는 시스템)에 계속 자동 게시하고 있었다는 것을 뒤늦게 발견. 새 is_public 플래그를 다 만들어놓고도 이 호출 하나를 제거하지 않으면 전체 기능이 무의미해지는 상황이었음 — 발견 즉시 자동 호출 제거, 판결문 카드의 게시판 링크도 새 public-board.html로 교체(옛 board.html은 이제 새 글이 안 쌓이는 페이지라 그대로 두면 사용자를 막다른 곳으로 보내는 셈이었음).

10. 표시 다듬기 STYLE

klaw #41, #42

항목	이전	이후
생성 시각	전체 로케일 문자열(폭 넓음)	`2026.09.16.15:36` 압축 표기
제목	없거나 "(제목 없음)"만 표시	사건명 자동 생성 + 옛 레코드 대체 제목(날짜 미포함)
일치도 칼럼	"종합 일치도", 값에 "(복잡도 N/10 기준)" 포함	"일치도 예상"으로 개명, 순수 %만(옛 값도 화면에서 걸러냄)
항목별 평가	미평가 항목에 "미평가" 텍스트, 2줄로 줄바꿈	흐린 색상의 항목명만, `flex-wrap:nowrap`으로 한 줄 강제
공개 칼럼	다른 칼럼과 동일 폭	토글 크기에 맞춘 최소 폭

11. 사고실험으로 발견한 문제들

코드를 실제로 추적하며 발견 → 즉시 수정한 항목들

구 SSO 죽은 코드 — _onGopangAuth/currentUser가 2026-07-23 제거된 인증 스크립트를 전제로 작성되어 있어, 이력 저장·조회·헤더 배지가 전부 "성공한 것처럼 보이지만 실제로는 항상 실패"하는 상태였다. 에러가 안 나서 오래 발견되지 않았을 가능성.

user_id 신뢰 취약점 — /klaw/sessions/*가 클라이언트가 보내는 user_id를 검증 없이 사용해, 값만 바꾸면 타인의 사건 요약·판결 내용을 조회하거나 타인 명의로 기록을 남길 수 있었다.

thinking 모드 토큰 소모 — max_tokens를 여러 차례 올려도 계속 잘리는 근본 원인이 "추론 토큰도 같은 예산을 먹는다"는 것이었음을 worker.js 코드 확인 후에야 발견. 이전 시도들은 증상(잘림)만 완화했을 뿐 원인을 못 잡았었다.

STEP별 예산 불균형 — 모든 STEP에 동일 예산(9000)을 줬을 때 STEP 0·C는 성공, STEP A·B만 실패하는 실사용 로그를 근거로 STEP별 차등 예산 필요성 확인.

이력 전문 저장 시 4가지 허점 — ① 저장 상한(60,000자)이 최악의 경우(STEP 예산 총합 48,000토큰) 대비 부족 + 무음 절단 → 200,000자 상향 + 명시적 절단 표시. ② 상세 모달에 사건 맥락(종류/개요/주문/요약)이 안 보임 → 표시 추가. ③ 토큰 만료 시 재로그인 미지원 → _klawCall과 동일한 자동복구 적용. ④ KAuth 미정의 방어 누락 → 추가.

patch 배포 사고 2건 — (a) 색상 통일 patch가 그 사이 merge된 다른 patch와 컨텍스트가 어긋나 git am이 반복 실패(원인: CRLF 정규화 이전 상태 기준으로 만들어졌던 patch). (b) 보완 전 원본 patch(#34)가 먼저 merge되어, 4가지 허점 보완판을 현재 head 기준으로 다시 만들어 별도 PR(#35)로 반영.

옛 klaw_cases 자동 게시 잔존 — "공개 옵션 도입"을 계획서에 적어놓고도 실제로는 _sendCaseToKlaw() 제거를 빠뜨려, 새 기능을 다 만든 뒤에도 모든 결과가 여전히 무조건 공개되고 있었다(9번 섹션 참조). 계획을 문서로 남겨도 실행을 별도로 검증해야 한다는 교훈.

"배포했는데 안 바뀐다" — 브라우저/CDN 캐시 — my-history.html 개선 사항을 merge했는데도 화면이 그대로라는 문의. 저장소 코드는 실제로 갱신되어 있었고(raw 파일로 직접 대조), 원인은 GitHub Pages CDN 전파 지연 또는 브라우저 캐시였음 — 강력 새로고침(Ctrl+Shift+R)이나 시크릿 창으로 확인하는 절차를 안내.

12. 알려진 제약 · 남은 과제

근본적 한계 — STEP별 maxTokens를 계속 올리는 건 "숫자 땜질"이라는 한계가 있다. 더 구조적인 해법은 (1) 이전 STEP 전체 출력을 그대로 이어붙이지 않고 요약해서 컨텍스트를 줄이거나, (2) finish_reason:'length' 발생 시 "이어서 계속 작성" 요청을 자동으로 보내 이어붙이는 방식일 것 — 둘 다 별도 설계가 필요한 큰 작업으로 남겨둠.
K-Law 전용 발급 키 없을 시 공용 DEEPSEEK_API_KEY로 폴백하는 공유 계정 구조상, 무료 경로 사용량이 늘면 하루 예산(1인 300원/계정 전체 30,000원) 소진이 더 빨라질 수 있다 — thinking 모드 토큰 상향과 트레이드오프 관계.
.caution-bar(동적 경고 메시지 스타일)는 이번 청색 통일 작업에서 의도적으로 제외 — 정적 안내 박스 묶음과 성격이 달라 보여서. 필요 시 후속 작업으로 통일 가능.
대법원 종합법률정보 예시 링크(portal.scourt.go.kr)가 특정 판례 하나를 가리키는 고정 링크라, 시간이 지나면 "최신 판례" 취지와 안 맞을 수 있음 — 주기적 갱신 필요.