57 lines
3.3 KiB
Markdown
57 lines
3.3 KiB
Markdown
# platform-common
|
|
|
|
## 목적 / 책임
|
|
|
|
여러 앱이 공유하는 설정, 인증, 정책, 메타데이터, 작업 상태, 관측성, 버전, protobuf 계약을 관리한다. 앱별 구현보다 안정적인 공통 계약과 작은 유틸리티를 제공하며, 내부 실행 계약은 `adapter + target` 방향을 우선한다.
|
|
|
|
## 포함 경로
|
|
|
|
- `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/` — 실행 그룹 컨트롤러와 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` — 비동기 작업 상태 placeholder; 내부 실행 대상은 `target`으로 표현
|
|
- `proto/iop/*.proto` — 앱 간 메시지 원본 계약
|
|
|
|
## 유지할 패턴
|
|
|
|
- 공통 패키지는 특정 앱의 내부 패키지를 import하지 않는다.
|
|
- 설정 struct 필드 변경 시 YAML tag, mapstructure tag, default, `configs/*.yaml` 예시를 함께 확인한다.
|
|
- protobuf 계약 변경은 `proto/iop/*.proto`에서 시작하고 `make proto`로 생성물을 갱신한다.
|
|
- 생성 파일(`proto/gen/iop/*.pb.go`)은 사람이 직접 편집하지 않는다.
|
|
- 공통 패키지는 작고 명확한 계약을 유지하고 앱별 정책을 과도하게 끌어올리지 않는다.
|
|
- `RunRequest`, `ExecutionSpec`, `NodeCommandRequest`, job/history 계열 계약을 변경할 때 내부 실행 용어는 `target`을 우선하고, `model`은 외부 호환 경계인지 확인한다.
|
|
|
|
## 다른 도메인과의 경계
|
|
|
|
- **node**: node가 필요로 하는 설정/타입/계약을 제공하지만 실행 파이프라인의 소유자는 node이다.
|
|
- **edge**: edge가 필요로 하는 설정/관측성/protobuf 계약을 제공하지만 실행 그룹 제어와 node registry 동작의 소유자는 edge이다.
|
|
- **control-plane/worker 후보**: 두 앱이 구현되면 필요한 공통 타입만 이 영역으로 승격하고 앱 내부 책임은 각 도메인에 둔다.
|
|
|
|
## 금지 사항
|
|
|
|
- `packages`에서 `apps/*/internal` 패키지를 import하지 않는다.
|
|
- 앱 하나만을 위한 임시 타입을 충분한 근거 없이 공통 패키지로 승격하지 않는다.
|
|
- 내부 실행 계약을 확장하면서 `model` 중심 명명을 되살리지 않는다. 외부 API 호환이 필요한 경우 경계와 변환 위치를 명시한다.
|
|
- protobuf 생성물을 직접 수정하지 않는다.
|
|
- 설정 파일만 바꾸고 `packages/config`의 로딩/default와 불일치하게 두지 않는다.
|