Commit Graph
15 Commits
Author SHA1 Message Date
donghyeon-ka aaa384c145 refactor: 템플릿에서 기본적으로 제공하고 있는 워크 플로우에 디자인과 라우팅 흡수 2026-09-23 12:42:10 +09:00
DongHyeonkaandClaude Opus 5 623a58942f fix: 홈의 「지금 집중하는 것」이 단계를 사람 말로 적는다
새로 찍은 화면에서 드러났다. 홈은 `DESIGN` 이라는 저장값을 그대로 찍고 있었고,
프로젝트 화면은 같은 값을 「설계」로 부르고 있었다 — 한 사이트가 같은 것을 두 이름으로
말했다. 활동 종류에서 겪은 것과 같은 실수다.

이름표를 도메인으로 옮긴다. 어댑터는 표현 계층을 import 할 수 없고(경계 규칙), 이름표를
어댑터마다 다시 적으면 정확히 이 문제가 다시 난다. 단계 집합도 도메인이 갖게 해서 포트가
그것을 쓰도록 했다 — 같은 집합을 두 곳에 적으면 한쪽만 늘어난다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
2026-09-15 21:12:34 +09:00
DongHyeonkaandClaude Opus 5 0b0c5cb42d feat: 홈이 길을 보여 주고, 활동이 사람 말로 적힌다
홈의 첫 문장은 글 쓰는 태도를 말했다 — "문제를 재현하고 검증해 정리합니다". 맞는
말이지만 처음 온 사람이 알아야 하는 것은 태도가 아니라 길이다. 이 사이트에서 기록은
한 편으로 끝나지 않고 프로젝트 안의 주제에 속하고 주제 안에서 서로 이어진다. 그 구조를
설명하는 문장보다 실제 사슬 하나가 빠르므로, 최근 기록이 가장 많이 모인 주제를 골라
프로젝트 → 주제 → 기록으로 편다. 예시를 코드에 적어 두지 않는다 — 그 기록을 지우는
순간 홈이 죽은 링크를 가리킨다.

프로젝트 활동은 종류 자리에 `CONCEPT_PUBLISHED` 를 그대로 찍고 있었다. 그것은
데이터베이스 제약(`project_activity_activity_type_check`)이 허용하는 값이지 방문자에게
할 말이 아니다 — 감사 로그처럼 읽히고, 정작 무슨 일이 있었는지는 알 수 없었다.

포트의 타입은 `"PUBLICATION" | "PROJECT UPDATE" | "QUESTION"` 셋으로 적혀 있었는데
서버는 그중 무엇도 보내지 않는다. 매퍼가 단언으로 통과시켜서 타입 검사도 이것을 잡지
못했다. 실제 값 열하나로 맞추고, `Record<ProjectActivityType, string>` 표로 사람이 읽는
문장을 만든다. 픽스처도 같은 값을 쓰게 했다 — 픽스처가 자기만의 말을 쓰던 동안 화면은
픽스처에서만 멀쩡했다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
2026-09-15 20:15:05 +09:00
DongHyeonkaandClaude Opus 5 02fff0cd03 feat: UX 리뷰의 남은 네 항목을 반영한다
H2. 편집기.
7,540px 폼에 섹션으로 갈 수단이 목차도 접기도 앵커도 없었다. 화면에 실제로 있는
`section[aria-labelledby]` 를 읽어 목차를 만든다 — 목록을 손으로 적지 않으므로
섹션이 바뀌어도 이 파일은 그대로다.

미리보기가 sticky 로 문서 맨 위에 고정돼, 폼 중반에서 지금 쓰는 문단이 미리보기
어디인지 볼 방법이 없었다. 커서가 지난 마지막 `##` 을 찾아 미리보기의 같은 제목으로
옮긴다. 스크롤 비율을 맞추는 방식은 두 쪽 길이가 다르면 늘 어긋난다. 손으로 넘기는
중에는 따라가지 않는다.

반복 그룹은 접을 수 있고 순서는 끌어서 바꾼다. 「위로/아래로」는 남긴다 — 끌기는
키보드로 할 수 없고, 그것만 두면 키보드로 쓰는 사람에게서 순서 바꾸기를 빼앗는다.
대신 작게 적는다.

H3. 주제와 프로젝트를 탭으로 나눈다.
한 화면이 성격이 다른 두 엔티티를 같은 문법으로 다뤘다. 「추가」 버튼 둘이 같은
이름·같은 모양으로 한 줄에 있었고, 주제 행은 프로젝트에 맞춘 그리드라 절반이
빈칸이었다. 버튼 이름을 「주제 추가」·「프로젝트 추가」로 가르고, 프로젝트 행에서
같은 주소를 두 번 가리키던 「내용 편집」 하나를 없애고, 주제 행에 편집 버튼을 둔다.

M10. 프로필에 연락·구독 수단. 계약은 처음부터 `contacts` 를 주고 있었고 화면이
읽지 않았다 — 읽고 나서 할 수 있는 일이 하나도 없었다. 프로필이 게시 전이면 빈
목록이고 그때는 구역을 그리지 않는다.

M11. 공개 화면 HTML 에 Studio 청크 셋이 modulepreload 로 붙어 있었다. 읽기만 하는
사람이 편집기 번들을 내려받았다. 빌드에서 그 셋만 뺀다 — 공개 라우트의 미리 받기는
그대로 둔다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
2026-09-09 19:27:25 +09:00
DongHyeonkaandClaude Opus 5 aca4f189d1 feat: 주제 목록 화면을 만들어 주 내비에 넣는다
주제로 가는 길이 기록의 breadcrumb 과 탐색의 묶음 제목뿐이었다. 주제가 이 기록의 뼈대인데
그 목록을 정면으로 보여 주는 자리가 없었고, 홈이 한 주제만 펼치던 동안 나머지는 최근
기록에 우연히 걸릴 때만 보였다.

목록의 각 줄은 이름·논지·축·기록 수를 싣는다. 이름은 무엇에 대한 것인지만 말하므로,
들어갈지 말지를 정하려면 그 주제가 무엇에 답하는지가 함께 있어야 한다. 그래서 계약의
`TopicListItem` 에 논지와 축을 더한다 — 그동안 이름과 개수뿐이었다.

홈의 「다른 주제」 줄은 목록으로 가는 한 줄로 줄인다. 주제가 늘면 옆으로 길어지던 자리다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-02 00:43:58 +09:00
DongHyeonkaandClaude Opus 5 67a549173d feat: 축에 자기 화면을 준다
주제 화면의 네 줄(SPA·Mediator·BFF·Forward-Auth)은 링크인데 눌러도 아무 일이 없었다.
축의 주소를 주제 화면 안의 앵커로 잡아 두어서, 정작 주제 화면에서는 그 링크가 자기 자신을
가리켰다 — 주소만 바뀌고 화면은 그대로였다.

축에 화면을 준다. 결론을 먼저 두고 그 아래 그 축에 걸린 기록만 모은다. 목록 조회에
`variant` 필터를 더해 `record_variant` 로 거른다 — 축 slug 는 주제 안에서만 유일하므로
주제까지 함께 맞춘다.

정적 어댑터는 축으로 거르면 빈 목록을 준다. 축은 사람이 Studio 에서 거는 값이라 픽스처가
지어낼 수 없고, 없는 것을 있는 척하면 이 어댑터로 그린 화면이 서버로 바꿨을 때 달라진다.

`RecordFilters` 가 포트와 정적 어댑터에 따로 있어, 포트에 필터가 늘어도 이쪽은 모르는
상태가 됐다 — 메서드 매개변수가 bivariant 라 `satisfies` 가 잡지 못한다. 하나로 합친다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 20:36:53 +09:00
DongHyeonkaandClaude Opus 5 3510ec013f feat: 프로젝트 화면이 어디서부터 읽을지를 말한다
숫자 셋(기록 12 · 결정 4 · 활동 9)은 이 프로젝트가 얼마나 큰지는 말해도 어디서부터
읽어야 하는지는 말하지 않는다. 세는 자리를 처음 몇 편으로 바꾸고, 숫자는 각 목록으로
가는 줄에 남긴다.

「주요 주제」는 글자 목록이었다. 매퍼가 이름만 남기고 slug 를 버려서 그 주제로 갈 수가
없었는데, 계약은 처음부터 둘 다 주고 있었다.

논지 자리의 제목도 고친다 — 「프로젝트가 지키는 기준」이 아니라 이 프로젝트가 밝힌
것이고, 여러 문단으로 쓸 수 있으므로 산문으로 그린다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 17:19:32 +09:00
DongHyeonkaandClaude Opus 5 15e6ea8f15 feat: 주제 화면을 계약에 잇고, 등록을 잊는 사고를 가드로 막는다
주제 화면은 주제 셋(`jpa`, `authentication`, `redis`)을 코드에 적어 두고 그 셋만
열었다. 제목과 설명까지 코드에 있었고, 목록에 없는 주제는 기록이 멀쩡히 있어도 404 로
갔다 — 픽스처의 `kubernetes` 가 그랬다. 계약에는 처음부터 `/topics/{slug}` 가 있었지만
아무도 부르지 않았다. 이제 그 연산을 부르고, 주제가 답하는 질문(논지)과 그 질문에 대해
실제로 만들어 본 답들(축)을 화면의 뼈대로 둔다.

프로젝트의 논지도 마찬가지다. 담을 칸이 없어 목적(`purpose`)을 대신 보여 주고
있었는데, 목적은 시작할 때 쓰는 글이라 화면에는 늘 시작할 때의 말만 남았다.

축 CRUD 네 연산은 계약에 있으면서 기여 목록에 없었다 — 등록되지 않은 연산은 타입에는
멀쩡히 보이는데 부를 수가 없다. `getPublicConcept` 과 `deleteConceptDraft` 가 정확히
그래서 못 불렸고, 개념 삭제가 질문 삭제를 불러 "질문을 찾을 수 없습니다" 가 떴다.
그래서 가드를 둘 넣는다. 공개 계약은 전수 대조하고(봉투 없이 바이트를 주는 `/media` 만
면제), 관리 계약은 **한 종류만 빠진 자리**를 본다 — 깨진 것이 늘 그 모양이었다.
개념 삭제 등록을 지워 보고 실제로 멈추는 것을 확인했다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 16:57:24 +09:00
DongHyeonkaandClaude Opus 5 048c1b2f68 feat: 개념(CONCEPT) 문서 종류 — 편집기·공개 화면·탐색
Kubernetes 내부 동작처럼 처음부터 풀어 읽어야 하는 글을 쓸 자리를 만든다. Reference 는
판단 기준을 빨리 찾는 글이라 규칙·적용·예외로 나뉘고, 그 틀에 개념을 넣으면 두 글이 서로를
망친다 — 기준을 찾으러 온 사람은 배경을 지나야 하고, 개념을 배우러 온 사람은 규칙에서
시작한다.

편집기는 Case 의 본문 칸과 Asset Picker 를 그대로 쓴다. 아키텍처 도식은 같은
`:::evidence` 로 들어오고, `##` 소제목이 목차가 된다. 개념이 따로 갖는 것은 기준 버전
하나다 — 개념이 낡는 방식은 날짜가 아니라 버전이다.

공개 렌더는 Case 와 본문·목차를 공유하되 머리말이 다르다. 문제도 결론도 검증 환경도 없고,
프로젝트 마디는 값이 있을 때만 그린다 — 개념은 프로젝트 없이 서는 유일한 종류다.

픽스처가 실제 결함을 하나 드러냈다. 프로젝트 없는 기록이 처음 생기자 `?project=` 빈 값이
"프로젝트가 없는 기록 전부" 를 뜻하게 됐다 — 고르지 않은 것이 고른 것이 되어 버린다. 빈
필터는 아무것도 고르지 않도록 고쳤다. 예전에는 빈 값에 걸릴 기록이 없어 저절로 맞았다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0189NzCryfeqDzS81EWidnBx
2026-08-28 19:51:20 +09:00
DongHyeonkaandClaude Opus 5 344a163d84 fix: 탐색 주제 필터가 slug 를 보내고, 편집기를 넓혀 두 칸이 함께 스크롤한다
주제 필터를 걸면 「조건에 맞는 공개 기록이 없습니다」만 남았다. 선택지가
`<option>{이름}</option>` 이라 값이 없어 이름이 그대로 나갔고 — `topic=OAuth/OIDC 인증
경계` — API 는 slug 로 거르므로 0건을 돌려줬다. 프로젝트 선택지는 처음부터
`value={slug}` 였고, 그래서 프로젝트만 멀쩡했다. 주제도 같은 모양으로 맞춘다.

테스트가 이 결함을 통과시킨 이유는 픽스처의 주제 이름이 `JPA`, `Authentication` 처럼
slug 와 구분되지 않는 값이어서다. 이름과 slug 가 다른 값을 쓰는 운영에서만 드러났다.
선택지의 값이 slug 인지 직접 묻는 단언을 넣는다.

`RecordFilters.topic` 은 어댑터마다 뜻이 달랐다. 정적 어댑터는 이름으로, HTTP 어댑터는
그 값을 그대로 API 에 넘겨 slug 로 걸렀다. 프로젝트가 이미 slug/제목 둘 다 받는 것과
같이 주제도 둘 다 받게 해서 두 어댑터가 같은 값을 이해하게 한다. 주제 페이지도 이름
대신 경로의 slug 로 묻는다.

「전체」를 고른 칸은 조건이 아니다. 빈 값까지 실어 보내고 있었고, URL 이 지저분해질 뿐
아니라 이 값을 그대로 API 에 넘기는 화면에서는 `topic=` 이 "slug 가 빈 문자열인 주제"로
해석되어 0건이 된다.

편집기는 미리보기를 붙박이로 두고 자체 스크롤을 줬다. 편집기를 내려도 미리보기는
제자리였고, 보려면 그 안을 따로 굴려야 했다 — 나란히 둔 이유가 둘을 같이 보는 것인데
움직임이 갈라지면 그 이점이 없다. 둘 다 페이지 스크롤을 그대로 타게 한다.

폭도 넓힌다. `.studio-main` 은 모든 Studio 화면이 1180px 를 함께 쓰는데, 본문 두 벌이
들어가야 하는 이 화면에서는 한 칸이 566px 였다. 편집기가 놓인 경우에만 1600px 로
넓히고 헤더도 같이 넓혀 좌우 끝을 맞춘다. 다른 화면은 그대로다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0189NzCryfeqDzS81EWidnBx
2026-08-26 17:30:11 +09:00
DongHyeonkaandClaude Opus 5 fd73bc88a1 fix: Decision 미리보기의 결정일 요구를 풀고, 화면 테스트가 실제 동작을 다시 말하게 한다
Decision 은 결정일이 없으면 미리보기가 열리지 않았다. 검증은 그것을 경고로만 다루므로
날짜 없이 게시할 수 있는데 렌더 모델이 필수로 요구했다 — 작성자는 "경고라면서 왜 안
되냐"를 만난다. 계약을 nullable 로 열고 화면이 "결정일 미정"이라고 말하게 한다.

한 칸의 실패가 화면을 통째로 날리지 않게 한다. `Promise.all([gateway.foo()])` 은 foo 가
거절하는 것만 잡는다 — 호출이 동기적으로 던지면 배열을 만드는 중에 터져 rejection
handler 를 지나지 못하고, 그러면 홈 focus 한 칸 때문에 대시보드 전체가 빈 화면이 된다.
프로젝트 편집도 같은 모양이라 함께 고친다.

`IntersectionObserver` 가 없는 환경을 견딘다. 목차는 픽스처 Case 하나에서만 쓰여 그런
환경을 만난 적이 없었는데, 모든 Case 가 목차를 받게 되면서 jsdom 에서 문서가 통째로
깨졌다. 없으면 "지금 읽는 절" 표시만 못 할 뿐이다.

픽스처의 최근 기록에서 릴리스를 뺀다. 서버의 `latestEntries` 는 공개 투영에서 고르므로
릴리스가 없고, 홈이 릴리스를 따로 읽어 합친다 — 픽스처가 넣으면 같은 릴리스가 두 번
나온다.

화면 테스트는 `test:unit` 이 아니라 `test:tech-log` 가 돌린다. 그것을 돌리지 않아 위
두 결함과, 라우트 두 개·`--body-copy`·Case 배치 통합·활동 링크 제거처럼 의도한 변경에
고정돼 있던 단언들이 23건 빨간 채로 여러 커밋을 지나갔다. 단언을 실제 동작으로 옮긴다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XEHXspz4rv5pB5wiiSsVDu
2026-08-24 18:03:11 +09:00
DongHyeonkaandClaude Opus 5 b3aa304975 feat: 프로젝트를 공개할 수 있게 하고, 홈이 무엇을 앞에 둘지 고를 수 있게 한다
공개 화면 다섯 곳이 조용히 비어 있었다. 원인은 하나씩 달랐지만 모두 "값을 채울
방법이 없었다"는 같은 모양이었다.

홈의 "지금 집중하는 것" — `home_focus_config` 는 마이그레이션이 빈 행 하나만
넣어 두었고, 계약에 선언된 `getHomeFocus`/`updateHomeFocus` 는 구현이 없었다.
세 슬롯이 모두 비면 홈은 그 영역을 아예 그리지 않으므로, 운영에서는 한 번도
나타난 적이 없다. Studio 대시보드에 고르는 화면을 둔다.

홈의 "최근 기록" — 화면이 공개된 프로젝트를 하나씩 돌며 타임라인을 조립했다.
그래서 게시한 문서라도 그 프로젝트가 공개되어 있지 않으면 목록에서 통째로
빠졌고, 실제로 릴리스 한 줄만 남았다. 무엇이 최근인지는 공개 투영이 이미 알고
있으므로 그것을 그대로 읽는다. 프로젝트마다 요청을 보내던 N+1 도 사라진다.

프로젝트 공개 — 프로젝트는 `RecordKind` 에 없어 문서 게시 파이프라인을 타지
못하는데, 공개 화면들(프로젝트 목록·프로필의 "현재 프로젝트"·홈 focus)은 전부
`public_resource_projection` 의 PROJECT 행을 가시성 관문으로 쓴다. 그 행을
세우는 경로가 없었으므로 프로젝트는 영원히 비공개였다. 계약에 이미 있던
`publishProject`/`unpublishProject` 를 구현하고 주제·프로젝트 화면에 버튼을 둔다.

문서 사이 관계 연결 — `JdbcCatalogQueryAdapter` 의 RELATION/EVIDENCE 가
`List.of()` 스텁이라 어떤 기록도 연결 대상 목록을 채울 수 없었다. RELATION 은
작성 중에 고르는 것이므로 작업본까지 포함하고, EVIDENCE 는 읽는 사람이 따라갈
수 있어야 하므로 공개된 것만 포함한다.

본문 너비 — 문서 한 편이 세 폭으로 갈라져 있었다. 머리말 920px, 유형·프로젝트
줄은 shell 전체 1180px, 본문은 672px 를 가운데 정렬. 셋을 같은 폭·같은 왼쪽
끝에 세우고 읽는 단을 56rem 으로 넓힌다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XEHXspz4rv5pB5wiiSsVDu
2026-08-23 17:38:49 +09:00
DongHyeonka c5e8735041 feat: read the profile's topics from Studio, and add working-copy deletion
Two things an author could not control from Studio.

The profile's "주요 관심 주제" was four strings in the JSX. Creating or removing
a topic in Studio changed nothing, and correcting the list meant a rebuild and
a redeploy. It now renders the published topic list. The old literal opened
with "Backend Architecture", which no record in the catalogue actually carries
— the profile was advertising a topic that did not exist, and nothing could
have caught that while the list lived in the markup.

The working-copy list gained a delete control. It routes by kind because the
contract and the storage both do: Case and Reference share one table split by
type, Question is its own. Decision has no delete — its lifecycle is accept,
reject, supersede, which records what happened rather than erasing it — so the
control does not appear for it.

The list summary carries no version, so deletion reads the working copy first
and uses the version it finds. A stale version from a list left open should
fail as a conflict, not delete whatever is there now.
2026-08-21 13:30:37 +09:00
DongHyeonka 4566f2d7a8 refactor: make the public read port async so a network adapter can implement it
`PublicContentQueries` returned arrays, not promises. That signature is only
implementable by something already in memory, so the port could hold exactly
one adapter — the bundled fixture — and no amount of configuration could put
the public site on the backend. Turning it async is the change that makes a
second adapter possible; the adapter itself follows.

The markup is untouched. Every page reads a value and hands it to a
presentational component, so the shape those components receive is mapped at
the adapter boundary and nothing below the page changes.

Screens load through one query, not one per read. Several pages read in a loop
— the home timeline walks every project for its activity, the explore filter
walks search results to resolve titles — and a hook per read would mean a
variable number of hooks per render, which React forbids. `usePublicContent`
takes the whole screen's reads as one loader, where a loop is a loop and
`Promise.all` is available; the loops that used to be N sequential lookups now
issue together.

Two places deliberately do not show the loading surface. The explore filter
sits inside a page that already renders one, so a second skeleton would move
the layout under it — it keeps its structure and fills its options in when they
arrive. The search dialog is a type-ahead: re-querying per keystroke would
replace the results with a skeleton on every key, so it loads the catalog once
and applies the same predicate locally.

`usePublicContent` requires an object because `undefined` is how the query
layer says "no result yet". A loader returning the record itself would make a
missing slug indistinguishable from a request in flight, and the page would sit
on a skeleton instead of rendering its not-found route.

Studio's `resolvePublishedLabel` stays synchronous. It is called from inside
the public renderer, so making it async would push awaits through the render
tree; the shell loads the catalog once and the callback remains a lookup.

The component tests now assemble the query providers the running app assembles.
Without them the render throws "No QueryClient set" — not a harness quirk, but
the same failure the app would produce if it were mounted without its query
layer.
2026-08-20 16:53:51 +09:00
DongHyeonka 27dda3e0e3 feat: compose TechLog static and mock adapters 2026-08-15 19:36:46 +09:00