85 lines
6.3 KiB
Markdown
85 lines
6.3 KiB
Markdown
# 구조
|
|
|
|
## 책임 분리
|
|
|
|
Ariadne는 오류 처리 생명주기의 기준 시스템이다.
|
|
|
|
```text
|
|
오류 발생 시스템
|
|
↓
|
|
Ariadne
|
|
├─ 오류 표준화와 중복 판별
|
|
├─ 조직·프로젝트·저장소·실행 환경 관리
|
|
├─ 분석 및 수정 작업 흐름
|
|
├─ 보고·승인·병합 요청
|
|
└─ 감사 기록
|
|
↓
|
|
IOP
|
|
├─ LLM 호출
|
|
├─ CLI 작업
|
|
└─ 작업 스트림과 결과
|
|
```
|
|
|
|
IOP가 일시적으로 사용할 수 없어도 Ariadne는 오류를 잃지 않고 작업을 대기 또는 실패 상태로 기록해야 한다.
|
|
|
|
## 조직 격리
|
|
|
|
조직은 최상위 소유 단위다. 프로젝트, 저장소, 실행 환경, 오류 묶음, 오류 발생 기록, 수정 작업과 감사 기록은 모두 `organization_id`를 필수로 가진다.
|
|
|
|
외부 요청 본문이나 임의의 헤더가 조직을 선택하지 않는다. 인증된 사용자 또는 조직에 귀속된 입력 자격 증명에서 조직 범위를 얻는다. 데이터 접근 계층의 모든 조회와 변경은 조직 범위를 명시적으로 요구한다.
|
|
|
|
오류 입력 자격 증명은 `ingestion_source` 하나에 귀속되며 조직과 프로젝트를 함께 결정한다. 같은 사건 식별자의 멱등성 범위도 입력 출처 안으로 제한해 서로 다른 송신자의 식별자가 충돌하지 않게 한다.
|
|
|
|
초기 데이터 구조는 복합 외래 키와 PostgreSQL 행 수준 보안 정책으로 다른 조직의 데이터를 참조하지 못하도록 한다.
|
|
|
|
서버 실행 역할은 테이블 소유자가 아니며 행 보안 우회 권한도 갖지 않는다. 마이그레이션은 별도 역할과 실행 명령이 담당한다. 애플리케이션의 조직 소유 데이터 접근은 조직 범위를 설정한 단일 트랜잭션 안에서만 수행한다.
|
|
|
|
사용자 신원과 사용자가 참여한 조직 목록을 찾는 초기 인증 경로는 읽기 전용 신원 데이터베이스 역할로 분리한다. 이 역할은 `issuer + subject`로 사용자와 활성 멤버십을 조회할 수 있지만 프로젝트·오류·수정 데이터에는 접근할 수 없다. 조직이 선택된 뒤의 업무 데이터는 일반 실행 역할과 조직 범위 트랜잭션을 사용한다.
|
|
|
|
최초 사용자·조직 생성 경로는 아직 이 스캐폴드에 노출하지 않는다. 이후 구현할 때는 인증이 끝난 별도 관리 경계와 감사 기록을 사용해야 하며, 읽기 전용 신원 역할이나 일반 실행 역할에 전역 생성 권한을 추가하지 않는다. 마이그레이션 역할도 요청 처리 경로에서 재사용하지 않는다.
|
|
|
|
조직 구성원은 탈퇴 시 행을 삭제하지 않고 탈퇴 시각을 기록한다. 사용자 행위가 남은 감사 기록은 해당 조직의 구성원 이력을 참조하므로, 탈퇴 후에도 책임 추적 관계가 보존된다.
|
|
|
|
서버 실행 역할은 감사 기록에 조회·추가만 할 수 있고 수정·삭제할 수 없다. 조직 구성원 이력도 물리 삭제 권한을 주지 않으며 탈퇴 시 상태만 변경한다.
|
|
|
|
수정 전 보고 방식의 승인과 거부는 별도 불변 기록으로 보관한다. 승인 기록은 분석 결과에서 생성한 수정안 해시를 참조하므로, 승인 뒤 수정안이 바뀌면 같은 승인으로 실행할 수 없다.
|
|
|
|
## 모듈형 단일 서버
|
|
|
|
초기에는 API, 작업 흐름과 배경 작업을 하나의 Go 배포 단위에 둔다. 코드 모듈은 분리하지만 네트워크 서비스는 불필요하게 나누지 않는다.
|
|
|
|
다음 조건이 실제로 발생하면 실행 단위를 분리할 수 있다.
|
|
|
|
- 오류 입력량과 분석 작업량의 확장 특성이 크게 달라짐
|
|
- 장시간 작업이 API 서버 안정성에 영향을 줌
|
|
- 원격 환경에 별도 수집기 설치가 필요함
|
|
|
|
분리하더라도 도메인 계약과 데이터 소유권은 Ariadne에 유지한다.
|
|
|
|
## 연동 경계
|
|
|
|
외부 시스템은 범용 HTTP/JSON 오류 입력 계약을 사용한다. Ariadne와 IOP 사이에는 작업 요청, 상태 이벤트, 결과, 취소와 표준 실패 원인 스택을 담는 버전 계약을 사용한다.
|
|
|
|
IOP 연결 구현은 `internal/integration/iop` 아래의 실행 인터페이스를 구현한다. 도메인 모듈은 IOP의 전송 방식이나 모델 요청 형식을 알지 않는다.
|
|
|
|
IOP에는 비밀값 대신 작업 공간과 접속 정보의 불투명 참조만 전달한다. 분석 작업은 저장소 읽기 전용, 수정 작업은 격리된 작업 가지로 제한한다. 운영 환경은 항상 읽기 전용이며 IOP에는 병합 권한을 주지 않는다.
|
|
|
|
수정 작업 요청에는 분석 결과의 수정안 해시를 다시 전달한다. 수정 전 보고 방식에서는 승인 기록의 해시와, 자동 수정 후 보고 방식에서는 정책이 허용한 분석 결과의 해시와 일치할 때만 수정 단계로 넘어간다.
|
|
|
|
하나의 수정 작업에서 분석과 수정 실행이 각각 여러 번 시도될 수 있으므로 IOP 실행은 별도 이력으로 보관한다. 각 실행은 목적, 시도 번호, 요청에 사용한 수정안 해시, 상태와 표준 실패를 기록하며 이전 시도를 덮어쓰지 않는다.
|
|
|
|
## 분석 대상 선택
|
|
|
|
프로젝트는 여러 저장소와 운영 환경을 가질 수 있다. 오류 입력 출처와 `source.system`, `source.service`, `source.environment`, `source.component`를 분석 대상 규칙과 대조한다.
|
|
|
|
- 규칙의 비어 있는 선택 조건은 모든 값과 일치한다.
|
|
- 숫자가 낮은 우선순위부터 평가한다.
|
|
- 프로젝트 안에서 우선순위는 중복될 수 없으며 처음 일치한 규칙을 사용한다.
|
|
- 규칙은 저장소 하나와 운영 환경 0개 이상을 가리킨다.
|
|
- 실제 수정 작업은 선택된 저장소와 기준 리비전, 운영 환경 목록을 실행 기록에 복사해 이후 규칙 변경의 영향을 받지 않는다.
|
|
|
|
## 운영 환경 연결
|
|
|
|
저장소 분석만 사용하는 프로젝트와 저장소·운영 환경을 함께 분석하는 프로젝트를 모두 지원한다. 원격 접속 또는 환경 수집기는 분석 자료 공급자이며 처리 방식과 독립된 설정 축이다.
|
|
|
|
운영 환경 분석은 읽기 전용이다. 비밀값은 참조 식별자로 관리하고 LLM 입력에 직접 포함하지 않는다. 쓰기 기능은 별도 권한·승인 경계가 설계되기 전까지 데이터 모델과 IOP 요청에서 표현할 수 없다.
|