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건 +``` + +결과: `
찍을 목록을 손으로 적지 않는다. 라우트 레지스트리를 그대로 돌고, 라우트 하나당 해석기를
+ * {@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 `null` 은 "지금 살아 있는 자료로는 이 화면을 열 수 없다"는 뜻이다. 결과 보고서에 이유와 함께
+ * 남는다 — 조용히 빠지면 검토에서 그 화면이 없었다는 사실 자체가 보이지 않는다.
+ */
+const RESOLVERS: Record 자격 증명을 스크립트가 들고 있지 않아도 되고, Keycloak 화면이 바뀌어도 깨지지 않는다.
+ */
+async function login(base: string): Promise 전체 페이지를 한 장으로 찍으면 세로로 긴 문서가 통째로 축소되어 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 이 사이트의 차별점은 "기록 하나에 아무 데서나 들어와도 그 결론을 만든 맥락의 사슬을 잃지
+ * 않는다"는 것이다. 그런데 그 사슬이 화면에서는 제목 위 얇은 breadcrumb 한 줄과 문서 맨 아래
+ * 「다음에 읽을 것」으로만 표현돼 있었다 — 검색으로 Case 하나에 들어온 사람은 바닥까지 내려가야
+ * 이 기록이 어느 프로젝트의 어느 질문에서 나왔는지 알 수 있었다. 저장은 되어 있는데 겪게 되지는
+ * 않는 상태였다.
+ *
+ * 그래서 제목·요약 바로 아래에 맥락을 하나의 덩어리로 세운다. 프로젝트 → 주제까지 올라가는
+ * 길과, 같은 조사 안에서 이웃한 기록들을 함께 보인다. 지금 보는 기록은 링크가 아니라 현재
+ * 위치로 표시한다.
+ *
+ * 이웃 기록에는 작성자가 그 관계에 남긴 문장을 그대로 붙인다. 「다음에 무엇을 읽을지」보다
+ * 「왜 그것을 읽어야 하는지」가 먼저 있어야 목록이 아니라 사슬로 읽힌다.
+ *
+ * ` Purpose
@@ -598,6 +607,7 @@ function ProjectDecisionDocument({
>
) : null}
+ 이 기록의 맥락
+
+ 이 기준을 쓰는 이유
@@ -508,6 +516,7 @@ function QuestionDocument({
model={model}
resolvePublishedLabel={resolvePublishedLabel}
/>
+