#1006 [docs] 실제 구현과 문서 내용 동기화 — 카탈로그·RCA 표준 검토 문서 정합

README.md

@@ -38,10 +38,10 @@
 └──────────────┬────────────┘
                │ provisioning
                ▼
-┌──────────────────────────────────────────────────────┐
-│  Kubernetes (EKS) · Strimzi Kafka                      │
-│  Debezium(source) → Kafka Topic → JDBC Connect(sink)   │
-└────────────────────────────────────────────────────────┘
+┌────────────────────────────────────────────────────────────┐
+│  Kubernetes (EKS) · Strimzi Kafka · Kafka Connect          │
+│  Debezium(source) → Kafka Topic → JDBC Connect(sink)       │
+└────────────────────────────────────────────────────────────┘
 ```
 
 - **operations-backend** (Spring Boot 모놀리스) — 플랫폼 API, 인증, datasource·pipeline 도메인, K8s/Kafka 자동화. 에이전트 전용 내부 API `/internal/ops/**`는 외부에 노출하지 않습니다.
@@ -59,7 +59,8 @@
 | Frontend | React, Vite, TypeScript, Tailwind CSS |
 | Data plane | Apache Kafka (Strimzi), Debezium, Kafka Connect (JDBC) |
 | Datastore | PostgreSQL(metadb), pgvector(agentdb), 테넌트 DB(PostgreSQL/MariaDB) |
-| Infra | AWS EKS, ArgoCD(GitOps), Harbor, Jenkins(CI/CD) |
+| Build/CI/CD | Gradle multi-module(`operations-backend`, `timestamptz-converter`), Jenkins(Kaniko), Harbor, Argo CD GitOps |
+| Infra | AWS EKS(Terraform), Strimzi, ingress-nginx+cert-manager, Sealed Secrets |
 | Observability | Prometheus, Grafana, Loki, Tempo |
 
 ## 빠른 시작
@@ -108,11 +109,20 @@ bifrost/
 │  ├─ operations-backend/    Spring Boot — 플랫폼 API·K8s/Kafka 자동화
 │  ├─ ai-service/            FastAPI — RCA 에이전트·LLM
 │  └─ frontend/              React UI
-├─ infra/                    Terraform·Helm·K8s manifest
+├─ connect-plugins/          Kafka Connect 커스텀 컨버터 Gradle 모듈
+├─ infra/                    Terraform·K8s manifest·CI/CD bootstrap
 ├─ scripts/                  로컬/배포 스크립트 (local-up.sh 등)
 └─ docker-compose.yml        로컬 의존 인프라
 ```
 
+## CI/CD·배포
+
+- Jenkins `bifrost-ci`는 `jenkins-values.yaml`의 JCasC/job-dsl로 생성되는 단일 Pipeline job이며, SCM 브랜치는 `*/main`, scriptPath는 루트 `Jenkinsfile`이다.
+- `main` push/webhook 빌드에서 직전 성공 커밋 대비 변경된 앱 서비스(`services/ai-service`, `services/operations-backend`, `services/frontend`)만 Kaniko로 빌드해 Harbor `harbor.harbor.svc.cluster.local/library/bifrost-<svc>:<git-sha>`와 `:latest`에 push한다.
+- `operations-backend`는 멀티모듈 Gradle 빌드라 Kaniko 컨텍스트가 레포 루트이고, `ai-service`와 `frontend`는 각 서비스 디렉터리를 컨텍스트로 쓴다.
+- `infra/docker/kafka-connect` 또는 `connect-plugins/` 변경 시 Kafka Connect 커스텀 이미지도 루트 컨텍스트로 빌드해 고정 태그 `1.0.0-converter`, git sha, `latest`로 Harbor에 push한다. 앱 서비스처럼 GitOps tag를 자동 변경하지는 않는다.
+- 앱 서비스 배포는 Jenkins가 `gitops` 브랜치의 `charts/<svc>/values.yaml` `image.tag`만 커밋하고, Argo CD `0-root-bifrost-root` app-of-apps가 `argocd/apps/`의 10개 child Application을 polling/reconcile해 적용한다.
+
 ## 개발
 
 브랜치·커밋·PR 컨벤션은 [docs/team/git-convention.md](docs/team/git-convention.md)를 따릅니다.

docs/README.md

@@ -60,6 +60,8 @@ Spring Boot Operations Backend
 | Agent run 상태(run·state·event·approval facade·report) | **FastAPI**(`agentdb`) | [contract-state-schema §14](./design/backend-fastapi/contract/contract-state-schema.md#14-contract-state-schema) |
 | Knowledge 코퍼스(RAG runbook·문서) | **FastAPI**(Vector Store) | [server-design §9](./design/backend-fastapi/server-design.md#2-server-design) |
 | Tool 매핑(논리 tool→operation) | **FastAPI** Tool Client Registry | [tool-catalog.md §8·§9](./design/backend-fastapi/tool-catalog.md#4-tool-catalog) |
+| CI 파이프라인·이미지 빌드 | **Jenkinsfile** + Jenkins JCasC | [infra/cicd README](../infra/cicd/README.md#ci-파이프라인-job-bifrost-ci) |
+| GitOps 배포 구조 | **gitops 브랜치** `argocd/`, `charts/`, `databases/`, `infra/`, `secrets/` | [infra.md §7](./design/infra.md#7-cicd) |
 | API 에러코드 | 표면별(각자 소유) | [Spring](./api/springboot.md) · [FastAPI](./api/fastapi.md) |
 | 인프라 현황(클러스터·용량) | 인프라 | [infra.md §2](./design/infra.md#2-리소스-계획현황-resource-plan) |
 

docs/adr/0004-monorepo-monolith.md

@@ -18,18 +18,18 @@ Frontend ─┬─► Spring Boot Operations Backend  (플랫폼 본체, 단일
 ## Decision
 
 1. **모노레포** 유지 (폴리레포 폐기).
-2. **Spring Boot는 단일 모놀리스** `services/operations-backend`로 통합한다.
+2. **Spring Boot는 단일 모놀리스** `services/operations-backend`로 통합한다. 현재 Gradle 모듈은 `services:operations-backend`와 Kafka Connect 이미지에 동봉되는 `connect-plugins:timestamptz-converter`만 포함한다.
    - `core-service` + `orchestrator-service` → `services/operations-backend` 병합.
    - base 패키지 `com.platform.*` → **`com.bifrost.ops`** 통일.
    - 패키지 구조는 설계 [springboot/DETAILS.md §5](../design/backend-springboot/server.md#5-패키지-구조)를 따른다.
-3. **Agent는 FastAPI(Python)** 로 별도 서비스 유지(`services/ai-service`). Spring Boot의 `/internal/ops`만 호출하며 K8s/Kafka에 직접 접근하지 않는다. (현재 Java 스캐폴드 → FastAPI 전환은 별도 이슈)
+3. **Agent는 FastAPI(Python)** 로 별도 서비스 유지(`services/ai-service`). Spring Boot의 `/internal/ops`만 호출하며 K8s/Kafka에 직접 접근하지 않는다.
 4. **`libs/common-dto` 흡수** — 모놀리스 내부 패키지로 옮기고 Gradle 모듈 제거. Spring ↔ FastAPI 계약은 공유 lib 대신 `/internal/ops` HTTP(JSON)/OpenAPI로 관리(언어가 갈리므로 공유 jar 불가).
 
 ## Consequences
 
 ### 긍정적
 - 서비스 간 호출/인증 경계 제거, `PipelineStatusService` in-process 단일 writer 그대로 구현.
-- 단일 빌드·배포물(Dockerfile/Helm 1개), 통합 테스트 단순화.
+- Spring 도메인은 단일 Gradle 모듈·단일 Dockerfile·단일 Helm release로 유지된다. 플랫폼 전체 배포 단위는 GitOps 브랜치의 `frontend`·`operations-backend`·`ai-service` 차트와 Kafka Connect 커스텀 이미지로 나뉜다.
 - 설계 문서(§2, §5)와 코드 구조 일치.
 
 ### 부정적

docs/api/fastapi.md

@@ -214,7 +214,7 @@ Spring Boot 내부 운영 API와 governance/mutation 계약은 [Spring Boot API
 | `GET` | `/api/v1/approvals/{approval_id}` | 구현됨 | 단일 approval 상세(`ApprovalSummary`). 없으면 `APPROVAL_NOT_FOUND` envelope |
 | `POST` | `/api/v1/agent/runs/{run_id}/approvals/{approval_id}/decision` | 미구현 | route 없음 |
 
-현재 FastAPI approval route는 local approval-link repository만 갱신한다. Spring Boot approval facade와 mutation single-use 검증 표면은 존재하지만, FastAPI executor는 Spring mutation 호출에 `X-Approval-Id`를 전달하지 않으므로 현재 실행 경로와 연결되어 있지 않다.
+현재 FastAPI approval route는 local approval-link repository를 갱신하고, 사용자 승인 후 Spring MutationGate용 pre-approved 레코드를 생성해 `spring_approval_id`를 저장할 수 있다. Executor는 approved action의 `approval_id`와 `change_ticket_id`를 `ToolContext`에 실어 Spring mutation 호출 시 `X-Approval-Id`/`X-Change-Ticket-Id`로 전달한다.
 
 ## 11. Change Management API
 
@@ -274,7 +274,7 @@ Incident, event, monitoring 목록/상세 조회는 Spring Boot 플랫폼 API가
 
 `POST /api/v1/tools/{tool_name}/execute`는 read-only slash command 실행 전용이다. tool이 없으면 HTTP 404 `TOOL_NOT_FOUND`, 대상 tool이 `RiskLevel.READ_ONLY`가 아니거나 `requires_approval`이면 HTTP 400 `POLICY_DENIED`로 거부한다. 실행은 `slash_command` agent 컨텍스트(`run_id=slash_...`)로 registry를 호출하고, tool 실패 시 Spring tool error code를 HTTP 400 envelope으로 그대로 전달한다. mutation tool은 이 route로 실행할 수 없다.
 
-FastAPI tool registry는 Agent의 논리 tool 목록이다. Spring Boot `GET /internal/ops/admin/tool-catalog`는 실제 Spring runtime endpoint catalog이며 현재 read operation과 approval-gated mutation operation을 함께 반환한다. 두 catalog의 목적과 범위는 다르다.
+FastAPI tool registry는 Agent의 논리 tool 목록이다. 현재 23개 logical tool(read-only 19개, approval-gated mutation 4개)을 반환하며, `get_kafka_lag`처럼 Spring operation 하나에 여러 논리 alias가 붙을 수 있다. Spring Boot `GET /internal/ops/admin/tool-catalog`는 실제 Spring runtime endpoint catalog이며 현재 22개 operation(read operation 18개, mutation 4개)을 반환한다. Spring mutation의 approval 필요 여부는 `PolicyGuard`가 결정하므로 FastAPI registry의 `requires_approval` flag와 목적이 다르다.
 
 ## 16. Feedback / Audit UI API
 

docs/api/internal-ops-read-tools.md

@@ -16,7 +16,7 @@
 
 ## Runtime Tool Catalog
 
-`GET /internal/ops/admin/tool-catalog`가 현재 Spring Boot에서 구현된 agent-callable internal-ops tool catalog를 반환한다. 현재 catalog에는 read operation과 approval-gated mutation operation이 함께 포함된다.
+`GET /internal/ops/admin/tool-catalog`가 현재 Spring Boot에서 구현된 agent-callable internal-ops tool catalog를 반환한다. 현재 catalog에는 18개 read operation과 4개 mutation operation이 함께 포함된다. mutation의 approval 필요 여부는 `PolicyGuard`가 operation risk와 workspace policy로 결정한다.
 
 | Operation | Spring endpoint | Status | Result 요약 |
 | --- | --- | --- | --- |
@@ -35,6 +35,9 @@
 | `get_pipeline_topology` | `GET /internal/ops/projects/{projectId}/pipelines/{pipelineId}/topology` | implemented | pipeline topology |
 | `get_connector_status` | `GET /internal/ops/projects/{projectId}/kafka/connectors/{connectorName}/status` | implemented | `PipelineProvisionStatus` |
 | `list_connectors` | `GET /internal/ops/projects/{projectId}/kafka/connectors/status` | implemented | connector status list |
+| `list_datasources` | `GET /internal/ops/projects/{projectId}/datasources` | implemented | datasource 목록, 역할, connection/readiness 상태 |
+| `get_cluster_info` | `GET /internal/ops/projects/{projectId}/kafka/cluster` | implemented | Kafka broker/controller/topic partition 상태 |
+| `sql_read` | `POST /internal/ops/projects/{projectId}/datasources/{datasourceId}/query` | implemented | datasource read-only SELECT 결과 |
 | `restart_connector` | `POST /internal/ops/projects/{projectId}/connectors/{connectorName}/restart` | implemented | approval/idempotency-gated mutation |
 | `pause_connector` | `POST /internal/ops/projects/{projectId}/connectors/{connectorName}/pause` | implemented | approval/idempotency-gated mutation |
 | `resume_connector` | `POST /internal/ops/projects/{projectId}/connectors/{connectorName}/resume` | implemented | approval/idempotency-gated mutation |
@@ -59,4 +62,4 @@ Health/metadata endpoints(`health`, `ready`, `version`)도 `/internal/ops`에 
 
 ## 구현 범위 밖
 
-FastAPI tool registry에는 Agent 설계용 논리 tool alias도 포함된다. Spring `tool-catalog`는 runtime에서 실제 호출 가능한 operation 이름을 반환하므로 FastAPI의 `get_metrics`/`get_deployments`는 각각 Spring `query_metrics`/`get_recent_changes`에 대응하고, `get_kafka_lag`는 `get_consumer_lag`의 FastAPI alias다. 실행 가능한 Spring mutation subset은 [Spring Boot API §6.4](./springboot.md#64-mutation-endpoints)에 별도로 문서화되어 있다.
+FastAPI tool registry에는 Agent 설계용 논리 tool alias도 포함된다. Spring `tool-catalog`는 runtime에서 실제 호출 가능한 operation 이름을 반환하므로 FastAPI의 `get_metrics`/`get_deployments`/`get_alerts`/`get_traces`는 각각 Spring `query_metrics`/`get_recent_changes`/`list_alerts`/`query_traces`에 대응하고, `get_kafka_lag`는 `get_consumer_lag`의 FastAPI alias다. 실행 가능한 Spring mutation subset은 [Spring Boot API §6.4](./springboot.md#64-mutation-endpoints)에 별도로 문서화되어 있다.