docs(TechLog): 남은 주제를 다시 쓰고 SSOT 를 저장소 실물로 더 보강한다

주제 11~13 을 다시 쓰고, Case 가 얇은 것들을 저장소에서 실물을 확인해 채웠다. §13.4 ManagementClientSafeMessages — 삭제 관련 코드 여섯의 고정 문구와 원문 메시지를 내보내지 않는 이유(javadoc) §16.1 다섯 참조가 전부 DOCUMENT_IN_USE 하나로 나가고, SSOT 가 인용한 영어 문장은 DeleteDocumentDraftUseCase 안에 남는 진단 메시지라 밖으로 나가지 않는다 §13.6 romanizeSyllable 실물과 음운 변동을 뺀 이유, 문서 slug 와 같은 정규식을 쓰는 이유 §15.4 check:types 가 도는 tsconfig 여섯 — app·node·test·recipes·web-worker·service-worker SSOT 62,643 → 67,526 자. 인용한 코드는 전부 저장소에서 찾아 대조했다. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-07 19:12:37 +09:00
parent b1653dbba8
commit 6917ce2420
14 changed files with 279 additions and 99 deletions
@@ -7,9 +7,18 @@ topicName: 주제 안의 축
 project: TechLog
 status: 게시 전
 lastVerifiedOn: 2026-09-04
+assets:
+  - key: home-tabs-keycloak
+    file: ../../../final/evidence/browser/home-tabs-keycloak.png
+  - key: home-topic-tabs-2
+    file: ../../../final/evidence/browser/home-topic-tabs-2.png
+  - key: home-tabs-grouped
+    file: ../../../final/evidence/browser/home-tabs-grouped.png
 evidence:
-  - ../../../final/evidence/browser/home-tabs-grouped.png
+  - ../../../final/evidence/browser/home-tabs-keycloak.png
  - ../../../final/evidence/browser/home-topic-tabs.png
+  - ../../../final/evidence/browser/home-topic-tabs-2.png
+  - ../../../final/evidence/browser/home-tabs-grouped.png
  - ../../../final/evidence/browser/tab-metrics.txt
 sourceRevision: tech-log@2026-09-02
 source:
@@ -62,23 +71,42 @@ tech-log-frontend : 604ded5 → de4cb8b → 3bb724b · 2b2f443

 ## 세 단계

-1단계는 주제 하나만 펼치고 아래에 「다른 주제 N개 보기」 한 줄을 뒀다. 그 줄은 목록을 다 읽고 나서야 만나는 곳이라 대개 지나쳤다 — JPA 주제는 홈에 있으면서도 없는 것과 같았다.
+1단계는 주제 하나만 펼치고 아래에 「다른 주제 N개 보기」 한 줄을 뒀다. 홈이 「무엇을 만들었나」로 시작하고 있었는데, 30초 안에 알아야 할 것은 무엇을 견줬는가였다.

-2단계에서 제목 자리를 주제 이름 탭이 대신하게 했다. 30px 에 굵기 650 으로 세웠다.
+그 줄은 목록을 다 읽고 나서야 만나는 곳이라 대개 지나쳤다. JPA 주제는 홈에 있으면서도 없는 것과 같았다.

-3단계에서 탭을 칩 크기로 낮추고 개수 상한을 없앴다. 상한은 주제마다 상세를 미리 받느라 둔 것인데, 그러면 상한 밖의 주제가 다시 밀려난다.
+2단계에서 제목 자리를 주제 이름 탭이 대신하게 했다. 30px 에 굵기 650 으로 세웠고, 고른 탭에 파란 밑줄을 뒀다.
+
+3단계에서 탭을 칩 크기로 낮추고 개수 상한을 없앴다. 주제가 열 개, 스무 개가 되면 이름만으로 화면이 덮이기 때문이다.
+
+:::evidence key="home-tabs-keycloak" alt="탭을 구역 제목 급으로 세운 2단계 화면" caption=" " zoom="true"
+:::
+
+## 상한이 왜 있었나
+
+상한은 주제마다 상세를 미리 받느라 둔 것이었다. 상세를 다 받으려면 요청이 주제 수만큼 늘어나므로 그 수를 제한해야 했다.
+
+그러면 상한 밖의 주제가 다시 밀려난다. 1단계에서 「다른 주제」 줄에 밀려나던 것과 같은 결과가 된다.

 ## 요청 구조를 바꿨다

 탭 줄은 목록 호출 하나가 주는 전부다. 상세는 고른 탭만 그때 받아 캐시한다.

-주제가 몇 개가 되든 홈이 처음 보내는 요청은 목록 하나와 주제 하나로 고정된다.
+그래서 주제가 몇 개가 되든 홈이 처음 보내는 요청은 목록 하나와 주제 하나로 고정된다. 상한을 없앨 수 있었던 이유가 이것이고, 상한을 먼저 없애고 요청을 그대로 뒀다면 주제가 늘수록 홈이 느려졌을 것이다.

 ## 시각 언어를 두 번 고쳤다

-고른 탭의 파란 밑줄을 없앴다. 주제가 스무 개면 밑줄 설 곳 스무 개가 나란히 늘어선다.
+고른 탭의 파란 밑줄을 없앴다. 주제가 스무 개면 밑줄 설 곳 스무 개가 함께 늘어선다.

-칩으로 낮추니 목록 위에 글자만 떠 있는 것처럼 보였다. 고른 탭에 알약 형태를 주고, 묶음의 윗선을 목록이 아니라 패널이 갖게 해서 탭 줄이 그 선에 바로 얹히게 했다.
+칩으로 낮추니 목록 위에 글자만 떠 있는 것처럼 보였다. 고른 것이 색으로만 달라 누를 수 있는 것으로 읽히지 않았고, 탭 줄과 목록 사이가 선 없이 30px 비어 두 덩어리로 갈렸다.
+
+:::evidence key="home-topic-tabs-2" alt="칩으로 낮춘 직후의 비교 구역 확대" caption=" " zoom="true"
+:::
+
+고른 탭에 알약 형태를 주고, 묶음의 윗선을 목록이 아니라 패널이 갖게 해서 탭 줄이 그 선에 바로 얹히게 했다.
+
+:::evidence key="home-tabs-grouped" alt="고른 탭에 형태를 주고 탭 줄을 패널 윗선에 얹은 최종 화면" caption=" " zoom="true"
+:::

 ## 확인하지 못한 것

@@ -50,23 +50,29 @@ topic (주제)

 ## 축 이름은 주제가 정한다

-내부 이름은 축으로 고정하고, 화면에 보이는 이름은 주제가 자기 칸에 적는다. 인증 경계 주제는 「구조」, 조회 성능 주제는 「조회 전략」이다.
+내부 이름은 축으로 고정하고, 화면에 보이는 이름은 주제가 자기 칸에 적는다.
+
+주제마다 비교하는 것이 다르기 때문이다. 인증 경계 주제는 credential 을 어디에 두느냐로 갈리므로 「구조」이고, 조회 성능 주제는 같은 데이터를 어떻게 읽느냐로 갈리므로 「조회 전략」이다. 이름을 한 값으로 고정하면 둘 중 하나에서 어긋난다.

 ## 기록은 여러 축에 걸린다

 한 기록이 여러 축에 걸릴 수 있다. PKCE 는 SPA 와 BFF 양쪽에 관계된다.

-아무 축에도 걸리지 않은 기록은 그 주제의 공통 기록으로 읽는다. 「공통」이라는 축을 따로 만들지 않는다.
+아무 축에도 걸리지 않은 기록은 그 주제의 공통 기록으로 읽는다. 「공통」이라는 축을 따로 만들지 않는 이유는, 만들면 그 축이 비교 화면에 한 줄로 서서 다른 축들과 견주는 것처럼 보이기 때문이다.

 ## 외래키가 없다

-`record_variant` 는 외래키를 갖지 않는다. 기록이 종류마다 다른 테이블에 살기 때문이다 — 문서·열린 질문·프로젝트 결정이 각각 다른 테이블이다. 종류와 아이디의 쌍으로만 가리킨다.
+기록이 어느 축에 걸리는지를 담는 표는 외래키를 갖지 않는다. 기록이 종류마다 다른 테이블에 살기 때문이다 — 문서·열린 질문·프로젝트 결정이 각각 다른 테이블이고, 하나의 외래키로 셋을 함께 가리킬 수 없다.

-검증 상태와 게시 기록이 이미 같은 방식으로 기록을 가리키고 있었다.
+그래서 종류와 아이디의 쌍으로만 가리킨다. 이 방식은 이 저장소에서 처음 쓰는 것이 아니고, 검증 상태와 게시 기록이 이미 같은 방식으로 기록을 가리키고 있었다.
+
+대가는 데이터베이스가 참조 무결성을 지켜 주지 않는다는 것이다. 기록을 지울 때 그 쌍을 함께 지우는 것은 코드가 한다.

 ## 사람이 쓰는 칸

-주제의 논지, 축의 요약과 결론은 기록을 합쳐 자동으로 나오는 글이 아니다. 특히 결론은 비교표가 읽는 칸이라 기록의 요약 첫 줄을 잘라 쓰면 안 된다.
+주제의 논지, 축의 요약과 결론은 기록을 합쳐 자동으로 나오는 글이 아니다.
+
+특히 결론은 비교표가 읽는 칸이라 기록의 요약 첫 줄을 잘라 쓰면 안 된다. 요약은 그 축이 무엇인지 말하고 결론은 그 축에서 무엇을 알게 됐는지 말하므로, 둘을 같은 문장으로 채우면 비교표가 아무것도 비교하지 않는다.

 ## 같은 구조가 다르게 보일 때

@@ -86,6 +92,6 @@ jpa-feed-query-performance  축 이름 「조회 전략」  축 3개
  fetch-join-paging  ← CASE 1
 ```

-축마다 기록이 하나씩이고 축 제목을 그 기록 제목과 비슷하게 적으면 「문서가 그대로 나온다」로 보인다.
+축마다 기록이 하나씩이고 축 제목을 그 기록 제목과 비슷하게 적으면 「문서가 그대로 나온다」로 보인다. 구조 차이가 아니라 내용 양의 차이다.

 <!-- body:end -->
@@ -32,24 +32,26 @@ source:

 ## 결정문

-한 질문에 여러 구조를 만들어 비교하는 경우, 주제를 그 수만큼 쪼개지 않고 주제 안에 축을 하나 둔다. 축의 이름은 주제가 정하고, 기록은 여러 축에 걸릴 수 있으며, 아무 축에도 걸리지 않은 기록은 그 주제의 공통 기록으로 읽는다.
+한 질문에 여러 구조를 만들어 비교하는 경우, 주제를 그 수만큼 쪼개지 않고 주제 안에 축을 하나 둔다.
+
+축의 이름은 주제가 정하고, 기록은 여러 축에 걸릴 수 있으며, 아무 축에도 걸리지 않은 기록은 그 주제의 공통 기록으로 읽는다.

 ## 판단 이유

-주제를 넷으로 쪼개면 PKCE·CSRF·Authorization Code 처럼 네 구조가 함께 쓰는 기록을 어디에 둘지 애매해진다. 어느 한 주제에 넣으면 나머지 셋에서 그 기록에 닿을 수 없고, 넷에 복사하면 같은 글이 넷이 된다.
+주제를 넷으로 쪼개면 네 구조가 함께 쓰는 기록을 어디에 둘지 애매해진다. PKCE·CSRF·Authorization Code 가 그런 기록이다. 어느 한 주제에 넣으면 나머지 셋에서 그 기록에 닿을 수 없고, 넷에 복사하면 같은 글이 넷이 된다.

-네 주제가 나란히 서면 그것이 같은 질문의 네 답이라는 것을 화면이 말하지 못해 비교도 어려워진다.
+비교도 어려워진다. 네 주제가 나란히 서면 그것이 같은 질문의 네 답이라는 것을 화면이 말하지 못하고, 독자는 목록에서 넷을 각각 열어 봐야 한다.

 축을 주제 안에 두면 공통 기록은 축을 고르지 않고 두면 되고, 여러 구조에 걸치는 기록은 여러 축에 건다. 화면은 축을 나란히 세워 비교로 그린다.

-축 이름을 주제가 정하게 한 것은 주제마다 비교 축이 다르기 때문이다. 인증 경계 주제의 축은 구조이고 조회 성능 주제의 축은 조회 전략이다.
+축 이름을 주제가 정하게 한 것은 주제마다 비교하는 것이 다르기 때문이다. 인증 경계 주제는 credential 을 어디에 두느냐로 갈리고 조회 성능 주제는 같은 데이터를 어떻게 읽느냐로 갈린다.

 ## 영향

-주제의 논지와 축의 이름·요약·결론은 기록에서 자동으로 나오지 않는다. 사람이 쓰는 칸이라 기록을 스무 개 붙여도 그 문장은 누가 고치기 전까지 바뀌지 않는다.
+축의 이름·요약·결론이 기록에서 자동으로 나오지 않는다. 주제의 논지와 축의 요약·결론은 사람이 쓰는 칸이고, 기록을 스무 개 붙여도 그 문장은 누가 고치기 전까지 그대로다.

 홈의 비교 구역에서 줄은 문서가 아니라 축이다. 줄을 늘리려면 Studio 에서 축을 추가해야 한다.

-기록이 어느 축에 걸리는지를 담는 표에 외래키를 걸 수 없다. 기록이 종류마다 다른 테이블에 살기 때문이다.
+기록이 어느 축에 걸리는지를 담는 표에 외래키를 걸 수 없다. 기록이 종류마다 다른 테이블에 살기 때문이고, 그래서 기록을 지울 때 그 쌍을 함께 지우는 것은 코드가 한다.

-축에 걸린 기록이 하나뿐이면 축 제목과 그 기록 제목이 비슷해져 「문서가 그대로 나온다」로 보인다. 구조 차이가 아니라 내용 양의 차이다.
+축이 붙은 기록 수가 적으면 「문서가 그대로 나온다」로 보인다. 축마다 기록이 하나씩이고 축 제목을 그 기록 제목과 비슷하게 적으면 그렇게 읽힌다. 구조 차이가 아니라 내용 양의 차이다.