개발가이드 페이지 추가

CLAUDE.md

@@ -265,6 +265,41 @@ API 키는 승인 워크플로우와 함께 관리됩니다:
 8. `src/main/resources/templates/views/newfeature/`에 Thymeleaf 템플릿 추가
 9. `application.yml`의 `pages` 섹션에 라우트 설정 (또는 `@GetMapping`/`@PostMapping`으로 직접 매핑)
 
+### 메뉴/네비게이션 항목 추가하기
+
+**중요:** 메뉴 정의가 **두 곳으로 분리**되어 있다. yml 한 곳만 고치면 헤더 드롭다운에 안 보이고, 헤더만 고치면 브레드크럼이 비어 보인다. 메뉴 추가/이름 변경/순서 변경 시 **반드시 두 파일을 같이 수정**한다.
+
+1. **`application.yml`의 `page:` 트리** (브레드크럼·페이지 메타용)
+   - `PageService`가 URL → breadcrumb 매핑에 사용
+   - 부모 메뉴(`service`, `apis`, `community` 등) 아래 `children:`에 새 키를 추가
+   ```yaml
+   page:
+     home:
+       children:
+         service:
+           children:
+             oauth2_guide:
+               name: "OAuth2 인증가이드"
+               path: "/service/oauth2-guide"
+   ```
+
+2. **`templates/views/fragment/djbank/header_container.html`** (상단 글로벌 네비)
+   - `<nav class="header-center"><ul class="nav-menu">` 블록에 정적 `<li>`로 하드코딩되어 있다 — yml 트리를 iterate 하지 **않음**
+   - 부모 메뉴의 `<ul class="sub-menu">`에 `<li><a th:href="@{/...}">메뉴명</a></li>` 직접 추가
+
+3. **라우트도 같이 등록** (`application.yml`의 `portal.pages` 매핑 섹션, 또는 `@GetMapping`)
+   ```yaml
+   portal:
+     pages:
+       - path-pattern: /service/oauth2-guide
+         method: GET
+         view-name: apps/service/oauth2-guide
+   ```
+
+4. **검증**: 변경 후 (a) 헤더 드롭다운에 항목이 보이는지, (b) 새 페이지 진입 시 브레드크럼에 메뉴명이 보이는지 둘 다 확인.
+
+5. **재시작**: `application.yml` 변경은 `PortalPageHandlerMapper`가 `@PostConstruct`에서 한 번만 등록하므로 **자동 라이브 리로드 안 됨** — 수동 재시작 필요. HTML/CSS만 라이브 반영됨.
+
 ### MapStruct DTO 매핑
 
 타입 안전한 DTO 변환을 위해 MapStruct 사용: