---
test_env: <env>
last_rule_updated_at: <YYYY-MM-DD>
---

# <env> 테스트 규칙

**현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.**
**<env> 테스트 환경의 핵심 실행 모드와 local/dev/qa 등 다른 환경과의 공존 기준을 이 문서에 둔다.**

## 공통 규칙

- <env> 테스트/검증은 이 파일을 기준으로 판단한다.
- 작업 완료 검증은 변경 범위 기준으로 선택한다.
- 필수 검증을 실행하지 못하면 차단 사유로 보고한다.
- 최종 보고에는 실행 명령, 결과, 생략 사유, 남은 위험을 남긴다.
- 환경값, secret, 개인 endpoint는 tracked docs/roadmap에 쓰지 않는다.
- token/secret 원문은 원격 환경에서 주입하고, shell stdout/stderr와 최종 보고에 출력하지 않는다.
- 테스트용 Docker 환경을 작성/수정할 때는 Docker Compose `networks`, IPAM subnet, static IPv4, `extra_hosts`, host publish 문서 어디에도 host LAN/VPN과 충돌하는 대역을 사용하지 않는다.

## 기본 환경

- host: <기본 실행 host 또는 runner SSH>
- repo root: <원격/로컬 repo root>
- sync 기준: <source sync 판단 기준>
- env file: <compose/env file 기준 또는 해당 없음>
- compose identity: <COMPOSE_PROJECT_NAME / network 또는 해당 없음>
- port: <핵심 포트 요약>
- optional field ports: <선택 포트 또는 해당 없음>
- runtime: <Go/Flutter/Docker/외부 runtime>
- package manager: <Go modules / Makefile / Flutter pub 등>
- docker: <Docker 사용 기준>
- external service: <외부 서비스 URL/host 요약>
- model endpoint: <OpenAI-compatible 등 모델 endpoint>
- credential: secret/token/API key 원문은 문서에 기록하지 않는다.

## 포트 매핑

| 용도 | local/test | dev | <env> |
|---|---:|---:|---:|
| Web preview | `13000-13099` | `13001` | `<port 또는 해당 없음>` |
| Control Plane HTTP | `18000` | `18001` | `<port 또는 해당 없음>` |
| CP Client WS | `19080` | `19001` | `<port 또는 해당 없음>` |
| CP-Edge wire | `19081` | `19002` | `<port 또는 해당 없음>` |
| Edge-Node TCP | `19090` | `19003` | `<port 또는 해당 없음>` |
| Edge artifact/bootstrap | `18080` | `18082` | `<port 또는 해당 없음>` |
| Edge OpenAI-compatible | `18081` | `18083` | `<port 또는 해당 없음>` |
| Edge metrics | `19092` | `19101` | `<port 또는 해당 없음>` |
| Control Plane metrics | `19100` | `19103` | `<port 또는 해당 없음>` |
| Prometheus UI/API | `19110` | `19111` | `<port 또는 해당 없음>` |
| Grafana UI | `19120` | `19121` | `<port 또는 해당 없음>` |
| PostgreSQL host publish | `15400` | `15401` | `<port 또는 해당 없음>` |
| Redis host publish | `16300` | `16301` | `<port 또는 해당 없음>` |

<환경 안에서 compose/native/dev-runtime처럼 Edge-Node TCP가 갈라지면 여기에 명시한다.>

## 런타임 프로필

- local quick check: 현재 checkout에서 가능한 quick check를 우선 실행한다.
- remote runner: <SSH, repo root, 어떤 evidence에 쓰는지>
- compose <env> stack: <compose file/env file/project/network/주요 포트>
- native/direct Edge profile: <필요 시 artifact/openai/metrics/edge-node 포트>
- provider pool profile: <필요 시 config path, model alias, Edge-Node TCP>
- external provider field: <필요 시 SSH/user/IP/provider endpoint>

## 프리플라이트

- plan 작성 시 필수 검증이 현재 checkout을 벗어나 원격 runner, field/bootstrap, 외부 provider, Docker/code-server, emulator/device, 공유 장기 runtime을 사용하면 먼저 테스트 환경 프리플라이트를 계획에 기록한다.
- 테스트 환경 프리플라이트에는 runner, repo root/workdir, branch/HEAD/dirty 상태, local 변경과 원격 source 동기화 여부, binary/artifact 경로와 필요한 help/version 출력, config path, runtime identity, port/process 상태, 외부 host, OS/arch 가정을 포함한다.
- 프리플라이트에서 dirty/divergent checkout, stale artifact, 잘못된 identity, missing command, closed port, host OS 불일치, source 미동기화가 확인되면 plan은 먼저 setup/sync/rebuild 단계를 만들거나 blocker로 보고한다. remote deploy 환경에서 dirty 변경을 보존하지 않는 정책이면 배포 전 clean sync와 rebuild를 기본 단계로 둔다. profile 값을 이미 참이라고 가정한 검증 명령만 쓰지 않는다.

## 노드/Provider 인벤토리 위치

- 공통 machine-readable 인벤토리 기준: `agent-test/inventory.yaml`
- 환경별 machine-readable 인벤토리 기준: `agent-test/inventory-<env>.yaml` 또는 `해당 없음`
- Edge/OpenAI-compatible 입력 표면 상세 기준: `agent-test/<env>/edge-smoke.md`
- Node 접속과 bootstrap 상세 기준: `agent-test/<env>/node-smoke.md`
- 공통 provider config 계약 기준: `agent-test/<env>/platform-common-smoke.md`
- compose stack 기준: `agent-test/<env>/control-plane-smoke.md`, `agent-test/<env>/client-smoke.md`, `agent-test/<env>/testing-smoke.md`

## Field/bootstrap 반복 테스트 기준

- field/bootstrap 검증은 이 환경의 runner, checkout, artifact 기준으로 수행한다. 세부 Edge/Node profile은 해당 env의 `edge-smoke.md`와 `node-smoke.md`를 따른다.
- compose stack과 native/provider-pool profile이 서로 다른 Edge-Node TCP를 쓰면 두 프로필을 섞어서 판정하지 않는다.
- Node bootstrap은 Edge의 `node register`가 출력한 OS별 완성 명령을 그대로 사용한다. 사용자에게 안내하는 명령에는 임의 placeholder, 수동 token 치환, `IOP_*=` named environment parameter를 넣지 않는다.
- token, API key, private credential 원문은 tracked docs, roadmap, 테스트 규칙에 기록하지 않는다. 실행 증거에는 token을 마스킹하거나 명령 생성 사실만 남긴다.
- Linux/macOS Node는 생성된 `curl | bash` 계열 명령을 사용한다. Windows Node는 native PowerShell bootstrap을 기본으로 사용한다.
- provider capacity, model/provider mapping의 live apply는 해당 Edge binary가 `config refresh`를 제공하는 경우에만 사용한다. refresh 지원이 필요한 환경에서 subcommand나 admin port가 없으면 stale binary로 보고 clean sync/rebuild를 먼저 수행한다.
- Edge process restart 또는 일시 단절 후에는 Node reconnect 정책을 검증한다. retry 한계를 넘겨 Node process가 종료된 경우에만 해당 Node host에서 새 bootstrap 실행이 필요하다.

## 라우팅

- node / smoke / node 실행 파이프라인 baseline: `agent-test/<env>/node-smoke.md`
- edge / smoke / edge 실행 그룹과 입력 표면 baseline: `agent-test/<env>/edge-smoke.md`
- control-plane / smoke / control-plane health와 wire baseline: `agent-test/<env>/control-plane-smoke.md`
- client / smoke / Flutter client와 IOP console package baseline: `agent-test/<env>/client-smoke.md`
- platform-common / smoke / 공통 설정과 protobuf 계약 baseline: `agent-test/<env>/platform-common-smoke.md`
- testing / smoke / 테스트 도구와 full-cycle 검증 baseline: `agent-test/<env>/testing-smoke.md`

## 라우팅 규칙

- 여러 항목이 맞으면 모두 읽는다.
- 도메인 매핑이나 domain rule이 있으면 각 도메인의 `<domain>-smoke` 문서를 기본 baseline으로 둔다.
- 도메인이 아직 없을 때만 `project-smoke`를 fallback baseline으로 둔다.
- 도메인/검증 시나리오별 문서는 다른 테스트 문서로 라우팅하지 않는다.