# CLO-1266 리소스 수집 흐름 정본

이 저장소는 여러 조사 결과를 현재 코드와 로컬 실행 증거로 다시 대조해 만든
CLO-1266 통합 정본이다. 기존 문서를 이어 붙이지 않고 서로 다른 강점은 합쳤으며,
표현이 충돌하는 부분은 2026-07-31 현재 소스에서 다시 확인했다. 특히 다음 세
가지를 바로잡았다.

1. **Account 등록과 리소스 수집은 연속된 자동 흐름이 아니다.** 등록 시 Temporal
   heartbeat로 자격증명을 확인하고 계정·secret을 저장하지만, 실제 수집은
   `POST /resources/collect` 또는 `daily-collect`가 별도로 시작한다.
2. **수집과 CSP event는 실행 기반이 다르다.** 리소스 수집·후처리는 Temporal,
   webhook→normalize→alert→ticket은 NATS JetStream 경로다.
3. **코드 기본값과 운영 배포 사실을 구분한다.** 예를 들어 로컬 기본 연결은
   `localhost:7233`이고 현재 client factory에 TLS 인자가 없지만, 이것만으로
   운영 클러스터의 네트워크·TLS 구성을 단정하지 않는다.

## 무엇을 읽으면 되는가

정본은 **읽는 문서 2개와 클릭형 HTML 1개**로 구성한다.

| 순서 | 질문 | 문서 |
|---|---|---|
| 1 | Temporal은 무엇이고 어떤 원칙으로 써야 하는가? | [01-temporal-concepts.md](01-temporal-concepts.md) |
| 2 | CloudOps 어디에 적용됐고 Account 등록부터 티켓까지 어떻게 이어지는가? | [02-cloudops-application-flow.md](02-cloudops-application-flow.md) |
| 3 | 전체 구조를 한눈에 보고 단계를 눌러 확인하려면? | [index.html](index.html) |

01은 계정 수집 예시부터 시작해 Workflow·Activity·Worker·Task Queue를 설명하고,
결정성·멱등성·재시도, gRPC, Worker/Scheduler 실행 모델, Kubernetes 종료 원칙과
Web UI를 뒤에서 단계적으로 다룬다.
02에는 실제 CloudOps 프로세스와 queue, Account 등록, 수집, relationship/mapping,
Well-Architected ticket, CSP event→alert ticket의 정확한 경로를 담는다. 특히
Temporal Workflow를 만드는 다섯 시작점과 단계별 DB 기록 시점·물리 테이블을
별도 지도로 정리했다.

처음 볼 때는 `HTML → 01 → 02`, CLO-1266 설계 검수 때는 `02 → HTML` 순서가
빠르다. 별도 운영 런북은 두지 않는다.

## 검증 수준을 읽는 법

| 표기 | 의미 |
|---|---|
| `CODE` | 아래 소스 스냅샷에서 정적 코드 계약을 확인했다. |
| `E2E-LOCAL` | 실제 Core REST·Temporal·Core Activity·Postgres·ticket 코드를 로컬에서 실행했다. 외부 AWS/KMS/Secrets Manager/API 경계만 로컬 어댑터로 대체했다. |
| `TRACE` | 실제 Workflow 정의를 실행했지만 Activity는 stub으로 대체해 순서와 대기 관계를 검증했다. |
| `DOC` | Temporal·Kubernetes 공식 문서에 근거한다. |
| `OPS-UNKNOWN` | 현재 작업공간만으로 운영 배포값이나 실제 가동 상태를 확정할 수 없다. |

`E2E-LOCAL`은 “AWS 실계정까지 포함한 운영 E2E”가 아니다. 반대로 단순 모형도
아니다. 계정 REST 처리, Temporal Workflow/Activity, Core DB 저장, WA 평가와 티켓
reconcile은 실제 코드를 사용했고 외부 자격증명 경계만 합성했다.

## 조사 기준 소스

모든 원격은 Forgejo(`git.sdlc.megaone.com`)를 가리킨다. 문서 내용은 아래 checkout
기준이며, `develop`을 최신 브랜치로 가정하지 않았다.

| 프로젝트 | 기준 브랜치 | 커밋 |
|---|---|---|
| `code/base` | `release/cloudops-1.4.0` | `90a4ba3` |
| `code/core` | `release/cloudops-1.4.0` | `c86c6f59` |
| AWS resource collector | `master` | `5b8e034` |
| Azure resource collector | `master` | `b907e13` |
| GCP resource collector | `master` | `b50c4d0` |
| `cloudops-db-schema` | `master` | `8d3e4dc` |

AWS collector에는 조사 전부터 존재하던 untracked
`scripts/diff_recheck_job.json`이 있으며 본 작업은 이를 수정하지 않았다.
사용자 지시에 따라 `code/docs`와 `poc-skeleton-plugin`은 판단 근거에서 제외했다.

## 범위

포함:

- CSP Account 등록 시 자격증명 확인과 저장 경계
- 자격증명 검증·수동/일일 수집·계정 삭제 후처리의 다섯 Workflow 시작점
- 계정별 plan → collect → upsert → 상태 확정
- relationship extract → promote → VPC materialize → mapping
- Well-Architected 평가 → finding → ticket reconcile
- CSP webhook 수신 → normalize → alert grouping → alert ticket
- Worker, task queue, scheduler, gRPC, Temporal Web UI
- 단계별 DB 쓰기 시점, transaction 경계와 실행 원장 공백
- 멱등성·결정성·재시도·payload·배포·Kubernetes 종료 원칙

제외:

- 비용/FinOps 집계와 대시보드
- 운영 EKS/Temporal 배포값의 추정
- 실제 CSP 자격증명을 사용한 재실행
- 기존 두 원본 폴더의 삭제나 변경

## 로컬 Temporal UI

이번 조사에서 사용한 dev server가 계속 실행 중이라면 다음 주소에서 볼 수 있다.

- Web UI: <http://localhost:8233>
- gRPC Frontend: `localhost:7233`
- Namespace: `default`

실행 목록에서 `resource-collection-run-e6beb746`를 검색하면 부모·자식 관계를,
`heartbeat-aws-1ce13929`를 검색하면 Account 등록 중 credential validation을 볼 수
있다. 서버가 내려갔다면 정본 폴더에서 다음과 같이 다시 기동한다.

```bash
mkdir -p .local
temporal server start-dev \
  --ip 127.0.0.1 \
  --port 7233 \
  --ui-port 8233 \
  --db-filename .local/temporal.db
```

## 산출물 관리 원칙

- 이 저장소의 `main`이 팀 공유용 정본이다.
- `runtime/*.db`, 캐시, `__pycache__`는 정본에 복제하지 않는다.
- 스크린샷은 합성 테스트임을 숨기지 않고 검증 수준과 Workflow ID를 함께 기록한다.
- 코드가 바뀌면 README의 source snapshot과 02 문서의 단계 표를 먼저 갱신하고,
  HTML의 `flow-data.js`를 같은 변경으로 맞춘다.
- Claude Code 검수 시에는 문장 다듬기보다
  `실행 주체 / 전이 조건 / 실패 동작 / 순서 이유 / 검증 수준` 다섯 열의 사실
  일치 여부를 우선 확인한다.