52 lines
2.6 KiB
Markdown
52 lines
2.6 KiB
Markdown
---
|
|
domain: workflow-execution
|
|
last_rule_review_commit: null
|
|
last_rule_updated_at: 2026-07-18
|
|
---
|
|
|
|
# workflow-execution
|
|
|
|
## 목적 / 책임
|
|
|
|
제어 플레인이 만든 workflow step을 lease하고 실행 상태를 보고한다. Go executor와 Python adaptation executor 사이의 버전 있는 실행 계약 및 취소·진행·결과 의미를 책임진다.
|
|
|
|
## 포함 경로
|
|
|
|
- `apps/worker/` — Go workflow worker 프로세스 조립과 실행 진입점
|
|
- `packages/go/workflow/` — step lease, executor registry, 재시도와 상태 전이
|
|
- `packages/python/` — Python gRPC executor와 adaptation 실행 구현
|
|
- `api/proto/` — Go/Python executor wire contract 원본
|
|
- `gen/go/rara/v1/` — Protobuf에서 생성된 Go 타입과 gRPC stub
|
|
|
|
## 제외 경로
|
|
|
|
- `packages/go/controlplane/`, `db/migrations/` — workflow 정의와 영속 상태의 소유권
|
|
- `packages/go/rag/` — 온라인 retrieve/answer 요청 처리
|
|
- `packages/go/integration/` — 제품 중립적인 외부 capability port
|
|
|
|
## 주요 구성 요소
|
|
|
|
- `workflow.Worker` — 실행 가능한 step을 lease하고 executor 결과에 따라 상태 갱신
|
|
- `workflow.Registry` — operation 이름과 Go executor 구현 연결
|
|
- `ExecutorService` — Python capability 조회, streaming 실행, 취소 gRPC 서비스
|
|
- `api/proto/rara/v1/executor.proto` — job, progress, artifact, error 계약
|
|
|
|
## 유지할 패턴
|
|
|
|
- worker identity, lease duration, retry delay를 설정에서 읽고 lease 소유권과 재시도 의미를 보존한다.
|
|
- executor operation과 capability는 명시적 이름과 버전으로 등록한다.
|
|
- ML 라이브러리 실행과 LoRA/QLoRA adaptation은 Python executor가 담당하고 제어 상태는 PostgreSQL이 소유한다.
|
|
- Protobuf 변경은 기존 field number를 재사용하지 않고 Go/Python 생성물을 `make proto`로 함께 갱신한다.
|
|
|
|
## 다른 도메인과의 경계
|
|
|
|
- **control-plane**: workflow와 job의 영속 상태는 control-plane 소유이며 이 도메인은 lease된 실행과 결과만 처리한다.
|
|
- **rag-data-plane**: 온라인 요청 경로를 worker에서 처리하지 않고, workflow가 만든 artifact를 release 승격 뒤 소비하게 한다.
|
|
- **platform-common**: database, config, observability, artifact와 integration port는 공통 adapter에 위임한다.
|
|
|
|
## 금지 사항
|
|
|
|
- `gen/go/rara/v1/`과 `packages/python/src/rara/v1/*_pb2*.py`를 직접 수정하지 않는다.
|
|
- lease 없이 step을 실행하거나 다른 worker 소유의 step 상태를 완료 처리하지 않는다.
|
|
- secret 원문이나 제품별 credential을 job payload와 추적 문서에 기록하지 않는다.
|
|
|