toki
6e2a1fc2f2
- Add edge runtime config and opsconsole package - Refactor edge console to use new runtime config - Add service source metadata support - Update CLI adapter with target terminology - Add edge operation contract and event bus replay - Update node label and command ops surface - Add E2E smoke tests and full validation - Update proto runtime definitions - Update documentation and agent-ops rules
122 lines
3.7 KiB
Text
122 lines
3.7 KiB
Text
<!-- task=04_edge_operation_contract plan=0 tag=OPC -->
|
|
|
|
# 04 Edge Operation Contract Plan - OPC
|
|
|
|
## 이 파일을 읽는 구현 에이전트에게
|
|
|
|
**필수: 구현 마지막에는 반드시 `CODE_REVIEW-*-G??.md`의 모든 섹션을 실제 구현 내용과 명령 출력으로 채운다.**
|
|
이 task는 CLI/HTTP 공유 edge service contract를 정리한다.
|
|
|
|
## 배경
|
|
|
|
Edge service는 console과 향후 HTTP/API의 공통 core가 되어야 한다. 현재는 `RunHandle`과 proto channel이 surface에 직접 노출되어 HTTP handler가 붙을 때 별도 변환이 반복될 가능성이 있다.
|
|
|
|
## 분석 결과
|
|
|
|
### 읽은 파일
|
|
|
|
- `agent-ops/skills/common/plan/SKILL.md`
|
|
- `agent-ops/rules/project/domain/edge/rules.md`
|
|
- `apps/edge/internal/service/service.go`
|
|
- `apps/edge/internal/service/service_test.go`
|
|
- `apps/edge/internal/node/registry.go`
|
|
- `apps/edge/internal/events/bus.go`
|
|
- `apps/edge/cmd/edge/console.go`
|
|
- `apps/edge/cmd/edge/console_events.go`
|
|
- `proto/iop/runtime.proto`
|
|
|
|
### 테스트 커버리지 공백
|
|
|
|
- Node list snapshot DTO 테스트가 없다.
|
|
- Run dispatch/result를 surface-neutral shape로 검증하는 테스트가 없다.
|
|
|
|
### 심볼 참조
|
|
|
|
- `RunHandle`: `service.go:51`, `SubmitRun` returns `service.go:78`.
|
|
- `UsageStatusResult`: `service.go:177`.
|
|
- `TerminateSessionResult`: `service.go:140`.
|
|
|
|
### 범위 결정 근거
|
|
|
|
- 실제 HTTP API handler 추가는 제외한다.
|
|
- proto schema 변경은 이 task에서 피한다. 필요한 경우 별도 proto task로 넘긴다.
|
|
|
|
### 빌드 등급
|
|
|
|
- Build `cloud-G08`: service public contract 변경과 console call-site 영향.
|
|
- Review `cloud-G08`: API boundary와 call-site regression 검토 필요.
|
|
|
|
### [OPC-1] surface-neutral DTO 추가
|
|
|
|
#### 문제
|
|
|
|
`RunHandle`이 proto event channel과 console-facing fields를 함께 가진다.
|
|
|
|
#### 해결 방법
|
|
|
|
- `NodeSnapshot`, `RunDispatch`, `RunStream`, `UsageStatusView`, `CommandResult` 등 DTO를 service package에 추가한다.
|
|
- 기존 함수를 깨지 않도록 wrapper 또는 alias를 사용한다.
|
|
- DTO는 proto 타입 의존을 최소화하되 event stream은 현재 단계에서 proto를 허용할 수 있다.
|
|
|
|
#### 수정 파일 및 체크리스트
|
|
|
|
- [ ] `apps/edge/internal/service/service.go`
|
|
- [ ] `apps/edge/internal/service/service_test.go`
|
|
|
|
#### 테스트 작성
|
|
|
|
- `TestListNodesReturnsSnapshots`
|
|
- `TestSubmitRunReturnsDispatchMetadata`
|
|
|
|
#### 중간 검증
|
|
|
|
```bash
|
|
go test -count=1 ./apps/edge/internal/service
|
|
```
|
|
|
|
### [OPC-2] opsconsole이 DTO를 우선 사용
|
|
|
|
#### 문제
|
|
|
|
Console rendering이 service internals와 proto event fields를 직접 많이 본다.
|
|
|
|
#### 해결 방법
|
|
|
|
- opsconsole run/status/terminate path가 DTO를 우선 사용한다.
|
|
- proto event rendering은 event router 내부로 격리한다.
|
|
|
|
#### 수정 파일 및 체크리스트
|
|
|
|
- [ ] `apps/edge/internal/opsconsole/console.go`
|
|
- [ ] `apps/edge/internal/opsconsole/events.go`
|
|
- [ ] `apps/edge/internal/opsconsole/*_test.go`
|
|
|
|
#### 테스트 작성
|
|
|
|
- Existing console output compatibility tests.
|
|
- DTO field fallback tests.
|
|
|
|
#### 중간 검증
|
|
|
|
```bash
|
|
go test -count=1 ./apps/edge/internal/service ./apps/edge/internal/opsconsole
|
|
```
|
|
|
|
## 수정 파일 요약
|
|
|
|
| 파일 | 항목 |
|
|
|---|---|
|
|
| `apps/edge/internal/service/service.go` | OPC-1 |
|
|
| `apps/edge/internal/service/service_test.go` | OPC-1 |
|
|
| `apps/edge/internal/opsconsole/console.go` | OPC-2 |
|
|
| `apps/edge/internal/opsconsole/events.go` | OPC-2 |
|
|
| `apps/edge/internal/opsconsole/*_test.go` | OPC-2 |
|
|
|
|
## 최종 검증
|
|
|
|
```bash
|
|
go test -count=1 ./apps/edge/internal/service ./apps/edge/internal/opsconsole ./apps/edge/cmd/edge
|
|
go test -count=1 ./...
|
|
```
|
|
|
|
모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 전체 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
|