ai-code-app/features/layout/feature-menu/resources/feature-menu-final.md

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

문서 목적

• 이 문서는 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