From fe1f23520e56fb06d467303be202ffa8f4714a87 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 15 Sep 2026 20:03:01 +0900 Subject: [PATCH] =?UTF-8?q?feat:=20=EA=B8=B0=EB=A1=9D=EB=A7=88=EB=8B=A4=20?= =?UTF-8?q?=EC=9D=B4=20=EC=A1=B0=EC=82=AC=EC=9D=98=20=EC=96=B4=EB=94=94?= =?UTF-8?q?=EC=AF=A4=EC=9D=B8=EC=A7=80=EB=A5=BC=20=EC=A0=9C=EB=AA=A9=20?= =?UTF-8?q?=EC=95=84=EB=9E=98=EC=97=90=20=EC=84=B8=EC=9A=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 이 사이트의 차별점은 "기록 하나에 아무 데서나 들어와도 그 결론을 만든 맥락의 사슬을 잃지 않는다"는 것이다. 그런데 그 사슬이 화면에서는 제목 위 얇은 breadcrumb 한 줄과 문서 맨 아래 「다음에 읽을 것」으로만 표현돼 있었다 — 검색으로 Case 하나에 들어온 사람은 바닥까지 내려가야 이 기록이 어느 프로젝트의 어느 질문에서 나왔는지 알 수 있었다. 저장은 되어 있는데 겪게 되지는 않는 상태였다. 제목·요약 바로 아래에 맥락을 하나의 덩어리로 세운다. 프로젝트 → 주제로 올라가는 길과, 같은 조사 안에서 이웃한 기록들을 함께 보인다. 이웃에는 작성자가 그 관계에 남긴 문장을 붙인다 — 「다음에 무엇을」보다 「왜 그것을」이 먼저 있어야 목록이 아니라 사슬로 읽힌다. 지금 보는 기록도 목록에 남겨 자기 자리가 보이게 한다. 여섯 종류 전부에 들어간다. 종류마다 하나씩 픽스처를 둔 `Record` 검사로 막았다 — 한 종류에서만 빠지면 그 종류로 들어온 방문자에게만 조용히 사슬이 끊긴다. Question 에서 빼 보고 그 검사만 실패하는 것을 확인했다. 화면 촬영기(`scripts/capture-screens.ts`)도 함께 넣는다. 라우트 레지스트리를 돌며 공개·Studio 전 화면을 찍는다. 찍을 목록을 손으로 적지 않고 `Record` 로 두어 라우트가 늘면 컴파일러가 빈 자리를 잡는다. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D --- .../2026-09-09-editor-design-proposal.md | 349 +++++++++++++ .../2026-09-09-studio-public-ux-review.md | 477 ++++++++++++++++++ ...026-09-15-techlog-product-design-review.md | 53 ++ package.json | 3 +- scripts/capture-screens.ts | 467 +++++++++++++++++ .../public-render/context-navigator.tsx | 107 ++++ .../public-render/public-record-renderer.tsx | 10 + .../tech-log/presentation/styles/globals.css | 142 ++++++ .../tech-log/context-navigator.test.tsx | 164 ++++++ .../tech-log/section-selector-scope.test.ts | 3 + .../studio-decision-authoring.test.tsx | 8 +- 11 files changed, 1781 insertions(+), 2 deletions(-) create mode 100644 docs/reviews/2026-09-09-editor-design-proposal.md create mode 100644 docs/reviews/2026-09-09-studio-public-ux-review.md create mode 100644 docs/reviews/2026-09-15-techlog-product-design-review.md create mode 100644 scripts/capture-screens.ts create mode 100644 src/features/tech-log/presentation/shared/public-render/context-navigator.tsx create mode 100644 tests/features/tech-log/context-navigator.test.tsx diff --git a/docs/reviews/2026-09-09-editor-design-proposal.md b/docs/reviews/2026-09-09-editor-design-proposal.md new file mode 100644 index 0000000..a6e71f1 --- /dev/null +++ b/docs/reviews/2026-09-09-editor-design-proposal.md @@ -0,0 +1,349 @@ +# 글 쓰는 화면 설계안 — 원고·판면·자료 + +- 일시: 2026-09-09 +- 대상: `/studio/documents/:id/edit` (Case·Question·Reference·Concept·Decision 공용 편집기) +- 측정 문서: `c1158754…` Collection Fetch Join Pagination의 In-memory Paging (본문 2,707자, Asset 27개) +- 선행 문서: `2026-09-09-studio-public-ux-review.md` + +--- + +## 1. 진단 — 세 가지가 각자 다른 곳을 본다 + +### 1.1 쓰는 글자와 읽는 글자가 다르다 + +| | 폰트 | 크기 / 줄간 | 한글 1자 폭 | 한 줄 자수 | +|---|---|---|---|---| +| 편집 상자 | IBM Plex Mono | 13px / 20.15px | 11.96px | **52자** | +| 즉시 미리보기 | Pretendard | 21px / 34.02px | 18.15px | **21자** | +| 실제 공개 페이지 | Pretendard | 21px / 34.02px | 18.15px | **43자** | + +세 판면이 전부 다르다. 세 가지가 따라온다. + +**하나.** 편집 상자에서 한 줄인 문장이 미리보기에서 2.5줄이 된다. +줄바꿈 위치, 문단 덩어리, 호흡 — 글 쓰면서 만드는 것 중 어느 것도 오른쪽에 그대로 나타나지 않는다. +오른쪽은 "방금 쓴 글"이 아니라 "방금 쓴 글의 다른 판본"이다. + +**둘.** 미리보기(21자)가 공개(43자)와도 다르다. **「즉시 미리보기」라는 이름이 사실이 아니다.** +실제로 어떻게 보일지는 게시해 봐야 안다. + +**셋.** `IBM Plex Mono`에는 한글 글리프가 없다. 편집 상자의 한글은 폴백 폰트로 떨어진다. +한 상자 안에서 라틴 문자는 모노, 한글은 다른 폰트로 렌더된다. 자간·기준선이 어긋난다. + +덧붙여 52자/줄은 한국어 산문 편집에 **너무 길다.** 한글 본문의 적정 측정폭은 25~40자다. +줄 끝에서 다음 줄 머리로 눈이 되돌아오는 거리가 길어 오독이 생긴다. +반대로 미리보기의 21자는 **너무 짧아** 문단이 세로로 늘어진다. +셋 중 유일하게 제대로 된 판면은 공개 페이지(43자)다. 정작 그건 쓸 때 볼 수 없다. + +### 1.2 스크롤이 셋이다 + +한 화면에 독립된 스크롤 컨텍스트가 세 개 있다. + +| 컨텍스트 | 내용 높이 | 보이는 높이 | 숨겨진 비율 | +|---|---|---|---| +| 페이지 | 6,075px | 900px | 85% | +| `textarea.studio-markdown-field` | 1,833px | 628px | **66%** | +| `section.studio-editor-preview` | 9,799px | 852px | **91%** | + +셋은 서로 연결돼 있지 않다. 지금 쓰는 문단의 결과를 보려면 **세 번째 스크롤바를 따로 굴려야 한다.** +미리보기는 `position: sticky; top: 28px`이라 화면에는 늘 있지만, 늘 문서 맨 위를 보여준다. +본문 y=3,802 지점을 편집하는 동안 오른쪽은 제목과 첫 문단을 비추고 있다. + +실측: `scrollY = 3110`일 때 +- 본문 상자는 630px 중 **208px만** 화면에 남는다 (커서 위치가 안 보인다) +- 미리보기는 `검증 기록 / JPA 피드 조회 성능 / … / Collection Fetch Join Pagination의 In-memory Paging` — 문서 첫머리 + +### 1.3 Asset은 이름표 27장이다 + +`/studio/documents/:id/edit`의 `본문에 Asset 삽입` 패널 (문서 y=4,460, 높이 1,321px): + +- Asset 27개가 **전부 텍스트 이름 pill**로 나열된다. **썸네일 0개.** +- 이름이 `<의미>-<8자리 해시>` 구조다. 해시만 다른 동명 항목이 나란히 있다. + +``` +ap4-edge-trust-architecture-8125e9e8 ap4-edge-trust-architecture-1a916e10 +ap3-bff-session-flow-1b005e15 ap3-bff-session-flow-a8dfff6f +ap2-mediator-handoff-flow-efe7039c ap2-mediator-handoff-flow-8c2a6f8f +``` + +같은 그림의 다른 버전인지, 아예 다른 그림인지 **이 화면에서는 알 방법이 없다.** +`screenshot-from-2026-08-21-18-04-49-72f1f9c6` 처럼 파일명이 그대로 올라온 것도 섞여 있다. + +- pill 27개마다 옆에 `삭제` 버튼이 붙어 있다. **삽입하려고 여는 목록에 영구 삭제가 27번.** + (확인 절차는 없다 — 선행 리뷰 B3) +- 본문 상자(y 3,802~4,432)와 이 패널(y 4,460~)은 900px 뷰포트에 **같이 담기지 않는다.** + 커서를 놓고 목록으로 내려가면 커서가 안 보이고, 목록을 보며 고르면 본문이 안 보인다. + +삽입 결과는 본문에 이렇게 들어간다. + +``` +:::evidence key="batch-fetch-in-clause-cb44066a" alt="조회 코드, Hibernate 세션, feed_items, +highlights 네 참여자 사이에서 부모 페이징이 먼저 일어나고 그다음 자식 IN 배치 조회가 +일어나는 순서도." caption=" " zoom="true" +::: +``` + +**한 줄 270자.** 52자/줄 상자에서 5~6줄을 차지하며 문장 흐름을 끊는다. +`alt`를 성실하게 쓴 건 좋은 습관인데, 그 성실함이 원고를 망가뜨리는 구조다. +`caption=" "` — 캡션을 안 쓰려고 공백 하나를 넣은 흔적도 남아 있다. + +### 1.4 왜 이렇게 됐나 — 폼이 스키마를 그대로 비춘다 + +편집 화면은 데이터 모델을 1:1로 옮긴 CRUD 폼이다. +Case = 문제 / 결론 / 검증환경 / 재현조건 / 마지막검증일 / 본문. 각 필드에 라벨 하나, textarea 하나. +선언 순서대로 세로로 쌓고, 폭도 무게도 같게. + +이건 데이터를 **입력**하는 화면의 문법이지, 글을 **쓰는** 화면의 문법이 아니다. 세 가지가 깨진다. + +**하나 — 「지금 어디인가」가 없다.** Question 문서 실측 7,540px에 textarea 21개. +전부 같은 크기, 같은 테두리, 같은 배경. `확인한 사실 2`와 `선택지 4`를 눈으로 구별할 수 없다. +목차도 접기도 앵커도 없다. 문서를 하나의 형태로 볼 방법이 없다. + +**둘 — 메타데이터와 산문이 같은 격이다.** `마지막 검증일`(날짜 하나)과 `본문`(2,707자의 논증)이 +둘 다 "라벨 붙은 입력칸"이다. 하나는 3초, 하나는 3시간이 드는 일인데 같은 옷을 입고 있다. + +**셋 — 고도(altitude)가 하나뿐이다.** 글쓰기 도구에는 두 개의 고도가 있어야 한다. + +- **구조 고도** — 문서를 형태로 본다. 어떤 섹션이 있고, 뭐가 비었고, 근거가 어디 붙었는지. + 계획하고, 재배치하고, 완성도를 점검할 때 쓴다. +- **원고 고도** — 한 대목에 집중한다. 넓은 판면, 편한 글자. + +현재 편집기는 이 둘 사이의 쓸모없는 중간에 갇혀 있다. +전체를 보기엔 7,540px이라 형태가 안 보이고, 쓰기엔 13px 모노 상자가 내용의 66%를 가린다. + +--- + +## 2. 「텍스트 상자 말고 다른 방식」— 선택지는 셋이다 + +| | 방식 | 대표 | 이 제품에서 | +|---|---|---|---| +| A | 블록 에디터 | Notion, Craft | 스키마와 충돌. `/` 메뉴는 다른 제품의 어휘 | +| B | **마크다운 + 인라인 렌더** | Obsidian Live Preview, Typora | **권장** | +| C | 위지윅 | Google Docs | 마크다운 소스를 잃는다. 이 저자에겐 손해 | + +**C를 버리는 이유.** 이 저자는 `:::evidence`, GFM 표, `EXPLAIN` 출력, 코드 펜스를 직접 쓴다. +소스 접근을 뺏으면 지금 쓰는 글을 못 쓰게 된다. + +**A를 버리는 이유.** 문서 종류마다 스키마가 정해져 있다(Case는 문제·결론·환경·재현·본문). +블록 에디터는 "무엇이든 놓을 수 있다"는 전제 위에 서는데, 이 제품의 가치는 그 반대다 — +**정해진 칸을 채우게 하는 것**이 이 도구의 존재 이유다. 또 이 사이트의 디자인 언어는 +타이포로만 말하는 절제된 문법인데, `/` 메뉴와 블록 핸들은 다른 제품의 시각 어휘를 들여온다. + +**B를 고르는 이유.** 소스는 마크다운 그대로 두되, **소스를 읽을 만하게 만든다.** +그러면 오른쪽 미리보기의 필요 자체가 줄어들고, 스크롤 동기화 문제가 사라진다. +동기화를 잘 하는 것보다 **동기화가 필요 없게 만드는 것**이 우아하다. + +--- + +## 3. 세 방향 + +### 방향 A — 「한 장의 원고」 + +**논지.** 편집기가 곧 문서다. 폼도 미리보기도 없고, 타이핑해 넣는 한 장의 지면만 있다. + +- 스키마 필드가 원고 흐름 안의 **유형 있는 블록**이 된다. 읽는 순서 그대로, 게시될 모습 그대로. +- 미리보기 패널 없음 — 미리볼 것이 없으니까. 편집면 = 게시면. +- 근거 이미지는 들어갈 자리에 실제 그림으로 놓인다. +- slug·Topic·Project·검증일은 흐름에서 빠져 접히는 머리말로. +- 서명 인터랙션: `/`가 **이 문서 종류에 남은 스키마 칸만** 보여준다. 폼 없이 구조가 지켜진다. +- 배제: 좌우 분할, 마크다운 소스, 미리보기. +- 위험: 가장 크다. 마크다운 소스를 잃는다. 블록당 「소스 보기」로 완화해야 한다. + +### 방향 B — 「원고와 판면」 + +**논지.** 두 판을 남기되 하나의 기구로 묶는다. 왼쪽은 원고, 오른쪽은 판면, 둘은 위치에 대해 절대 어긋나지 않는다. + +- 픽셀 비율이 아니라 **블록 경계**(`##` 헤딩, 지시문 블록) 기준의 양방향 스크롤 동기화. +- 지금 커서가 있는 블록을 양쪽에서 같이 강조. +- 본문 textarea의 고정 높이를 없애 내용만큼 자라게 한다 → **스크롤 컨텍스트 3개가 2개로.** +- 근거는 원고 쪽에서도 270자 지시문이 아니라 카드로 보인다. +- 서명 인터랙션: 미리보기가 **교정쇄**다. 오른쪽 문단을 클릭하면 왼쪽 커서가 그 자리로 간다. +- 배제: 위지윅. 마크다운이 계속 정본이다. +- 위험: 동기화 구현이 까다롭다. 그리고 아래 4.2에서 보듯 **1440px에서는 양쪽을 동시에 제대로 못 놓는다.** + +### 방향 C — 「작업대」 + +**논지.** 문서는 섹션의 더미다. 한 번에 한 섹션을 전폭으로 다루고, 전체 형태는 레일이 갖는다. + +- 왼쪽 레일: 문서의 구조 — 모든 섹션(스키마 + `##`), 채움 상태, 분량, 근거 개수. + 1.4에서 없다고 한 「지금 어디인가」가 여기 산다. +- 가운데: **한 섹션만.** 649px 칸이 아니라 720px 판면에 17px. +- 오른쪽: 기본은 없음. 미리보기는 가운데를 **대체하는** 토글. +- 근거: 쓰는 영역 하단에 상주하는 자료 선반. 썸네일, 이 문서의 주제 것부터. +- 서명 인터랙션: 선반에서 본문으로 **끌어 놓으면** 지시문이 대신 쓰이고 썸네일이 그 자리에 남는다. +- 배제: 문서 전체를 한눈에 보기, 상시 좌우 분할. +- 위험: 문서를 통으로 사고하는 사람은 한 섹션씩 보는 걸 답답해한다. 레일이 강해야 성립한다. + +--- + +## 4. 권고 — B의 척추에 C의 두 기관, A의 근거 표현 + +세 개를 평균 내지 않는다. **B의 구조적 결정**(마크다운 정본 + 위치가 어긋나지 않는 두 면)을 뼈대로 삼고, +**C의 레일과 자료 선반**, **A의 인라인 근거 렌더링**을 가져온다. + +이유는 브리프에 있다. + +- 이 저자는 표·코드·`EXPLAIN` 출력·다이어그램이 섞인 측정 기반 산문을 쓴다. 마크다운이 정본이어야 한다 (A 탈락) +- 호소한 불편은 셋 — ①미리보기가 따로 논다 ②자료가 뭐가 있는지 모르겠다 ③그냥 상자다. + ①은 B, ②는 C의 선반, ③은 메타데이터와 산문의 고도를 나누는 것으로 풀린다 +- 사이트의 디자인 언어가 절제된 타이포다. 블록 에디터의 어휘를 들이면 제품이 둘로 쪼개진다 + +### 4.1 판면 — 쓰는 글자를 읽는 글자에 맞춘다 + +``` +산문 편집: Pretendard 17px / 1.75 (29.75px), 측정폭 620~660px → 34~36자/줄 +코드·지시문: IBM Plex Mono 13px / 1.55 (지금 값 유지) +``` + +**픽셀이 아니라 자수를 맞춘다.** 공개는 21px·43자다. 편집을 21px로 하면 화면에 안 담기고, +13px 모노를 유지하면 52자로 벌어진다. 17px·34~36자면 **줄바꿈 감각이 공개로 이전된다** — +한 문장이 편집에서 2줄이면 공개에서도 2줄이다. 이게 지금 없는 것이다. + +부수 효과로 한글 폴백 문제가 사라진다. 산문에서 모노를 걷어내면 한 상자 안에 폰트가 하나만 남는다. + +### 4.2 상시 좌우 분할을 포기한다 + +미리보기를 공개와 같은 43자/줄로 맞추려면 `21px × 18.15px × 43자 = 780px`가 필요하다. +현재 미리보기 패널은 656px, 그 안의 본문은 **399px**다. + +``` +1440px 화면에서: 편집 620 + 간격 40 + 미리보기 780 = 1440 → 좌우 여백 0 +``` + +**1440px에서는 양쪽을 동시에 제대로 놓을 수 없다.** 지금 오른쪽이 21자/줄인 건 그래서다. +반쪽짜리 미리보기를 붙잡고 있으면 이 계산은 영원히 안 맞는다. + +그래서: + +| | 지금 | 제안 | +|---|---|---| +| 기본 | 편집 649 + 미리보기 656 (상시) | **편집 단일 판, 660px 판면 중앙** | +| 확인 | 오른쪽 21자/줄 축소판 | **전폭 미리보기 토글 (`Ctrl+/`), 공개와 픽셀 동일** | +| 근거·표·코드 | 오른쪽에서만 확인 | **그 자리에서 인라인 렌더** | + +핵심은 마지막 줄이다. **소스로 읽을 수 있는 것(산문)은 소스로 읽고, +소스로 읽을 수 없는 것(이미지·표·코드 하이라이팅)만 그 자리에서 결과로 보여준다.** +그러면 스크롤 동기화라는 문제가 존재하지 않게 된다. 볼 것이 이미 거기 있으니까. + +동시에 스크롤 컨텍스트가 **3개에서 1개**로 준다 — textarea 고정 높이 제거, 미리보기 패널 제거. +페이지 하나만 구르면 된다. + +> 1920px 이상에서는 B의 원안대로 좌우 분할을 켤 수 있다. 780px 미리보기가 들어가니까. +> 다만 기본값은 아니다 — 기본이 예외 상황에 맞춰지면 안 된다. + +### 4.3 자료 — 이름표 27장을 그림으로 바꾼다 + +| # | 문제 | 처방 | +|---|---|---| +| 1 | 썸네일 0개, 해시 이름 27개 | **96×72 썸네일 격자.** 27개면 4열 × 7행 — 한 화면에 다 들어온다 | +| 2 | `…-8125e9e8` / `…-1a916e10` 구별 불가 | 표시 이름을 사람 말로. `Edge 신뢰 구조 · v2`. 해시는 상세에만 | +| 3 | 27개 중 이 문서와 관련된 건 3~4개 | 정렬을 **이 문서의 주제·프로젝트 → 최근 업로드 → 전체**로. 상단에 「이 주제에서 쓰인 것」 묶음 | +| 4 | 패널이 본문에서 658px 아래 | 커서 자리에서 여는 **인라인 팝오버** (툴바 `그림` 또는 `/그림`). 스크롤 이동 0 | +| 5 | 삽입 목록에 `삭제` 27개 | **삭제를 목록에서 뺀다.** 자료 관리는 `/studio/assets`에서만 (그리고 그 화면을 nav에 넣는다 — 선행 리뷰 B2) | +| 6 | 삽입 결과가 270자 지시문 | 본문에 **썸네일 + 캡션 카드**. `alt`·`caption`·`zoom`은 카드를 눌러 편집. 「소스 보기」로 원문 확인 | +| 7 | `caption=" "` 같은 잔재 | 카드 편집기에서 캡션 비우면 속성 자체를 안 쓴다 | + +6번이 특히 중요하다. 지금 구조는 **성실한 `alt`가 원고를 망가뜨린다.** +카드로 빼면 접근성 텍스트를 길게 쓸수록 좋아지기만 한다. + +4번의 서명 인터랙션은 C에서 가져온다 — **선반에서 본문으로 끌어 놓기.** +놓은 자리에 지시문이 쓰이고 썸네일이 남는다. 「어디에 넣을지」와 「무엇을 넣을지」를 한 동작으로 합친다. + +### 4.4 정보 배치 — 스키마 폼을 원고로 + +**메타데이터를 흐름에서 뺀다.** +제목·slug·요약·Topic·Project·관계는 접히는 머리말 한 줄로. +처음 만들 때만 펼쳐지고, 그다음부터는 `JPA 피드 조회 성능 · Liner N+1문제 · 관계 3` + 「펼치기」. +지금은 이것들이 본문 위 1,900px을 차지한다. + +**Case의 기록 필드를 카드 하나로 묶는다.** +`문제`·`결론`·`검증 환경`·`재현 조건`·`마지막 검증일`을 2열 「기록 카드」로. +지금은 세로 스택으로 1,240px. 카드로 묶으면 600px 안에 들어가고, 무엇보다 +**이 다섯이 한 덩어리라는 사실**이 보인다. 지금은 본문과 같은 격의 낱개 칸들이다. + +**본문이 첫 화면의 주인이 된다.** +현재 900px 중 530px을 지나야 첫 입력칸이 나온다 (`문서 편집` + 문서 제목 + `DOCUMENT` + `기본 정보`). +문서 제목은 한 화면에 세 번 나온다 — 부제, 제목 입력칸, 미리보기. +머리말을 접고 나면 **첫 화면에서 바로 본문**이다. + +**반복 그룹을 행으로.** +Question의 `확인한 사실`·`가정`·`남은 미지수`·`제약`·`검토한 선택지`는 지금 +항목 하나가 textarea 1개 + 버튼 3개 ≈ 190px, 17개가 쌓여 있다 (버튼만 51개). +→ 한 줄 요약 행 + 클릭하면 인라인으로 펼쳐지는 편집. 재정렬은 드래그 핸들 하나로. +버튼 51개가 **핸들 17개**로 준다. + +**왼쪽 레일 — 「지금 어디인가」.** +스키마 섹션 + 본문 `##` 헤딩의 목차. 각 항목에 채움 상태(빈칸/작성 중/완료), 분량, 근거 개수. + +지금 하단 바에 이렇게 적혀 있다. + +> 게시를 누르면 채워야 할 칸을 그 자리에 표시합니다. + +**누르기 전에 보여야 한다.** 레일이 그 일을 한다. +이 사이트에는 이미 공개 상세 페이지에 sticky 목차 구현이 있다 (`position: sticky; top: 28px`, 정상 동작). +새로 만들 것이 아니라 옮겨 오면 된다. + +### 4.5 되돌릴 수 없는 것 + +선행 리뷰 M1과 이어진다. `저장`(rgb 90,93,100 / 600)과 `게시`(rgb 23,24,27 / 700)의 차이가 +회색 한 단계와 굵기 100뿐이다. 같은 16px, 같은 92×44 박스, 배경 없음. + +타이포로만 격을 나누는 방향(`studio.css:60-67`)은 유지할 만하다. 다만 +**되돌릴 수 없는 동작은 위계가 아니라 절차로 구분한다.** `게시`는 확인 단계를 거치게 하고, +그 단계에서 무엇이 공개되는지 보여준다 — 이미 `/publish` 화면이 그 일을 하도록 만들어져 있다. +편집기의 `게시` 버튼은 그 화면으로 가는 링크면 충분하다. + +--- + +## 5. 실행 순서 + +측정된 불편을 큰 것부터, 위험이 낮은 것부터. + +**1단계 — 판면 (1~2일, 위험 낮음)** +1. 산문 편집 폰트를 `Pretendard 17px / 1.75`, 판면 620~660px로 (4.1) +2. 코드·지시문만 `IBM Plex Mono 13px` 유지 +3. 본문 textarea 고정 높이 제거 → 내용 높이만큼 성장 (스크롤 컨텍스트 3 → 2) + +> 이것만으로 「52자 vs 21자」와 「66% 숨김」이 사라진다. 코드는 CSS 수준이다. + +**2단계 — 자료 (3~5일)** +4. 자료 목록을 썸네일 격자로, 표시 이름을 사람 말로 (4.3 #1, #2) +5. 삽입 목록에서 `삭제` 제거, `/studio/assets`를 nav에 추가 (4.3 #5) +6. 이 문서의 주제·프로젝트 우선 정렬 (4.3 #3) + +**3단계 — 배치 (1주)** +7. 메타데이터 머리말 접기 (4.4) +8. Case 기록 카드 2열 묶음 (4.4) +9. 왼쪽 목차 레일 — 공개 상세 페이지 구현 이식 (4.4) +10. 반복 그룹을 행 + 인라인 편집 + 드래그 핸들 (4.4) + +**4단계 — 원고와 판면 (2주)** +11. 상시 좌우 분할 해제, 전폭 미리보기 토글 `Ctrl+/` (4.2) +12. 근거·표·코드 인라인 렌더 (4.2, 4.3 #6) +13. 커서 자리 자료 팝오버 + 끌어 놓기 삽입 (4.3 #4) +14. 1920px 이상에서만 좌우 분할 옵션 (4.2) + +--- + +## 6. 측정 근거 + +``` +편집 상자 IBM Plex Mono 13px/20.15px, 폭 649px, 한글 11.96px/자 → 52자 +미리보기 Pretendard 21px/34.02px, 본문 폭 399px → 21자 +공개 페이지 Pretendard 21px/34.02px, 본문 폭 790px → 43자 + +스크롤 컨텍스트 + document 6,075 / 900 (85% 숨김) + textarea.studio-markdown-field 1,833 / 628 (66% 숨김) + section.studio-editor-preview 9,799 / 852 (91% 숨김) + +편집기 세로 좌표 (문서 기준) + 본문 textarea y 3,802 h 630 + Asset 삽입 패널 y 4,460 h 1,321 + → 900px 뷰포트에 동시 수용 불가. scrollY 3,110에서 본문 208/630px만 노출 + +Asset 27개 · 썸네일 0 · 삭제 버튼 27 + 해시만 다른 동명 3쌍 확인 + evidence 지시문 1개 = 270자 (52자/줄 상자에서 5~6줄) +``` + +스크린샷: `w-editor-asset-reality.png` (ai-design-harness 루트) — 위 사실이 한 화면에 다 있다. diff --git a/docs/reviews/2026-09-09-studio-public-ux-review.md b/docs/reviews/2026-09-09-studio-public-ux-review.md new file mode 100644 index 0000000..0fbc079 --- /dev/null +++ b/docs/reviews/2026-09-09-studio-public-ux-review.md @@ -0,0 +1,477 @@ +# TechLog Studio · Public 사이트 UX 리뷰 + +- 일시: 2026-09-09 +- 대상: `https://hyeonworks.com` (public) / `https://hyeonworks.com/studio` (Studio, 로그인 상태) +- 방법: Playwright로 전 라우트 실측(뷰포트 1440x900 / 390x844), 계산 스타일·DOM·번들 대조 +- 데이터: 실서버 실데이터 (작업본 61, 게시 기록 21, 주제 3, 프로젝트 4, 공개 기록 18, Asset 20) +- Verdict: **NEEDS_FIX** — 출시 차단 5건, 높음 7건 + +--- + +## 0. 한 줄 요약 + +편집기와 공개 상세 페이지의 **내용 구조는 이미 제품급**이다. 문제는 그 위에 얹힌 **작업 흐름**이다. +상태가 URL에 없어서 되돌아올 수 없고, 게시 파이프라인 3화면 중 2화면이 스타일 없이 나가며, +같은 개념이 화면마다 다른 이름으로 불린다. "초기 단계 느낌"의 정체는 미감이 아니라 이 세 가지다. + +--- + +## 1. 출시 차단 (Blocking) + +### B1. 검증·미리보기 화면이 CSS 없이 배포됨 + +`workflow.module.css`를 **import하는 파일이 하나도 없다.** Vite CSS Module은 import되어야 번들에 들어간다. + +``` +$ grep -rn "workflow.module.css" src/ # 0건 +$ grep -l "studio-workflow-screen" dist/assets/*.css # 없음 +$ grep -l "studio-primary-button" dist/assets/*.css # dist/assets/index-BOZQfhnb.css +``` + +실측 (`/studio/documents/:id/validation`): + +| 요소 | 실제 | 다른 Studio 페이지 | +|---|---|---| +| `main h1` | 16px / 400 | 62px | +| `main h2` | 16px / 400 | 27px | + +영향 화면 3개 — `validation-screen.tsx`, `public-preview-screen.tsx`, `validation-report.tsx`. +`/preview`에서는 링크 두 개가 공백 없이 붙어 `검증 화면으로 이동편집으로 돌아가기`로 렌더된다. + +자매 파일 `publication-flow.module.css`는 `studio/components/publication-flow-classes.ts:1`에서 import된다. +그 패턴을 workflow 쪽에서 빠뜨린 것이다. + +> 수정: `workflow.module.css`를 참조하는 `workflow-classes.ts`를 만들어 import하거나, +> `:global()` 규칙을 `studio.css`로 옮긴다. 후자가 이 저장소의 다른 studio 스타일과 일관된다. + +### B2. Asset 라이브러리에 스타일이 없고, 진입 경로도 없다 + +`asset-library.tsx`가 쓰는 클래스 중 CSS가 정의된 것이 하나도 없다. + +``` +asset-library-list → CSS 규칙 0건 +asset-detail → 0건 +asset-detail-actions → 0건 +studio-assets-page → 0건 +``` + +결과: `
  • `가 브라우저 기본 `display: list-item`으로 떨어지고, 키·상태·사용 수가 공백 없이 이어붙는다. + +``` +vm-exit-handling-cycle-f8448581READY사용 0건 +ap4-edge-trust-architecture-8125e9e8READY사용 0건 +``` + +- 이미지 Asset 20개인데 **썸네일이 하나도 없다** (`item.querySelector('img')` → null) +- `/studio/assets`는 **Studio nav에 없다**. nav href = documents / publications / documents/new / taxonomy / releases / `/` + 화면 설명은 "사용하지 않는 Asset을 정리합니다"인데 그 화면에 갈 방법이 URL 직접 입력뿐이다. + +### B3. 삭제에 확인도 되돌리기도 없다 + +``` +$ grep -rn "confirm(" src/features/tech-log/presentation/studio/ # 0건 +$ grep -rn "실행 취소|되돌리기|undo" src/features/tech-log/presentation/studio/ # 0건 +``` + +문서·주제·프로젝트·릴리즈 전부 `삭제` 한 번에 영구 삭제된다. +그리고 그 `삭제`가 행에서 **시각적으로 가장 강한 요소**다. 작업본 목록 첫 행 실측: + +| 요소 | 색 | 굵기 | 크기 | +|---|---|---|---| +| `삭제` | `rgb(180,35,42)` | 600 | 16px | +| `편집` | `rgb(90,93,100)` | 600 | 16px | +| 문서 제목 | `rgb(23,24,27)` | 400 | 17px | +| `검증하기` (실제 다음 단계) | `rgb(23,24,27)` | **400** | **13px** | + +`document-list.tsx:331` 주석은 이 문제를 이미 인지하고 "편집을 같은 격의 버튼으로 올리고 삭제는 그 옆에 둔다"고 적었다. +그런데 정작 행의 목적인 `검증하기`가 13px/400으로 가장 약하다. 우선순위가 뒤집혀 있다. + +### B4. 공개 사이트에 공유·검색 메타데이터가 없다 + +서버가 내려주는 HTML은 **모든 URL에서 동일**하다. + +```html +Tech Log + +``` + +제목·설명은 JS가 마운트된 뒤에 바뀐다. Slack/카카오/X/Discord 링크 미리보기는 JS를 실행하지 않는다. + +| 항목 | 상태 | +|---|---| +| `og:*` | 0개 | +| `twitter:*` | 0개 | +| `link[rel=canonical]` | 없음 | +| JSON-LD (`Article`) | 0개 | +| `sitemap.xml` | **404** | + +`public/robots.txt`는 `Sitemap: https://hyeonworks.com/sitemap.xml`을 광고하는데 그 URL이 404다. + +> 지금 상태로 글을 공유하면 어디에 붙이든 "Tech Log — Tech Log frontend"로 보인다. +> 공개 기록을 읽히려고 만든 사이트에서 이건 기능 결손이다. + +### B5. 라우트 프리픽스 밖 URL은 앱 404를 못 만난다 + +| URL | 결과 | +|---|---| +| `/cases/does-not-exist-slug` | 앱 404 정상 (`404 / 페이지를 찾을 수 없습니다.`) | +| `/no-such-page` | **nginx 원시 `Not Found`** (흰 화면, 헤더·내비 없음) | + +`NOT_FOUND` 라우트는 `tech-log-route-contract.ts:65`에 `path: "*"`로 선언돼 있고 +`route-not-found` 청크도 빌드된다. SPA fallback이 알려진 프리픽스에만 걸려 있어 도달하지 못한다. +오타 링크·옛 링크·크롤러 프로브가 전부 흰 화면으로 끝난다. + +--- + +## 2. 지적하신 것들 — 재현 결과 + +### H1. 검색·필터·페이지가 URL에 없다 → 뒤로가기가 전부 날린다 + +**실서버 재현** (작업본 61개, 20개씩 4쪽): + +``` +3쪽으로 이동 → URL: /studio/documents meta: "61개 중 20개 표시 중 · 3 / 4 쪽" +문서 열기 → /studio/documents/08a74b35…/edit +뒤로가기 → URL: /studio/documents meta: "61개 중 20개 표시 중 · 1 / 4 쪽" + scrollY: 0 +``` + +**로컬 재현** (필터 포함): + +``` +종류=적용 기준, 검색=Fetch → "1개 중 1개 표시 중", URL: /studio/documents (쿼리 없음) +문서 열기 → 뒤로가기 → "7개 중 7개 표시 중", 검색칸 "", 셀렉트 ["", ""] +``` + +**원인.** Studio 라우트가 전부 검색 코덱을 선언하지 않았다. + +```ts +// src/features/tech-log/contracts/tech-log-route-contract.ts:50 +defineSpec({ routeId: "TECH_LOG_STUDIO_DOCUMENTS", path: "/studio/documents", + layoutGroup: "STUDIO", paramsSchema: null, searchSchema: null, … }) +``` + +Studio 15개 라우트 전부 `searchSchema: null`이다. + +**공개 쪽도 같다.** `/explore`는 코덱을 **선언은 했는데** 페이지가 URL에 쓰지 않는다. + +```ts +// :26 searchSchema: "TechLogExploreSearch" +``` +``` +종류 필터 변경 → location.search === "" +``` + +**단, `/search`는 제대로 한다** — `?q=fetch+join`. 패턴은 이미 저장소 안에 있고, 나머지에 적용되지 않았을 뿐이다. + +> 수정 순서: `TechLogStudioDocumentsSearch` 코덱(`q`, `kind`, `status`, `page`)을 추가하고 +> `document-list.tsx`가 `useSearchParams`로 읽고 쓰게 한다. 그다음 `/explore`, `/studio/publications`. +> 스크롤 복원은 그 뒤 문제다 — URL이 먼저다. + +### H2. "그냥 상자로 되어있다" — 편집기 실측 + +본문 편집 수단은 `본문 Markdown` textarea 한 장 + 삽입 버튼 3개(`코드`/`표`/`목록`)가 전부다. +문법 하이라이팅, 자동 완성, 링크·이미지 삽입 단축키, 붙여넣기 변환 — 없다. + +**미리보기가 따라오지 않는다.** `position: sticky; top: 28px`으로 문서 맨 위에 고정된다. + +``` +scrollY = 2700 (폼 중반, "가정" 섹션 편집 중) +preview.getBoundingClientRect() → { top: 24, height: 852 } +preview 내용 → "LIVE / 즉시 미리보기 / 열린 질문 / … / 이 호스트의 NUMA 토폴로지는 …" ← 문서 맨 위 +``` + +지금 쓰는 문단이 미리보기 어디에 있는지 볼 방법이 없다. + +**Question 문서 한 건 실측:** + +| 항목 | 값 | +|---|---| +| 페이지 높이 | 7,540px | +| textarea | 21개 | +| button | 64개 | +| 그중 `위로`/`아래로`/`삭제` | **51개 (17세트)** | +| 반복 그룹 | 확인한 사실 / 가정 / 남은 미지수 / 제약 / 검토한 선택지 / 관계 | +| 오른쪽 열 사용 | 852px (전체의 11%) | + +7,540px 폼에 **섹션 이동 수단이 없다.** 목차도, 접기도, 앵커도 없다. +21개 textarea는 크기·테두리·배경이 전부 같아서 "확인한 사실 2"와 "선택지 4"를 눈으로 구분할 수 없다. + +**첫 화면 낭비.** 900px 중 530px이 지나야 첫 입력칸이 나온다. +`문서 편집`(어차피 편집을 눌러서 왔다) → 문서 제목 → `DOCUMENT` → `기본 정보` → `제목` 입력칸. +문서 제목은 한 화면에 3번 나온다 (부제 / 제목 입력칸 / 미리보기). + +> 방향: 좌우 분할을 유지하되 미리보기를 편집 중인 섹션에 스크롤 동기화한다. +> 반복 그룹은 카드가 아니라 **행**으로 접고, `위로/아래로` 텍스트 버튼 34개는 드래그 핸들 하나로 대체한다. +> 7,540px 폼에는 좌측 섹션 목차가 필요하다 — 이미 공개 상세 페이지에 sticky 목차 구현이 있다. + +### H3. 주제와 프로젝트를 한 화면에서 관리하는 것 + +`/studio/taxonomy` 한 페이지가 성격이 다른 두 엔티티를 같은 문법으로 취급한다. + +**생성 폼이 한 줄에 붙어 있다.** + +``` +[새 주제: 이름(375px)] [slug(375px)] [추가] [새 프로젝트: 이름(145px)] [추가] +``` + +`추가` 버튼 두 개가 같은 이름, 같은 모양, 같은 줄에 있다. 어느 것이 어느 폼인지 시각적 단서가 없다. + +**두 목록의 컬럼 수가 다른데 같은 행 문법을 쓴다.** + +| | 컬럼 | +|---|---| +| 주제 행 | 이름 · slug · 상태(활성) · `삭제` | +| 프로젝트 행 | 이름 · 목표 · 단계 · 공개 · 다음 · `내용 편집` · `게시 취소` · `삭제` | + +프로젝트에 맞춘 그리드라 주제 행은 절반이 빈칸이다. 공유한 문법이 주는 게 없다. + +**프로젝트 행에 `내용 편집`이 두 번 나온다.** href 동일, 같은 행에서 ~150px 간격. + +``` +projectLinks: ["가상화", "내용 편집", "내용 편집", "Liner N + 1문제", "내용 편집", "내용 편집", …] +``` + +**주제 편집 진입점이 제목 링크뿐이다.** 라벨이 없어서 클릭 가능한지 알 수 없고, +목록 행(이름/slug/활성)은 편집 화면에 **축 이름·설명·논지·범위·축 목록**이 있다는 사실을 전혀 드러내지 않는다. + +두 목록 다 검색·필터·정렬이 없다. 지금은 3+4개라 괜찮지만 그게 이유가 되진 않는다. + +> 방향: 주제와 프로젝트를 별도 라우트로 분리하거나, 최소한 탭으로 나눈다. +> 생성은 각 목록 위에 두고 버튼 이름을 `주제 추가` / `프로젝트 추가`로 구분한다. +> 주제 행에 `편집`을 명시하고, 축 개수를 행에 노출한다. + +--- + +## 3. Studio 나머지 발견 + +### H4. 문서 종류 이름이 화면마다 다르다 + +같은 다섯 종류에 대해 라벨 정의가 **세 군데**에 흩어져 있다. + +| 위치 | CASE | REFERENCE | CONCEPT | QUESTION | +|---|---|---|---|---| +| `shared/document-kind-labels.ts:21` | 검증 기록 | 적용 기준 | 동작 원리 | 열린 질문 | +| `studio/components/new-document-form.tsx:13` | Case | Reference | 개념 | Question | +| `public/pages/search-page.tsx:6` | Case | Reference | 개념 | Open Question | + +화면에서 실제로 보이는 것: + +``` +작업본 목록 → 검증 기록 +새 문서 → Case +공개 탐색 → 검증 기록 +공개 검색 → CASE +``` + +`search-page.tsx:6`은 공용 모듈이 있는데도 자기 라벨 맵을 따로 갖고 있다. + +릴리즈 노트 v0.3.0이 "화면마다 달랐던 문서 종류 이름을 하나로 통일시켰습니다"라고 적혀 있는데, 통일되지 않았다. + +### M1. Studio에 버튼이 없다 — 의도는 알겠으나 대가가 크다 + +`studio.css:60-67`에 방향이 기록돼 있다. + +> 상자도 선도 두지 않는다. 격은 글자의 굵기와 색으로만 나눈다 — 주 동작은 진한 굵은 글자, +> 보조는 옅은 글자, 되돌릴 수 없는 것은 붉은 글자. + +실제 계산값 (`.studio-primary-button`): + +``` +background: rgba(0,0,0,0) border: 0px none border-radius: 0px +padding: 0px 2px font-weight: 700 height: 44px +``` + +즉 굵은 본문 글자다. 문제 세 가지: + +1. **되돌릴 수 없는 `게시`와 `저장`의 차이가 색 한 단계.** + `저장` = `rgb(90,93,100)`/600, `게시` = `rgb(23,24,27)`/700. 같은 16px, 같은 92×44 박스, 배경 없음. + 규칙은 "되돌릴 수 없는 것은 붉은 글자"인데 `게시`는 붉지 않고 화면에서 가장 강하다. +2. **공개 사이트는 다른 언어를 쓴다.** `/explore`의 `적용`, `/search`의 `검색`은 검은 채움 박스다. + 한 제품 안에 버튼 언어가 두 개다. +3. **자기 규칙의 예외가 하필 모바일 Studio에 있다.** 390px에서 유일하게 테두리 박스를 가진 요소가 + `Studio 메뉴 열기`다. + +디자인 시스템에는 `--button-primary-background` 같은 토큰이 이미 있고(`tokens/component.css:2`), Studio가 우회한다. + +> 방향은 유지할 만하다. 다만 **되돌릴 수 없는 동작**에만 예외를 만든다. +> `게시`·`삭제`·`게시 취소`는 확인 단계를 갖고, 타이포 위계가 아니라 절차로 구분한다. + +### M2. 대시보드가 61개에 대해 5개만 말한다 + +``` +전체 작업본 61 검증할 기록 5 게시 준비 0 게시 기록 21 +``` + +- 통계 4개가 **클릭 불가**다. 61에서 목록으로 가는 길이 없다. +- `이어서 작성`, `게시 준비` 두 섹션이 비어 있고 각각 ~150px를 차지해 "없습니다"를 말한다. +- `검증할 기록 5`와 바로 아래 5행 목록이 같은 정보다. +- `검증과 미리보기` 5행이 전부 `열린 질문 / 가상화 / 검증하기` — 라벨 컬럼이 같은 값을 5번 반복한다. +- **공개 홈 설정 폼**(`지금 집중하는 것`: 프로젝트·열린 질문·최근 결정 셀렉트 + `홈 설정 저장`)이 + `게시 준비`와 `최근 게시` 사이, 작업 대시보드 한가운데에 있다. 설정이 워크플로 안에 섞였다. + +### M3. 작업본 목록 밀도와 필터 + +- 1440×900에서 **3행**만 보인다 (헤더 블록 470px). +- 정렬 컨트롤 없음. 다중 선택 없음. 일괄 작업 없음. +- **프로젝트·주제 필터가 없다.** 공개 `/explore`는 종류+주제+프로젝트 3개를 주는데, + 61개를 관리하는 작성자는 종류+상태 2개만 쓴다. 독자가 작성자보다 좋은 도구를 갖고 있다. +- 행마다 값이 같은 라벨 컬럼이 110px을 쓴다 — 릴리즈는 `RELEASE` 3번, taxonomy는 `TOPIC`/`PROJECT`, + 게시 기록은 `재게시`가 반복되고 본문에 `이벤트: 재게시 · 현재 상태: 게시 중`으로 또 나온다. + +### M4. 필터 제출 방식이 화면마다 다르다 + +| 화면 | 방식 | +|---|---| +| `/studio/documents` | 셀렉트 즉시 적용 + 검색은 `검색` 버튼 | +| `/studio/publications` | 셀렉트·검색 묶어서 `적용` 버튼 | + +### M5. 새 문서가 라우트를 통째로 쓴다 + +5지선다 하나 고르는 데 페이지 이동이 두 번 필요하다 (`새 문서` → 선택 → `작업본 만들기` → 편집기). +글쓰기 도구에서 빈 문서까지의 최단 경로다. + +그리고 `new-document-form.tsx:186`: + +> 이 화면의 작업본은 현재 Studio 세션에서만 유지됩니다. 세션이 끝나면 사라집니다. + +조건부 렌더링이 아니라 항상 나온다. 실서버에는 작업본 61개가 남아 있다. +MOCK 어댑터 시절 문구가 남은 것으로 보인다. 사실이면 출시 차단이고, 사실이 아니면 지워야 한다. + +### M7. `aria-current` 오용 + +`/studio/documents/:id/edit`에서 nav의 `작업본` 링크에 `aria-current="page"`가 붙는다. +현재 페이지가 아니다. `NavLink`에 `end`가 빠졌거나 섹션 표시에 `page`를 쓴 것이다. + +--- + +## 4. Public 사이트 + +공개 쪽은 확실히 더 완성돼 있다. 상세 페이지는 코드 블록 복사 버튼, 실측 데이터 표, +시퀀스 다이어그램, sticky 목차, `다음에 읽을 것`까지 갖춘 제품급 화면이다. +아래는 "출시한다면" 기준의 남은 것들. + +### H5. 공개 화면에 raw enum이 새어 나온다 + +```tsx +// src/features/tech-log/presentation/public/pages/projects-page.tsx:43 +{project.stage} +``` + +`/projects`와 `/profile` 두 곳에서 프로젝트 4개 전부 `DESIGN`으로 표시된다. +같은 프로젝트를 Studio taxonomy는 `조사 / 조사 / 조사 / 설계`로 보여준다. **두 화면이 서로 다른 값을 말한다.** + +덤으로 `DESIGN` 배지가 공개 사이트에서 테두리·radius를 가진 유일한 요소이고, 한국어 화면의 영어 단어다. + +### H6. 빈 값에 라벨만 렌더된다 + +`/projects` 4개 중 3개가 `현재 목표`·`다음 작업` 라벨만 있고 값이 없다. + +``` +가상화 goal: "" +Liner N + 1문제 goal: "" +Backend Clean Architecture goal: "" +KeyCloak Patterns goal: "keycloak 인증 구조 설계를 직접 …" +``` + +Studio 홈은 "셋 다 비워 두면 그 영역은 나타나지 않습니다"라는 규칙을 갖고 있다. +같은 규칙이 공개 목록에 적용되지 않았다. + +`/topics`에는 기록 0개인 `CPU 가상화`가 공개돼 있다. + +### H7. 검색 결과 요약문이 깨져 나온다 + +`/search?q=fetch+join` 첫 결과 발췌: + +> 컬렉션 Fetch join에 페이징앞 단계의 데이터와 매핑은 그대로 두고 페이징 처리만 진행 했다.**반환은 한 +> 페이지인데 메모리에 전부 로드Nreturned(페이지)feedItemLoaded시드 하이라이트1010101,285100201001, +> 9611,000201,0002,917데이터가** 커지게 되면 반환 크기와 실제 로드 수의 차이가 보인다.fetch join + +마크다운 헤딩과 **표 셀 값까지** 공백 없이 이어붙였다. 독자에게는 그냥 깨진 글자다. +발췌는 표·코드 블록을 제외하고 문단만 뽑아야 한다. + +### M8. 공개 홈 첫 화면이 가장 적게 말한다 + +900px 중 상단 300px이 제품명 `TechLog` + 일반적인 한 문장이고, 그 아래 130px이 빈 공간이다. +근거도 최신성도 훅도 없다. 스크롤할 이유를 주지 않는다. + +그런데 이 사이트에서 **가장 특이한 자산**은 그 아래 y≈600에 있다 — +SPA / Mediator / BFF / Forward-Auth 네 구조를 나란히 비교하는 표. 다른 데서 못 얻는 것이고, +11px 회색 텍스트로 묻혀 있다. 이게 맨 위로 와야 한다. + +`다른 주제 1개 보기`는 코퍼스가 작다는 사실을 스스로 노출한다. + +### M9. 상세 페이지의 문제·결론이 가장 흐리다 + +글의 두 핵심 사실(`문제`, `결론`)이 회색 바탕 위 11px 회색으로, 페이지에서 가장 읽기 어려운 텍스트다. +그 아래 본문은 16px이다. 위계가 반대다. + +### M10. 프로필에 연락 수단·구독 수단이 없다 + +이메일·GitHub·RSS·피드 — 없다. 읽고 나서 할 수 있는 게 없다. + +### M11. 공개 아티클이 studio 청크를 preload한다 + +익명 독자가 여는 `/cases/...` HTML에 다음이 들어 있다. + +```html + + + +``` + +읽기만 하는 사람이 편집기 번들을 내려받는다. + +--- + +## 5. 확인했지만 문제 아님 + +- 모바일 390px: public·studio 둘 다 가로 넘침 없음 (`scrollWidth 375 ≤ 390`), 12px 미만 텍스트 없음 +- `:focus-visible` 전역 정의됨 (`globals.css:81`) +- 공개 상세 목차는 `position: sticky; top: 28px`로 정상 동작 (전체 페이지 캡처에서만 안 따라오는 것처럼 보임) +- `favicon.svg` 참조 정상 (`/favicon.ico` 404는 브라우저의 추가 프로브) +- `robots.txt`가 `/studio`, `/api/`를 차단하고 있음 + +--- + +## 6. 권고 순서 + +**1주차 — 배포된 결손** +1. `workflow.module.css` import 연결 (B1) — 한 줄 +2. Asset 라이브러리 스타일 + nav 진입점 (B2) +3. 삭제 확인 단계 (B3) +4. `sitemap.xml` 생성 + SPA fallback 전체 경로 (B4 일부, B5) + +**2주차 — 되돌아올 수 있게** +5. `/studio/documents` 검색·필터·페이지를 URL로 (H1). `/search`가 이미 하는 방식 그대로 +6. `/explore`, `/studio/publications` 동일 적용 +7. 문서 종류 라벨을 `document-kind-labels.ts` 하나로 (H4). `search-page.tsx:6`, `new-document-form.tsx:13` 제거 + +**3주차 — 쓰는 화면** +8. 미리보기 스크롤 동기화 + 편집기 섹션 목차 (H2) +9. 반복 그룹 접기 + 드래그 재정렬 (H2) +10. 작업본 목록에 프로젝트·주제 필터, 정렬 (M3) +11. `주제`와 `프로젝트` 분리 (H3) + +**4주차 — 공개 준비** +12. OG/Twitter/canonical/JSON-LD — prerender 또는 라우트별 정적 HTML (B4) +13. `project.stage` 라벨 매핑, 빈 값 라벨 숨김 (H5, H6) +14. 검색 발췌에서 표·코드 제외 (H7) +15. 공개 홈 첫 화면 재구성 — 구조 비교표를 위로 (M8) + +--- + +## 7. 근거 파일 + +측정에 쓴 스크린샷은 리뷰 저장소(`ai-design-harness/`)에 있다. + +``` +p-studio-home.png p-studio-docs-vp.png p-studio-docs-mobile.png +p-studio-new.png p-studio-edit-question.png p-studio-validation.png +p-studio-preview.png p-studio-publish.png p-studio-taxonomy.png +p-studio-topic-edit.png p-studio-publications.png p-studio-assets.png +p-studio-releases.png p-pub-home.png p-pub-home-mobile.png +p-pub-explore.png p-pub-case.png p-pub-topics.png +p-pub-projects.png p-pub-search-results.png p-pub-profile.png +p-pub-releases.png p-pub-404.png p-pub-case-404.png +``` diff --git a/docs/reviews/2026-09-15-techlog-product-design-review.md b/docs/reviews/2026-09-15-techlog-product-design-review.md new file mode 100644 index 0000000..e57d41b --- /dev/null +++ b/docs/reviews/2026-09-15-techlog-product-design-review.md @@ -0,0 +1,53 @@ +# TechLog Product Design Review (2026-09-15) + +전 화면 스크린샷(공개 21 · Studio 16, 1440/900/390px) 기반 제품 디자인 리뷰. +원문은 사용자가 제공했고, 아래는 실행 단위로 정리한 것이다. + +## 핵심 판정 + +제품의 차별점은 "기술 조사를 어느 지점에서 들어가도 그 결론을 만든 맥락의 사슬을 잃지 않는다"는 +것이다. 모델에는 그 정보가 다 있는데 화면이 숨기고 있다. 그래서 첫 목표는 장식이 아니라 +**맥락을 일급 UI 객체로 드러내는 것**이다. + +## 우선순위 + +### P0 — 정체성 / 탐색 +- [x] 기록 페이지의 Context Navigator (제목·요약 바로 아래) +- [ ] 프로젝트 = 조사 지도 +- [ ] 주제 = 하나의 질문 축 (질문 + 알려진 것/미해결/결정 상태) +- [ ] 추론 순서를 아는 "다음" 탐색 +- [ ] 기록 역할(종류)의 일관된 표현 + +### P0 — 작성 사용성 +- [ ] 편집기 재구성 (아웃라인 · 편집 · 미리보기, 종류별 구조화 편집) +- [ ] Asset 라이브러리 재설계 (해시가 아니라 뜻으로 찾기, 사용처 그래프) +- [ ] 검증 이슈에서 해당 필드로 바로 가는 링크 +- [ ] 관계 편집 +- [ ] 모바일 편집기 정리 + +### P1 — 읽기 품질 +- [ ] 타이포 스케일 조정 (데스크톱 H1 44–48px, 모바일 30–34px) +- [ ] 실험 조건 메타데이터 접기 +- [ ] 모바일 도식 확대 +- [ ] 표 반응형 +- [ ] 우측 레일 강화 (IN THIS RECORD / CONTEXT / RELATED 분리) +- [ ] Reference 훑기 쉽게 (적용/비적용 요약 + 번호 + 한 줄 규칙) + +### P1 — 발견 +- [ ] 맥락 검색 (프로젝트·주제·결정까지) +- [ ] Explore 결과에 관계 메타데이터 +- [ ] 주제 목록에 질문 문장 +- [ ] 빈 화면이 이웃 맥락을 드러내게 + +### P2 — 마감 +- [ ] 마이크로 인터랙션, hover/focus, 스켈레톤, 전환, 아이콘 + +## 베타 목표 8개 화면 + +Home · Project hub · Topic hub · Case · Question · Reference · Studio 편집기 · Asset 라이브러리. +이 여덟이 같은 맥락 모델과 시각 문법을 공유하면 나머지는 그 체계를 물려받는다. + +## 하지 말 것 + +카드 남발, 종류마다 채도 높은 색, 큰 둥근 상자, 그라디언트, 아이콘 과용. +정체성은 타이포와 구조 컴포넌트에서 나온다. diff --git a/package.json b/package.json index 5d13b60..d3c04e5 100644 --- a/package.json +++ b/package.json @@ -86,7 +86,8 @@ "generate:artifact-schemas": "node scripts/generate-artifact-schemas.ts", "check:artifact-schemas": "node scripts/generate-artifact-schemas.ts --check", "generate:tech-log-contract": "node scripts/generate-tech-log-contract.ts", - "capture:screens": "node scripts/capture-public-screens.ts", + "capture:screens": "node scripts/capture-screens.ts", + "measure:screens": "node scripts/capture-public-screens.ts", "check:tech-log-contract": "node scripts/generate-tech-log-contract.ts --check", "generate:dev-release-manifest": "node scripts/check-dev-release-manifest.ts --write", "check:dev-release-manifest": "node scripts/check-dev-release-manifest.ts", diff --git a/scripts/capture-screens.ts b/scripts/capture-screens.ts new file mode 100644 index 0000000..735b6e9 --- /dev/null +++ b/scripts/capture-screens.ts @@ -0,0 +1,467 @@ +import { mkdir, readFile, rm, writeFile } from "node:fs/promises"; +import path from "node:path"; +import process from "node:process"; + +import { chromium, type APIRequestContext, type BrowserContext, type Page } from "@playwright/test"; + +import { TECH_LOG_ROUTE_REGISTRY } from "../src/features/tech-log/contracts/tech-log-route-contract.ts"; + +/** + * 공개 화면과 Studio 화면 전부를 찍는다. UI 검토용이다. + * + *

    찍을 목록을 손으로 적지 않는다. 라우트 레지스트리를 그대로 돌고, 라우트 하나당 해석기를 + * {@link RESOLVERS} 에 반드시 하나 두게 한다 — `Record` 라 라우트가 늘면 컴파일러가 + * 빈 자리를 잡는다. 이 저장소에서 손으로 나열한 목록에 새 항목을 빠뜨리는 일이 반복됐고(종류 + * 필터에서 개념·환경 구성이 빠졌던 것이 같은 실수다), 검토용 목록이 조용히 낡으면 "찍히지 않은 + * 화면은 문제가 없는 것처럼" 보인다. + * + *

    `:slug` 같은 자리는 지어내지 않고 살아 있는 API 에서 실제 값을 가져온다. 지어낸 주소는 + * 404 화면을 찍어 놓고 검토가 끝난 것처럼 보이게 만든다. 채울 값이 없으면 건너뛰되 그 사실을 + * 결과에 남긴다. + * + *

    Studio 는 로그인이 필요하다. 세션을 파일로 저장해 두고 재사용하며, 매 화면마다 로그인 관문 + * (`[data-surface="authentication-required"]`)이 아닌지 확인한다 — 세션이 끊긴 채로 돌면 같은 + * 로그인 화면 수십 장을 찍어 놓고 Studio 를 다 봤다고 착각한다. + * + * 사용법: + * node scripts/capture-screens.ts --login # 창을 열어 직접 로그인하고 세션 저장 + * node scripts/capture-screens.ts # 공개 + Studio 전부 + * node scripts/capture-screens.ts --only=public + * node scripts/capture-screens.ts --widths=1440 --slices=3 + * node scripts/capture-screens.ts --base=http://localhost:5173 + */ + +type RouteId = keyof typeof TECH_LOG_ROUTE_REGISTRY; + +const DEFAULT_BASE = "https://hyeonworks.com"; + +/** 이 사이트의 반응형 분기는 1179 / 1050 / 900 / 767 이다. 그 위와 아래를 하나씩 본다. */ +const DEFAULT_WIDTHS = [1440, 390] as const; + +const VIEWPORT_HEIGHT = 900; + +/** 한 폭당 이만큼까지만 자른다. 긴 문서라도 검토는 앞쪽에서 대부분 끝난다. */ +const DEFAULT_SLICES = 5; + +const OUTPUT_DIRECTORY = "artifacts/design-review/screens"; +const SESSION_FILE = "artifacts/design-review/studio-session.json"; + +/** 로그인 관문. 이것이 보이면 그 화면은 Studio 화면이 아니라 로그인 화면이다. */ +const AUTH_GATE = '[data-surface="authentication-required"]'; + +type LiveData = { + /** 종류별 공개 경로 한 개씩. 값이 없으면 그 종류로 게시된 기록이 아직 없다는 뜻이다. */ + readonly knowledgePaths: Readonly>; + readonly questionPath: string | null; + readonly topicSlug: string | null; + /** 접근(variant)을 가진 주제와 그 접근 하나. 접근이 없는 주제만 있으면 null 이다. */ + readonly topicWithVariant: Readonly<{ slug: string; variant: string }> | null; + readonly projectSlug: string | null; + readonly releaseVersion: string | null; + readonly documentId: string | null; + readonly publicationEventId: string | null; + readonly studioProjectId: string | null; + readonly studioTopicId: string | null; + readonly studioReleaseId: string | null; +}; + +type Resolver = (data: LiveData) => string | null; + +function knowledge(kind: string): Resolver { + return (data) => data.knowledgePaths[kind] ?? null; +} + +/** + * 라우트 하나를 실제 주소로 바꾸는 법. + * + *

    `null` 은 "지금 살아 있는 자료로는 이 화면을 열 수 없다"는 뜻이다. 결과 보고서에 이유와 함께 + * 남는다 — 조용히 빠지면 검토에서 그 화면이 없었다는 사실 자체가 보이지 않는다. + */ +const RESOLVERS: Record = { + TECH_LOG_HOME: () => "/", + TECH_LOG_EXPLORE: () => "/explore", + // `/explore/:kind` 는 두 갈래가 화면이 서로 다르다. 둘 다 찍는다. + TECH_LOG_EXPLORE_KIND: () => "/explore/knowledge", + TECH_LOG_CASE: knowledge("CASE"), + TECH_LOG_REFERENCE: knowledge("REFERENCE"), + TECH_LOG_CONCEPT: knowledge("CONCEPT"), + TECH_LOG_SETUP: knowledge("SETUP"), + TECH_LOG_QUESTION: (data) => data.questionPath, + TECH_LOG_TOPICS: () => "/topics", + TECH_LOG_TOPIC: (data) => (data.topicSlug ? `/topics/${data.topicSlug}` : null), + TECH_LOG_TOPIC_VARIANT: (data) => + data.topicWithVariant + ? `/topics/${data.topicWithVariant.slug}/${data.topicWithVariant.variant}` + : null, + TECH_LOG_PROJECTS: () => "/projects", + TECH_LOG_PROJECT: (data) => (data.projectSlug ? `/projects/${data.projectSlug}` : null), + TECH_LOG_PROJECT_RECORDS: (data) => + data.projectSlug ? `/projects/${data.projectSlug}/records` : null, + TECH_LOG_PROJECT_DECISIONS: (data) => + data.projectSlug ? `/projects/${data.projectSlug}/decisions` : null, + TECH_LOG_PROJECT_ACTIVITY: (data) => + data.projectSlug ? `/projects/${data.projectSlug}/activity` : null, + TECH_LOG_RELEASES: () => "/releases", + TECH_LOG_RELEASE: (data) => (data.releaseVersion ? `/releases/${data.releaseVersion}` : null), + TECH_LOG_PROFILE: () => "/profile", + // 빈 검색 결과가 아니라 실제로 걸리는 말을 넣는다. 빈 화면은 배치를 보여 주지 않는다. + TECH_LOG_SEARCH: () => "/search?q=%EA%B0%80%EC%83%81%ED%99%94", + TECH_LOG_STUDIO_HOME: () => "/studio", + TECH_LOG_STUDIO_DOCUMENTS: () => "/studio/documents", + TECH_LOG_STUDIO_DOCUMENT_NEW: () => "/studio/documents/new", + TECH_LOG_STUDIO_DOCUMENT_EDIT: (data) => + data.documentId ? `/studio/documents/${data.documentId}/edit` : null, + TECH_LOG_STUDIO_DOCUMENT_VALIDATION: (data) => + data.documentId ? `/studio/documents/${data.documentId}/validation` : null, + TECH_LOG_STUDIO_DOCUMENT_PREVIEW: (data) => + data.documentId ? `/studio/documents/${data.documentId}/preview` : null, + TECH_LOG_STUDIO_DOCUMENT_PUBLISH: (data) => + data.documentId ? `/studio/documents/${data.documentId}/publish` : null, + TECH_LOG_STUDIO_PUBLICATIONS: () => "/studio/publications", + TECH_LOG_STUDIO_PUBLICATION_PREVIEW: (data) => + data.publicationEventId ? `/studio/publications/${data.publicationEventId}/preview` : null, + TECH_LOG_STUDIO_ASSETS: () => "/studio/assets", + TECH_LOG_STUDIO_TAXONOMY: () => "/studio/taxonomy", + TECH_LOG_STUDIO_PROJECT_EDIT: (data) => + data.studioProjectId ? `/studio/projects/${data.studioProjectId}` : null, + TECH_LOG_STUDIO_TOPIC_EDIT: (data) => + data.studioTopicId ? `/studio/topics/${data.studioTopicId}` : null, + TECH_LOG_STUDIO_RELEASES: () => "/studio/releases", + TECH_LOG_STUDIO_RELEASE_EDIT: (data) => + data.studioReleaseId ? `/studio/releases/${data.studioReleaseId}` : null, + // 없는 주소여야 찍을 수 있는 화면이다. + TECH_LOG_STUDIO_NOT_FOUND: () => "/studio/no-such-studio-page", + NOT_FOUND: () => "/no-such-page", +}; + +/** + * 한 라우트가 여러 화면을 그리는 경우. `/explore/:kind` 의 두 갈래처럼 같은 코드가 아니라 서로 + * 다른 화면이면 검토에서 둘 다 봐야 한다. + */ +const EXTRA_TARGETS: ReadonlyArray> = + [{ id: "TECH_LOG_EXPLORE_KIND-questions", group: "PUBLIC", url: "/explore/questions" }]; + +type Target = Readonly<{ id: string; group: "PUBLIC" | "STUDIO"; url: string }>; +type Skipped = Readonly<{ id: string; group: string; reason: string }>; + +async function json(request: APIRequestContext, url: string): Promise { + const response = await request.get(url, { headers: { Accept: "application/json" } }); + if (!response.ok()) return null; + try { + return (await response.json()) as unknown; + } catch { + return null; + } +} + +function envelope(value: unknown): Record | null { + if (typeof value !== "object" || value === null) return null; + const data = (value as { data?: unknown }).data; + return typeof data === "object" && data !== null ? (data as Record) : null; +} + +function itemsOf(value: unknown): ReadonlyArray> { + const data = envelope(value); + const items = data?.["items"]; + return Array.isArray(items) ? (items as Record[]) : []; +} + +function text(row: Record | undefined, key: string): string | null { + const value = row?.[key]; + return typeof value === "string" && value.length > 0 ? value : null; +} + +/** 공개 화면에 필요한 값. 로그인 없이 읽는다. */ +async function readPublic(request: APIRequestContext, base: string) { + const [knowledgeRaw, questionsRaw, topicsRaw, projectsRaw, releasesRaw] = await Promise.all([ + json(request, `${base}/api/v1/public/explore/knowledge?limit=100`), + json(request, `${base}/api/v1/public/explore/questions?limit=20`), + json(request, `${base}/api/v1/public/topics`), + json(request, `${base}/api/v1/public/projects`), + json(request, `${base}/api/v1/public/releases`), + ]); + + const knowledgePaths: Record = {}; + for (const row of itemsOf(knowledgeRaw)) { + const kind = text(row, "type"); + const routePath = text(row, "path"); + if (kind && routePath && !(kind in knowledgePaths)) knowledgePaths[kind] = routePath; + } + + const topics = itemsOf(topicsRaw); + const withVariant = topics.find((row) => Number(row["variantCount"] ?? 0) > 0); + let topicWithVariant: { slug: string; variant: string } | null = null; + const withVariantSlug = text(withVariant, "slug"); + if (withVariantSlug) { + const detail = envelope(await json(request, `${base}/api/v1/public/topics/${withVariantSlug}`)); + const variants = detail?.["variants"]; + const first = Array.isArray(variants) ? (variants[0] as Record) : undefined; + const variant = text(first, "slug") ?? text(first, "variantSlug"); + if (variant) topicWithVariant = { slug: withVariantSlug, variant }; + } + + return { + knowledgePaths, + questionPath: text(itemsOf(questionsRaw)[0], "path"), + topicSlug: text(topics[0], "slug"), + topicWithVariant, + projectSlug: text(itemsOf(projectsRaw)[0], "slug"), + releaseVersion: text(itemsOf(releasesRaw)[0], "version"), + }; +} + +/** Studio 화면에 필요한 값. 저장된 세션으로 읽는다. */ +async function readStudio(request: APIRequestContext, base: string) { + const [documentsRaw, publicationsRaw, projectsRaw, topicsRaw, releasesRaw] = await Promise.all([ + json(request, `${base}/api/v1/studio/documents?limit=1`), + json(request, `${base}/api/v1/studio/publications?limit=1`), + json(request, `${base}/api/v1/studio/catalog?type=PROJECT&limit=1`), + json(request, `${base}/api/v1/studio/catalog?type=TOPIC&limit=1`), + json(request, `${base}/api/v1/studio/releases?size=1`), + ]); + + const event = itemsOf(publicationsRaw)[0]?.["event"]; + const releases = itemsOf(releasesRaw); + + return { + documentId: text(itemsOf(documentsRaw)[0], "id"), + publicationEventId: text( + typeof event === "object" && event !== null ? (event as Record) : undefined, + "publicationEventId", + ), + studioProjectId: text(itemsOf(projectsRaw)[0], "id"), + studioTopicId: text(itemsOf(topicsRaw)[0], "id"), + studioReleaseId: text(releases[0], "id") ?? text(releases[0], "releaseId"), + }; +} + +const EMPTY_STUDIO = { + documentId: null, + publicationEventId: null, + studioProjectId: null, + studioTopicId: null, + studioReleaseId: null, +} as const; + +/** + * 창을 열어 사람이 직접 로그인하게 하고 그 세션을 파일로 남긴다. + * + *

    자격 증명을 스크립트가 들고 있지 않아도 되고, Keycloak 화면이 바뀌어도 깨지지 않는다. + */ +async function login(base: string): Promise { + const browser = await chromium.launch({ headless: false }); + const context = await browser.newContext({ viewport: { width: 1440, height: 900 } }); + const page = await context.newPage(); + await page.goto(`${base}/studio`); + process.stdout.write("열린 창에서 로그인하세요. Studio 화면이 뜨면 자동으로 저장합니다...\n"); + try { + await page.waitForSelector('a[href="/studio/documents"]', { timeout: 300_000 }); + await mkdir(path.dirname(SESSION_FILE), { recursive: true }); + await context.storageState({ path: SESSION_FILE }); + process.stdout.write(`세션 저장: ${SESSION_FILE}\n`); + } finally { + await browser.close(); + } +} + +async function sessionState(): Promise { + try { + await readFile(SESSION_FILE, "utf8"); + return SESSION_FILE; + } catch { + return undefined; + } +} + +/** + * 한 화면을 폭마다 찍는다. + * + *

    전체 페이지를 한 장으로 찍으면 세로로 긴 문서가 통째로 축소되어 17px 글자가 7~8px 로 + * 뭉갠다. 덩어리는 보이지만 정작 타이포는 못 본다. 그래서 화면 높이만큼씩 잘라 찍는다. + */ +async function capture( + page: Page, + target: Target, + base: string, + widths: readonly number[], + maxSlices: number, +): Promise<{ files: string[]; problem: string | null }> { + const files: string[] = []; + const directory = path.join(OUTPUT_DIRECTORY, target.group.toLowerCase()); + + for (const width of widths) { + await page.setViewportSize({ width, height: VIEWPORT_HEIGHT }); + await page.goto(`${base}${target.url}`, { waitUntil: "domcontentloaded" }); + await page.waitForSelector("main", { timeout: 20_000 }).catch(() => undefined); + // 자료를 받아 다시 그리는 화면이 많다. 반쯤 그려진 상태를 남기면 검토가 그것을 지적한다. + await page.waitForLoadState("networkidle", { timeout: 15_000 }).catch(() => undefined); + await page.waitForTimeout(400); + + if (target.group === "STUDIO" && (await page.locator(AUTH_GATE).count()) > 0) { + return { files, problem: "세션이 끊겨 로그인 화면이 떴습니다 — --login 으로 다시 로그인하세요" }; + } + + const height = await page.evaluate(() => document.documentElement.scrollHeight); + const slices = Math.min(Math.max(Math.ceil(height / VIEWPORT_HEIGHT), 1), maxSlices); + for (let index = 0; index < slices; index += 1) { + await page.evaluate((top: number) => window.scrollTo(0, top), index * VIEWPORT_HEIGHT); + await page.waitForTimeout(200); + const file = path.join(directory, `${target.id}-${width}-${index + 1}.png`); + await page.screenshot({ path: file, scale: "css" }); + files.push(file); + } + } + return { files, problem: null }; +} + +function flag(name: string): string | null { + const found = process.argv.slice(2).find((entry) => entry.startsWith(`--${name}=`)); + return found ? found.slice(name.length + 3) : null; +} + +async function main(): Promise { + const base = (flag("base") ?? DEFAULT_BASE).replace(/\/+$/u, ""); + + if (process.argv.includes("--login")) { + await login(base); + return; + } + + const only = flag("only"); + const widths = flag("widths")?.split(",").map(Number).filter(Number.isFinite) ?? [ + ...DEFAULT_WIDTHS, + ]; + const maxSlices = Number(flag("slices") ?? DEFAULT_SLICES); + + /* + 이번에 찍는 묶음만 비운다. 통째로 지우면 `--only=studio` 한 번이 직전에 찍어 둔 공개 화면을 + 전부 날린다 — 실제로 한 번 날렸다. + */ + const clearing = only === "public" ? ["public"] : only === "studio" ? ["studio"] : ["public", "studio"]; + for (const group of clearing) { + await rm(path.join(OUTPUT_DIRECTORY, group), { recursive: true, force: true }); + await mkdir(path.join(OUTPUT_DIRECTORY, group), { recursive: true }); + } + + const browser = await chromium.launch(); + const skipped: Skipped[] = []; + const captured: Array<{ target: Target; files: string[] }> = []; + + try { + const publicContext = await browser.newContext({ viewport: { width: 1440, height: 900 } }); + const publicData = await readPublic(publicContext.request, base); + + const storage = await sessionState(); + let studioContext: BrowserContext | null = null; + let studioData: Awaited> = { ...EMPTY_STUDIO }; + if (only !== "public") { + if (!storage) { + process.stdout.write( + `Studio 세션이 없습니다(${SESSION_FILE}). 공개 화면만 찍습니다.\n` + + " → node scripts/capture-screens.ts --login 으로 먼저 로그인하세요.\n\n", + ); + } else { + studioContext = await browser.newContext({ + storageState: storage, + viewport: { width: 1440, height: 900 }, + }); + studioData = await readStudio(studioContext.request, base); + } + } + + const data: LiveData = { ...publicData, ...studioData }; + + const targets: Target[] = []; + for (const [routeId, definition] of Object.entries(TECH_LOG_ROUTE_REGISTRY)) { + const group = definition.layoutGroup === "STUDIO" ? "STUDIO" : "PUBLIC"; + if (only === "public" && group === "STUDIO") continue; + if (only === "studio" && group === "PUBLIC") continue; + if (group === "STUDIO" && !studioContext) { + skipped.push({ id: routeId, group, reason: "Studio 세션 없음" }); + continue; + } + const url = RESOLVERS[routeId as RouteId](data); + if (url === null) { + skipped.push({ id: routeId, group, reason: "이 화면을 채울 실제 자료가 없습니다" }); + continue; + } + targets.push({ id: routeId, group, url }); + } + for (const extra of EXTRA_TARGETS) { + if (only === "studio" && extra.group === "PUBLIC") continue; + if (only === "public" && extra.group === "STUDIO") continue; + targets.push(extra); + } + + const publicPage = await publicContext.newPage(); + const studioPage = studioContext ? await studioContext.newPage() : null; + + for (const target of targets) { + const page = target.group === "STUDIO" ? studioPage : publicPage; + if (!page) continue; + const result = await capture(page, target, base, widths, maxSlices); + if (result.problem) { + skipped.push({ id: target.id, group: target.group, reason: result.problem }); + process.stdout.write(` ✗ ${target.id} ${target.url} — ${result.problem}\n`); + continue; + } + captured.push({ target, files: result.files }); + process.stdout.write(` ✓ ${target.id} ${target.url} (${result.files.length}장)\n`); + } + } finally { + await browser.close(); + } + + /* + 묶음별로 결과를 남기고, 목차는 남아 있는 파일 전부에서 다시 만든다. `--only` 로 한쪽만 찍어도 + 목차에서 다른 쪽이 사라지지 않는다. + */ + for (const group of clearing) { + const rows = captured.filter((entry) => entry.target.group.toLowerCase() === group); + const groupSkipped = skipped.filter((entry) => entry.group.toLowerCase() === group); + await writeFile( + path.join(OUTPUT_DIRECTORY, `captured-${group}.json`), + `${JSON.stringify({ base, captured: rows, skipped: groupSkipped }, null, 2)}\n`, + "utf8", + ); + } + + const merged: Array<{ target: Target; files: string[] }> = []; + const mergedSkipped: Skipped[] = []; + for (const group of ["public", "studio"]) { + try { + const raw = JSON.parse( + await readFile(path.join(OUTPUT_DIRECTORY, `captured-${group}.json`), "utf8"), + ) as { captured: Array<{ target: Target; files: string[] }>; skipped: Skipped[] }; + merged.push(...raw.captured); + mergedSkipped.push(...raw.skipped); + } catch { + // 아직 찍지 않은 묶음이다. + } + } + + const lines = ["# 화면 목록", "", `기준 주소: ${base}`, ""]; + for (const group of ["PUBLIC", "STUDIO"] as const) { + const rows = merged.filter((entry) => entry.target.group === group); + if (rows.length === 0) continue; + lines.push(`## ${group === "PUBLIC" ? "공개" : "Studio"} (${rows.length})`, ""); + for (const { target, files } of rows) { + lines.push(`### ${target.id}`, "", `\`${target.url}\``, ""); + for (const file of files) lines.push(`![${path.basename(file)}](${path.relative(OUTPUT_DIRECTORY, file)})`); + lines.push(""); + } + } + if (mergedSkipped.length > 0) { + lines.push("## 찍지 못한 화면", ""); + for (const entry of mergedSkipped) lines.push(`- \`${entry.id}\` (${entry.group}) — ${entry.reason}`); + lines.push(""); + } + await writeFile(path.join(OUTPUT_DIRECTORY, "index.md"), `${lines.join("\n")}\n`, "utf8"); + + process.stdout.write( + `\n찍은 화면 ${captured.length}개, 건너뛴 화면 ${skipped.length}개\n` + + `${OUTPUT_DIRECTORY}/index.md\n`, + ); +} + +await main(); diff --git a/src/features/tech-log/presentation/shared/public-render/context-navigator.tsx b/src/features/tech-log/presentation/shared/public-render/context-navigator.tsx new file mode 100644 index 0000000..e0f986f --- /dev/null +++ b/src/features/tech-log/presentation/shared/public-render/context-navigator.tsx @@ -0,0 +1,107 @@ +import { Link } from "react-router-dom"; + +import type { components } from "../../../contracts/studio/generated.ts"; +import { resolvesToPublicRoute } from "../../../domain/navigation/public-path.ts"; +import { DOCUMENT_KIND_LABELS } from "../document-kind-labels.ts"; + +type PublicRenderModelBase = components["schemas"]["PublicRenderModelBase"]; +type ResolvedRelation = components["schemas"]["ResolvedRelation"]; + +/** 관계 대상의 종류 이름. 프로젝트만 표에 없다 — 기록이 아니라 묶음이기 때문이다. */ +function kindLabel(kind: ResolvedRelation["targetKind"]): string { + return kind === "PROJECT" ? "프로젝트" : DOCUMENT_KIND_LABELS[kind]; +} + +/** + * 이 기록이 어느 조사의 어디쯤인지. + * + *

    이 사이트의 차별점은 "기록 하나에 아무 데서나 들어와도 그 결론을 만든 맥락의 사슬을 잃지 + * 않는다"는 것이다. 그런데 그 사슬이 화면에서는 제목 위 얇은 breadcrumb 한 줄과 문서 맨 아래 + * 「다음에 읽을 것」으로만 표현돼 있었다 — 검색으로 Case 하나에 들어온 사람은 바닥까지 내려가야 + * 이 기록이 어느 프로젝트의 어느 질문에서 나왔는지 알 수 있었다. 저장은 되어 있는데 겪게 되지는 + * 않는 상태였다. + * + *

    그래서 제목·요약 바로 아래에 맥락을 하나의 덩어리로 세운다. 프로젝트 → 주제까지 올라가는 + * 길과, 같은 조사 안에서 이웃한 기록들을 함께 보인다. 지금 보는 기록은 링크가 아니라 현재 + * 위치로 표시한다. + * + *

    이웃 기록에는 작성자가 그 관계에 남긴 문장을 그대로 붙인다. 「다음에 무엇을 읽을지」보다 + * 「왜 그것을 읽어야 하는지」가 먼저 있어야 목록이 아니라 사슬로 읽힌다. + * + *

    `

    ` 하나로 두 폭을 모두 쓴다. 좁은 화면에서는 접을 수 있고, 넓은 화면에서는 CSS 가 + * 여는 손잡이를 감춰 늘 펼친 덩어리로 보인다 — 폭을 재서 DOM 을 둘로 만들면 같은 이름의 landmark + * 가 둘이 되어 보조 기술에는 같은 것이 두 번 나온다. + */ +export function ContextNavigator({ model }: { model: PublicRenderModelBase }) { + const project = model.project; + const topic = model.topic.label ? model.topic : null; + /* + 열리지 않는 주소는 줄로 그리지 않는다. 게시할 때 만들어 저장한 문자열이라 라우트가 없는 + 모양이면 화면 코드 어디에도 흔적이 없고 방문자만 404 를 만난다 — 결정의 주소가 실제로 그랬다. + */ + const siblings = [...model.relations] + .filter((relation) => resolvesToPublicRoute(relation.publicPath ?? "")) + .sort((left, right) => left.order - right.order); + + // 올라갈 곳도 옆으로 갈 곳도 없으면 맥락이랄 것이 없다. 빈 상자를 남기지 않는다. + if (!project && !topic && siblings.length === 0) return null; + + return ( +
    +
    + 이 기록의 맥락 + +
    +
    + ); +} diff --git a/src/features/tech-log/presentation/shared/public-render/public-record-renderer.tsx b/src/features/tech-log/presentation/shared/public-render/public-record-renderer.tsx index d68d70b..1534fa6 100644 --- a/src/features/tech-log/presentation/shared/public-render/public-record-renderer.tsx +++ b/src/features/tech-log/presentation/shared/public-render/public-record-renderer.tsx @@ -8,6 +8,7 @@ import type { ResolvePublishedLabel, } from "../../../domain/public-render-content.ts"; import { CaseBodyRenderer } from "./case-body-renderer.tsx"; +import { ContextNavigator } from "./context-navigator.tsx"; import { DocumentToc } from "./document-toc.tsx"; import { PublicDocumentRelations, @@ -218,6 +219,8 @@ function CaseDocument({ + +
    @@ -293,6 +296,8 @@ function ConceptDocument({ + +
    @@ -380,6 +385,8 @@ function SetupDocument({ + +
    @@ -415,6 +422,7 @@ function ReferenceDocument({ model={model} resolvePublishedLabel={resolvePublishedLabel} /> +

    Purpose

    이 기준을 쓰는 이유

    @@ -508,6 +516,7 @@ function QuestionDocument({ model={model} resolvePublishedLabel={resolvePublishedLabel} /> +

    @@ -598,6 +607,7 @@ function ProjectDecisionDocument({ ) : null} +

    1. diff --git a/src/features/tech-log/presentation/styles/globals.css b/src/features/tech-log/presentation/styles/globals.css index f98484f..e69a53a 100644 --- a/src/features/tech-log/presentation/styles/globals.css +++ b/src/features/tech-log/presentation/styles/globals.css @@ -3245,3 +3245,145 @@ textarea.studio-control { min-height: 118px; resize: vertical; line-height: 1.65 text-align: left; } } + +/* Context Navigator — 이 기록이 어느 조사의 어디쯤인지 */ + +/* + 제목·요약 바로 아래 자리다. 맥락이 breadcrumb 한 줄과 문서 맨 아래 「다음에 읽을 것」에만 + 있던 동안, 검색으로 기록 하나에 들어온 사람은 바닥까지 내려가야 이 기록이 어디에서 나왔는지 + 알 수 있었다. 상자를 두르지 않고 왼쪽 선 하나로만 묶는다 — 이 사이트의 나머지 화면이 카드를 + 쓰지 않는다. +*/ +.context-navigator-wrap { + padding-bottom: 8px; +} + +.context-navigator { + max-width: 860px; + padding-left: 17px; + border-left: 2px solid var(--line-strong); +} + +.context-navigator > summary { + color: var(--muted); + cursor: pointer; + font-size: 12px; + font-weight: 660; + letter-spacing: 0.06em; + list-style: none; + text-transform: uppercase; +} + +.context-navigator > summary::-webkit-details-marker { + display: none; +} + +.context-navigator > summary::after { + content: " ▾"; +} + +.context-navigator:not([open]) > summary::after { + content: " ▸"; +} + +.context-trail { + display: flex; + flex-wrap: wrap; + gap: 8px 26px; + margin: 14px 0 0; + padding: 0; + list-style: none; +} + +.context-trail li { + display: flex; + gap: 9px; + align-items: baseline; +} + +.context-trail span { + color: var(--faint); + font-size: 12px; + font-weight: 620; +} + +.context-trail a, +.context-trail strong { + color: var(--ink); + font-size: 15px; + font-weight: 620; +} + +.context-trail a:hover { + color: var(--signal); +} + +.context-siblings { + margin: 16px 0 0; + padding: 0; + list-style: none; +} + +.context-siblings li { + display: grid; + grid-template-columns: 96px minmax(0, 1fr); + gap: 16px; + padding: 9px 0; + border-top: 1px solid var(--line); +} + +.context-siblings li:first-child { + border-top: 0; +} + +.context-kind { + color: var(--faint); + font-size: 12px; + font-weight: 620; + line-height: 1.7; +} + +.context-siblings a, +.context-siblings strong { + color: var(--ink); + font-size: 15px; + font-weight: 560; + line-height: 1.55; +} + +.context-siblings a:hover { + color: var(--signal); +} + +/* 지금 보는 기록. 링크가 아니라 현재 위치다. */ +.context-siblings li[aria-current] .context-kind, +.context-siblings li[aria-current] strong { + color: var(--signal); +} + +.context-here, +.context-why { + margin: 3px 0 0; + color: var(--muted); + font-size: 13px; + line-height: 1.6; +} + +.context-here { + color: var(--signal); + font-weight: 560; +} + +/* 넓은 화면에서는 접는 손잡이를 감춘다. 늘 펼쳐 둔 덩어리로 읽힌다. */ +@media (min-width: 900px) { + .context-navigator > summary { + display: none; + } +} + +@media (max-width: 767px) { + .context-siblings li { + grid-template-columns: minmax(0, 1fr); + gap: 3px; + } +} diff --git a/tests/features/tech-log/context-navigator.test.tsx b/tests/features/tech-log/context-navigator.test.tsx new file mode 100644 index 0000000..cda2d42 --- /dev/null +++ b/tests/features/tech-log/context-navigator.test.tsx @@ -0,0 +1,164 @@ +// @vitest-environment jsdom + +import { render, screen, within } from "@testing-library/react"; +import { MemoryRouter } from "react-router-dom"; +import { describe, expect, it } from "vitest"; + +import type { components } from "../../../src/features/tech-log/contracts/studio/generated.ts"; +import type { + ResolveEvidenceAsset, + ResolvePublishedLabel, +} from "../../../src/features/tech-log/domain/public-render-content.ts"; +import { PublicRecordRenderer } from "../../../src/features/tech-log/presentation/shared/public-render/public-record-renderer.tsx"; + +type RenderModel = components["schemas"]["PublicRenderModel"]; +type RecordKind = RenderModel["kind"]; + +const base = { + slug: "sample", + title: "표본 기록", + summary: "요약", + topic: { id: "topic-kvm", label: "CPU 가상화", publicPath: "/topics/cpu" }, + project: { id: "project-v", label: "가상화", publicPath: "/projects/gasanghwa" }, + relations: [ + { + id: "relation-1", + targetId: "reference-1", + targetKind: "REFERENCE" as const, + title: "이어지는 기준", + publicPath: "/references/linked", + reason: "이 기록의 결론이 그대로 이 기준이 되었다.", + order: 1, + }, + ], + renderContext: { generatedAt: "2030-01-02T00:00:00Z", dependencyRevision: "r1" }, +}; + +/* + 종류마다 하나씩 둔다. `Record` 라 종류가 늘면 컴파일러가 빈 자리를 잡는다 — + 이 저장소에서 손으로 나열한 목록에 새 종류를 빠뜨리는 일이 반복됐고, 맥락 덩어리가 한 종류에서만 + 빠지면 그 종류로 들어온 방문자에게만 조용히 사슬이 끊긴다. +*/ +const MODELS: Record = { + CASE: { + ...base, + kind: "CASE", + publicPath: "/cases/sample", + problem: "문제", + conclusion: "결론", + environment: "환경", + reproduction: "데이터셋", + lastVerifiedOn: "2030-01-02", + bodyBlocks: [], + }, + CONCEPT: { + ...base, + kind: "CONCEPT", + publicPath: "/concepts/sample", + basisVersion: "Linux 6.8", + bodyBlocks: [], + }, + SETUP: { + ...base, + kind: "SETUP", + publicPath: "/setups/sample", + pinnedVersions: [{ name: "Keycloak", version: "26.7.0" }], + bodyBlocks: [], + }, + REFERENCE: { + ...base, + kind: "REFERENCE", + publicPath: "/references/sample", + purpose: "쓰는 이유", + rules: [{ id: "11111111-1111-4111-8111-111111111111", title: "기준 하나", body: "본문", order: 1 }], + applyWhen: [{ id: "22222222-2222-4222-8222-222222222222", text: "적용", order: 1 }], + exceptions: [], + examples: [], + verifiedOn: "2030-01-02", + }, + QUESTION: { + ...base, + kind: "QUESTION", + publicPath: "/questions/sample", + status: "OPEN", + facts: [], + assumptions: [], + unknowns: [], + constraints: [], + options: [], + nextValidation: "다음 검증", + resolution: null, + }, + PROJECT_DECISION: { + ...base, + kind: "PROJECT_DECISION", + publicPath: "/projects/gasanghwa/decisions#sample", + status: "ADOPTED", + decidedOn: "2030-01-02", + statement: "결정", + rationale: "이유", + consequences: [], + }, +}; + +// 이 검사는 본문을 보지 않는다. 본문이 빈 기록이라 이 둘은 불리지 않는다. +const dependencies = { + resolveEvidenceAsset: (key: string) => ({ + src: `/media/${key}`, + width: 1, + height: 1, + triggerLabel: "열기", + dialogLabel: "그림", + }), + resolvePublishedLabel: () => undefined, +} satisfies { + resolveEvidenceAsset: ResolveEvidenceAsset; + resolvePublishedLabel: ResolvePublishedLabel; +}; + +describe("기록마다 맥락이 제목 바로 아래에 있다", () => { + for (const [kind, model] of Object.entries(MODELS)) { + it(`${kind} 기록이 프로젝트·주제·이웃 기록을 함께 보여 준다`, () => { + render( + + + , + ); + + const context = screen.getByRole("navigation", { name: "이 기록의 맥락" }); + expect(within(context).getByRole("link", { name: "가상화" })).toHaveAttribute( + "href", + "/projects/gasanghwa", + ); + expect(within(context).getByRole("link", { name: "CPU 가상화" })).toHaveAttribute( + "href", + "/topics/cpu", + ); + // 이웃 기록은 제목만이 아니라 "왜 그것을 읽어야 하는지"를 함께 보여야 사슬로 읽힌다. + expect(within(context).getByRole("link", { name: "이어지는 기준" })).toBeInTheDocument(); + expect( + within(context).getByText("이 기록의 결론이 그대로 이 기준이 되었다."), + ).toBeInTheDocument(); + // 지금 보는 기록도 목록에 있어야 "내가 그중 어디인가"가 보인다. + expect(within(context).getByText("지금 읽는 기록")).toBeInTheDocument(); + }); + } + + it("올라갈 곳도 옆으로 갈 곳도 없으면 빈 상자를 남기지 않는다", () => { + render( + + + , + ); + + expect(screen.queryByRole("navigation", { name: "이 기록의 맥락" })).toBeNull(); + }); +}); diff --git a/tests/features/tech-log/section-selector-scope.test.ts b/tests/features/tech-log/section-selector-scope.test.ts index 4284a8b..6d25f37 100644 --- a/tests/features/tech-log/section-selector-scope.test.ts +++ b/tests/features/tech-log/section-selector-scope.test.ts @@ -35,6 +35,9 @@ const SETTLED = new Set([ ".studio-readiness-list li", ".studio-relations-editor li", ".project-index-title span", + // 맥락 덩어리의 두 목록은 한 모양의 항목만 담는다 — 프로젝트/주제 한 쌍, 기록 한 줄. + ".context-trail li", + ".context-siblings li", ".studio-warning-check span", ]); diff --git a/tests/features/tech-log/studio-decision-authoring.test.tsx b/tests/features/tech-log/studio-decision-authoring.test.tsx index e2c1e60..9a981e4 100644 --- a/tests/features/tech-log/studio-decision-authoring.test.tsx +++ b/tests/features/tech-log/studio-decision-authoring.test.tsx @@ -175,7 +175,13 @@ describe("TechLog Studio project decision authoring", () => { expect(within(preview).getByText("판단 이유")).toBeVisible(); expect(within(preview).getByText("영향")).toBeVisible(); expect(within(preview).getByText("근거 기록")).toBeVisible(); - expect(within(preview).getByRole("link", { + /* + 같은 기록이 화면에 두 번 나온다 — 위쪽 「이 기록의 맥락」이 이 결정이 어느 조사에 속하는지 + 보여 주고, 아래 「근거 기록」이 그 결정을 뒷받침한 기록을 다시 세운다. 목차가 본문의 제목을 + 다시 적는 것과 같은 중복이므로, 확인은 근거 목록 안으로 좁힌다. + */ + const evidence = within(preview).getByText("근거 기록").closest("section")!; + expect(within(evidence as HTMLElement).getByRole("link", { name: "컬렉션 Fetch Join과 페이징은 왜 충돌하는가", })).toHaveAttribute("href", "/cases/collection-fetch-join-pagination"); });