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>
This commit is contained in:
DongHyeonka
2026-09-07 19:12:37 +09:00
co-authored by Claude Opus 5
parent b1653dbba8
commit 6917ce2420
14 changed files with 279 additions and 99 deletions
+53 -4
View File
@@ -1082,7 +1082,27 @@ QUESTION → 열린 질문
게이트웨이가 서버의 클라이언트 안전 메시지를 실어 나르고 화면이 그것을 보이게 했습니다.
**이 문제는 아직 완전히 안 끝났습니다** — §14.2 를 보세요.
서버는 오류 코드마다 고정 문구를 갖고 있습니다(`ManagementClientSafeMessages`). 예외의 원문
메시지를 그대로 내보내지 않는 이유가 클래스 javadoc 에 적혀 있습니다:
> code 별 고정 문구. 예외의 원문 메시지는 진단용이라 그대로 내보내지 않는다 — 저장소 제약
> 이름이나 SQL 조각이 새어 나갈 수 있고, 그건 클라이언트가 분기할 값도 아니다.
삭제와 관련된 코드만 여섯입니다. 화면이 추측하던 세 가지는 이 중 셋에 해당합니다:
```java
case VERSION_CONFLICT -> "다른 곳에서 먼저 수정되었습니다. 새로 불러온 뒤 다시 시도해 주세요";
case DOCUMENT_PUBLISHED -> "공개된 기록은 삭제할 수 없습니다. 먼저 공개를 취소해 주세요";
case DOCUMENT_IN_USE -> "이 기록을 참조하는 곳이 있어 삭제할 수 없습니다";
case QUESTION_IN_USE -> "이 질문을 참조하는 곳이 있어 삭제할 수 없습니다";
case DECISION_IN_USE -> "이 결정을 참조하는 곳이 있어 삭제할 수 없습니다";
case TOPIC_IN_USE -> "이 주제를 쓰는 기록이 있어 삭제할 수 없습니다";
```
코드는 카테고리와 재시도 가능 여부도 함께 답합니다 — `DOCUMENT_IN_USE(Category.CONFLICT, 409,
false)`. 그래서 화면이 셋을 나열하지 않아도 어느 것인지 코드로 갈립니다.
**이 문제는 아직 완전히 안 끝났습니다** — §16.1 을 보세요.
### 13.5 편집기 칸 이름을 공개 화면과 맞췄다 (`82e992d`)
@@ -1108,9 +1128,30 @@ QUESTION → 열린 질문
- `Redis 캐시``Redis 클러스터`**둘 다 `redis`** → 두 번째가 충돌
**한글을 버리지 않고 로마자로 옮깁니다.** 음절을 초성·중성·종성으로 산술 분해하므로 표가
필요 없고 결정적입니다: `백엔드 아키텍처``baekendeu-akitekcheo`. 국어의 로마자 표기법의
**자모 대응만** 적용하고 음운 변화 규칙은 일부러 뺐습니다 — slug 는 읽는 것이지 발음하는 것이
아니고, 그 규칙을 넣으면 같은 이름이 문맥에 따라 다른 slug 가 됩니다.
필요 없고 결정적입니다: `백엔드 아키텍처``baekendeu-akitekcheo`.
```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]}`;
}
```
국어의 로마자 표기법의 **자모 대응만** 적용하고 음운 변화 규칙은 일부러 뺐습니다. 함수의
javadoc 이 그 이유와 결과 모양까지 적어 두었습니다:
> 표기법은 국어의 로마자 표기법의 자모 대응만 쓴다 — 음운 변동(자음동화 같은 것)은 반영하지
> 않는다. slug 는 읽히기 위한 것이지 발음을 옮기기 위한 것이 아니고, 변동 규칙을 넣으면 같은
> 이름이 문맥에 따라 다른 slug 가 될 수 있다.
>
> 결과는 문서 slug 와 같은 모양이다 (`^[a-z0-9]+(?:-[a-z0-9]+)*$`) — 한 저장소가 두 가지 slug
> 규칙을 갖지 않도록.
---
@@ -1267,6 +1308,9 @@ jpa-feed-query-performance 축 이름 「조회 전략」 축 3개
### 15.4 배포 전 검증 (사람이 돌려야 하는 것)
`check:types` 는 tsconfig 여섯 개를 차례로 돌립니다 — app · node · test · recipes ·
web-worker · service-worker. 루트 tsconfig 를 직접 부르는 명령은 그중 어느 것도 지나지 않습니다.
```bash
# 프론트 — 다섯 개를 다 돌린다. npx tsc --noEmit 은 아무것도 검사하지 않는다
npm run check:types
@@ -1299,6 +1343,11 @@ python3 scripts/check-openapi.py && python3 scripts/check-consistency.py \
another record still links to this one; unlink it first
```
막는 것은 다섯 참조 중 하나인데, 다섯이 전부 같은 오류 코드(`DOCUMENT_IN_USE`)로 나갑니다.
클라이언트에 나가는 문구는 코드마다 하나로 고정돼 있으므로(§13.4), 참조 종류를 문구로 가르려면
코드를 먼저 갈라야 합니다. 위 영어 문장은 서버 안에 남는 진단 메시지이고 밖으로 나가지
않습니다(`DeleteDocumentDraftUseCase`).
실제로 막는 것은 이 중 하나입니다:
```sql