docs(TechLog): 글감 56개를 기록으로 쓴다

주제 13개 · Case 28 · Concept 5 · Reference 15 · Question 4 · Decision 4. 계약의 노드마다 종류가 요구하는 칸을 채우고, 본문이 있는 두 종류에는 SSOT 가 이미 그려 둔 도식 셋(value-boundaries · decision-path-404 · topic-variant-model)을 tech-log-studio/ 로 옮겨 붙였다. 새로 그린 그림은 없다. 검사 셋 전부 통과한다. check_body.mjs 56 편 중 본문이 있는 33 편 PASS check_prose.mjs 56 편 error 0 check_evidence.mjs --repo 포함 문제 없음 verify-tech-log-tree.py 프로젝트 5 · error 0 · warn 0 인용한 코드블록은 전부 SSOT 에서 찾아 대조했다. check_evidence.mjs 가 본문의 각 줄과 source 앵커와 계약 제목을 다시 확인한다. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-07 15:29:33 +09:00
parent 6955611439
commit f6c825e858
62 changed files with 6381 additions and 186 deletions
@@ -0,0 +1,89 @@
+---
+kind: CASE
+slug: the-comparison-band-changed-three-times
+title: 홈의 비교 구역이 세 번 바뀌었다 — 상한을 없애고 요청을 목록 하나와 주제 하나로 고정했다
+topic: an-axis-inside-a-topic
+topicName: 주제 안의 축
+project: TechLog
+status: 게시 전
+lastVerifiedOn: 2026-09-04
+evidence:
+  - ../../../final/evidence/browser/home-tabs-grouped.png
+  - ../../../final/evidence/browser/home-topic-tabs.png
+  - ../../../final/evidence/browser/tab-metrics.txt
+sourceRevision: tech-log@2026-09-02
+source:
+  - final/document.md#§14.2
+---
+
+# 홈의 비교 구역이 세 번 바뀌었다 — 상한을 없애고 요청을 목록 하나와 주제 하나로 고정했다
+
+홈의 비교 구역을 세 번 바꿨다. 처음에는 주제 하나만 펼치고 아래에 다른 주제로 가는 줄을 뒀고, 다음에는 주제 이름을 탭으로 세웠고, 마지막에 탭을 칩 크기로 낮추고 개수 상한을 없앴다. 상한을 없앨 때 요청 구조를 함께 바꿔 주제가 몇 개가 되든 첫 요청이 고정되게 했다.
+
+## 관계
+
+- **축은 주제가 이름을 정하고, 기록은 종류와 아이디의 쌍으로 축에 걸린다**
+  이 화면이 그리는 구조다.
+- **축의 결론 문장과 기록 수는 기록을 붙여도 따라오지 않는다**
+  이 화면에서 자동으로 안 따라오는 것이 그 질문에 있다.
+- **한 칸의 실패가 옆 칸을 끌고 내려갔다**
+  탭 하나를 못 받아도 나머지가 남게 한 판단이 그 기록에 있다.
+
+## 문제
+
+홈이 「무엇을 만들었나」로 시작하고 있었다. 30초 안에 알아야 할 것은 무엇을 견줬는가다.
+
+## 결론
+
+세 단계를 거쳤고 각 단계가 앞 단계의 무엇을 고치려 했는지가 남아 있다.
+
+| 단계 | 무엇 | 왜 바꿨나 |
+|---|---|---|
+| 1 | 주제 하나만 펼치고 아래 「다른 주제 N개 보기」 한 줄 | 홈이 「무엇을 만들었나」로 시작했다 |
+| 2 | 제목 자리를 주제 이름 탭이 대신 (30px/650) | 「다른 주제」 줄은 목록을 다 읽고 나서야 만나는 곳이라 대개 지나쳤다 |
+| 3 | 탭을 칩 크기로 낮추고 개수 상한 제거 | 주제가 열 개, 스무 개가 되면 이름만으로 화면이 덮인다 |
+
+3단계에서 요청 구조를 바꿨다. 탭은 목록 호출 하나가 주는 전부이고, 상세는 고른 탭만 그때 받아 캐시한다. 그래서 주제가 몇 개가 되든 홈이 처음 보내는 요청은 목록 하나와 주제 하나로 고정된다.
+
+## 검증 환경
+
+tech-log-frontend : 604ded5 → de4cb8b → 3bb724b · 2b2f443
+확인 방식 : 배포본에서 단계마다 화면을 찍고 getComputedStyle 로 실측
+
+## 재현 조건
+
+1. 홈을 열고 개발자도구 네트워크에서 처음 나가는 요청 수를 센다
+2. 탭을 하나 고르고 추가로 나가는 요청을 본다
+3. 같은 탭을 다시 고른다 — 캐시되어 요청이 나가지 않는다
+
+## 본문
+
+<!-- body:start -->
+
+## 세 단계
+
+1단계는 주제 하나만 펼치고 아래에 「다른 주제 N개 보기」 한 줄을 뒀다. 그 줄은 목록을 다 읽고 나서야 만나는 곳이라 대개 지나쳤다 — JPA 주제는 홈에 있으면서도 없는 것과 같았다.
+
+2단계에서 제목 자리를 주제 이름 탭이 대신하게 했다. 30px 에 굵기 650 으로 세웠다.
+
+3단계에서 탭을 칩 크기로 낮추고 개수 상한을 없앴다. 상한은 주제마다 상세를 미리 받느라 둔 것인데, 그러면 상한 밖의 주제가 다시 밀려난다.
+
+## 요청 구조를 바꿨다
+
+탭 줄은 목록 호출 하나가 주는 전부다. 상세는 고른 탭만 그때 받아 캐시한다.
+
+그래서 주제가 몇 개가 되든 홈이 처음 보내는 요청은 목록 하나와 주제 하나로 고정된다. 상한을 없앨 수 있었던 이유가 이것이다.
+
+## 시각 언어를 두 번 고쳤다
+
+고른 탭의 파란 밑줄을 없앴다. 주제가 스무 개면 밑줄 설 곳 스무 개가 함께 늘어선다.
+
+칩으로 낮추니 목록 위에 글자만 떠 있는 것처럼 보였다. 고른 탭에 알약 형태를 주고, 묶음의 윗선을 목록이 아니라 패널이 갖게 해서 탭 줄이 그 선에 바로 얹히게 했다.
+
+## 확인하지 못한 것
+
+주제가 스무 개일 때의 화면은 만들어 보지 않았다. 상한을 없앤 근거는 요청 구조이지 그 규모의 측정이 아니다.
+
+「지금 집중하는 것」 탭에는 파란 밑줄이 그대로 있다. 주제 탭은 알약이라 한 화면 안에서 두 언어가 섞여 있다.
+
+<!-- body:end -->
@@ -0,0 +1,91 @@
+---
+kind: CONCEPT
+slug: topic-variant-and-record-variant
+title: 축은 주제가 이름을 정하고, 기록은 종류와 아이디의 쌍으로 축에 걸린다
+topic: an-axis-inside-a-topic
+topicName: 주제 안의 축
+project: TechLog
+status: 게시 전
+basisVersion: tech-log-backend 2026-09-01 의 축 스키마 · record_variant 에 외래키 없음 · studio_validation 과 publication 이 쓰는 방식을 따름
+assets:
+  - key: topic-variant-model
+    file: ../../../final/assets/tech-log-studio/topic-variant-model.svg
+evidence:
+  - ../../../final/evidence/raw/db/topic-variant-rows.txt
+  - ../../../final/evidence/raw/db/record-variant-links.txt
+sourceRevision: tech-log@2026-09-02
+source:
+  - final/document.md#§14.1
+---
+
+# 축은 주제가 이름을 정하고, 기록은 종류와 아이디의 쌍으로 축에 걸린다
+
+주제 안의 축은 세 테이블로 표현된다. 주제가 축의 이름을 스스로 정하고, 축의 값들이 따로 있고, 어느 기록이 어느 축에 걸리는지를 종류와 아이디의 쌍으로 적는다. 기록이 종류마다 다른 테이블에 살기 때문에 그 쌍에 외래키를 걸지 못한다.
+
+## 관계
+
+- **주제를 넷으로 쪼개지 않고 주제 안에 축을 하나 뒀다**
+  이 구조를 만든 결정이다.
+- **축 링크가 자기 자신을 가리켰고, 고친 뒤에는 백엔드를 먼저 배포했다**
+  이 구조 위에 축 화면을 만든 사건이다.
+- **홈의 비교 구역이 세 번 바뀌었다**
+  이 구조가 화면에서 어떻게 쓰이는지가 그 기록에 있다.
+
+## 본문
+
+<!-- body:start -->
+
+## 세 테이블
+
+```text
+topic (주제)
+  ├─ variant_label   축의 이름 — 주제마다 다르다
+  │                  인증 경계 → 「구조」 / 조회 성능 → 「조회 전략」
+  └─ topic_variant   축의 값들 (SPA, Mediator, BFF, Forward-Auth)
+       └─ record_variant   어느 기록이 어느 축에 걸리는지 (kind, id) 쌍
+```
+
+:::evidence key="topic-variant-model" alt="topic·topic_variant·record_variant 가 이어지고 record_variant 가 세 테이블을 가리키는 구조도" caption=" " zoom="true"
+:::
+
+## 축 이름은 주제가 정한다
+
+내부 이름은 축으로 고정하고, 화면에 보이는 이름은 주제가 자기 칸에 적는다. 인증 경계 주제는 「구조」, 조회 성능 주제는 「조회 전략」이다.
+
+## 기록은 여러 축에 걸린다
+
+한 기록이 여러 축에 걸릴 수 있다. PKCE 는 SPA 와 BFF 양쪽에 관계된다.
+
+아무 축에도 걸리지 않은 기록은 그 주제의 공통 기록으로 읽는다. 「공통」이라는 축을 따로 만들지 않는다.
+
+## 외래키가 없다
+
+`record_variant` 는 외래키를 갖지 않는다. 기록이 종류마다 다른 테이블에 살기 때문이다 — 문서·열린 질문·프로젝트 결정이 각각 다른 테이블이다. 종류와 아이디의 쌍으로만 가리킨다.
+
+이 방식은 이 저장소에서 처음 쓰는 것이 아니다. 검증 상태와 게시 기록이 이미 같은 방식으로 기록을 가리키고 있었다.
+
+## 사람이 쓰는 칸
+
+주제의 논지, 축의 요약과 결론은 기록을 합쳐 자동으로 나오는 글이 아니다. 특히 결론은 비교표가 읽는 칸이라 기록의 요약 첫 줄을 잘라 쓰면 안 된다.
+
+## 같은 구조가 다르게 보일 때
+
+두 주제가 같은 구조를 쓰는데 축에 걸린 기록 수가 달라 다르게 보인다.
+
+```text
+oauth-oidc-auth-boundary   축 이름 「구조」    축 4개
+  spa           ← CASE 1 + REFERENCE 3                 (기록 4)
+  mediator      ← CASE 1 + QUESTION 2 + REFERENCE 2    (기록 5)
+  bff           ← CASE 1 + QUESTION 3 + REFERENCE 1    (기록 5)
+  forward-auth  ← CASE 1 + QUESTION 1 + REFERENCE 1    (기록 3)
+  공통 기록: CONCEPT 1 + 결정 2 + REFERENCE 2
+
+jpa-feed-query-performance  축 이름 「조회 전략」  축 3개
+  derived-query      ← CASE 1
+  fetch-join         ← CASE 1
+  fetch-join-paging  ← CASE 1
+```
+
+축마다 기록이 하나씩이고 축 제목을 그 기록 제목과 비슷하게 적으면 「문서가 그대로 나온다」로 보인다. 구조 차이가 아니라 내용 양의 차이다.
+
+<!-- body:end -->
@@ -0,0 +1,55 @@
+---
+kind: PROJECT_DECISION
+slug: an-axis-inside-a-topic-not-four-topics
+title: 주제를 넷으로 쪼개지 않고 주제 안에 축을 하나 뒀다
+topic: an-axis-inside-a-topic
+topicName: 주제 안의 축
+project: TechLog
+status: 게시 전
+decisionStatus: ADOPTED
+decidedOn: 2026-09-01
+evidence:
+  - ../../../final/evidence/raw/db/topic-variant-rows.txt
+  - ../../../final/evidence/raw/db/record-variant-links.txt
+sourceRevision: tech-log@2026-09-02
+source:
+  - final/document.md#§14.1
+  - final/document.md#§14.3
+---
+
+# 주제를 넷으로 쪼개지 않고 주제 안에 축을 하나 뒀다
+
+「브라우저와 서버 사이 credential 책임을 어디에 둘 것인가」 하나의 질문에 네 구조를 만들어 봤는데, 기록에 붙는 축이 주제와 프로젝트뿐이라 그 넷을 담을 데가 없었다. 주제를 넷으로 쪼개는 대신 주제 안에 축을 하나 뒀다.
+
+## 근거
+
+- **축은 주제가 이름을 정하고, 기록은 종류와 아이디의 쌍으로 축에 걸린다**
+  이 결정을 담은 스키마다.
+- **홈의 비교 구역이 세 번 바뀌었다**
+  이 결정이 화면에 어떻게 나타났는지가 그 기록에 있다.
+- **축의 결론 문장과 기록 수는 기록을 붙여도 따라오지 않는다**
+  이 결정으로 감수한 비용이 그 질문에 있다.
+
+## 결정문
+
+한 질문에 여러 구조를 만들어 비교하는 경우, 주제를 그 수만큼 쪼개지 않고 주제 안에 축을 하나 둔다. 축의 이름은 주제가 정하고, 기록은 여러 축에 걸릴 수 있으며, 아무 축에도 걸리지 않은 기록은 그 주제의 공통 기록으로 읽는다.
+
+## 판단 이유
+
+주제를 넷으로 쪼개면 PKCE·CSRF·Authorization Code 처럼 네 구조가 함께 쓰는 기록을 어디에 둘지 애매해진다. 어느 한 주제에 넣으면 나머지 셋에서 그 기록에 닿을 수 없고, 넷에 복사하면 같은 글이 넷이 된다.
+
+비교도 어려워진다. 네 주제가 나란히 서면 그것이 같은 질문의 네 답이라는 것을 화면이 말하지 못한다.
+
+축을 주제 안에 두면 공통 기록은 축을 고르지 않고 두면 되고, 여러 구조에 걸치는 기록은 여러 축에 건다. 화면은 축을 나란히 세워 비교로 그린다.
+
+축 이름을 주제가 정하게 한 것은 주제마다 비교 축이 다르기 때문이다. 인증 경계 주제의 축은 구조이고 조회 성능 주제의 축은 조회 전략이다.
+
+## 영향
+
+축의 이름·요약·결론이 기록에서 자동으로 나오지 않는다. 주제의 논지, 축의 요약과 결론은 사람이 쓰는 칸이고, 기록을 스무 개 붙여도 그 문장은 누가 고치기 전까지 그대로다.
+
+홈의 비교 구역에서 줄은 문서가 아니라 축이다. 줄을 늘리려면 Studio 에서 축을 추가해야 한다.
+
+기록이 어느 축에 걸리는지를 담는 표에 외래키를 걸 수 없다. 기록이 종류마다 다른 테이블에 살기 때문이다.
+
+축이 붙은 기록 수가 적으면 「문서가 그대로 나온다」로 보인다. 축마다 기록이 하나씩이고 축 제목을 그 기록 제목과 비슷하게 적으면 그렇게 읽힌다.
@@ -0,0 +1,80 @@
+---
+kind: QUESTION
+slug: the-conclusion-line-does-not-follow-the-records
+title: 축의 결론 문장과 기록 수는 기록을 붙여도 따라오지 않는다
+topic: an-axis-inside-a-topic
+topicName: 주제 안의 축
+project: TechLog
+status: 게시 전
+questionStatus: OPEN
+evidence:
+  - ../../../final/evidence/raw/db/record-variant-links.txt
+sourceRevision: tech-log@2026-09-02
+source:
+  - final/document.md#§14.3
+  - final/document.md#§16.2
+---
+
+# 축의 결론 문장과 기록 수는 기록을 붙여도 따라오지 않는다
+
+홈의 비교 구역에서 줄은 문서가 아니라 축이다. 기록을 스무 개 붙여도 줄 수는 그대로이고, 줄에 보이는 결론 문장은 축에 손으로 쓴 글이라 누가 고치기 전까지 바뀌지 않는다. 주제 화면에는 축마다 기록 수가 붙는데 홈에는 없다.
+
+## 관계
+
+- **주제를 넷으로 쪼개지 않고 주제 안에 축을 하나 뒀다**
+  이 결정으로 감수한 비용이 이 질문이다.
+- **홈의 비교 구역이 세 번 바뀌었다**
+  이 화면을 세 번 고친 기록이다.
+- **프록시 지표가 아니라 보이는 것을 측정한다**
+  화면에서 무엇이 달라지는지 확인하는 방법이 그 기준에 있다.
+
+## 사실
+
+홈의 비교 구역에서 한 줄은 축 하나다. 기록을 스무 개 붙여도 줄 수는 그대로다.
+
+줄에 보이는 결론 문장은 축에 손으로 쓴 글이다. 기록을 붙여도 그 문장은 누가 고치기 전까지 그대로다.
+
+주제 화면에는 축마다 「기록 N」이 붙는다. 홈에는 그 수가 없다.
+
+그래서 기록 1개짜리 축과 20개짜리 축이 홈에서 똑같아 보인다.
+
+주제의 논지와 축의 결론은 2026-09-01 에 DB 에 직접 넣은 초안이고 아직 검토되지 않았다.
+
+## 가정
+
+결론을 사람이 쓰게 한 것이 의도라고 보고 있다. 요약은 「무엇인가」이고 결론은 「무엇을 알게 됐나」라서 기록의 요약 첫 줄을 잘라 쓰면 안 된다고 판단했지만, 그 판단이 지금도 맞는지 다시 보지 않았다.
+
+기록 수는 유도할 수 있다고 보고 있다. 주제 화면이 이미 그 수를 그리므로 같은 값을 홈에 붙이면 된다고 짐작하지만, 홈의 목록 호출이 그 수를 싣는지 확인하지 않았다.
+
+## 미지수
+
+홈에 기록 수를 붙이면 축에 기록을 더했을 때 화면이 달라지는가. 달라진다면 결론 문장이 낡았다는 것도 같은 화면에서 드러나는가.
+
+결론을 사람이 갱신해야 한다는 것을 화면이 말해야 하는가. 말한다면 어디에 말해야 읽히는가.
+
+DB 에 직접 넣은 초안을 누가 언제 검토하는가. 검토 전까지 그 문장을 공개 화면에 그대로 둘지.
+
+## 제약
+
+축의 요약과 결론은 기록을 합쳐 자동으로 만들지 않는다. 결론은 비교표가 읽는 칸이라 기록의 요약 첫 줄을 잘라 쓰면 안 된다.
+
+홈이 처음 보내는 요청은 목록 하나와 주제 하나로 고정한다. 기록 수를 붙이려고 주제마다 상세를 미리 받지 않는다.
+
+## 선택지
+
+**홈 비교표에 기록 수를 붙인다**
+목록 호출이 이미 그 수를 실을 수 있으면 요청이 늘지 않는다. 결론 문장은 그대로 사람이 쓴다.
+
+**결론 문장이 마지막으로 고쳐진 때를 함께 보인다**
+기록이 그 뒤에 늘었으면 낡았다는 것이 드러난다. 화면에 날짜가 하나 더 늘어난다.
+
+**결론을 쓰지 않은 축은 결론 줄을 비운다**
+쓰지 않은 것과 낡은 것을 구분한다. 지금은 초안이 들어 있어 둘이 같아 보인다.
+
+## 다음 검증
+
+1. 홈의 목록 호출 응답에 축별 기록 수가 실려 있는지 확인하고, 없으면 싣는 비용을 잰다
+2. 축 하나에 기록을 더하고 홈에서 무엇이 달라지고 무엇이 그대로인지 화면으로 가른다
+3. DB 에 직접 넣은 주제 논지와 축 결론을 사용자가 검토하고, 남길 것과 지울 것을 가른다
+
+닫는 조건 : 축에 기록을 더했을 때 자동으로 따라오는 것과 사람이 고쳐야 하는 것이 화면에서 구분되면 닫는다