# 기능설명 관리 패키지 최종 설계문서

## 문서 목적
- 이 문서는 `src/features/layout/feature-menu/` 패키지의 최종 설계 기준 문서다.
- 실제 개발이 진행된 뒤에는 세션 리소스 문서보다 이 문서를 우선 기준으로 사용한다.
- 세션 리소스 문서는 대화 기록용 보조 산출물로만 유지하고, 최종 분석/검증 산출물은 패키지 내부 `resources/`를 기준으로 관리한다.

## 대상 범위
- 메뉴명: `기능설명 관리`
- 관련 저장 레이아웃 ID: `layout-1777643627048`
- 패키지 루트: `src/features/layout/feature-menu/`
- 진입 시 현재 메뉴 레이아웃 ID를 우선 선택하고, 같은 이름/ID 레코드에 바로 덮어쓴다.
- 모바일에서는 전체 편집 레이아웃이 부모 높이를 넘지 않도록 루트와 편집 박스의 높이 계산을 `border-box` 기준으로 고정하고, 편집 셸은 남는 높이를 강제로 늘리지 않고 내용 기준 높이로 먼저 맞춘다.

## 패키지 구조 기준
- 전용 화면과 로직은 `feature-menu` 패키지 내부에만 둔다.
- 현재 패키지 구성은 `FeatureMenuLayoutPage.tsx`, `FeatureMenuLayoutPage.css`, `featureMenu.types.ts`, `featureMenu.utils.ts`, `featureMenu.chat.ts`로 분리한다.
- 공용 app 계층으로 승격하는 작업은 다른 화면 재사용 근거가 확인될 때만 진행한다.

## 화면 역할
- 이 메뉴는 일반 메모 관리가 아니라 선택한 레이아웃의 `tree.interactions`를 선택, 편집, 실행하는 관리 화면이다.
- 선택된 기능설명의 저장 대상은 `selectedLayout.tree.interactions[].description`이다.
- `implementationNotes`는 본문 저장 대상이 아니라 관련 설명 탭에서만 읽는 보조 메타데이터다.

## 화면 구성 최종본
1. 상단 필터 영역
- `레이아웃명` 선택
- `기능설명 선택`
- `Codex 실행` 아이콘 버튼

2. 본문 편집 영역
- 상단 요약 description 박스는 두지 않는다.
- `추가`, `저장`, `삭제` 액션 아이콘은 두번째 섹션 상단에 고정해 하단 잘림을 피한다.
- 편집영역 툴바에는 문구 없는 `입력 최대화` 아이콘을 함께 둔다.
- 탭 버튼은 본문 상단에 두고, 선택된 탭 내용이 아래로 바로 이어지게 한다.
- 탭 구성: `기능설명 입력`, `Codex 설명`
- `기능설명 입력` 탭은 별도 제목 입력 없이 textarea 하나만 둔다.
- 기능설명 제목은 상단 `기능설명 선택` 드롭다운 항목명으로만 유지한다.
- `기능설명 입력` textarea는 편집 카드 높이를 최대한 채우도록 늘린다.
- `Codex 설명`이 비어 있을 때는 설명 문구를 따로 노출하지 않는다.
- 완료 기준 문서와 검증 산출물은 세션 리소스가 아니라 이 패키지 내부 경로를 우선 기준으로 본다.

## UI 규칙
- 기능설명 입력과 관련 설명은 같은 본문에 섞지 않고 탭으로 분리한다.
- 상시 노출 액션 버튼은 문구 없이 아이콘만 사용한다.
- 버튼 의미는 tooltip과 `aria-label`로 보완한다.
- 모바일에서는 설명성 문구보다 입력 영역과 하단 액션/탭 가시성을 우선한다.
- 모바일에서는 첫 섹션 높이를 줄여 두번째 섹션이 더 위에서 시작되도록 배치한다.
- `textarea`는 일반 상태와 최대화 상태 모두에서 마지막 줄이 잘리지 않게 내부 스크롤을 유지한다.
- 하단 입력 마지막 줄이 잘리지 않도록 탭 본문은 내부 스크롤과 하단 여백을 유지한다.
- 모바일에서는 제목 input, 탭 헤더, textarea가 같은 편집 카드 안에서 보이되, 편집 카드 자체는 다시 `auto + 1fr`로 남는 높이를 채운다.
- 모바일 편집 셸과 탭 본문은 `1fr` 채움을 유지하되, 하단 safe-area를 포함한 바깥 padding을 최소한으로 남긴다.
- 모바일에서는 아이폰 12 Pro 실기기 기준으로 페이지 하단 padding을 `calc(2px + env(safe-area-inset-bottom))`로 더 줄이고, 편집 셸 높이 감산은 `24px`, 입력/설명 패널 감산은 `4px` 수준으로 맞춰 wrapper와 입력 영역이 함께 더 아래까지 늘어나게 한다.
- 모바일 `Codex 설명` 탭도 같은 높이 체계를 유지하고, 하단 padding만 줄여 wrapper 하단의 큰 빈 영역처럼 보이지 않게 한다.
- 전체 페이지 overflow는 숨기고, 넘치는 내용은 페이지 바깥이 아니라 textarea 또는 `Codex 설명` 패널 내부 스크롤에서만 처리한다.

## Codex Live 실행 규칙
- 이 메뉴에서 Codex 실행 시 현재 선택된 레이아웃과 기능설명 본문을 프롬프트 입력으로 사용한다.
- 실제 구현 요청을 보낼 때는 이 패키지 최종 설계문서를 함께 갱신 대상으로 간주한다.
- 후속 개발에서 설계가 바뀌면 세션 문서만 수정하지 말고 이 문서를 먼저 갱신한다.

## 검증 기준
- 실제 수정본이 있으면 문서 설명보다 화면 결과와 preview 검증을 우선한다.
- 운영 비교 도메인은 `https://test.sm-home.cloud/`다.
- 소스 변경 검증과 최종 확인 도메인은 `https://preview.sm-home.cloud/`다.
- 최종 검증 산출물은 `resources/verification/` 아래에 패키지 기준으로 함께 보관한다.

## 패키지 내부 산출물
- 분석 문서: `resources/feature-menu-analysis.md`
- 개발 완료 문서: `resources/feature-menu-implementation.md`
- 최종 preview 검증 이미지: `resources/verification/feature-menu-preview-mobile-final.png`
- 최종 preview 검증 이미지: `resources/verification/feature-menu-preview-desktop-final.png`
- `test.sm-home.cloud` 운영 비교 이미지: `resources/verification/feature-menu-test-sm-home-mobile.png`
