# TO-DO.md — 추후 개발 항목

> 본 파일은 ARCHITECTURE.md와 CLAUDE.md 등에 정의되었으나 **아직 구현되지 않은** 항목들을 추적한다.
> Phase 0 (데모 UI)는 완료되었으며, Phase 1부터 순차적으로 진행 예정이다.

---

## 1. 서버·전송 계층 구현 (Phase 1)

### 1.1. Proto 정의 및 코드 생성
- `proto/aiot/inference/inference.proto` — AI 추론 요청/응답
- `proto/aiot/device/device.proto` — 디바이스 등록·상태 보고
- `proto/aiot/gateway/gateway.proto` — 게이트웨이 데이터 전달 서비스
- `make proto` — protoc + protoc-gen-go + protoc-gen-go-grpc 설치 및 자동화

### 1.2. 전송 계층 (`internal/transport/`)
- `transport.go` — Listener/Dialer 인터페이스 정의
- `h2_listener.go` — HTTP/2 (TCP) 리스너
- `quic_listener.go` — QUIC 리스너 (quic-go 래핑)
- `quic_dialer.go` — QUIC 클라이언트 다이얼러
- **리스크**: quic-go `quic.Stream`과 `net.Conn` 인터페이스 호환성 검증 필요

### 1.3. 서버 구현 (`internal/server/`, `cmd/server/`)
- `internal/server/inference_server.go` — InferenceService 구현
- `internal/server/device_server.go` — DeviceRegistry 구현
- `internal/server/gateway_server.go` — GatewayService 구현
- `cmd/server/main.go` — `--transport=quic|h2` 플래그 기반 진입점

### 1.4. 클라이언트 구현 (`internal/client/`)
- `internal/client/inference_client.go` — gRPC 클라이언트 (재시도·타임아웃)
- `internal/client/rest_client.go` — REST 비교군 클라이언트

### 1.5. 미들웨어 (`internal/middleware/`)
- `logging.go` — 요청/응답 로깅 인터셉터
- `metrics.go` — latency 측정 인터셉터

---

## 2. REST 비교군 구현 (Phase 1)

### 2.1. REST 서버
- `cmd/rest-server/main.go` — HTTP/1.1 + JSON REST API 서버
- `--edge` 플래그 지원 (REST-Edge, 엣지 ROI 1차 처리)

### 2.2. REST 클라이언트
- `rest_client.go` — gRPC 클라이언트와 동일 시나리오 보장

---

## 3. 게이트웨이 구현 (Phase 2~3)

### 3.1. 게이트웨이 코어 (`internal/gateway/`)
- `gateway.go` — 라우팅·변환 엔진
- `protocol_adapter.go` — IoT 프로토콜 어댑터 인터페이스
- `mqtt_adapter.go` — MQTT → Protobuf 변환
- `coap_adapter.go` — CoAP → Protobuf 변환 (P1)
- `route_table.go` — 서비스 디스커버리·라우팅 테이블 (YAML 기반)

### 3.2. 라우터 (`internal/router/`)
- `task_router.go` — 엣지 라우팅 로직 (ROI 결과 기반)

### 3.3. 게이트웨이 서버
- `cmd/gateway/main.go` — 게이트웨이 진입점
- HTTP/2 fallback 모드 지원 (quic-go 리스크 대비)

---

## 4. 스크립트·빌드 인프라

### 4.1. Shell 스크립트 (`scripts/`)
- `proto-gen.sh` — protoc 컴파일 자동화
- `tc-setup.sh` — `--delay --loss --rate --interface` 옵션 지원
- `tc-reset.sh` — tc 설정 초기화

### 4.2. Docker (`docker/`)
- `Dockerfile.server` — gRPC 서버 컨테이너
- `Dockerfile.rest-server` — REST 서버 컨테이너
- `docker-compose.yml` — 전체 실험 환경 구성

### 4.3. Makefile (루트)
- `make proto`, `make build`, `make run-server`, `make test`
- `make benchmark`, `make lint`, `make docker-up/down`, `make clean`

### 4.4. Lint 설정
- `.golangci-lint.yaml` — errcheck, govet, staticcheck 등

### 4.5. `go.mod` / `go.sum` (루트)
- 루트 Go 모듈 초기화 (`src/`와 별도)

---

## 5. 벤치마크 (Phase 2~3)

### 5.1. 벤치마크 러너 CLI
- `cmd/benchmark-runner/main.go` — `--mode=once|matrix --scenario --transport`
- 분산 환경 end-to-end 측정 (P50/P95/P99, RPS)
- 2모드: 단일 측정(`once`) / 전체 매트릭스 sweep(`matrix`)

### 5.2. Go testing.B 벤치마크 (`benchmarks/scenarios/`)
- `unary_test.go` — Unary RPC 마이크로벤치마크
- `streaming_test.go` — Streaming RPC 벤치마크
- `rest_compare_test.go` — REST vs gRPC 비교
- 역할: 단일 프로세스 내 직렬화 시간·처리량 측정 (benchmark-runner와 분리)

### 5.3. 실험 결과 저장소
- `benchmarks/results/YYYY-MM-DD/*.json` — raw latency + 메타데이터
- 사후 분석: percentile + CI95 + Tukey outlier + Mann-Whitney U

---

## 6. 문서·설계 결정

### 6.1. ADR (Architecture Decision Records)
`docs/decisions/` 디렉터리에 다음 ADR 작성 필요:
- `001-go-grpc-baseline.md` — Go + gRPC 기술 스택 선정 배경
- `002-quic-grpc-compatibility-poc.md` — quic-go 호환성 검증 결과
- `003-gateway-architecture.md` — 게이트웨이 아키텍처 및 novelty 정의
- `004-protocol-adapter-design.md` — MQTT/CoAP 변환 전략
- `005-routing-data-model.md` — 라우팅 데이터 모델 및 설정 형식
- `006-experiment-design.md` — 실험 매트릭스·워크로드 파라미터 고정

### 6.2. 위험 관리 (`docs/risks.md`)
- quic-go 호환성 (R-01)
- Docker tc 미작동 (R-02)
- MQTT/CoAP 범위 과다 (R-03)
- Go 버전업 호환성 (R-04)
- 합성 부하의 한계 (R-05)

---

## 7. Phase 0 UI — 사소한 개선

### 7.1. `types.go` — 6개 시스템 확장 (낮은 우선순위)
- REST-Cloud / REST-Edge / gRPC-H3-Stream / gRPC-H3-GW 추가
- **메인 비교 대상은 REST-H2 / gRPC-H2 / gRPC-H3 3개**이므로 시급하지 않음

### 7.2. `Result.Latencies` RingBuffer 전환 (선택)
- 타입 레벨에서 cap을 명시하거나 RingBuffer로 변경
- 현재는 simulator.go에서 500개로 제한 중

### 7.3. `padVisible()` 개선 (선택)
- `runewidth.StringWidth()` 사용하여 한글 정렬 보정
- (`mattn/go-runewidth`는 이미 간접 의존성에 존재)

---

## Phase별 요약

| Phase | 주요 작업 | 의존성 |
|-------|---------|--------|
| **1** | Proto 정의 + 전송 계층 + gRPC 서버/클라이언트 + REST 비교군 | — |
| **2** | 게이트웨이 + MQTT 어댑터 + 라우팅 | Phase 1 완료 |
| **3** | tc 스크립트 + Docker + 벤치마크 러너 | Phase 1 완료 |
| **4** | Mininet 토폴로지 + 다중 컨테이너 부하 | Phase 3 완료 |
| **5** | simulator 실측 교체 + 0-RTT/HoL 측정 | Phase 3~4 완료 |

> 상세 우선순위는 `TASK_LIST.md`를, 의존 순서는 `IMPLEMENTATION.md` §6.2를 참조한다.