feat: 명세 문서 API 연결 · 웹소켓 재연결 보완 · 400 재시도 제외

[jeonbinggu]

🔀 Pull Request Title

feat: 명세 문서 API 연결 · 웹소켓 재연결 보완 · 400 재시도 제외

• Closes [FEAT] 명세 문서 API 연결 · 웹소켓 재연결 보완 · 400 재시도 제외 #42

🎞️ 주요 코드 설명

명세 문서 (entities/spec, widgets/docs/DocsView.tsx)

• useSpecs(projectId): GET /projects/{projectId}/specs (featureKey 순). 문서라 폴링하지 않고 specs 신호로 다시 읽는다
• 명세 탭: featureKey 목차 → 명세마다 제목 · 버전 · 생성 시각 · 내용(마크다운) · 시험지(잠김 시각 / "잠기지 않음 · V2 근거 아님", 시험 코드 펼치기)
• 헌법 · 계약 · 결정기록은 API가 없어 목업을 읽는다. 목업이 없는 실제 프로젝트는 그 탭에만 "API 연결 전" 안내 — 예전에는 페이지 전체가 막혔다
• 기존 border-amber-200(Tailwind 기본 색)을 토큰 border-human으로

웹소켓 보완 (shared/api/stream.ts)

let rejectedToken: string | null = null;           // 4401로 거절된 토큰
// onclose: if (e.code === 4401) rejectedToken = token;
// acquire: if (!ws && !retryTimer && token !== rejectedToken) open();

window.addEventListener("online", () => {          // 재연결 대기 중일 때만 바로 연결
  if (!retryTimer) return;
  clearTimeout(retryTimer); retryDelay = 1_000; open();
});

기타

• useRealtimeSync: specs: (id) => [specKeys.list(id)]
• providers.tsx: 재시도 제외에 400 추가
• docs/conventions.md: 엔티티 슬라이스 목록에 빠져 있던 approval과 새 spec

📌 PR 설명

이번 PR에서 어떤 작업을 했는지 요약해주세요.

• 명세 탭 API 연결 + specs 실시간 매핑
• 목업 없는 문서 탭은 탭별 안내
• 4401 토큰 기억 · online 즉시 재연결
• 400 재시도 제외

pnpm format · pnpm lint · pnpm typecheck · pnpm build 통과

테스트 — 브라우저 확장이 연결되지 않아, 웹소켓은 stream.ts를 그대로 복사해 Node 22 내장 WebSocket으로 실제 서버에 붙여 확인했다 (임시 파일, 커밋 안 함)

케이스	결과
4401 뒤 화면 이동 흉내(해제 → 재획득 2번)	연결 시도 1번 (수정 전 코드로 같은 시나리오: 3번) — 프록시로 시도 기록
그 뒤 다른 토큰으로 획득	바로 다시 시도함
서버 종료 → 재시작 → online 이벤트	0.026초 뒤 재연결 + resync (예정된 다음 재시도보다 먼저)
명세 생성	서버가 ["events","specs"] 신호 전송 (wsprobe로 확인)
명세 API 응답	featureKey · 버전 · 시험지 잠김/안 잠김이 화면 코드가 쓰는 모양과 일치
형식이 틀린 레포 id	서버 400 → 이제 재시도 없이 바로 에러

브라우저 확인 (Chrome 확장 재연결 후, 로컬 BE 3000)

케이스	결과
명세 탭	목차 3개 · 명세별 제목·버전·시각·내용 · F-02 시험지 "잠김 · 10월 6일" / "잠기지 않음 · V2 근거 아님" 배지
시험 코드 펼치기	expect(res.status).toBe(201) 표시
화면을 띄운 채 명세 생성(F-04)	요청 0.53초 뒤 표시, 탭 카운트 3개 → 4개 (명세는 폴링이 없으므로 specs 신호로 반영)
헌법 · 계약 · 결정기록 탭	각 탭에만 "OO API 연결 전입니다" + 목업 배지, 문서 내비게이션은 그대로 사용 가능
형식이 틀린 레포 id (400)	0.3초 만에 "입력값을 다시 확인해 주세요", 요청 1번 (재시도 없음)
없는 레포 id (404)	요청 1번, "조직으로" 버튼 (기존 동작 유지)

알아둘 것

• Node의 WebSocket(undici)은 연결 거부 때 error만 내고 close를 내지 않는다. 브라우저는 표준대로 close(1006)도 낸다. 테스트 하네스에서만 브라우저처럼 맞췄다

📷 스크린샷

명세 탭(시험지 잠김/미잠김 배지)과 "API 연결 전" 탭 화면을 로컬에서 확인함. 위 표로 대신함

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
frontend	Ready	Preview	Oct 6, 2026 4:51am UTC