<!-- task=m-core-server-boundary-cleanup/01_routes plan=1 tag=REVIEW_ROUTES -->

# Implementation Plan - REVIEW_ROUTES

## 이 파일을 읽는 구현 에이전트에게

구현 완료의 마지막 단계는 active `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채우는 것이다. 검증을 실행하고, active 파일은 그대로 둔 채 리뷰 준비 상태로 보고한다. 종결 처리, log archive, `complete.log` 작성, task directory archive 이동은 code-review 전용이다. 구현 중 사용자 결정, 사용자 소유 외부 환경, scope conflict 없이는 진행할 수 없으면 리뷰 stub의 `사용자 리뷰 요청`에 근거를 기록하고 멈춘다. 구현 중 사용자에게 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다.

## 배경

이 후속 계획은 `code_review_local_G06_0.log`의 Required 이슈만 다룬다. 이전 구현은 `NewServerWithRegistryAndStore`의 route 등록을 `routes.go`로 분리했지만, `/api/v1/` path parsing과 manual router 구성이 여전히 `server.go`의 handler 구현 사이에 남아 있다. 이번 작업은 endpoint behavior를 유지하면서 `/api/v1/` router helper 경계를 `routes.go`로 완성한다.

## 사용자 리뷰 요청 흐름

구현 중 blocker는 active review stub의 `사용자 리뷰 요청` 섹션에 기록한다. 이 섹션은 `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` 기준이다. 구현 에이전트는 직접 사용자 prompt를 만들지 않으며, code-review가 사용자 리뷰 요청의 타당성 검증과 실제 `USER_REVIEW.md` 작성을 담당한다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/independent-control-plane/milestones/core-server-boundary-cleanup.md`
- Task ids:
  - `routes`: route 등록과 subrouter 구성을 handler 구현에서 분리한다.
- Completion mode: check-on-pass

## 분석 결과

### 이전 리뷰 결과

- Archived plan: `agent-task/m-core-server-boundary-cleanup/01_routes/plan_local_G06_0.log`
- Archived review: `agent-task/m-core-server-boundary-cleanup/01_routes/code_review_local_G06_0.log`
- Verdict: `FAIL`
- Required issue: `routes.go`에는 route 등록 helper만 있고, `/api/v1/` subrouter helper인 `apiPathSegments`와 `handleRouter`가 `server.go`에 남아 있어 계획의 subrouter boundary가 완료되지 않았다.

### 범위 결정 근거

- 포함: `/api/v1/` path parsing과 manual router helper의 파일 경계 정리, `handleRouter(store, registry)` 호환 유지, route path/method behavior 회귀 검증.
- 제외: handler body 분리, DTO helper 이동, store/domain 동작 변경, 새 endpoint 추가, 테스트 의미 변경.
- 이슈는 명확하고 deterministic하며 기존 Go tests로 검증 가능하므로 `local-G07`로 상향한다.

## 구현 체크리스트

- [ ] `services/core/internal/httpserver/routes.go`가 `/api/v1/` path parsing과 API router helper를 소유하도록 `apiPathSegments`와 실제 router helper를 이동하거나 `handleAPIRouter(store, registry)`를 추가한다.
- [ ] 기존 tests가 직접 호출하는 `handleRouter(store, registry)` symbol은 wrapper 또는 같은 signature의 helper로 유지한다.
- [ ] `services/core/internal/httpserver/server.go`에는 server 생성, lifecycle, handler 구현만 남기고 route registration/subrouter 구성 코드를 남기지 않는다.
- [ ] endpoint path 목록과 HTTP method behavior를 변경하지 않고 `gofmt`를 실행한 뒤 `cd services/core && go test -count=1 ./internal/httpserver`를 통과시킨다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [REVIEW_ROUTES-1] API Subrouter Boundary Completion

#### 문제

- `services/core/internal/httpserver/routes.go`는 `registerRoutes`만 소유하고 `/api/v1/` router는 `server.go`의 handler 구현 사이에 남아 있다.
- `services/core/internal/httpserver/server.go`의 `apiPathSegments`와 `handleRouter`는 route/subrouter 구성 책임이므로 이번 milestone task의 완료 조건을 충족하려면 route boundary 파일로 옮겨야 한다.

#### 해결 방법

- `apiPathSegments`와 API router helper를 `routes.go`로 이동한다.
- `handleRouter(store, registry)`는 기존 테스트 호환을 위해 유지한다. 이름을 유지한 채 이동해도 되고, 새 `handleAPIRouter(store, registry)`를 만든 뒤 `handleRouter`가 이를 반환하는 wrapper가 되어도 된다.
- `server.go`의 import가 변경되면 unused import를 정리한다.
- handler body, DTO helper, store 동작은 수정하지 않는다.

#### 수정 파일 및 체크리스트

- [ ] `services/core/internal/httpserver/routes.go` 수정.
- [ ] `services/core/internal/httpserver/server.go` 수정.
- [ ] `services/core/internal/httpserver/server_test.go`는 기존 tests 유지. symbol wrapper가 꼭 필요할 때만 최소 수정.

#### 테스트 작성

- 신규 테스트 작성은 필수 아님. 기존 `TestServerMux`와 `/api/v1/` `handleRouter` direct-call tests가 route/subrouter behavior 회귀를 덮는다.

#### 중간 검증

```bash
cd services/core && go test -count=1 ./internal/httpserver
```

기대 결과: `ok github.com/toki/oto/services/core/internal/httpserver`.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `services/core/internal/httpserver/routes.go` | REVIEW_ROUTES-1 |
| `services/core/internal/httpserver/server.go` | REVIEW_ROUTES-1 |
| `services/core/internal/httpserver/server_test.go` | REVIEW_ROUTES-1 |

## 최종 검증

```bash
cd services/core && go test -count=1 ./...
```

기대 결과: 모든 `services/core` package test 통과. Go test cache output은 허용하지 않는다.

모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
