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
@@ -64,7 +64,7 @@ tech-log-frontend : 5cffe30 · 7093d84

 ## 간헐적으로 보인 이유

-slug 생성이 영문 소문자와 숫자만 남기고 나머지를 버렸다. 한글 이름은 통째로 사라지므로, 결과가 이름에 영문이 얼마나 섞였는지에 따라 갈린다.
+slug 생성이 영문 소문자와 숫자가 아닌 것을 전부 하이픈으로 바꿨다. 한글은 전부 거기 걸리므로 이름에 섞인 영문과 숫자만 남는다.

 | 이름 | 옛 규칙이 만든 slug | 무엇이 일어났나 |
 |---|---|---|
@@ -72,13 +72,28 @@ slug 생성이 영문 소문자와 숫자만 남기고 나머지를 버렸다.
 | `Redis 캐시` | `redis` | 만들어짐 |
 | `Redis 클러스터` | `redis` | 두 번째가 충돌 |

-사용자는 둘 다 만났다. 어느 쪽도 「한글이 버려졌다」로 보이지 않고, 하나는 폼 오류로 하나는 중복 오류로 나타난다.
+두 결과가 서로 달라 보인다. 하나는 폼 오류이고 하나는 중복 오류이며, 어느 쪽도 「한글이 버려졌다」로 읽히지 않는다. 작성자에게는 「가끔 안 되다가 이름을 바꾸면 되는」 현상이었다.

 > 규칙은 간헐적이었던 적이 없다. **보이지 않았을 뿐이다** — slug 생성이 `[a-z0-9]` 만 남기고 나머지를 버려서, 한글 이름은 아무것도 기여하지 못했다.

 ## 산술 분해로 로마자를 만든다

-한글 음절은 초성·중성·종성이 정해진 순서로 조합된 코드다. 음절 코드에서 세 값을 산술로 분해할 수 있으므로 변환표가 필요 없고, 같은 입력에 늘 같은 결과가 나온다.
+한글 음절은 초성·중성·종성이 정해진 순서로 조합된 코드다. 음절 코드에서 시작 코드를 빼고 중성 수와 종성 수로 나누면 세 값이 그대로 나온다.
+
+```ts
+function romanizeSyllable(codePoint: number): string {
+  if (codePoint < SYLLABLE_BASE || codePoint > SYLLABLE_LAST) {
+    return String.fromCodePoint(codePoint);
+  }
+  const offset = codePoint - SYLLABLE_BASE;
+  const initial = Math.floor(offset / (MEDIAL_COUNT * FINAL_COUNT));
+  const medial = Math.floor((offset % (MEDIAL_COUNT * FINAL_COUNT)) / FINAL_COUNT);
+  const final = offset % FINAL_COUNT;
+  return `${INITIALS[initial]}${MEDIALS[medial]}${FINALS[final]}`;
+}
+```
+
+변환표가 필요 없고 같은 입력에 늘 같은 결과가 나온다. 한글이 아닌 문자는 그대로 돌려주고 뒤의 필터가 처리한다.

 ```text
 백엔드 아키텍처 → baekendeu-akitekcheo
@@ -86,9 +101,13 @@ slug 생성이 영문 소문자와 숫자만 남기고 나머지를 버렸다.

 ## 음운 변화 규칙을 뺀 이유

-국어의 로마자 표기법에는 자모 대응 외에 음운 변화 규칙이 있다. 그것을 넣지 않았다.
+국어의 로마자 표기법에는 자모 대응 외에 음운 변화 규칙이 있다. 그것을 넣지 않았고, 함수의 javadoc 이 이유를 적는다.

-slug 는 읽는 것이지 발음하는 것이 아니다. 음운 변화를 적용하면 같은 글자가 앞뒤에 무엇이 오느냐에 따라 다르게 옮겨지고, 그러면 이름의 일부만 바뀌어도 앞쪽 slug 가 달라진다. 결정적이지 않은 slug 는 주소로 쓸 수 없다.
+> 표기법은 국어의 로마자 표기법의 자모 대응만 쓴다 — 음운 변동(자음동화 같은 것)은 반영하지 않는다. slug 는 읽히기 위한 것이지 발음을 옮기기 위한 것이 아니고, 변동 규칙을 넣으면 같은 이름이 문맥에 따라 다른 slug 가 될 수 있다.
+
+## 문서 slug 와 같은 모양으로 맞췄다
+
+결과가 문서 slug 와 같은 정규식을 만족하게 했다. 한 저장소가 두 가지 slug 규칙을 갖지 않도록 한 것이고, 그래서 주제 slug 와 문서 slug 를 같은 검사로 볼 수 있다.

 ## 확인하지 못한 것