iop/agent-ops/rules/project/domain/platform-common/rules.md

platform-common

목적 / 책임

여러 앱이 공유하는 설정, 인증, 정책, 메타데이터, 작업 상태, 관측성, 버전, protobuf 계약을 관리한다. 앱별 구현보다 안정적인 공통 계약과 작은 유틸리티를 제공하는 영역이다.

포함 경로

• packages/auth/ — mTLS 인증 설정 helper
• packages/config/ — 앱 설정 struct, 기본값, YAML 로딩
• packages/jobs/ — 작업 상태와 작업 메타데이터 타입
• packages/metadata/ — 공통 metadata map helper
• packages/observability/ — zap logger와 Prometheus health/metrics 서버
• packages/policy/ — 정책 엔진 인터페이스와 passthrough 구현
• packages/version/ — 앱 버전 상수
• proto/iop/ — protobuf 메시지 계약 원본
• proto/gen/iop/ — protobuf 생성물
• configs/ — 앱별 설정 예시

제외 경로

• apps/node/ — node 실행 파이프라인과 adapter 관리
• apps/edge/ — gateway 서버와 node registry
• apps/control-plane/ — control-plane 앱 구현 예정 영역
• apps/worker/ — worker 앱 구현 예정 영역

주요 구성 요소

• config.NodeConfig / config.EdgeConfig — 앱 설정 계약
• auth.LoadServerTLS / auth.LoadClientTLS — mTLS TLS config 생성
• observability.NewLogger / observability.ServeMetrics — 공통 로깅/메트릭
• policy.Engine — 정책 적용/검증 계약
• jobs.Job — 비동기 작업 상태 모델
• proto/iop/*.proto — 앱 간 메시지 원본 계약

유지할 패턴

• 공통 패키지는 특정 앱의 내부 패키지를 import하지 않는다.
• 설정 struct 필드 변경 시 YAML tag, mapstructure tag, default, configs/*.yaml 예시를 함께 확인한다.
• protobuf 계약 변경은 proto/iop/*.proto에서 시작하고 make proto로 생성물을 갱신한다.
• 생성 파일(proto/gen/iop/*.pb.go)은 사람이 직접 편집하지 않는다.
• 공통 패키지는 작고 명확한 계약을 유지하고 앱별 정책을 과도하게 끌어올리지 않는다.

다른 도메인과의 경계

• node: node가 필요로 하는 설정/타입/계약을 제공하지만 실행 파이프라인의 소유자는 node이다.
• edge: edge가 필요로 하는 설정/관측성/protobuf 계약을 제공하지만 gateway 동작의 소유자는 edge이다.
• control-plane/worker 후보: 두 앱이 구현되면 필요한 공통 타입만 이 영역으로 승격하고 앱 내부 책임은 각 도메인에 둔다.

금지 사항

• packages에서 apps/*/internal 패키지를 import하지 않는다.
• 앱 하나만을 위한 임시 타입을 충분한 근거 없이 공통 패키지로 승격하지 않는다.
• protobuf 생성물을 직접 수정하지 않는다.
• 설정 파일만 바꾸고 packages/config의 로딩/default와 불일치하게 두지 않는다.