@simplysm/sd-claude 14.0.96 → 14.0.97

package/claude/references/sd-simplysm14/README.md

@@ -39,6 +39,7 @@ ORM 호출, 파일 변환, 비즈니스 로직 등은 위 두 경우에 해당
 | 앱에서 공유 마스터 데이터 사용 (provider 정의·항목 추가, 선택 컨트롤의 관리·선택 모달, 좌측 선택+우측 상세 레이아웃) | [client-shared-data.md](./manuals/client-shared-data.md) |
 | 클라이언트·서버 간 실시간 이벤트 정의·발생·구독         | [event.md](./manuals/event.md)                         |
 | 앱 메뉴 구조·권한 정의 추가/수정                        | [client-app-structure.md](./manuals/client-app-structure.md) |
+| 클라이언트 SSG(프리렌더·SEO) 셋업, `prerender` 설정, SSR-safe 화면 작성 | [client-ssg.md](./manuals/client-ssg.md)               |
 | ORM 쿼리 작성(조회 흐름·안티패턴), 컬럼 nullable/default·유니크 정책, 삭제 전략 | [orm.md](./manuals/orm.md)                             |
 | 이종 엔티티를 한 목록으로 합쳐 표시 (UNION)             | [orm-union.md](./manuals/orm-union.md)                 |
 | CRUD 처리에 데이터 변경 이력 적재·조회·표시 (누가·언제·무엇을 변경, 목록의 수정일시·수정자 컬럼) | [data-log.md](./manuals/data-log.md)                   |

package/claude/references/sd-simplysm14/apis/angular/README.md

@@ -33,6 +33,8 @@ provideSdAngular(opt: { clientName: string }): EnvironmentProviders
 
 `makeEnvironmentProviders` 로 다음을 한 번에 등록: `IMAGE_CONFIG`(이미지 경고 비활성), ng-icons 기본 설정(strokeWidth 1.5, size 1.33em), 테마 dark/fontSize 의 localStorage 복원·저장 effect, 전역 `unhandledrejection`/`error` 리스너→`ErrorHandler`, `SdAngularConfigProvider`(clientName 주입), `SdOptionEventPlugin`(이벤트 수식어 지원), `ErrorHandler=SdGlobalErrorHandlerPlugin`, `provideZonelessChangeDetection()`, `SwUpdate` 주기 점검(5분 시작 → 실패 시 지수 백오프 최대 60분, 업데이트 발견 시 confirm 후 reload), 라우팅 네비게이션을 `SdBusyProvider.globalBusyCount` 와 연동. 앱 `ApplicationConfig.providers` 에 1회 추가.
 
+SSR(프리렌더) 안전: 부트스트랩 경로의 브라우저 의존 동작(테마 localStorage 복원, window 에러 리스너, SW 업데이트 점검, busy 오버레이, 에러 오버레이, `setupBgTheme`/`setupRipple`, core-browser prototype 확장)은 서버 플랫폼에서 무동작 — `prerender`(SSG) 클라이언트에서 그대로 사용 가능. 그 외 컴포넌트의 SSR-safe 여부는 개별 확인 필요.
+
 ```ts
 export const appConfig: ApplicationConfig = {
   providers: [provideRouter(routes), provideSdAngular({ clientName: "my-app" })],

package/claude/references/sd-simplysm14/apis/sd-cli/sd-config-types.md

@@ -94,6 +94,7 @@ interface SdClientPackageConfig {
   exclude?: string[];
   browserSupport?: SdBrowserSupportConfig;
   pwa?: false | SdPwaConfig;
+  prerender?: string[];
 }
 ```
 
@@ -106,6 +107,10 @@ interface SdClientPackageConfig {
 - exclude?: string[] — Capacitor/Electron `package.json` 에 추가(번들에서 빼 외부 패키지로 둘)할 패키지 목록.
 - browserSupport?: SdBrowserSupportConfig — 브라우저 호환(browserslist/PostCSS/legacyModule) 설정.
 - pwa?: false | SdPwaConfig — PWA 설정. `false` 면 비활성화, 미지정 시 기본값으로 활성화, 객체면 manifest 커스텀. PWA 가 필요 없으면 `false`.
+- prerender?: string[] — SSG(빌드 타임 프리렌더) 라우트 목록(예: `["/", "/about"]`). SEO 가 필요한 공개 페이지에 지정. 프로덕션 빌드에서만 동작하며 dev/watch 모드는 기존 SPA 그대로. 동작:
+  - `src/main.server.ts` 가 서버 부트스트랩(`(context: BootstrapContext) => bootstrapApplication(App, config, context)`)을 default export 해야 하며, 앱 설정에 `provideClientHydration()`, 서버 설정에 `provideServerRendering()` 포함. `@angular/platform-server` 의존성 필요 (Angular 표준 SSR 셋업과 동일).
+  - 라우트별 `<경로>/index.html` 을 서버 렌더 결과로 생성 (`"/"` 는 `index.html` 대체). SPA 셸은 `index.csr.html` 로 별도 보존되어 비프리렌더 라우트 딥링크 폴백에 사용 (service-server 정적 핸들러가 처리).
+  - 라우트 1건이라도 렌더 실패 시 빌드 전체 실패.
 
 ### SdServerPackageConfig (server)
 

package/claude/references/sd-simplysm14/apis/service-server/transport-internals.md

@@ -79,7 +79,7 @@ function createWebSocketHandler(
 
 - `handleHttpRequest(req, reply, jwtSecret, runMethod)` — `/api/:service/:method` 처리. `x-sd-client-name` 헤더 필수, `Authorization: Bearer <token>` 검증(실패 시 401). GET 은 `?json=` 쿼리, POST 는 배열 본문에서 파라미터를 받아 `runMethod` 실행. 본문이 배열이 아니면 400, 그 외 HTTP 메서드는 405.
 - `handleUpload(req, reply, rootPath, jwtSecret)` — `/upload` multipart 처리. multipart 아니면 400, 인증 토큰 필수(없거나 무효면 401). 파일을 `rootPath/www/uploads/<uuid><ext>` 로 저장하고 `ServiceUploadResult[]`(`{ path, filename, size }`) 반환. 도중 실패 시 그 요청에서 저장한 파일을 모두 롤백 삭제 후 500.
-- `handleStaticFile(req, reply, rootPath, urlPath)` — `rootPath/www` 하위 정적 파일 전송. `www` 밖 경로는 차단(throw), 디렉터리면 슬래시 리다이렉트 후 `index.html`, `.` 으로 시작하는 숨김 파일은 403, 미존재는 404, 그 외 전송 실패는 500 HTML 응답.
+- `handleStaticFile(req, reply, rootPath, urlPath)` — `rootPath/www` 하위 정적 파일 전송. `www` 밖 경로는 차단(throw), 디렉터리면 슬래시 리다이렉트 후 `index.html`, `.` 으로 시작하는 숨김 파일은 403, 미존재는 404, 그 외 전송 실패는 500 HTML 응답. SPA 폴백: 미존재 + 확장자 없는 페이지 요청이면 `www` 루트 방향으로 가장 가까운 `index.csr.html`(SSG 클라이언트의 SPA 셸)을 찾아 반환 — 셸 파일이 없는 기존 클라이언트는 그대로 404.
 
 ## ServerProtocolWrapper / createServerProtocolWrapper
 

package/claude/references/sd-simplysm14/manuals/client-ssg.md

@@ -0,0 +1,89 @@
+# 클라이언트 SSG(빌드 타임 프리렌더) 매뉴얼
+
+공개 페이지의 검색 노출(SEO)이 필요한 클라이언트를 만들 때 참조. 지정한 라우트의 HTML 을 프로덕션 빌드 시점에 미리 생성해, 검색봇이 완성된 HTML 을 받게 함.
+
+동작 개요:
+
+```
+빌드(pnpm build):
+  browser 번들 (기존 SPA 와 동일)
+  + src/main.server.ts 진입의 node 번들 → 라우트별 <경로>/index.html 생성
+  + SPA 셸을 index.csr.html 로 별도 보존
+
+운영(service-server 정적 서빙):
+  /q (프리렌더됨)      → 완성된 HTML 즉시 응답 → browser 번들이 hydration 후 SPA 동작
+  /r/abc (프리렌더 안 됨) → index.csr.html 셸 + 브라우저에서 데이터 로드 (기존 SPA 와 동일)
+```
+
+- dev/watch 모드에는 적용되지 않음 — 개발은 기존 SPA dev 서버 그대로, SSG 동작 확인은 프로덕션 빌드로.
+- 라우트 1건이라도 렌더 실패하면 빌드 전체 실패.
+
+## SSG 클라이언트를 셋업하려면
+
+`sd-cli init` 으로 워크스페이스를 새로 만들 때는 클라이언트별 "SSG 를 쓸까요?" 질문에서 켜면 아래 절차가 자동 반영됨 (기본 `prerender: ["/"]`). 아래는 기존 클라이언트에 수동으로 추가하는 절차.
+
+① `sd.config.ts` 의 client 패키지에 `prerender` 로 라우트 목록 지정:
+
+```ts
+"client-portal": {
+  target: "client",
+  server: "server",
+  prerender: ["/", "/about"],
+},
+```
+
+② `@angular/platform-server` 의존성 추가 (클라이언트 패키지 `package.json`, Angular 패키지들과 동일 버전).
+
+③ 라우팅을 path 방식으로 — 검색엔진은 hash(`/#/about`) 뒤를 별개 페이지로 보지 않으므로 `withHashLocation()` 제거:
+
+```ts
+provideRouter(routes), // withHashLocation() 없이
+```
+
+④ 앱 설정에 hydration 추가:
+
+```ts
+import { provideClientHydration } from "@angular/platform-browser";
+
+providers: [..., provideClientHydration()],
+```
+
+⑤ `src/main.server.ts` 작성 (Angular 표준 — 서버 부트스트랩 default export):
+
+```ts
+import { bootstrapApplication, type BootstrapContext } from "@angular/platform-browser";
+import { provideServerRendering } from "@angular/platform-server";
+import { AppRoot } from "./app.root";
+import { appProviders } from "./app.providers"; // main.ts 와 공유하는 providers
+
+const bootstrap = (context: BootstrapContext) =>
+  bootstrapApplication(AppRoot, { providers: [...appProviders, provideServerRendering()] }, context);
+
+export default bootstrap;
+```
+
+## 프리렌더 화면 코드를 SSR-safe 하게 작성하려면
+
+프리렌더 라우트에서 쓰는 코드는 빌드 시 node 에서 한 번 실행됨. 컴포넌트 생성·초기화 시점에 브라우저 전역(`window`/`document`/`localStorage`)을 직접 만지면 빌드가 실패함 (빌드 에러로 즉시 드러남).
+
+- 이벤트 핸들러 안의 브라우저 API 는 무방 — 서버에서는 실행되지 않음.
+- 생성자·`effect()` 등 초기화 경로의 브라우저 API 는 가드:
+
+```ts
+import { inject, PLATFORM_ID } from "@angular/core";
+import { isPlatformBrowser } from "@angular/common";
+
+if (isPlatformBrowser(inject(PLATFORM_ID))) {
+  // 브라우저 전용 초기화
+}
+```
+
+- 또는 `afterNextRender(() => { ... })` — 브라우저에서만 실행됨.
+- `@simplysm/angular` 부트스트랩 경로(provideSdAngular·테마·busy 등)는 이미 가드되어 그대로 사용 가능. 그 외 컴포넌트는 프리렌더 화면에 쓸 때 개별 확인 — 빌드가 깨지면 그 컴포넌트의 초기화 경로를 가드.
+
+## 지킬 것
+
+- SEO 대상 페이지는 빌드 시점에 URL 이 고정된 라우트만 가능 — 동적 URL(예: `/r/:id`) 은 프리렌더 불가, 셸 폴백으로 동작하며 검색 노출 안 됨. 동적 페이지 SEO 가 필요해지면 SSG 가 아니라 SSR 검토.
+- `prerender` 라우트는 `"/"` 로 시작.
+- 프리렌더 결과는 빌드 시점 데이터로 고정 — 콘텐츠 갱신은 재빌드·재배포로 반영됨을 전제로 라우트를 선정.
+- 기존 SPA 클라이언트에 영향 없음 — `prerender` 미설정 클라이언트는 동작이 바뀌지 않으므로, SEO 필요 페이지를 별도 클라이언트 패키지로 분리하는 구성을 우선 검토.

package/claude/sd-system-prompt.md

@@ -203,6 +203,7 @@ X 함수에 캐시 도입 검토 중. 기존 의존성 확인 결과 lru-cache
 | 명령·승인                    | "고쳐줘", "응 그렇게", "적용해"           | "해줘", "응", "ㅇㅇ", "진행" | 도구 호출 (실행)                            |
 | 의문·요청 (원인·방법·가능성) | "왜 ~?", "어떻게 ~안될까?", "~방법 있어?" | "왜", "어떻게", "?"          | [문제 발생 시](#문제-발생-시) 워크플로 따름 |
 | 제안·아이디어                | "X 하면 어때?", "Y 가 좋을듯", "X 할 생각을 해", "X 검토해봐" | "어때", "좋을듯", "할까?", "생각을 해", "검토해봐", "고려해" | 텍스트 응답 (검토·대안 제시) → 합의 후 실행 |
+| 추측·가능성·소망 표명        | "~나오지 않을까?", "~수도 있고", "~면 좋겠다" | "않을까", "수도", "~듯", "~면 좋겠" | 텍스트 응답 (확정 아님 — 합의 전 결정 근거 불가) |
 | 문제 기술·현상 보고          | "이거 안돼", "버그 있어"                  | "안돼", "버그"               | [문제 발생 시](#문제-발생-시) 워크플로 따름 |
 | 위치·맥락 정보 단독          | "X 파일에..", "Y 섹션쪽에.."              | "X에", "Y쪽에"               | 의도 확인 질문 또는 다음 발언 대기          |
 

package/claude/settings.json

@@ -1,4 +1,5 @@
 {
+  "defaultShell": "powershell",
   "hooks": {
     "PreToolUse": [
       {

package/claude/skills/sd-impl/SKILL.md

@@ -44,9 +44,8 @@ spec 본문 수정이 필요한 경우(인라인 `[OPEN]` 해소·섹션 `[OPEN]
 
 1. **sd-spec SKILL.md Read** — 룰 인지: 부분 수정 인라인 경로·신뢰도 표기·형식 준수(§ 작성법 Read)·이름 기반 참조 cascade.
 2. **sd-spec "부분 수정 (인라인)" 경로로 Edit** — 정밀 반영(도메인 답이 이미 확정된 인라인 `[OPEN]`·6단계 결정 반영)은 바로 Edit, 초안·판단 필요분(섹션 `[OPEN]` 초안·구조 변경·모순 정정)은 진단·초안 제시 → 합의 후 Edit. 수정분은 사후 보고.
-3. **의존 추적** — 수정된 § 항목을 의존으로 가진 §4.x/§5.x/§6.x 를 이름 기반 참조 cascade(`[카테고리.이름]` grep 전수 추적) + 관련 섹션 한 줄로 탐색. 본 작업 단위 자신은 제외 (작업 중).
-4. **마커 제거** — 의존 §4.x/§5.x/§6.x 헤더의 `[구현]` 마커 제거 (이전 구현 무효화).
-  - 영향 단위에 번호를 매겨 사용자에게 모아서 "맞나요?" 질문 — 전체 동의 → 일괄 제거 / 일부 유지 지목 → 지목 항목 마커 유지.
+3. **의존 추적** — sd-spec "§4~6 `[구현]` 마커 제거" 절의 의존 식별 규칙으로 수정된 § 를 의존으로 가진 §4.x/§5.x/§6.x 를 전수 추적. 본 작업 단위 자신은 제외 (작업 중).
+4. **마커 제거** — 추적된 §4.x/§5.x/§6.x 헤더의 `[구현]` 마커 제거 (이전 구현 무효화). 합의 절차도 같은 절 따름.
 
 본 작업 단위(§4.x/§5.x/§6.x 자신)의 헤더에는 9단계에서 `[구현]` 마커를 부착.
 
@@ -245,6 +244,8 @@ subagent 출력을 받은 후 분류별로 처리:
 
 ### 8단계: 시연 검증
 
+**시연 스킵 조건**: 대상 단위에 세션 시작 시점부터 이미 `[구현]` 마커가 있었고(이전 시연 완료) + 이번 세션이 코드 파일을 하나도 생성·수정하지 않음(5단계 편집 0건 + 6단계 (a) 코드 위반 0건) → 본 단계 스킵 후 9단계 진입. 마커가 없던 단위(첫 검증)는 코드 변경이 없어도 시연 수행.
+
 사용자에게 요청: "**dev 서버**를 실행하고 접속 주소를 알려달라."
 
 **dev 서버·외부 프로세스 자체 실행 금지**: assistant 가 직접 `ng serve`·`npm run dev`·`vite`·`pnpm dev` 등으로 dev 서버를 띄우지 않음. 사용자가 띄워 주소를 회신할 때까지 대기. 사용자가 본 단계의 스킵을 지시하거나 시연 불가 환경이 명시되면 본 단계 스킵 후 9단계 진입.

package/claude/skills/sd-spec/SKILL.md

@@ -57,8 +57,24 @@ sd-spec 은 2종의 연산으로 동작. 사용자 지시를 받으면 아래
 - **구조 변경** (병합·분할·추가: "A 화면과 B 화면을 합쳐", "이 프로세스를 둘로 나눠") → 이름 기반 참조 cascade:
   - `[화면.X]`·`[모델.X]`·`[프로세스.X]` 등 이름 기반 참조("본문 내 참조" 절)를 grep 으로 전수 추적해, 병합·분할·삭제로 끊기는 참조를 함께 갱신.
   - § 번호는 자주 바뀌므로 이름으로 추적. 변경 후 dangling 참조가 남지 않게 확인.
+- **구현 마커 제거** (§4~6 자신 또는 그 의존 § 를 수정한 경우) → 아래 "§4~6 `[구현]` 마커 제거" 절을 따라 영향 §4~6 의 `[구현]` 마커를 제거.
 - 작성 형식·신뢰도 표기는 아래 "작성 원칙" 과 **대상 섹션의 작성법** (아래 "§별 작성법" 절 표에서 해당 ref 를 Read) 을 따름.
 
+### §4~6 `[구현]` 마커 제거
+
+§4.x/§5.x/§6.x 본문, 또는 그 본문이 의존하는 § 본문을 수정하면 그 §4~6 의 이전 구현은 무효가 됨 → 해당 §4.x/§5.x/§6.x 헤더의 `[구현]` 마커 제거 (sd-impl 재실행 대기 상태로). sd-spec 부분 수정·sd-impl spec 수정 양쪽이 이 절을 따름 (의존 식별·합의의 단일 출처).
+
+**의존 식별** — §4.x/§5.x/§6.x 본문에 다음 중 하나라도 나타나는 §x.x 는 그 §4~6 의 의존 대상:
+
+- `관련 섹션:` 줄의 `[프로세스.X]`·`[기타.X]`·`[화면.X]`·`[자동 처리.X]`·`[기반.X]`·`[외부 인터페이스.X]`.
+- 본문 어느 위치든 등장하는 `[모델.X…]`·`[공통 정의.X]`.
+- §7 외부 자료 명세를 컬럼명 일치로 끌어다 쓴 양식 매핑 표 (해당 §7.x).
+- 모달 호출 `→ [화면.X]` 의 그 §4.x.
+
+수정 대상이 §4~6 자신이면 그 자신의 `[구현]` 도 제거 대상 (sd-spec). 단 sd-impl 은 본 작업 단위(재구현 중)는 제외.
+
+**합의** — 영향 §4.x/§5.x/§6.x 를 번호 매겨 각각 한 줄 이유와 묶어 "맞나요?" 합의 → 전체 동의 일괄 제거 / 일부 유지 지목 시 지목 항목만 마커 유지.
+
 ### 연산 사이 검토
 
 각 연산(배치·부분 수정) 완료 후 동일하게:
@@ -119,7 +135,7 @@ spec.md 본문에서 항목의 신뢰도를 나타내는 표기. 전부 날짜
 | (무표기)            | 직접·자명, 또는 미검토 초안. 기본 상태.                                                                    |
 | 줄끝 `(근거: 출처)` | 자료에서 해석·도출한 **비자명** 항목의 근거 (예: `(근거: 회의록 L12)`). 사용자가 직접 말한 자명 항목엔 안 붙임. 위치 = 표는 비고 칸, 산문은 줄 끝. |
 | `[OPEN]`            | 근거 없음. 필요 시 추측·필요자료 메모 동반 (예: `[OPEN] 박스당 수량 — As-Is상 24 추정, 미확인`).            |
-| `[구현]`            | sd-impl 소관. sd-spec 은 존재만 인지, 부착·제거하지 않음.                                                  |
+| `[구현]`            | §4~6 구현 완료 표시. 부착은 sd-impl 소관. §4~6 또는 그 의존 § 수정 시 제거는 sd-spec·sd-impl 양쪽 수행 (아래 "§4~6 `[구현]` 마커 제거" 절).                                                  |
 
 - `[OPEN]` 판정: 근거 부족(상위 행동 규칙 "결정 근거" 적용). As-Is 만 근거 / 추정 / 답변 범위 흡수 = 근거 없음 → `[OPEN]`.
 - 확정 여부는 사용자가 직접 관리 — 헤더에 상태 마커(`[확정: 날짜]`·`[OPEN: 날짜]` 등)를 붙이지 않음.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/sd-claude",
-  "version": "14.0.96",
+  "version": "14.0.97",
   "description": "심플리즘 패키지 - Claude Code 셋업",
   "author": "심플리즘",
   "license": "Apache-2.0",