# Local Server 실행환경 보정 규칙

이 명령은 일반 Next.js 앱 코드를 생성하는 것이 아니라, `ju-hong-e` 가 관리하는 local-server Storybook 실행환경에서 바로 렌더링될 `*.stories.tsx` + `*.module.scss` 조합을 생성한다.

`project-context.md`, `coding-convention.md`, `naming-rule.md`, `figma-to-code.md` 의 일반 프론트엔드 규칙은 참고하되, 아래 항목이 충돌하면 **이 문서가 우선**이다.

## 참조 조건

- local-server Storybook 실행환경 제약과 허용 파일 구조를 확인해야 할 때 이 문서를 읽는다.
- Next.js 앱 코드 대신 독립 story bundle을 생성해야 할 때 이 문서를 읽는다.

## 수행 계약

- 결과물은 local-server에서 바로 실행 가능한 `*.stories.tsx` + `*.module.scss` 2파일로만 구성한다.
- Next.js 앱 라우터 구조, `next/*` import, 앱 전용 alias import는 사용하지 않는다.
- Storybook preview에서 즉시 렌더링되는 독립 실행 환경을 기준으로 코드를 작성한다.

## 실행환경

- 결과물은 `.ju-hong-e/local-server/generated/...` 아래에 저장된다.
- Storybook + Vite 환경에서 바로 실행된다.
- local-server preview decorator가 이미 아래 환경을 제공한다.
  - `QueryClientProvider`
  - `<div id="wrap" className="wrap">`
  - `<div id="ds-portal">`
- 따라서 생성물은 앱 라우터 엔트리나 페이지 파일이 아니라, **독립 실행 가능한 Storybook story 파일** 이어야 한다.

## 파일 구조

- `page.tsx`, `layout.tsx`, `page-container/` 구조를 만들지 않는다.
- 결과물은 정확히 2개 파일만 생성한다.
  - `*.stories.tsx`
  - `*.module.scss`
- 화면 본체, 하위 UI 블록, mock data, helper 함수는 모두 `*.stories.tsx` 안에 인라인으로 작성한다.
- 추가 ts/tsx/scss 파일을 분리 생성하지 않는다.

## import / 런타임 제약

- `next/image`, `next/link`, `next/navigation`, `next/router` 를 import 하지 않는다.
- `'use client'` 지시어를 추가하지 않는다.
- `@/`, `~`, `src/` 같은 앱 전용 path alias import 를 사용하지 않는다.
- 로컬 워크스페이스 내부 상대경로 import 에 의존하지 않는다.
- local-server 기본/추가 dependency로 해석 가능한 패키지 import 만 사용한다.
- 디자인 토큰 SCSS는 `@use 'sales-frontend-design-system/design-system-context' as *;` 기준으로 작성한다.

## 레이아웃 / 상태 처리

- 일반적인 네이밍·구조화 원칙은 참고하되, `page.tsx -> page-container` 같은 App Router 전용 규칙은 적용하지 않는다.
- story 파일 안에서 필요한 `useState`, `useMemo`, `useEffect` 등 React 훅 사용은 허용한다.
- 단, Storybook preview 안에서 바로 동작해야 하므로 외부 앱 상태나 라우터 컨텍스트를 전제로 하지 않는다.
- 모달/드롭다운처럼 portal이 필요한 컴포넌트는 preview shell에 `#ds-portal` 이 이미 존재한다고 가정하고 사용한다. story 안에서 portal root를 다시 만들지 않는다.

## 산출물 목표

- 최종 목표는 “앱 코드 구조 재현”이 아니라 “local-server Storybook에서 즉시 실행 가능한 미리보기”다.
- 따라서 앱 레이어 분리보다도 아래를 우선한다.
  - Storybook에서 오류 없이 렌더링될 것
  - 디자인 레이아웃을 최대한 보존할 것
  - 필요한 import가 local-server dependency로 해석 가능할 것
  - 지정된 story export 계약을 정확히 지킬 것
