Projects-Status.md

# Projects-Status — saas-engine

> 최초 작성일: 2026-03-21 · 마지막 갱신: 2026-04-08

---

## 다음에 프로젝트 시작할 때 (먼저 읽기)

1. **작업 디렉터리**: 반드시 **이 저장소의 Git 루트(`CLAUDE/projects/openclaw`)** 에서 명령 실행. 상위 워크스페이스 루트 `CLAUDE/`만 열려 있으면 이 앱의 `package.json`이 없어 `pnpm dev`가 실패할 수 있음.
2. **개발 서버**: 저장소 루트에서 `pnpm dev` → http://localhost:3000
3. **환경 점검**: `pnpm check-env` — 필수 키(`POLAR_*`, `SUPABASE_*`, `NEXT_PUBLIC_APP_URL` 등) 비어 있으면 여기서 멈춤.
4. **Polar 웹훅**: 엔드포인트 `POST /api/webhooks/polar` (`app/api/webhooks/polar/route.ts`). 로컬 `.env.local`에 **`POLAR_WEBHOOK_SECRET`** 이 채워져 있음(값은 Git에 넣지 말 것). Polar 대시보드의 Webhook URL은 **실제 공개 URL**(ngrok·Vercel 등) + `/api/webhooks/polar` — 터널/도메인이 바뀌면 대시보드에서 URL 재등록.
5. **상세 이력·운영 순서**: `docs/progress-saas-engine.md`, `docs/operational-order.md`
6. **대시보드 (`/dashboard`) 일일 업데이트**: **`docs/dashboard-update-routine.md`** — 작업 시작 시 §2 체크리스트로 진행 상황 검토 후 §3 백로그에서 개선 항목 선택.
7. **대시보드 시나리오 QA**: **`docs/dashboard-qa-checklist.md`** — 무료/유료/오류/링크 동작 회귀 점검.
8. **메인메뉴 서브페이지 작업 전 필수 참조**: **`docs/hub-template-standard.md`** — 소개(1번)·허브(2번) 템플릿 구조/체크리스트를 반드시 먼저 확인.
9. **구조화·개선 순차 플랜**: **`docs/structure-improvement-plan.md`** — 문서 정렬(Phase 1) → **대시보드 중심 5프로젝트·허브 맵(Phase 2)** → 엔진 이관(3) → `apps/*` 전략(4) → 품질·운영(5). 상세 표: **`docs/dashboard-workspace-map.md`**.

---

## 0. 대시보드 진행 요약 (빠른 참고)

- **구현됨**: 환영 카드(구독 요약), 워크스페이스 프로젝트 타임라인, 구독/플랜 상세, Polar 고객 포털·요금 링크, 계정 정보, AI 채팅·로그아웃.
- **API**: `GET /api/subscription`, 고객 포털 라우트, (앱 전반) usage·플랜 연동은 `docs/work-log.md` 참고.
- **매일**: `docs/dashboard-update-routine.md`의 체크리스트 + `docs/dashboard-qa-checklist.md` A~E 시나리오 점검 → 필요 시 §1 스냅샷·`docs/progress-saas-engine.md` 동기화.

---

## 1. 한눈에 요약 (10줄 이내)

1. Next.js(루트) SaaS 엔진 + 데모 앱 — **실서비스 구현과 강의용 튜토리얼**을 함께 가져감.
2. **engine/**: `auth`·`usage` 구현; **Polar 결제·웹훅·`subscriptions` 테이블** 연동됨(환경·Supabase 마이그레이션 적용 전제).
3. **features/**: `gemini-chat` 구현, `image-generator`·`automation`은 스캐폴드.
4. Supabase(OAuth), 미들웨어 보호 라우트.
5. 결제: `GET /api/checkout` → Polar Checkout, `POST /api/webhooks/polar` → `public.subscriptions` upsert.
6. `/pricing`·`/checkout`에서 Polar 결제 버튼; `/checkout/success` 완료 안내.
7. `.env.local`: `POLAR_ACCESS_TOKEN`, **`POLAR_WEBHOOK_SECRET`**, `POLAR_PRODUCT_ID_PRO`, `SUPABASE_SERVICE_ROLE_KEY`, `NEXT_PUBLIC_APP_URL` 등 — `pnpm check-env`로 검증.
8. **2026-03-21**: `POLAR_WEBHOOK_SECRET` 로컬 반영 후 `pnpm check-env` 통과. 채팅에 시크릿 노출 이력 있으면 Polar에서 시크릿 로테이션 권장.
9. 상세: `docs/progress-saas-engine.md`, Notion: `docs/reference/notion-saas.md`.
10. 운영 순서: `docs/operational-order.md`

---

## 2. 목적 · 진도 · 추가 구현 (확정)

| 구분 | 내용 |
|------|------|
| **목적** | 실서비스를 구현하면서 그 내용을 **강의용 튜토리얼**로 남긴다. |

### 진도

1. **로그인·인증** 완료 — Supabase OAuth, `public.users`, 미들웨어 보호 라우트.
2. **Polar 결제·웹훅·`subscriptions` DB** 연동 코드 반영; 로컬 `.env`에서 웹훅 시크릿·`pnpm check-env`까지 완료.
3. **실제 결제/웹훅 E2E** — 공개 URL·Polar 대시보드 Webhook URL 등록 후 검증하면 됨.

### 추가 구현

1. 플랜별 **usage**를 대시보드에 **표시**(API는 확장됨 — `docs/work-log.md` 2026-04-07).
2. **Customer Portal**·구독 관리 UX 다듬기(에러·빈 상태·재시도).
3. **프로덕션 배포**·강의/튜토리얼 문서 정리.

### 대시보드 전용

- 상세·일일 루틴: **`docs/dashboard-update-routine.md`**

---

## 3. 질문 · 답변 기록

### Q1. 이 프로젝트의 목적은 무엇인가요?

**답변:** 실서비스를 구현하면서, 그 내용을 강의용 튜토리얼로 만든다.

---

### Q2. 이 프로젝트는 진도가 어디까지 나갔나요?

**답변:** 로그인·인증 완료. Polar 결제 플로우·웹훅·Supabase `subscriptions` 연동 코드 반영. 로컬 `.env`에서 `POLAR_WEBHOOK_SECRET` 포함 필수 키 설정 및 `pnpm check-env` 통과(2026-03-21).

---

### Q3. 이번에 추가로 구현하거나 손보고 싶은 내용·기능은 무엇인가요?

**답변:** 결제까지 완료하는 것.

---

## 4. 위 표(목적·진도) 반영 요약

| 구분 | 내용 |
|------|------|
| **목적** | 실서비스 + 강의 튜토리얼 병행 |
| **진도** | (1) 인증 (2) Polar·웹훅·DB·env (3) E2E는 공개 URL·대시보드 후 |
| **추가 구현** | (1) usage (2) 포털 (3) 배포·문서 |

<h1>Projects-Status — saas-engine</h1>
<blockquote>
<p>최초 작성일: 2026-03-21 · 마지막 갱신: 2026-04-08</p>
</blockquote>
<hr>
<h2>다음에 프로젝트 시작할 때 (먼저 읽기)</h2>
<ol>
<li><strong>작업 디렉터리</strong>: 반드시 <strong>이 저장소의 Git 루트(<code>CLAUDE/projects/openclaw</code>)</strong> 에서 명령 실행. 상위 워크스페이스 루트 <code>CLAUDE/</code>만 열려 있으면 이 앱의 <code>package.json</code>이 없어 <code>pnpm dev</code>가 실패할 수 있음.</li>
<li><strong>개발 서버</strong>: 저장소 루트에서 <code>pnpm dev</code> → <a href="http://localhost:3000">http://localhost:3000</a></li>
<li><strong>환경 점검</strong>: <code>pnpm check-env</code> — 필수 키(<code>POLAR_*</code>, <code>SUPABASE_*</code>, <code>NEXT_PUBLIC_APP_URL</code> 등) 비어 있으면 여기서 멈춤.</li>
<li><strong>Polar 웹훅</strong>: 엔드포인트 <code>POST /api/webhooks/polar</code> (<code>app/api/webhooks/polar/route.ts</code>). 로컬 <code>.env.local</code>에 <strong><code>POLAR_WEBHOOK_SECRET</code></strong> 이 채워져 있음(값은 Git에 넣지 말 것). Polar 대시보드의 Webhook URL은 <strong>실제 공개 URL</strong>(ngrok·Vercel 등) + <code>/api/webhooks/polar</code> — 터널/도메인이 바뀌면 대시보드에서 URL 재등록.</li>
<li><strong>상세 이력·운영 순서</strong>: <code>docs/progress-saas-engine.md</code>, <code>docs/operational-order.md</code></li>
<li><strong>대시보드 (<code>/dashboard</code>) 일일 업데이트</strong>: <strong><code>docs/dashboard-update-routine.md</code></strong> — 작업 시작 시 §2 체크리스트로 진행 상황 검토 후 §3 백로그에서 개선 항목 선택.</li>
<li><strong>대시보드 시나리오 QA</strong>: <strong><code>docs/dashboard-qa-checklist.md</code></strong> — 무료/유료/오류/링크 동작 회귀 점검.</li>
<li><strong>메인메뉴 서브페이지 작업 전 필수 참조</strong>: <strong><code>docs/hub-template-standard.md</code></strong> — 소개(1번)·허브(2번) 템플릿 구조/체크리스트를 반드시 먼저 확인.</li>
<li><strong>구조화·개선 순차 플랜</strong>: <strong><code>docs/structure-improvement-plan.md</code></strong> — 문서 정렬(Phase 1) → <strong>대시보드 중심 5프로젝트·허브 맵(Phase 2)</strong> → 엔진 이관(3) → <code>apps/*</code> 전략(4) → 품질·운영(5). 상세 표: <strong><code>docs/dashboard-workspace-map.md</code></strong>.</li>
</ol>
<hr>
<h2>0. 대시보드 진행 요약 (빠른 참고)</h2>
<ul>
<li><strong>구현됨</strong>: 환영 카드(구독 요약), 워크스페이스 프로젝트 타임라인, 구독/플랜 상세, Polar 고객 포털·요금 링크, 계정 정보, AI 채팅·로그아웃.</li>
<li><strong>API</strong>: <code>GET /api/subscription</code>, 고객 포털 라우트, (앱 전반) usage·플랜 연동은 <code>docs/work-log.md</code> 참고.</li>
<li><strong>매일</strong>: <code>docs/dashboard-update-routine.md</code>의 체크리스트 + <code>docs/dashboard-qa-checklist.md</code> A~E 시나리오 점검 → 필요 시 §1 스냅샷·<code>docs/progress-saas-engine.md</code> 동기화.</li>
</ul>
<hr>
<h2>1. 한눈에 요약 (10줄 이내)</h2>
<ol>
<li>Next.js(루트) SaaS 엔진 + 데모 앱 — <strong>실서비스 구현과 강의용 튜토리얼</strong>을 함께 가져감.</li>
<li><strong>engine/</strong>: <code>auth</code>·<code>usage</code> 구현; <strong>Polar 결제·웹훅·<code>subscriptions</code> 테이블</strong> 연동됨(환경·Supabase 마이그레이션 적용 전제).</li>
<li><strong>features/</strong>: <code>gemini-chat</code> 구현, <code>image-generator</code>·<code>automation</code>은 스캐폴드.</li>
<li>Supabase(OAuth), 미들웨어 보호 라우트.</li>
<li>결제: <code>GET /api/checkout</code> → Polar Checkout, <code>POST /api/webhooks/polar</code> → <code>public.subscriptions</code> upsert.</li>
<li><code>/pricing</code>·<code>/checkout</code>에서 Polar 결제 버튼; <code>/checkout/success</code> 완료 안내.</li>
<li><code>.env.local</code>: <code>POLAR_ACCESS_TOKEN</code>, <strong><code>POLAR_WEBHOOK_SECRET</code></strong>, <code>POLAR_PRODUCT_ID_PRO</code>, <code>SUPABASE_SERVICE_ROLE_KEY</code>, <code>NEXT_PUBLIC_APP_URL</code> 등 — <code>pnpm check-env</code>로 검증.</li>
<li><strong>2026-03-21</strong>: <code>POLAR_WEBHOOK_SECRET</code> 로컬 반영 후 <code>pnpm check-env</code> 통과. 채팅에 시크릿 노출 이력 있으면 Polar에서 시크릿 로테이션 권장.</li>
<li>상세: <code>docs/progress-saas-engine.md</code>, Notion: <code>docs/reference/notion-saas.md</code>.</li>
<li>운영 순서: <code>docs/operational-order.md</code></li>
</ol>
<hr>
<h2>2. 목적 · 진도 · 추가 구현 (확정)</h2>
<table>
<thead>
<tr>
<th>구분</th>
<th>내용</th>
</tr>
</thead>
<tbody><tr>
<td><strong>목적</strong></td>
<td>실서비스를 구현하면서 그 내용을 <strong>강의용 튜토리얼</strong>로 남긴다.</td>
</tr>
</tbody></table>
<h3>진도</h3>
<ol>
<li><strong>로그인·인증</strong> 완료 — Supabase OAuth, <code>public.users</code>, 미들웨어 보호 라우트.</li>
<li><strong>Polar 결제·웹훅·<code>subscriptions</code> DB</strong> 연동 코드 반영; 로컬 <code>.env</code>에서 웹훅 시크릿·<code>pnpm check-env</code>까지 완료.</li>
<li><strong>실제 결제/웹훅 E2E</strong> — 공개 URL·Polar 대시보드 Webhook URL 등록 후 검증하면 됨.</li>
</ol>
<h3>추가 구현</h3>
<ol>
<li>플랜별 <strong>usage</strong>를 대시보드에 <strong>표시</strong>(API는 확장됨 — <code>docs/work-log.md</code> 2026-04-07).</li>
<li><strong>Customer Portal</strong>·구독 관리 UX 다듬기(에러·빈 상태·재시도).</li>
<li><strong>프로덕션 배포</strong>·강의/튜토리얼 문서 정리.</li>
</ol>
<h3>대시보드 전용</h3>
<ul>
<li>상세·일일 루틴: <strong><code>docs/dashboard-update-routine.md</code></strong></li>
</ul>
<hr>
<h2>3. 질문 · 답변 기록</h2>
<h3>Q1. 이 프로젝트의 목적은 무엇인가요?</h3>
<p><strong>답변:</strong> 실서비스를 구현하면서, 그 내용을 강의용 튜토리얼로 만든다.</p>
<hr>
<h3>Q2. 이 프로젝트는 진도가 어디까지 나갔나요?</h3>
<p><strong>답변:</strong> 로그인·인증 완료. Polar 결제 플로우·웹훅·Supabase <code>subscriptions</code> 연동 코드 반영. 로컬 <code>.env</code>에서 <code>POLAR_WEBHOOK_SECRET</code> 포함 필수 키 설정 및 <code>pnpm check-env</code> 통과(2026-03-21).</p>
<hr>
<h3>Q3. 이번에 추가로 구현하거나 손보고 싶은 내용·기능은 무엇인가요?</h3>
<p><strong>답변:</strong> 결제까지 완료하는 것.</p>
<hr>
<h2>4. 위 표(목적·진도) 반영 요약</h2>
<table>
<thead>
<tr>
<th>구분</th>
<th>내용</th>
</tr>
</thead>
<tbody><tr>
<td><strong>목적</strong></td>
<td>실서비스 + 강의 튜토리얼 병행</td>
</tr>
<tr>
<td><strong>진도</strong></td>
<td>(1) 인증 (2) Polar·웹훅·DB·env (3) E2E는 공개 URL·대시보드 후</td>
</tr>
<tr>
<td><strong>추가 구현</strong></td>
<td>(1) usage (2) 포털 (3) 배포·문서</td>
</tr>
</tbody></table>