docs(TechLog): 얇은 Case 열 편과 Question 셋을 저장소 실물로 채운다

SSOT 를 저장소에서 확인해 더 보강하고 그것으로 다시 썼다. §7.2 참조 검사 SQL 을 문자열로 조립하는 실제 코드 — 컴파일러가 표 이름도 컬럼 이름도 보지 않는다는 것이 그 모양에서 드러난다 §11.2 section-heading-rank 가 미디어 쿼리 값을 먼저 걷어내는 이유(테스트 주석) §16.1 질문 삭제는 참조가 둘뿐이라 같은 문제가 덜하다는 대조 Case 열 편과 Question 셋을 다시 썼다. Question 은 사실·가정·미지수·제약을 갈라 채우고 선택지마다 무엇을 감수하는지 적었다 — 오류 코드를 나누면 계약과 반입한 두 저장소가 함께 움직인다는 것처럼. SSOT 62,643 → 68,319 자. 검사 넷 전부 통과한다. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-07 19:18:37 +09:00
parent 6917ce2420
commit fd221353a3
15 changed files with 162 additions and 50 deletions
@@ -61,7 +61,7 @@ tech-log-backend : 911e8ba — 없던 두 컨트롤러를 구현

 편집기는 질문 목록을 받아 고를 수 있게 그린다. 목록이 비면 「이 프로젝트에 열린 질문이 없습니다」를 적는다.

-요청이 실패했을 때도 빈 배열이 되고 있었다. 그래서 「없다」와 「못 읽었다」가 같은 화면이 됐다.
+요청이 실패했을 때도 빈 배열이 되고 있었다. 실패 경로가 빈 값을 만들고, 그 아래의 「비어 있으면 이 문구」 분기가 두 경우를 같은 화면으로 만든다.

 서버는 404 를 주고 있었다. 그 두 목록 조회에 컨트롤러가 없었고, 계약에는 선언돼 있어 프론트가 그것을 믿고 불렀다.

@@ -69,9 +69,9 @@ tech-log-backend : 911e8ba — 없던 두 컨트롤러를 구현

 작성자는 자기가 쓴 것과 화면을 대조한다. 화면이 「없습니다」라고 하면 아직 안 썼거나 게시하지 않았다고 읽는다.

-이 경우에는 넷이 있었고 공개 사이트에도 나오고 있었다. 두 화면이 같은 데이터베이스를 보는데 한쪽만 비어 있었으므로, 공개 사이트를 함께 보지 않으면 알아챌 방법이 없었다.
+이 경우에는 넷이 있었고 공개 사이트에도 나오고 있었다. 두 화면이 같은 데이터베이스를 보는데 한쪽만 비어 있었으므로, 공개 사이트를 함께 열어 보지 않으면 알아챌 방법이 없었다.

-작성 도구에서 이 부류가 특히 오래 숨는다. 읽기 전용 화면이면 방문자가 「데이터가 없나 보다」로 넘어가지만, 작성 도구에서는 그 오독이 곧바로 작업 판단이 된다 — 없다고 읽으면 다시 쓰게 된다.
+읽기 전용 화면이면 방문자가 「데이터가 없나 보다」로 넘어간다. 작성 도구에서는 그 오독이 곧바로 작업 판단이 된다 — 없다고 읽으면 다시 쓰게 된다.

 ## 못 읽었다고 적는다

@@ -79,11 +79,13 @@ tech-log-backend : 911e8ba — 없던 두 컨트롤러를 구현

 요청이 실패하면 실패했다고 적고 0건은 0건이라고 적는다. 이 둘을 구분할 수 있어야 작성자가 다음에 무엇을 할지 정한다 — 실패면 다시 부르거나 서버를 보고, 0건이면 쓰면 된다.

+실패를 빈 값으로 접는 지점을 없애는 것이 고치는 방법이다. 문구만 바꾸면 그 지점이 그대로여서 다음 화면에서 같은 일이 난다.
+
 ## 같은 판단을 다른 화면에

 주제 탭에도 같은 판단을 적용했다. 탭 하나를 못 받아도 탭 줄과 나머지 탭은 그대로 그리고, 못 받은 탭에는 못 받았다고 적는다.

-탭 줄이 남는 것이 중요하다. 탭 줄까지 사라지면 그 주제가 없는 것처럼 보이고, 그러면 못 읽은 범위가 화면에서 더 넓어진다.
+탭 줄이 남는 것이 중요하다. 탭 줄까지 사라지면 그 주제가 없는 것처럼 보이고, 못 읽은 범위가 화면에서 더 넓어진다.

 ## 확인하지 못한 것

@@ -70,10 +70,16 @@ tech-log-frontend : 6e784ed · fd73bc8 · 3bb724b

 > `Promise.all([gateway.foo()])` 은 foo 가 **거절하는 것만** 잡는다. 호출이 **동기적으로 던지면** 배열을 만드는 중에 터져 rejection handler 를 지나지 못하고, 그러면 홈 focus 한 칸 때문에 대시보드 전체가 빈 화면이 된다.

-배열 리터럴 안에서 함수를 부르는 시점은 `Promise.all` 에 배열이 넘어가기 전이다. 그 호출이 동기적으로 던지면 배열이 완성되지 않으므로 `Promise.all` 이 시작조차 하지 않고, 거기에 붙인 거절 처리기도 붙을 대상이 없다.
+배열 리터럴 안에서 함수를 부르는 시점은 그 배열이 `Promise.all` 에 넘어가기 전이다. 그 호출이 동기적으로 던지면 배열이 완성되지 않으므로 `Promise.all` 이 시작조차 하지 않고, 거기에 붙인 거절 처리기도 붙을 대상이 없다.

 거절만 잡는 처리로는 부족하다. 던지는 경로도 함께 잡아야 한 칸의 실패가 화면 전체로 번지지 않는다.

+## 왜 동기적으로 던질 수 있나
+
+게이트웨이 호출이 비동기 함수여도 그 안의 첫 줄이 동기적으로 실행된다. 인자를 검증하거나 연산을 고르는 코드가 거기 있고, 등록되지 않은 연산을 고르면 거기서 바로 던진다.
+
+그래서 「비동기 함수를 불렀으니 거절로 온다」는 전제가 성립하지 않는다.
+
 ## 탭에도 같은 판단을

 탭 줄은 목록 호출 하나가 주는 전부이고 상세는 고른 탭만 그때 받는다. 상세 하나를 못 받아도 탭 줄과 나머지 탭은 그대로 그리고, 못 받은 탭에는 못 받았다고 적는다.
@@ -62,7 +62,7 @@ tech-log-design-package : 76a7ccb

 ## null 을 돌려주고 걸러 내면 흔적이 없다

-매퍼가 아는 종류가 아니면 `null` 을 돌려주고, 호출부는 그 목록에서 `null` 을 걸러 낸다.
+매퍼가 아는 종류가 아니면 빈 값을 돌려주고, 호출부는 그 목록에서 빈 값을 걸러 낸다.

 이 조합에서는 오류가 나지 않고 빈 줄도 생기지 않는다. 목록의 길이만 줄어든다.

@@ -72,22 +72,27 @@ tech-log-design-package : 76a7ccb
 | 화면의 빈 줄 | x |
 | 목록 길이의 변화 | o |

-목록에 몇 개가 있어야 하는지 아는 사람만 알아챌 수 있고, 공개 화면에서는 그것을 아는 사람이 작성자뿐이다.
+목록에 몇 개가 있어야 하는지 아는 사람만 알아챌 수 있다. 공개 화면에서는 그것을 아는 사람이 작성자뿐이고, 작성자는 그 목록을 자기 기록의 전부로 읽는다.

 ## 응답 모양이 다른 목록에 다른 매퍼를 썼다

-프로젝트 기록 목록과 탐색의 지식 목록은 응답 모양이 다르다. 프로젝트 쪽은 관계 항목을 그대로 실어 요약도 주제도 게시일도 없었고, 지식 목록은 처음부터 그 칸들을 갖고 있었다.
+프로젝트 기록 목록과 탐색의 지식 목록은 응답 모양이 다르다.

-모양이 다른데 매퍼를 공유하면서 종류 판정까지 그쪽 것을 따랐다. 지식 목록의 매퍼는 CASE 와 REFERENCE 만 다루면 되는 화면을 위해 만들어졌으므로, 질문과 개념을 받으면 `null` 을 돌려준다.
+| | 프로젝트 기록 목록 | 탐색의 지식 목록 |
+|---|---|---|
+| 무엇을 실었나 | 관계 항목 그대로 | 요약·주제·게시일까지 |
+| 아는 종류 | (매퍼를 빌림) | CASE · REFERENCE |

-## 고친 것
+모양이 다른데 매퍼를 공유하면서 종류 판정까지 그쪽 것을 따랐다. 지식 목록의 매퍼는 CASE 와 REFERENCE 만 다루면 되는 화면을 위해 만들어졌으므로, 질문과 개념을 받으면 빈 값을 돌려준다.

-응답 모양에 맞는 매퍼를 쓰고 모든 종류를 싣게 했다. 목록 항목에 요약과 주제와 게시일을 더해 「제목만 있고 가운뎃점만 남은」 줄을 없앴다.
+## 두 가지를 함께 고쳐야 했다

-이 목록은 계약도 함께 고쳐야 했다. 관계 항목을 그대로 싣던 구조라 요약·주제·게시일을 담을 칸이 응답에 없었다.
+응답 모양에 맞는 매퍼를 쓰고 모든 종류를 싣게 했다. 그것만으로는 줄이 「제목만 있고 가운뎃점만 남은」 모양이었다.
+
+목록 항목이 관계 항목을 그대로 싣던 구조라 요약도 주제도 게시일도 담을 칸이 응답에 없었기 때문이다. 계약에 그 칸들을 더하고 백엔드가 그것을 채우게 한 뒤에야 줄이 완성됐다.

 ## 확인하지 못한 것

-`null` 을 돌려주고 호출부가 거르는 매퍼가 다른 목록에도 남아 있는지는 세지 않았다.
+빈 값을 돌려주고 호출부가 거르는 매퍼가 다른 목록에도 남아 있는지는 세지 않았다.

 <!-- body:end -->