feat: 기록마다 이 조사의 어디쯤인지를 제목 아래에 세운다
이 사이트의 차별점은 "기록 하나에 아무 데서나 들어와도 그 결론을 만든 맥락의 사슬을 잃지 않는다"는 것이다. 그런데 그 사슬이 화면에서는 제목 위 얇은 breadcrumb 한 줄과 문서 맨 아래 「다음에 읽을 것」으로만 표현돼 있었다 — 검색으로 Case 하나에 들어온 사람은 바닥까지 내려가야 이 기록이 어느 프로젝트의 어느 질문에서 나왔는지 알 수 있었다. 저장은 되어 있는데 겪게 되지는 않는 상태였다. 제목·요약 바로 아래에 맥락을 하나의 덩어리로 세운다. 프로젝트 → 주제로 올라가는 길과, 같은 조사 안에서 이웃한 기록들을 함께 보인다. 이웃에는 작성자가 그 관계에 남긴 문장을 붙인다 — 「다음에 무엇을」보다 「왜 그것을」이 먼저 있어야 목록이 아니라 사슬로 읽힌다. 지금 보는 기록도 목록에 남겨 자기 자리가 보이게 한다. 여섯 종류 전부에 들어간다. 종류마다 하나씩 픽스처를 둔 `Record<RecordKind, …>` 검사로 막았다 — 한 종류에서만 빠지면 그 종류로 들어온 방문자에게만 조용히 사슬이 끊긴다. Question 에서 빼 보고 그 검사만 실패하는 것을 확인했다. 화면 촬영기(`scripts/capture-screens.ts`)도 함께 넣는다. 라우트 레지스트리를 돌며 공개·Studio 전 화면을 찍는다. 찍을 목록을 손으로 적지 않고 `Record<RouteId, …>` 로 두어 라우트가 늘면 컴파일러가 빈 자리를 잡는다. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
This commit is contained in:
co-authored by
Claude Opus 5
parent
9e5642cd9f
commit
fe1f23520e
@@ -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 루트) — 위 사실이 한 화면에 다 있다.
|
||||
@@ -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건
|
||||
```
|
||||
|
||||
결과: `<li>`가 브라우저 기본 `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
|
||||
<title>Tech Log</title>
|
||||
<meta name="description" content="Tech Log frontend" />
|
||||
```
|
||||
|
||||
제목·설명은 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
|
||||
<span>{project.stage}</span>
|
||||
```
|
||||
|
||||
`/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
|
||||
<link rel="modulepreload" href="/assets/route-tech-log-studio-assets-CXKgHVan.js">
|
||||
<link rel="modulepreload" href="/assets/route-tech-log-studio-document-edit-CUEcUv75.js">
|
||||
<link rel="modulepreload" href="/assets/route-tech-log-studio-documents-DFho0Lfg.js">
|
||||
```
|
||||
|
||||
읽기만 하는 사람이 편집기 번들을 내려받는다.
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
```
|
||||
@@ -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 라이브러리.
|
||||
이 여덟이 같은 맥락 모델과 시각 문법을 공유하면 나머지는 그 체계를 물려받는다.
|
||||
|
||||
## 하지 말 것
|
||||
|
||||
카드 남발, 종류마다 채도 높은 색, 큰 둥근 상자, 그라디언트, 아이콘 과용.
|
||||
정체성은 타이포와 구조 컴포넌트에서 나온다.
|
||||
+2
-1
@@ -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",
|
||||
|
||||
@@ -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 검토용이다.
|
||||
*
|
||||
* <p>찍을 목록을 손으로 적지 않는다. 라우트 레지스트리를 그대로 돌고, 라우트 하나당 해석기를
|
||||
* {@link RESOLVERS} 에 반드시 하나 두게 한다 — `Record<RouteId, …>` 라 라우트가 늘면 컴파일러가
|
||||
* 빈 자리를 잡는다. 이 저장소에서 손으로 나열한 목록에 새 항목을 빠뜨리는 일이 반복됐고(종류
|
||||
* 필터에서 개념·환경 구성이 빠졌던 것이 같은 실수다), 검토용 목록이 조용히 낡으면 "찍히지 않은
|
||||
* 화면은 문제가 없는 것처럼" 보인다.
|
||||
*
|
||||
* <p>`:slug` 같은 자리는 지어내지 않고 살아 있는 API 에서 실제 값을 가져온다. 지어낸 주소는
|
||||
* 404 화면을 찍어 놓고 검토가 끝난 것처럼 보이게 만든다. 채울 값이 없으면 건너뛰되 그 사실을
|
||||
* 결과에 남긴다.
|
||||
*
|
||||
* <p>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<Record<string, string>>;
|
||||
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;
|
||||
}
|
||||
|
||||
/**
|
||||
* 라우트 하나를 실제 주소로 바꾸는 법.
|
||||
*
|
||||
* <p>`null` 은 "지금 살아 있는 자료로는 이 화면을 열 수 없다"는 뜻이다. 결과 보고서에 이유와 함께
|
||||
* 남는다 — 조용히 빠지면 검토에서 그 화면이 없었다는 사실 자체가 보이지 않는다.
|
||||
*/
|
||||
const RESOLVERS: Record<RouteId, Resolver> = {
|
||||
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<Readonly<{ id: string; group: "PUBLIC" | "STUDIO"; url: string }>> =
|
||||
[{ 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<unknown> {
|
||||
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<string, unknown> | 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<string, unknown>) : null;
|
||||
}
|
||||
|
||||
function itemsOf(value: unknown): ReadonlyArray<Record<string, unknown>> {
|
||||
const data = envelope(value);
|
||||
const items = data?.["items"];
|
||||
return Array.isArray(items) ? (items as Record<string, unknown>[]) : [];
|
||||
}
|
||||
|
||||
function text(row: Record<string, unknown> | 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<string, string> = {};
|
||||
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<string, unknown>) : 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<string, unknown>) : 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;
|
||||
|
||||
/**
|
||||
* 창을 열어 사람이 직접 로그인하게 하고 그 세션을 파일로 남긴다.
|
||||
*
|
||||
* <p>자격 증명을 스크립트가 들고 있지 않아도 되고, Keycloak 화면이 바뀌어도 깨지지 않는다.
|
||||
*/
|
||||
async function login(base: string): Promise<void> {
|
||||
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<string | undefined> {
|
||||
try {
|
||||
await readFile(SESSION_FILE, "utf8");
|
||||
return SESSION_FILE;
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 한 화면을 폭마다 찍는다.
|
||||
*
|
||||
* <p>전체 페이지를 한 장으로 찍으면 세로로 긴 문서가 통째로 축소되어 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<void> {
|
||||
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<ReturnType<typeof readStudio>> = { ...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(`})`);
|
||||
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();
|
||||
@@ -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];
|
||||
}
|
||||
|
||||
/**
|
||||
* 이 기록이 어느 조사의 어디쯤인지.
|
||||
*
|
||||
* <p>이 사이트의 차별점은 "기록 하나에 아무 데서나 들어와도 그 결론을 만든 맥락의 사슬을 잃지
|
||||
* 않는다"는 것이다. 그런데 그 사슬이 화면에서는 제목 위 얇은 breadcrumb 한 줄과 문서 맨 아래
|
||||
* 「다음에 읽을 것」으로만 표현돼 있었다 — 검색으로 Case 하나에 들어온 사람은 바닥까지 내려가야
|
||||
* 이 기록이 어느 프로젝트의 어느 질문에서 나왔는지 알 수 있었다. 저장은 되어 있는데 겪게 되지는
|
||||
* 않는 상태였다.
|
||||
*
|
||||
* <p>그래서 제목·요약 바로 아래에 맥락을 하나의 덩어리로 세운다. 프로젝트 → 주제까지 올라가는
|
||||
* 길과, 같은 조사 안에서 이웃한 기록들을 함께 보인다. 지금 보는 기록은 링크가 아니라 현재
|
||||
* 위치로 표시한다.
|
||||
*
|
||||
* <p>이웃 기록에는 작성자가 그 관계에 남긴 문장을 그대로 붙인다. 「다음에 무엇을 읽을지」보다
|
||||
* 「왜 그것을 읽어야 하는지」가 먼저 있어야 목록이 아니라 사슬로 읽힌다.
|
||||
*
|
||||
* <p>`<details>` 하나로 두 폭을 모두 쓴다. 좁은 화면에서는 접을 수 있고, 넓은 화면에서는 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 (
|
||||
<div className="shell context-navigator-wrap">
|
||||
<details className="context-navigator" open>
|
||||
<summary>이 기록의 맥락</summary>
|
||||
<nav aria-label="이 기록의 맥락">
|
||||
{project || topic ? (
|
||||
<ol className="context-trail">
|
||||
{project ? (
|
||||
<li>
|
||||
<span>프로젝트</span>
|
||||
{project.publicPath ? (
|
||||
<Link to={project.publicPath}>{project.label}</Link>
|
||||
) : (
|
||||
<strong>{project.label}</strong>
|
||||
)}
|
||||
</li>
|
||||
) : null}
|
||||
{topic ? (
|
||||
<li>
|
||||
<span>주제</span>
|
||||
{topic.publicPath ? (
|
||||
<Link to={topic.publicPath}>{topic.label}</Link>
|
||||
) : (
|
||||
<strong>{topic.label}</strong>
|
||||
)}
|
||||
</li>
|
||||
) : null}
|
||||
</ol>
|
||||
) : null}
|
||||
|
||||
<ul className="context-siblings">
|
||||
{/*
|
||||
지금 보는 기록도 목록에 둔다. 빼 두면 이웃만 나열되어 "내가 그중 어디인가"가 보이지
|
||||
않는다 — 맥락은 주변이 아니라 자기 자리를 포함해야 위치가 된다.
|
||||
*/}
|
||||
<li aria-current="true">
|
||||
<span className="context-kind">{DOCUMENT_KIND_LABELS[model.kind]}</span>
|
||||
<div>
|
||||
<strong>{model.title}</strong>
|
||||
<p className="context-here">지금 읽는 기록</p>
|
||||
</div>
|
||||
</li>
|
||||
{siblings.map((relation) => (
|
||||
<li key={relation.id}>
|
||||
<span className="context-kind">{kindLabel(relation.targetKind)}</span>
|
||||
<div>
|
||||
<Link to={relation.publicPath ?? ""}>{relation.title}</Link>
|
||||
{relation.reason?.trim() ? (
|
||||
<p className="context-why">{relation.reason}</p>
|
||||
) : null}
|
||||
</div>
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
</nav>
|
||||
</details>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -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({
|
||||
</dl>
|
||||
</header>
|
||||
|
||||
<ContextNavigator model={model} />
|
||||
|
||||
<DocumentToc headings={headings} variant="mobile" />
|
||||
|
||||
<div className="shell document-layout">
|
||||
@@ -293,6 +296,8 @@ function ConceptDocument({
|
||||
</dl>
|
||||
</header>
|
||||
|
||||
<ContextNavigator model={model} />
|
||||
|
||||
<DocumentToc headings={headings} variant="mobile" />
|
||||
|
||||
<div className="shell document-layout">
|
||||
@@ -380,6 +385,8 @@ function SetupDocument({
|
||||
</dl>
|
||||
</header>
|
||||
|
||||
<ContextNavigator model={model} />
|
||||
|
||||
<DocumentToc headings={headings} variant="mobile" />
|
||||
|
||||
<div className="shell document-layout">
|
||||
@@ -415,6 +422,7 @@ function ReferenceDocument({
|
||||
model={model}
|
||||
resolvePublishedLabel={resolvePublishedLabel}
|
||||
/>
|
||||
<ContextNavigator model={model} />
|
||||
<section className="reference-purpose" aria-labelledby="purpose-title">
|
||||
<p className="section-kicker">Purpose</p>
|
||||
<h2 id="purpose-title">이 기준을 쓰는 이유</h2>
|
||||
@@ -508,6 +516,7 @@ function QuestionDocument({
|
||||
model={model}
|
||||
resolvePublishedLabel={resolvePublishedLabel}
|
||||
/>
|
||||
<ContextNavigator model={model} />
|
||||
<p
|
||||
className={`question-status question-status--${model.status.toLowerCase()}`}
|
||||
>
|
||||
@@ -598,6 +607,7 @@ function ProjectDecisionDocument({
|
||||
</>
|
||||
) : null}
|
||||
</nav>
|
||||
<ContextNavigator model={model} />
|
||||
<ol className="project-decision-list">
|
||||
<li>
|
||||
<article id={model.slug}>
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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<RecordKind, …>` 라 종류가 늘면 컴파일러가 빈 자리를 잡는다 —
|
||||
이 저장소에서 손으로 나열한 목록에 새 종류를 빠뜨리는 일이 반복됐고, 맥락 덩어리가 한 종류에서만
|
||||
빠지면 그 종류로 들어온 방문자에게만 조용히 사슬이 끊긴다.
|
||||
*/
|
||||
const MODELS: Record<RecordKind, RenderModel> = {
|
||||
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(
|
||||
<MemoryRouter>
|
||||
<PublicRecordRenderer {...dependencies} model={model} />
|
||||
</MemoryRouter>,
|
||||
);
|
||||
|
||||
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(
|
||||
<MemoryRouter>
|
||||
<PublicRecordRenderer
|
||||
{...dependencies}
|
||||
model={{
|
||||
...MODELS.CONCEPT,
|
||||
topic: { id: "t", label: "", publicPath: null },
|
||||
project: null,
|
||||
relations: [],
|
||||
}}
|
||||
/>
|
||||
</MemoryRouter>,
|
||||
);
|
||||
|
||||
expect(screen.queryByRole("navigation", { name: "이 기록의 맥락" })).toBeNull();
|
||||
});
|
||||
});
|
||||
@@ -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",
|
||||
]);
|
||||
|
||||
|
||||
@@ -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");
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user