기술 문서 (프로토타입 버전)

업데이트 루틴

저장소의 docs/dashboard-update-routine.md 와 동일한 원문입니다. 아래에서 Markdown과 HTML 변환 결과를 각각 복사할 수 있습니다.

공개 문서 원문 (Markdown)

# 대시보드 (`/dashboard`) 진행 상황 · 일일 검토 루틴

**목적**: 대시보드 관련 구현 상태를 한곳에 두고, **매일 업데이트 작업을 시작할 때** 같은 순서로 검토한 뒤 개선을 이어간다.

**연계 문서**: `Projects-Status.md`(프로젝트 전체), `docs/progress-saas-engine.md`(엔진·페이지 진도), `docs/work-log.md`(날짜별 이슈), `docs/dashboard-qa-checklist.md`(시나리오 QA), **`docs/dashboard-workspace-map.md`**(헤더·랜딩·대시보드 공통 5프로젝트·허브 자산 표).

> **경로(Phase 13):** 아래 루틴의 `cd`·`pnpm` 은 **Git 루트 `./`** 에서 실행한다(`cd "$(git rev-parse --show-toplevel)"`).

---

## 1. 현재 구현 스냅샷 (갱신: 2026-04-08)

### 1.1 화면 구성 (`app/dashboard/page.tsx`)

| 영역 | 내용 | 데이터/동작 |
|------|------|-------------|
| 헤더 | 제목, 로그아웃 | `getCurrentUser()` — 미인증 시 `/login?next=/dashboard` |
| 사용량 + 시작하기 | 2열(큰 화면) | `UsageSummarySection` → `GET /api/usage`; `DashboardTimeline` → `buildDashboardTimelineSteps(sub, …)` |
| 환영 카드 (`ShineBorder`) | 이메일, 플랜·상태 한 줄, CTA | `GET /api/subscription` → 플랜/상태/기간 종료 |
| 워크스페이스 프로젝트 | 타임라인 5종 | `workspace-projects-data.ts` — 소개 `href`, 허브 `startHref`, 미리보기 `highlights`(최대 2줄); 컴포넌트 `workspace-projects-timeline.tsx` |
| 구독/플랜 섹션 | 상세 필드, Polar 포털·요금 링크 | 동일 subscription API + `/api/customer-portal` |
| 계정 섹션 | 이메일, id, provider | `AuthUser` |

### 1.2 관련 컴포넌트 (`components/dashboard/`)

- `shine-border.tsx` — 환영 카드 테두리 효과
- `usage-summary-section.tsx` — 월간 채팅 사용량 바·`/api/usage`
- `workspace-projects-timeline.tsx` / `workspace-projects-data.ts` — 모노레포 프로젝트 안내(하이라이트·학습 허브 CTA)
- `dashboard-timeline.tsx` — `DashboardTimeline` + `buildDashboardTimelineSteps` (온보딩 3단계)

### 1.3 백엔드·연동

- `app/api/subscription/route.ts` — 구독 요약
- `app/api/usage/route.ts` — `allowed`, `current`, `limit`, `remaining` (플랜별 한도는 `engine/usage`)
- `app/api/customer-portal/route.ts` — Polar 고객 포털
- Usage/플랜 연동은 `docs/work-log.md`(2026-04-07) 기준으로 채팅 쿼터 등에 반영됨

### 1.4 알려진 이슈·주의 (검토 시 확인)

- Supabase에서 **Google/Kakao Provider 미활성화** 시 로그인 400 가능 — `docs/work-log.md` 2026-04-07. **완화**: `/api/health`의 `auth.oauthProviderHint`를 로그인·대시보드 상단에 표시.
- Polar 고객 포털은 **결제·고객 등록 전** 502 등이 날 수 있음 — 대시보드 카피에 이미 안내
- 구독 API 실패 시 **`hint` 필드**·「다시 불러오기」 버튼. 무료 미구독(`free` / `none`)은 별도 안내 문구.

---

## 2. 매일 대시보드 작업을 시작할 때 (체크리스트)

아래를 **순서대로** 하고, 필요하면 `docs/work-log.md`에 한 줄 기록한다.

1. **상태 문서 읽기**
   - 이 파일 §1 스냅샷이 어제와 맞는지 훑기
   - `Projects-Status.md` §2 진도·추가 구현
2. **로컬 동작**
   - `cd "$(git rev-parse --show-toplevel)" && pnpm check-env` 후 `pnpm dev`
   - 로그인 가능 환경이면 `/dashboard`에서 구독 카드·에러 문구·링크 동작 확인
   - 변경이 있으면 `docs/dashboard-qa-checklist.md`의 A~E 시나리오를 빠르게 점검
3. **빌드·린트 (코드 수정한 날)**
   - `pnpm build`, 변경 파일 기준 `pnpm exec eslint <경로>` (`CLAUDE.md` 마감 체크)
4. **개선 후보 스캔**
   - §3 백로그에서 오늘 할 1~2개만 고르기
5. **문서 동기화**
   - 화면·API·데이터 흐름이 바뀌면 §1과 `docs/progress-saas-engine.md` 해당 표를 같은 날 수정

---

## 3. 대시보드 개선 백로그 (우선순위 제안)

| 우선 | 항목 | 비고 |
|------|------|------|
| ~~P1~~ | ~~OAuth/헬스 이슈 시 대시보드 진입 전 안내~~ | ~~완료~~ 2026-04-08: `oauthProviderHint`, 대시보드 env 경고 |
| ~~P1~~ | ~~구독 API 실패 시 재시도·빈 상태 UX~~ | ~~완료~~ 2026-04-08: 재시도 버튼·`hint`·무료 안내 |
| ~~P2~~ | ~~Usage 요약 위젯 (`/api/usage`)~~ | ~~완료~~ 2026-04-08: `UsageSummarySection` |
| ~~P2~~ | ~~`DashboardTimeline` 활용~~ | ~~완료~~ 2026-04-08: 「시작하기」 섹션; 무료 채팅 문구 정합 |
| ~~P3~~ | ~~Apple 테마 UI 컴포넌트 정렬~~ | ~~완료~~ 2026-04-08: 대시보드/사용량/시작하기/계정 섹션 `Card` 컴포넌트 정렬 |

---

## 4. 갱신 이력

| 일자 | 내용 |
|------|------|
| 2026-04-08 | 초기 작성: 스냅샷·일일 루틴·백로그 정리 |
| 2026-04-08 | P1 구현 반영: 헬스 OAuth 힌트, 대시보드 경고/재시도/무료 상태 |
| 2026-04-08 | P2: 사용량 위젯·온보딩 타임라인 섹션·타임라인 무료 채팅 카피 |
| 2026-04-08 | P3: 섹션형 UI를 `Card`(`CardHeader`/`CardContent`) 중심으로 통일 |

공개 문서 변환 코드 (HTML)

<h1>대시보드 (<code>/dashboard</code>) 진행 상황 · 일일 검토 루틴</h1>
<p><strong>목적</strong>: 대시보드 관련 구현 상태를 한곳에 두고, <strong>매일 업데이트 작업을 시작할 때</strong> 같은 순서로 검토한 뒤 개선을 이어간다.</p>
<p><strong>연계 문서</strong>: <code>Projects-Status.md</code>(프로젝트 전체), <code>docs/progress-saas-engine.md</code>(엔진·페이지 진도), <code>docs/work-log.md</code>(날짜별 이슈), <code>docs/dashboard-qa-checklist.md</code>(시나리오 QA), <strong><code>docs/dashboard-workspace-map.md</code></strong>(헤더·랜딩·대시보드 공통 5프로젝트·허브 자산 표).</p>
<blockquote>
<p><strong>경로(Phase 13):</strong> 아래 루틴의 <code>cd</code>·<code>pnpm</code> 은 <strong>Git 루트 <code>./</code></strong> 에서 실행한다(<code>cd &quot;$(git rev-parse --show-toplevel)&quot;</code>).</p>
</blockquote>
<hr>
<h2>1. 현재 구현 스냅샷 (갱신: 2026-04-08)</h2>
<h3>1.1 화면 구성 (<code>app/dashboard/page.tsx</code>)</h3>
<table>
<thead>
<tr>
<th>영역</th>
<th>내용</th>
<th>데이터/동작</th>
</tr>
</thead>
<tbody><tr>
<td>헤더</td>
<td>제목, 로그아웃</td>
<td><code>getCurrentUser()</code> — 미인증 시 <code>/login?next=/dashboard</code></td>
</tr>
<tr>
<td>사용량 + 시작하기</td>
<td>2열(큰 화면)</td>
<td><code>UsageSummarySection</code> → <code>GET /api/usage</code>; <code>DashboardTimeline</code> → <code>buildDashboardTimelineSteps(sub, …)</code></td>
</tr>
<tr>
<td>환영 카드 (<code>ShineBorder</code>)</td>
<td>이메일, 플랜·상태 한 줄, CTA</td>
<td><code>GET /api/subscription</code> → 플랜/상태/기간 종료</td>
</tr>
<tr>
<td>워크스페이스 프로젝트</td>
<td>타임라인 5종</td>
<td><code>workspace-projects-data.ts</code> — 소개 <code>href</code>, 허브 <code>startHref</code>, 미리보기 <code>highlights</code>(최대 2줄); 컴포넌트 <code>workspace-projects-timeline.tsx</code></td>
</tr>
<tr>
<td>구독/플랜 섹션</td>
<td>상세 필드, Polar 포털·요금 링크</td>
<td>동일 subscription API + <code>/api/customer-portal</code></td>
</tr>
<tr>
<td>계정 섹션</td>
<td>이메일, id, provider</td>
<td><code>AuthUser</code></td>
</tr>
</tbody></table>
<h3>1.2 관련 컴포넌트 (<code>components/dashboard/</code>)</h3>
<ul>
<li><code>shine-border.tsx</code> — 환영 카드 테두리 효과</li>
<li><code>usage-summary-section.tsx</code> — 월간 채팅 사용량 바·<code>/api/usage</code></li>
<li><code>workspace-projects-timeline.tsx</code> / <code>workspace-projects-data.ts</code> — 모노레포 프로젝트 안내(하이라이트·학습 허브 CTA)</li>
<li><code>dashboard-timeline.tsx</code> — <code>DashboardTimeline</code> + <code>buildDashboardTimelineSteps</code> (온보딩 3단계)</li>
</ul>
<h3>1.3 백엔드·연동</h3>
<ul>
<li><code>app/api/subscription/route.ts</code> — 구독 요약</li>
<li><code>app/api/usage/route.ts</code> — <code>allowed</code>, <code>current</code>, <code>limit</code>, <code>remaining</code> (플랜별 한도는 <code>engine/usage</code>)</li>
<li><code>app/api/customer-portal/route.ts</code> — Polar 고객 포털</li>
<li>Usage/플랜 연동은 <code>docs/work-log.md</code>(2026-04-07) 기준으로 채팅 쿼터 등에 반영됨</li>
</ul>
<h3>1.4 알려진 이슈·주의 (검토 시 확인)</h3>
<ul>
<li>Supabase에서 <strong>Google/Kakao Provider 미활성화</strong> 시 로그인 400 가능 — <code>docs/work-log.md</code> 2026-04-07. <strong>완화</strong>: <code>/api/health</code>의 <code>auth.oauthProviderHint</code>를 로그인·대시보드 상단에 표시.</li>
<li>Polar 고객 포털은 <strong>결제·고객 등록 전</strong> 502 등이 날 수 있음 — 대시보드 카피에 이미 안내</li>
<li>구독 API 실패 시 <strong><code>hint</code> 필드</strong>·「다시 불러오기」 버튼. 무료 미구독(<code>free</code> / <code>none</code>)은 별도 안내 문구.</li>
</ul>
<hr>
<h2>2. 매일 대시보드 작업을 시작할 때 (체크리스트)</h2>
<p>아래를 <strong>순서대로</strong> 하고, 필요하면 <code>docs/work-log.md</code>에 한 줄 기록한다.</p>
<ol>
<li><strong>상태 문서 읽기</strong><ul>
<li>이 파일 §1 스냅샷이 어제와 맞는지 훑기</li>
<li><code>Projects-Status.md</code> §2 진도·추가 구현</li>
</ul>
</li>
<li><strong>로컬 동작</strong><ul>
<li><code>cd &quot;$(git rev-parse --show-toplevel)&quot; &amp;&amp; pnpm check-env</code> 후 <code>pnpm dev</code></li>
<li>로그인 가능 환경이면 <code>/dashboard</code>에서 구독 카드·에러 문구·링크 동작 확인</li>
<li>변경이 있으면 <code>docs/dashboard-qa-checklist.md</code>의 A~E 시나리오를 빠르게 점검</li>
</ul>
</li>
<li><strong>빌드·린트 (코드 수정한 날)</strong><ul>
<li><code>pnpm build</code>, 변경 파일 기준 <code>pnpm exec eslint &lt;경로&gt;</code> (<code>CLAUDE.md</code> 마감 체크)</li>
</ul>
</li>
<li><strong>개선 후보 스캔</strong><ul>
<li>§3 백로그에서 오늘 할 1~2개만 고르기</li>
</ul>
</li>
<li><strong>문서 동기화</strong><ul>
<li>화면·API·데이터 흐름이 바뀌면 §1과 <code>docs/progress-saas-engine.md</code> 해당 표를 같은 날 수정</li>
</ul>
</li>
</ol>
<hr>
<h2>3. 대시보드 개선 백로그 (우선순위 제안)</h2>
<table>
<thead>
<tr>
<th>우선</th>
<th>항목</th>
<th>비고</th>
</tr>
</thead>
<tbody><tr>
<td><del>P1</del></td>
<td><del>OAuth/헬스 이슈 시 대시보드 진입 전 안내</del></td>
<td><del>완료</del> 2026-04-08: <code>oauthProviderHint</code>, 대시보드 env 경고</td>
</tr>
<tr>
<td><del>P1</del></td>
<td><del>구독 API 실패 시 재시도·빈 상태 UX</del></td>
<td><del>완료</del> 2026-04-08: 재시도 버튼·<code>hint</code>·무료 안내</td>
</tr>
<tr>
<td><del>P2</del></td>
<td><del>Usage 요약 위젯 (<code>/api/usage</code>)</del></td>
<td><del>완료</del> 2026-04-08: <code>UsageSummarySection</code></td>
</tr>
<tr>
<td><del>P2</del></td>
<td><del><code>DashboardTimeline</code> 활용</del></td>
<td><del>완료</del> 2026-04-08: 「시작하기」 섹션; 무료 채팅 문구 정합</td>
</tr>
<tr>
<td><del>P3</del></td>
<td><del>Apple 테마 UI 컴포넌트 정렬</del></td>
<td><del>완료</del> 2026-04-08: 대시보드/사용량/시작하기/계정 섹션 <code>Card</code> 컴포넌트 정렬</td>
</tr>
</tbody></table>
<hr>
<h2>4. 갱신 이력</h2>
<table>
<thead>
<tr>
<th>일자</th>
<th>내용</th>
</tr>
</thead>
<tbody><tr>
<td>2026-04-08</td>
<td>초기 작성: 스냅샷·일일 루틴·백로그 정리</td>
</tr>
<tr>
<td>2026-04-08</td>
<td>P1 구현 반영: 헬스 OAuth 힌트, 대시보드 경고/재시도/무료 상태</td>
</tr>
<tr>
<td>2026-04-08</td>
<td>P2: 사용량 위젯·온보딩 타임라인 섹션·타임라인 무료 채팅 카피</td>
</tr>
<tr>
<td>2026-04-08</td>
<td>P3: 섹션형 UI를 <code>Card</code>(<code>CardHeader</code>/<code>CardContent</code>) 중심으로 통일</td>
</tr>
</tbody></table>