docs(admin-ops) spec write[#55]

docs/Diagram/sequence_diagram/SD_Mermaid.md

@@ -141,4 +141,190 @@ SS->>LLM: LLM 답변 생성 직접 요청 (Direct SDK)<br/>generate_answer(query
 LLM-->>SS: answer (+ cited_chunk_ids)
 
 SS-->>C: 최종 응답 반환<br/>{answer, timestamps, topk_chunk_ids, cited_chunk_ids}
+```
+
+# 4. Feedback Loop
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant CoreAPI as Core API Server
+    participant MetaDB as Metadata DB
+    participant FIP as Feedback Ingestion Pipeline
+    participant ObjStore as Object Storage
+    participant MLWorker as ML Lifecycle Worker
+    participant ModelFiles as Model Artifact Files
+    participant MEE as Managed Embedding Endpoint
+    participant VS as Vector Store
+
+    %% === 피드백 수집 (2.6) ===
+    rect rgb(230, 245, 255)
+    Note over Client, ObjStore: 피드백 수집 
+    Client ->> CoreAPI: 검색 응답 단위 피드백 (req_id, rating)
+    CoreAPI ->> CoreAPI: 사용자 권한 검증
+    CoreAPI ->> MetaDB: req_id 검색 응답 스냅샷 조회
+    MetaDB -->> CoreAPI: 스냅샷
+    CoreAPI ->> CoreAPI: 피드백 유효성 검증<br/>(동일 사용자, 허용 시간, 무효화 여부)
+    CoreAPI ->> FIP: 검증된 피드백 이벤트 전달<br/>(질의, 응답, 활성 모델/인덱스 정보 포함)
+    FIP ->> ObjStore: 원본 이벤트 로그 적재
+    end
+
+    %% === 데이터셋 전처리 (2.7) ===
+    rect rgb(245, 255, 230)
+    Note over MLWorker, ObjStore: 피드백 데이터셋 생성 - 정기 배치 <br/>운영자 수동 트리거도 가능
+    MLWorker ->> ObjStore: 신규 피드백 원본 로그 읽기
+    ObjStore -->> MLWorker: 원본 로그
+    MLWorker ->> MLWorker:  서빙 맥락(모델 버전, 인덱스)이 기록된 이벤트만<br/>학습 데이터셋으로 변환
+    MLWorker ->> ObjStore: 학습용 피드백 데이터셋 저장
+
+    alt 실행 중인 MLPipelineRun 없음
+        MLWorker ->> MLWorker: 학습 파이프라인 자동 트리거
+    else 실행 중인 MLPipelineRun 존재
+        MLWorker ->> MLWorker: 최신 데이터셋 기준 다음 실행 대기 등록
+        Note over MLWorker: 이전 대기 실행은 SUPERSEDED 처리
+    end
+    end
+
+    %% === 모델 재학습 및 재색인  ===
+    rect rgb(255, 245, 230)
+    Note over MLWorker, VS: 모델 재학습 및 재색인 
+
+    %% 학습
+    MLWorker ->> ObjStore: 학습용 데이터셋 읽기
+    ObjStore -->> MLWorker: 학습 데이터셋
+    MLWorker ->> MLWorker: 후보 임베딩 모델 학습
+    MLWorker ->> ModelFiles: 후보 모델 저장
+    MLWorker ->> MetaDB: MLPipelineRun 생성
+
+    %% 평가
+    MLWorker ->> ObjStore: 평가용 데이터셋 읽기
+    ObjStore -->> MLWorker: 평가 데이터셋 (immutable versioned artifact)
+    MLWorker ->> MLWorker: 후보 모델 vs 기준 모델 비교 평가
+    MLWorker ->> MetaDB: 평가 결과 집계 저장
+    MLWorker ->> ObjStore: 평가 질의별 상세 아티팩트 저장
+
+    alt 평가 PASS
+        MLWorker ->> MEE: 후보 모델 로드
+        MEE -->> MLWorker: readiness 확인
+        MLWorker ->> MEE: 재색인용 임베딩 요청 (후보 모델)
+        MEE -->> MLWorker: 임베딩 벡터
+        MLWorker ->> VS: 후보 인덱스 구축
+        Note over MLWorker, VS: 전환 기준 시각까지 데이터 반영 +<br/>후보 모델 readiness 모두 확인
+        Note over MLWorker, VS: 재색인 중 신규 유입 데이터는<br/>기존 서빙 유지하며 후보 인덱스에도 반영
+        MLWorker ->> MEE: 서빙 모델 전환
+        MLWorker ->> MetaDB: ModelRelease 갱신 (서빙 전환)
+        Note over MLWorker: 이전 모델/인덱스 정보 롤백용 보존
+    else 평가 FAIL 또는 시스템 ERROR
+        MLWorker ->> MetaDB: MLPipelineRun 실패 단계 및 유형 기록
+        Note over MLWorker, MetaDB: 기존 서빙 유지,<br/>Admin Dashboard에서 실패 상태 확인 가능
+    end
+    end
+
+```
+
+# 5. Admin_Video_Ops
+```mermaid
+sequenceDiagram
+    participant Admin as Admin Dashboard
+    participant CoreAPI as Core API Server
+    participant MetaDB as Metadata DB
+    participant Broker as Message Broker
+    participant PipelineWorker as Media & AI Pipeline Worker
+    participant ObjStore as Object Storage
+
+    Note over Admin, CoreAPI: 모든 Admin 요청은 JWT claim role 기반 운영자 권한 검증,<br/>소유권(user_id) 제한 없이 모든 리소스 접근
+
+    %% === 파이프라인 상태 조회 ===
+    rect rgb(230, 245, 255)
+    Note over Admin, MetaDB: 파이프라인 상태 조회 
+    Admin ->> CoreAPI: 임의 video_id 처리 현황 조회 
+    CoreAPI ->> MetaDB: Video 상태 및 실패 상세 조회
+    MetaDB -->> CoreAPI: 처리 현황, failed_stage, error_message
+    CoreAPI -->> Admin: 처리 현황 및 실패 상세 응답
+    end
+
+    %% === 재처리 ===
+    rect rgb(245, 255, 230)
+    Note over Admin, PipelineWorker: 비디오 재처리 
+    Admin ->> CoreAPI: 임의 video_id 재처리 요청 
+    CoreAPI ->> MetaDB: 현재 Video.status 확인
+    MetaDB -->> CoreAPI: 현재 상태
+    Note over CoreAPI: 재처리 가능 상태인지 검증 후 진행
+    CoreAPI ->> MetaDB: Video.status를 PENDING으로 초기화
+    CoreAPI ->> Broker: PREPROCESS_REQUEST 발행
+    CoreAPI -->> Admin: 202 Accepted
+    Broker ->> PipelineWorker: PREPROCESS_REQUEST 전달
+    PipelineWorker ->> MetaDB: Video 정보 로드, failed_stage 확인
+    MetaDB -->> PipelineWorker: failed_stage, 보존 산출물 정보
+    PipelineWorker ->> PipelineWorker: 완료된 작업 Skip, 안전한 재개 지점부터 Resume
+    end
+
+    %% === 삭제 ===
+    rect rgb(255, 245, 230)
+    Note over Admin, ObjStore: 비디오 삭제 
+    Admin ->> CoreAPI: 임의 video_id 삭제 요청 
+    CoreAPI ->> MetaDB: Video.status를 DELETING으로 전이
+    Note over MetaDB: 이 시점부터 검색 범위에서 즉시 제외
+    CoreAPI ->> Broker: DELETE_REQUEST 발행
+    CoreAPI -->> Admin: 202 Accepted
+    Broker ->> PipelineWorker: DELETE_REQUEST 전달
+    PipelineWorker ->> MetaDB: VectorIndexEntry, Chunk,<br/>TranscriptSegment, Asset 삭제 (단일 트랜잭션)
+    PipelineWorker ->> MetaDB: Video 레코드 hard-delete
+    PipelineWorker ->> ObjStore: 원본 영상, 오디오, 키프레임 삭제 (비동기)
+    Note over PipelineWorker: 수집 피드백 이벤트 및 학습 데이터셋은 보존
+    end
+```
+
+#6. Admin_ML(feedback_loop)_Ops
+```mermaid
+sequenceDiagram
+    participant Admin as Admin Dashboard
+    participant CoreAPI as Core API Server
+    participant MetaDB as Metadata DB
+    participant Broker as Message Broker
+    participant MLWorker as ML Lifecycle Worker
+    participant ModelFiles as Model Artifact Files
+    participant MEE as Managed Embedding Endpoint
+    participant VS as Vector Store
+
+    Note over Admin, CoreAPI: 모든 Admin 요청은 JWT claim role 기반 운영자 권한 검증
+
+    %% === ML 파이프라인 상태 조회 ===
+    rect rgb(230, 245, 255)
+    Note over Admin, MetaDB: ML 파이프라인 상태 조회 
+    Admin ->> CoreAPI: MLPipelineRun 상태 조회 
+    CoreAPI ->> MetaDB: MLPipelineRun 진행 상태 및 실패 현황 조회
+    MetaDB -->> CoreAPI: 실행 상태, 실패 단계/유형,<br/>대기 실행 유무, FAIL/ERROR 구분
+    CoreAPI -->> Admin: ML 파이프라인 현황 응답
+    end
+
+    %% === ML 파이프라인 수동 재트리거 ===
+    rect rgb(245, 255, 230)
+    Note over Admin, MLWorker: ML 파이프라인 수동 재트리거 
+    Admin ->> CoreAPI: ML 파이프라인 재트리거 요청 
+    CoreAPI ->> MetaDB: MLPipelineRun 상태 확인
+    MetaDB -->> CoreAPI: 현재 실행 상태
+    CoreAPI ->> MetaDB: MLPipelineRun 상태 갱신
+    CoreAPI ->> Broker: ML 재트리거 작업 발행
+    CoreAPI -->> Admin: 202 Accepted
+    Broker ->> MLWorker: 재트리거 작업 전달
+    MLWorker ->> MLWorker: 파이프라인 재트리거 (실패한 경우 실패 지점부터 재개)
+    end
+
+    %% === 모델 롤백 ===
+    rect rgb(255, 245, 230)
+    Note over Admin, VS: 모델 롤백 
+    Admin ->> CoreAPI: 모델 롤백 요청 
+    CoreAPI ->> Broker: 롤백 작업 발행
+    CoreAPI -->> Admin: 202 Accepted
+    Broker ->> MLWorker: 롤백 작업 전달
+    MLWorker ->> ModelFiles: 롤백 대상 모델 아티팩트 조회
+    ModelFiles -->> MLWorker: 이전 모델 아티팩트
+    MLWorker ->> MEE: 롤백 대상 모델 로드
+    MEE -->> MLWorker: readiness 확인
+    Note over VS: 이전 인덱스는 서빙 전환 시점에 롤백 대비용으로 보존됨
+    MLWorker ->> VS: 이전 인덱스 활성화
+    MLWorker ->> MetaDB: ModelRelease 복원 (이전 모델 버전 + 이전 인덱스)
+    end
+
 ```