구조 개선

# saas-engine 구조화·개선 플랜

**작성**: 2026-04-09 · **Phase 1 문서·경로 정합성 재점검**: 2026-04-09 (`pnpm build` 통과)  
**범위**: **Git 루트 `./`** (루트 Next.js + `engine/` + `features/` + `apps/`; *상위 워크스페이스 관례·과거 표기: `CLAUDE/projects/openclaw`*)  
**참조**: `CLAUDE.md`, `docs/design-saas-engine.md`, `docs/progress-saas-engine.md`, `Projects-Status.md`

---

## 0. 현황 진단 (요약)

| 영역 | 상태 | 비고 |
|------|------|------|
| **경로** | 단일 진실: **Git 루트 `./`** *(과거 표기 `CLAUDE/projects/openclaw` 병기)* | Phase 1에서 루트 `CLAUDE.md`·`CLAUDE/projects/README.md`(형제)·`index.md`·스크립트 예시·`.project-progress-focus`를 **`.` 기준**에 맞춤 *(당시 문서는 `CLAUDE/projects/openclaw` 경로로 서술)* |
| **레이어** | `engine/auth`·`engine/usage` 실구현 | `engine/billing`·`engine/subscription`은 스캐폴드; Polar·구독은 `lib/polar*.ts`, `app/api/*` |
| **기능** | `features/gemini-chat` 실구현 | `image-generator`, `automation` 스캐폴드 |
| **앱** | 루트 앱이 배포 단위 | `apps/gemini-saas`는 별도 패키지(Phase 4에서 전략 정리) |
| **허브·정적 라우트** | 5프로젝트 맵 고정 | `docs/dashboard-workspace-map.md` + `hub-template-standard` 부록 |
| **문서 정합성** | Phase 1 완료 후 | `workspace-structure`·`engine/README`·`design` §3.1 엔진 표 동기화 유지 |

---

## 1. 목표

1. **단일 진실 공급원**: 설계(`design`)·진도(`progress`)·워크스페이스 구조 문서·엔진 README가 같은 사실을 말한다.  
2. **명확한 경계**: 결제/구독/사용량 코드가 `engine/*` vs `lib/*` vs `app/api/*` 중 어디가 “소유”인지 단계적으로 정리한다.  
3. **확장 준비**: `features/*`, `apps/*` 추가 시 따를 규칙과 체크리스트가 문서에 있다.  
4. **대시보드 중심 UX**: 상단 헤더 메인메뉴와 `/dashboard` 의 **워크스페이스 프로젝트 5종**은 동일 데이터(`workspaceProjectTimeline`)에서 나온다. 구조·허브·문서 작업은 **대시보드에서 사용자가 보는 맥락을 더 구체화**하는 방향(링크 완결성, 향후 상태·배지·CTA)과 정렬한다.

---

## 2. 단계별 플랜 (순서 고정)

### Phase 1 — 문서·진실 공급원 정렬 (우선)

- [x] 본 플랜 문서 추가 (`docs/structure-improvement-plan.md`)
- [x] `docs/workspace-structure.md` 갱신: 실제 폴더명(`saas-engine`), `auth`·`usage`·앱 수준 Polar/구독 반영
- [x] `engine/README.md` 갱신: 모듈별 실제 상태·진입 파일 포인터
- [x] 워크스페이스 루트 `index.md`의 saas-engine 문서 경로를 `./docs/` 기준으로 수정 *(당시 완료 표기: `CLAUDE/projects/openclaw/docs/`)*

**완료 기준**: `design-saas-engine.md` / `progress-saas-engine.md`와 모순되는 문장이 `workspace-structure`·`engine/README`에 없음.

---

### Phase 2 — 대시보드 중심: 5개 프로젝트·허브·정적 라우트 맵

**전제**: 메인메뉴·랜딩·`/dashboard` 워크스페이스 구역은 **`components/dashboard/workspace-projects-data.ts`** 한 소스에서 5개 프로젝트를 공유한다. Phase 2는 이 축을 문서로 고정하고, 허브 자산 추가 절차를 **대시보드 가시성**과 연동한다.

- [x] **`docs/dashboard-workspace-map.md`** — 5프로젝트 표(소개·허브·컴포넌트·`lib/*-hub-index`·`*-files` 라우트), 데이터 흐름, “대시보드 구체화” 원칙
- [x] **`docs/hub-template-standard.md`** — 부록 A(맵 참조·대시보드와의 관계), 부록 B(정적 `*-files` 라우트 추가 절차)
- [x] **`docs/workspace-structure.md`** — 대시보드 맵으로의 링크
- [x] **`WorkspaceProjectsTimeline` / `WorkspaceProjectsTimelineSection`** — `highlights` 최대 2줄 미리보기, `startHref`「학습 허브」CTA, 섹션 카피(소개 vs 허브 역할 구분)

**완료 기준 (문서+UI)**: 새 프로젝트를 메뉴·대시보드에 올릴 때 `dashboard-workspace-map.md` 표 + `hub-template-standard` 체크리스트만으로 자산을 빠짐없이 나열할 수 있음. **온보딩 타임라인**(`buildDashboardTimelineSteps`)과 **워크스페이스 5종**의 역할이 맵·대시보드 카피에서 구분되어 있음.

---

### Phase 3 — 엔진으로의 점진 이관 (billing / subscription)

- [ ] `lib/polar.ts`, `lib/polar-subscription-sync.ts`의 공개 API를 식별
- [ ] `engine/billing`에서 Polar 클라이언트·체크아웃 헬퍼 래핑(얇은 레이어부터)
- [ ] `engine/subscription`에서 구독 조회·동기화 헬퍼 래핑; `app/api/subscription`, 웹훅은 엔진 호출로 위임
- [ ] `@/lib/*` re-export로 기존 import 깨짐 최소화

**완료 기준**: 결제·구독 관련 단위 테스트 또는 최소한 `pnpm build` + 수동 Polar 플로우 회귀(체크리스트) 통과.

---

### Phase 4 — `apps/gemini-saas` 모노레포 전략

- [ ] 루트 `package.json` vs `apps/gemini-saas/package.json` 의존성·버전 비교
- [ ] 선택지 문서화: (A) 실험용으로 유지 + README에 “동기화 안 함” 명시 (B) pnpm workspace로 승격 (C) 제거/아카이브

**완료 기준**: README에 채택한 전략 한 단락 + 유지보수 책임이 명확함.

---

### Phase 5 — 품질·운영

- [ ] `pnpm lint` / `pnpm build` CI(선택: GitHub Actions) 최소 파이프라인
- [ ] `Projects-Status.md` §2와 본 플랜 Phase 체크박스 주기적 동기화
- [ ] Polar E2E·Vercel 배포: `docs/operational-order.md`·`Projects-Status`에 있는 항목과 통합

---

## 3. 진행 방식

- 한 번에 한 Phase만 “완료”로 친다. Phase 1 완료 후 사용자/에이전트가 Phase 2 착수.
- 코드 변경이 있는 Phase는 **반드시** `pnpm build` 및 관련 API 수동 확인.
- 시크릿·`.env`는 `env-secrets-security` 규칙 준수.

---

## 4. 참조

- 설계: `docs/design-saas-engine.md`
- 진도: `docs/progress-saas-engine.md`
- 허브 표준: `docs/hub-template-standard.md`
- 일일 루틴: `docs/dashboard-update-routine.md`
- 대시보드·5프로젝트 맵: `docs/dashboard-workspace-map.md`

<h1>saas-engine 구조화·개선 플랜</h1>
<p><strong>작성</strong>: 2026-04-09 · <strong>Phase 1 문서·경로 정합성 재점검</strong>: 2026-04-09 (<code>pnpm build</code> 통과)<br><strong>범위</strong>: <strong>Git 루트 <code>./</code></strong> (루트 Next.js + <code>engine/</code> + <code>features/</code> + <code>apps/</code>; <em>상위 워크스페이스 관례·과거 표기: <code>CLAUDE/projects/openclaw</code></em>)<br><strong>참조</strong>: <code>CLAUDE.md</code>, <code>docs/design-saas-engine.md</code>, <code>docs/progress-saas-engine.md</code>, <code>Projects-Status.md</code></p>
<hr>
<h2>0. 현황 진단 (요약)</h2>
<table>
<thead>
<tr>
<th>영역</th>
<th>상태</th>
<th>비고</th>
</tr>
</thead>
<tbody><tr>
<td><strong>경로</strong></td>
<td>단일 진실: <strong>Git 루트 <code>./</code></strong> <em>(과거 표기 <code>CLAUDE/projects/openclaw</code> 병기)</em></td>
<td>Phase 1에서 루트 <code>CLAUDE.md</code>·<code>CLAUDE/projects/README.md</code>(형제)·<code>index.md</code>·스크립트 예시·<code>.project-progress-focus</code>를 <strong><code>.</code> 기준</strong>에 맞춤 <em>(당시 문서는 <code>CLAUDE/projects/openclaw</code> 경로로 서술)</em></td>
</tr>
<tr>
<td><strong>레이어</strong></td>
<td><code>engine/auth</code>·<code>engine/usage</code> 실구현</td>
<td><code>engine/billing</code>·<code>engine/subscription</code>은 스캐폴드; Polar·구독은 <code>lib/polar*.ts</code>, <code>app/api/*</code></td>
</tr>
<tr>
<td><strong>기능</strong></td>
<td><code>features/gemini-chat</code> 실구현</td>
<td><code>image-generator</code>, <code>automation</code> 스캐폴드</td>
</tr>
<tr>
<td><strong>앱</strong></td>
<td>루트 앱이 배포 단위</td>
<td><code>apps/gemini-saas</code>는 별도 패키지(Phase 4에서 전략 정리)</td>
</tr>
<tr>
<td><strong>허브·정적 라우트</strong></td>
<td>5프로젝트 맵 고정</td>
<td><code>docs/dashboard-workspace-map.md</code> + <code>hub-template-standard</code> 부록</td>
</tr>
<tr>
<td><strong>문서 정합성</strong></td>
<td>Phase 1 완료 후</td>
<td><code>workspace-structure</code>·<code>engine/README</code>·<code>design</code> §3.1 엔진 표 동기화 유지</td>
</tr>
</tbody></table>
<hr>
<h2>1. 목표</h2>
<ol>
<li><strong>단일 진실 공급원</strong>: 설계(<code>design</code>)·진도(<code>progress</code>)·워크스페이스 구조 문서·엔진 README가 같은 사실을 말한다.  </li>
<li><strong>명확한 경계</strong>: 결제/구독/사용량 코드가 <code>engine/*</code> vs <code>lib/*</code> vs <code>app/api/*</code> 중 어디가 “소유”인지 단계적으로 정리한다.  </li>
<li><strong>확장 준비</strong>: <code>features/*</code>, <code>apps/*</code> 추가 시 따를 규칙과 체크리스트가 문서에 있다.  </li>
<li><strong>대시보드 중심 UX</strong>: 상단 헤더 메인메뉴와 <code>/dashboard</code> 의 <strong>워크스페이스 프로젝트 5종</strong>은 동일 데이터(<code>workspaceProjectTimeline</code>)에서 나온다. 구조·허브·문서 작업은 <strong>대시보드에서 사용자가 보는 맥락을 더 구체화</strong>하는 방향(링크 완결성, 향후 상태·배지·CTA)과 정렬한다.</li>
</ol>
<hr>
<h2>2. 단계별 플랜 (순서 고정)</h2>
<h3>Phase 1 — 문서·진실 공급원 정렬 (우선)</h3>
<ul>
<li><input checked="" disabled="" type="checkbox"> 본 플랜 문서 추가 (<code>docs/structure-improvement-plan.md</code>)</li>
<li><input checked="" disabled="" type="checkbox"> <code>docs/workspace-structure.md</code> 갱신: 실제 폴더명(<code>saas-engine</code>), <code>auth</code>·<code>usage</code>·앱 수준 Polar/구독 반영</li>
<li><input checked="" disabled="" type="checkbox"> <code>engine/README.md</code> 갱신: 모듈별 실제 상태·진입 파일 포인터</li>
<li><input checked="" disabled="" type="checkbox"> 워크스페이스 루트 <code>index.md</code>의 saas-engine 문서 경로를 <code>./docs/</code> 기준으로 수정 <em>(당시 완료 표기: <code>CLAUDE/projects/openclaw/docs/</code>)</em></li>
</ul>
<p><strong>완료 기준</strong>: <code>design-saas-engine.md</code> / <code>progress-saas-engine.md</code>와 모순되는 문장이 <code>workspace-structure</code>·<code>engine/README</code>에 없음.</p>
<hr>
<h3>Phase 2 — 대시보드 중심: 5개 프로젝트·허브·정적 라우트 맵</h3>
<p><strong>전제</strong>: 메인메뉴·랜딩·<code>/dashboard</code> 워크스페이스 구역은 <strong><code>components/dashboard/workspace-projects-data.ts</code></strong> 한 소스에서 5개 프로젝트를 공유한다. Phase 2는 이 축을 문서로 고정하고, 허브 자산 추가 절차를 <strong>대시보드 가시성</strong>과 연동한다.</p>
<ul>
<li><input checked="" disabled="" type="checkbox"> <strong><code>docs/dashboard-workspace-map.md</code></strong> — 5프로젝트 표(소개·허브·컴포넌트·<code>lib/*-hub-index</code>·<code>*-files</code> 라우트), 데이터 흐름, “대시보드 구체화” 원칙</li>
<li><input checked="" disabled="" type="checkbox"> <strong><code>docs/hub-template-standard.md</code></strong> — 부록 A(맵 참조·대시보드와의 관계), 부록 B(정적 <code>*-files</code> 라우트 추가 절차)</li>
<li><input checked="" disabled="" type="checkbox"> <strong><code>docs/workspace-structure.md</code></strong> — 대시보드 맵으로의 링크</li>
<li><input checked="" disabled="" type="checkbox"> <strong><code>WorkspaceProjectsTimeline</code> / <code>WorkspaceProjectsTimelineSection</code></strong> — <code>highlights</code> 최대 2줄 미리보기, <code>startHref</code>「학습 허브」CTA, 섹션 카피(소개 vs 허브 역할 구분)</li>
</ul>
<p><strong>완료 기준 (문서+UI)</strong>: 새 프로젝트를 메뉴·대시보드에 올릴 때 <code>dashboard-workspace-map.md</code> 표 + <code>hub-template-standard</code> 체크리스트만으로 자산을 빠짐없이 나열할 수 있음. <strong>온보딩 타임라인</strong>(<code>buildDashboardTimelineSteps</code>)과 <strong>워크스페이스 5종</strong>의 역할이 맵·대시보드 카피에서 구분되어 있음.</p>
<hr>
<h3>Phase 3 — 엔진으로의 점진 이관 (billing / subscription)</h3>
<ul>
<li><input disabled="" type="checkbox"> <code>lib/polar.ts</code>, <code>lib/polar-subscription-sync.ts</code>의 공개 API를 식별</li>
<li><input disabled="" type="checkbox"> <code>engine/billing</code>에서 Polar 클라이언트·체크아웃 헬퍼 래핑(얇은 레이어부터)</li>
<li><input disabled="" type="checkbox"> <code>engine/subscription</code>에서 구독 조회·동기화 헬퍼 래핑; <code>app/api/subscription</code>, 웹훅은 엔진 호출로 위임</li>
<li><input disabled="" type="checkbox"> <code>@/lib/*</code> re-export로 기존 import 깨짐 최소화</li>
</ul>
<p><strong>완료 기준</strong>: 결제·구독 관련 단위 테스트 또는 최소한 <code>pnpm build</code> + 수동 Polar 플로우 회귀(체크리스트) 통과.</p>
<hr>
<h3>Phase 4 — <code>apps/gemini-saas</code> 모노레포 전략</h3>
<ul>
<li><input disabled="" type="checkbox"> 루트 <code>package.json</code> vs <code>apps/gemini-saas/package.json</code> 의존성·버전 비교</li>
<li><input disabled="" type="checkbox"> 선택지 문서화: (A) 실험용으로 유지 + README에 “동기화 안 함” 명시 (B) pnpm workspace로 승격 (C) 제거/아카이브</li>
</ul>
<p><strong>완료 기준</strong>: README에 채택한 전략 한 단락 + 유지보수 책임이 명확함.</p>
<hr>
<h3>Phase 5 — 품질·운영</h3>
<ul>
<li><input disabled="" type="checkbox"> <code>pnpm lint</code> / <code>pnpm build</code> CI(선택: GitHub Actions) 최소 파이프라인</li>
<li><input disabled="" type="checkbox"> <code>Projects-Status.md</code> §2와 본 플랜 Phase 체크박스 주기적 동기화</li>
<li><input disabled="" type="checkbox"> Polar E2E·Vercel 배포: <code>docs/operational-order.md</code>·<code>Projects-Status</code>에 있는 항목과 통합</li>
</ul>
<hr>
<h2>3. 진행 방식</h2>
<ul>
<li>한 번에 한 Phase만 “완료”로 친다. Phase 1 완료 후 사용자/에이전트가 Phase 2 착수.</li>
<li>코드 변경이 있는 Phase는 <strong>반드시</strong> <code>pnpm build</code> 및 관련 API 수동 확인.</li>
<li>시크릿·<code>.env</code>는 <code>env-secrets-security</code> 규칙 준수.</li>
</ul>
<hr>
<h2>4. 참조</h2>
<ul>
<li>설계: <code>docs/design-saas-engine.md</code></li>
<li>진도: <code>docs/progress-saas-engine.md</code></li>
<li>허브 표준: <code>docs/hub-template-standard.md</code></li>
<li>일일 루틴: <code>docs/dashboard-update-routine.md</code></li>
<li>대시보드·5프로젝트 맵: <code>docs/dashboard-workspace-map.md</code></li>
</ul>