Glossary

용어집

develop 04c0e10 (2026-10-27) 기준

위키와 코드에 나오는 도메인 용어, 상태값, 기술 용어를 한곳에 모았다. 같은 개념을 여러 페이지가 다르게 설명하던 곳은 코드를 기준으로 한 줄로 맞췄고, 용어마다 코드에서 쓰는 이름을 함께 적어 위키 용어로 코드를 찾아갈 수 있게 했다.

arc42 12절 용어집(Glossary) 형식을 따른다. "코드 이름"은 코드베이스에서 실제로 쓰는 클래스·enum·컬럼·설정 키를 그대로 적었고, 코드 이름이 없는 개념은 —로 둔다. 용어와 코드 이름이 다르면 코드 이름이 맞다. 각 절 안은 한글 용어를 가나다순으로, 그 뒤에 영문 용어를 알파벳순으로 놓았다. 상태 사이의 전이는 레포 문서에, 각 결정의 경위는 결정 로그에 있다.

도메인 용어

용어	뜻	코드 이름
검수	손해사정사가 AI 초안을 검토·수정해 자기 의견을 붙이는 일	ReportReview
검수 대기 목록	손해사정사가 검수할 사건을 고르는 목록. 지역·사고 유형으로 거른다	PendingReviewController
검수본	손해사정사별로 격리된 검수 작업본. 리포트당 손해사정사 한 명에 한 행이다	ReportReview (report_reviews)
경쟁 검수	같은 AI 초안을 여러 손해사정사가 서로 격리된 채 각자 검수하고, 사용자가 그중 하나를 고르는 구조	—
리포트	사용자가 접수한 사고 건과 그에 대한 AI 초안. 원본 콘텐츠는 바뀌지 않고 생명주기 상태만 바뀐다	Report (reports)
무음 실패	실패가 어떤 이벤트로도 알려지지 않아 사용자가 알 수 없는 상태. 스윕러로 알림을 보내 없앤다	—
보류	손해사정사가 당장 볼 수 없는 사건을 사유와 함께 검수 대기 목록에서 빼 두는 것	ReportHold (report_holds), HoldReason
사건번호	사람이 부르는 리포트 식별자. yyyyMMdd-NNNNNN 형식이고 전역 시퀀스로 발급해 번호 빈틈이 생길 수 있다	case_no, CaseNoGenerator, core.report_case_seq
상담 시작(상담 수락)	사용자가 제안 하나를 골라 그 손해사정사와 채팅방을 여는 행동. 제안과 리포트가 COUNSELING이 된다	PATCH /reports/{reportId}/proposals/{proposalId}
스켈레톤	검수 제출 때 별도 트랜잭션으로 먼저 확보해 두는 빈 검수본 행	ReportReviewSkeletonInitializer
실패 사유	확정 실패의 대표 원인. 재업로드로 풀리는 UNREADABLE_FILE을 가장 낮은 우선순위에 둬 다른 사유와 섞이면 고르지 않는다	AnalysisFailureReason
실패 저널	AI 워커가 OCR 작업 실패를 기록하는 AI 소유 테이블. 일시 실패와 확정 실패를 terminal로 구분하고, 백엔드는 SELECT만 한다	ai.ocr_job_failures, OcrJobFailureView
알림 타입	인앱 알림·푸시의 종류. 시스템 실패 통지는 도메인 접두어를 붙이고 수신 설정과 무관하게 항상 보낸다	NotificationType (ANALYSIS_FAILED, REPORT_BLOCKED, REPORT_NEEDS_REUPLOAD 등)
읽음 커서	채팅방의 참여자별 마지막 읽은 시각. 안 읽은 메시지 수를 세는 기준이다	ChatRoom.markRead, user_last_read_at·adjuster_last_read_at
자격 신청	손해사정사가 등록번호·자격증·등록증을 내고 관리자 승인을 받는 절차	AdjusterApplication
쟁점	보상에 영향을 주는 판단 항목. AI가 뽑은 쟁점과 손해사정사가 추가한 쟁점이 있다	ReportIssue, ReportReviewIssue (report_issues_reviews)
제안	사용자에게 전달된 손해사정사의 검수본. 검수본과 같은 행이며 API에서는 proposal이라 부른다	ReportReview, ReviewStatus
채택(담당 확정)	사용자가 채팅방에서 손해사정사를 담당으로 확정하는 것. 리포트는 CLOSED, 제안은 ACCEPTED가 된다	Report.accept(), PATCH /chats/{chatRoomId}/accept
형제 제안	같은 리포트에 달린 다른 손해사정사의 제안. 한 제안이 담당으로 확정되면 나머지는 REJECTED가 된다	—
AI 초안	AI 워커가 만든 보상 분석 결과. 사용자에게 직접 보여주지 않고 손해사정사 검수를 거친다	reports, ReportIssue (report_issues)
B2B2C	AI → 손해사정사 → 사용자 순으로 결과가 전달되는 서비스 구조	—
OCR 트리거	AI 워커에 OCR과 초안 생성을 시작하라고 보내는 SQS 메시지. 문서 1건당 하나를 보낸다	OcrJob

상태값

용어	뜻	코드 이름
리포트 상태	리포트의 검수·매칭 생명주기. 정상 흐름은 AWAITING_INSPECTION → AWAITING_ADOPTION → COUNSELING → CLOSED다	ReportStatus (reports.status)
분석 처리 상태	OCR·AI 분석이 어디까지 왔는지. 리포트 상태와 다른 축이며 저장하지 않고 조회 때 계산한다. 값은 PROCESSING·COMPLETED·FAILED·BLOCKED·NEEDS_REUPLOAD	AnalysisState, ReportAnalysis
쟁점 검토 상태	검수본 안 쟁점의 처리 결과. 수락 ACCEPTED, 수정 MODIFIED, 제외 EXCLUDED, 손해사정사가 새로 넣은 ADDED	IssueReviewStatus
제안 상태	제안(검수본)의 상태. 검수 등록 SENT → 상담 중 COUNSELING → 채택 ACCEPTED 또는 거절 REJECTED	ReviewStatus
AWAITING_ADOPTION	제안이 1건 이상 있고 사용자 선택을 기다림	ReportStatus
AWAITING_INSPECTION	접수됨, 검수 대기	ReportStatus
BLOCKED	AI 입력 가드레일(보험·법률 외 주제, PII 복호화 실패 등)이 차단한 리포트. AI 워커가 원시 SQL로 직접 쓰는 종료 상태이고, 분석 처리 상태에도 같은 이름의 값이 있다	ReportStatus, AnalysisState
CLOSED	담당 손해사정사가 확정됨. 고객용 응답에는 "MATCHED"로 나간다	ReportStatus, ReportResponseSupport.customerStatus
COUNSELING	사용자가 특정 제안으로 상담 중. 리포트와 제안 양쪽에 같은 이름의 값이 있다	ReportStatus, ReviewStatus
NEEDS_REUPLOAD	OCR 품질 미달(신뢰도 미달 + 이름·도메인 정보 미검출)로 AI가 생성을 건너뛴 리포트. 실패가 아니라 품질 판정이라 실패 저널에 남지 않는다. 종료 상태이며 회복은 새 리포트 업로드뿐이다	ReportStatus, AnalysisState
NOT_SELECTED (미채택)	접수 후 1주일 안에 상담 완료(CLOSED)되지 못했거나 검수를 하나도 받지 못한 리포트가 스윕으로 도달하는 상태. 신규 검수는 막지만 진행 중인 상담은 유지되고 COUNSELING으로 돌아갈 수 있어 종료 상태가 아니다	ReportStatus, ReportNotSelectionSweeper

인증·보안

용어	뜻	코드 이름
가입 티켓	소셜 인증을 통과한 신규 사용자에게 주는 5분짜리 purpose=signup JWT. /auth/register에서 회원 생성에 쓴다	SignupTicket, SignupTicketProvider
개발용 로그인	소셜 로그인 없이 테스트 사용자(닉네임을 주면 그 사용자)의 access_token 쿠키를 바로 내주는 엔드포인트. app.dev-login.enabled=true일 때만 생기고, dev에서는 공유 시크릿 헤더가 필수이며 prod에서는 기동이 막힌다. 로컬 개발과 dev 부하테스트에 쓴다	DevAuthController (POST /auth/dev/login), DevLoginService, DevLoginGuard
매직바이트	파일 앞부분의 포맷 시그니처. 선언된 Content-Type과 대조해 실제 타입을 확인한다	ChatAttachmentService
미인증 손해사정사	자격 신청 후 관리자 승인 전인 손해사정사. 검수·제안을 할 수 없다	UNCERTIFICATED_ADJUSTER
봉투 암호화	데이터는 DEK로 암호화하고 DEK는 KMS CMK로 감싸 함께 저장하는 키 관리 방식. PII 컬럼에 AES-256-GCM으로 쓴다	PiiCipher, PiiEnvelope, EncryptionKeyStore
블라인드 인덱스	암호화 컬럼을 동등 조건으로 찾기 위해 따로 저장하는 HMAC-SHA256 값	PiiHmac
블랙리스트	탈퇴한 사용자의 남은 access 토큰을 userId 단위로 막는 Redis 엔트리. 로그아웃 때는 등록하지 않는다	TokenBlacklistRepository (auth:blacklist:{userId})
수동 REST OAuth	oauth2Login 없이 프론트가 넘긴 인가코드를 백엔드가 직접 교환하는 소셜 로그인 방식	OAuthProviderStrategy, OAuthClientRouter
역할	사용자 권한 구분. 이 값으로 인가하는 방식이 RBAC다	Role (USER / CERTIFICATED_ADJUSTER / UNCERTIFICATED_ADJUSTER / ADMIN), CustomUserDetails, @PreAuthorize
핸드셰이크 인증	WebSocket 업그레이드 요청의 access_token 쿠키를 검증하는 단계	ChatHandshakeInterceptor
AAD	암호문에 묶는 추가 인증 데이터. {table}:{column}을 넣어 암호문을 다른 컬럼으로 옮겨 쓰지 못하게 한다	PiiAad
access 토큰	보호 API 인증에 쓰는 30분짜리 JWT. access_token HttpOnly 쿠키(Path /)로만 받는다	JwtProvider, CookieProvider, jwt.access-token-expiry
DEK / CMK	데이터 암호화 키 / DEK를 감싸는 KMS 마스터 키	KmsEnvelopePiiDataKeyProvider
fail-closed	필요한 설정·조건이 없으면 기능을 열지 않거나 기동을 막는 정책. 예: dev에서 시크릿 없이 개발용 로그인을 켜면 기동 실패	DevAuthController
fail-fast 가드	안전하지 않은 설정으로 뜨려 하면 기동을 멈추는 컴포넌트	PiiCryptoProdGuard, DevLoginGuard
fail-open	의존 시스템이 장애일 때 검사를 건너뛰고 통과시키는 정책. 예: Redis 장애 시 블랙리스트 조회	—
Lua CAS	Redis Lua 스크립트로 GET·비교·SET/DEL을 원자적으로 수행하는 compare-and-set. refresh 회전에 쓴다	RefreshTokenRepository.rotate, RefreshTokenRepository.RotateResult (ROTATED / NOT_FOUND / MISMATCH)
MISMATCH	저장된 refresh 토큰이 제시한 값과 달라 이미 회전됐거나 탈취된 것으로 보고 키를 지우는 회전 결과	RefreshTokenRepository.RotateResult.MISMATCH
pgAudit	PostgreSQL 감사 로그 확장. 객체 단위 감사로 원문이 저장된 민감 테이블의 SELECT를 기록한다	— (RDS 파라미터 설정)
refresh 토큰	access 재발급에 쓰는 14일짜리 JWT. refresh_token 쿠키(Path /auth)로 받고 Redis refresh:{userId}에 사용자당 1개 저장한다	RefreshTokenRepository, jwt.refresh-token-expiry
RTR (Refresh Token Rotation)	refresh 토큰을 한 번 쓰면 버리고 새 토큰으로 바꿔 재사용·탈취를 탐지하는 방식	RefreshTokenRepository.rotate, AuthTokenService
SUBSCRIBE 인가	채팅방을 구독할 때 세션 사용자가 그 방 참여자인지 확인하는 단계	ChatSubscribeInterceptor

아키텍처·패턴

용어	뜻	코드 이름
값 객체(VO)	식별자 없는 불변 값. record로 만든다	AmountRange, LicenseProof, ReportAnalysis 등
멱등 키	중복 실행을 걸러 내는 식별자. OCR 메시지에서는 job_id다	OcrJob.jobId
문서화된 예외	native query 금지 규칙에서, 리포지토리에 사유 주석을 달고 허용한 경우	—
부분 수정(PATCH)	보낸 필드만 반영하는 계약. null·필드 없음은 유지하고 빈 값은 비운다	ReviewReportRequest, ReportReview.updateReviewContent
스윕러	주기적으로 대상 행을 찾아 상태 전이나 알림을 처리하는 스케줄러. 미채택 전이용 하나와, AI 워커가 남긴 실패·차단·재업로드 신호를 알림으로 바꾸는 알림 스윕러들이 있다	ReportNotSelectionSweeper, *NotificationSweeper
아웃박스 릴레이	OCR 아웃박스 행을 폴링해 SQS로 발행하는 스케줄러	OutboxRelay
아웃박스 프로세서	회원 탈퇴 후처리 아웃박스 행을 폴링해 Redis 정리·Apple 토큰 폐기를 수행하는 스케줄러	OutboxProcessor
커서 페이지네이션	마지막 항목의 (created_at, id)를 불투명 커서로 넘겨 다음 페이지를 찾는 방식	ChatMessageRepositoryImpl
통지 시각 컬럼(알림 가드)	알림을 한 번만 보내도록 null에서 시각으로 한 방향으로만 바뀌는 멱등 가드 컬럼	reports.*_notified_at
트랜잭셔널 아웃박스	외부 부수효과를 "할 일" 행으로 도메인 변경과 같은 커밋에 적재하고 별도 스케줄러가 처리하는 패턴. 탈퇴 후처리용과 OCR 발행용 두 테이블이 있다	OutboxEvent (outbox_events), OcrOutboxEvent (kafka_outbox_events)
AFTER_COMMIT 리스너	트랜잭션이 커밋된 뒤에 도는 이벤트 리스너. 알림 생성·FCM 발송에 쓴다	@TransactionalEventListener(phase = AFTER_COMMIT)
Aggregate / Root	불변식을 함께 지키는 엔티티 묶음과 그 진입점. 외부는 Root 메서드로만 상태를 바꾸고, Aggregate끼리는 ID로 참조한다	—
at-least-once	한 번 이상 실행될 수 있음을 전제로 하는 전달 보장. 처리 로직이 멱등이어야 한다	—
at-most-once (best-effort)	실패해도 재시도하지 않아 많아야 한 번 실행되는 전달	—
Bounded Context	도메인 경계 단위. domain/ 아래 패키지 하나다	auth, user, adjuster, report, chat, notification, upload
dead-letter (FAILED 파킹)	재시도 한도를 넘겨 자동 처리를 멈추고 운영 확인 대상으로 남긴 아웃박스 행	아웃박스 status = FAILED
degrade	일부 조회가 실패해도 전체를 실패시키지 않고 더 낮은 판정으로 응답하는 것	ReportAnalysisStatusQueryService
dual-write 문제	서로 다른 두 저장소(DB와 Redis 등)에 원자적으로 쓸 수 없어 생기는 불일치	—
fan-in	AI 워커가 한 청구의 문서 완료 수가 doc_total에 닿으면 리포트를 생성하는 방식	— (AI 워커)
FOR UPDATE SKIP LOCKED	다른 트랜잭션이 잠근 행은 건너뛰고 잠기지 않은 행만 가져오는 PostgreSQL 잠금 조회. 다중 인스턴스 아웃박스 폴링에 쓴다	—
Redis relay	한 인스턴스에서 발행한 채팅 메시지를 Redis pub/sub으로 모든 인스턴스의 세션에 전달하는 구조	ChatEventPublisher, ChatMessageSubscriber
REQUIRES_NEW 별도 빈	새 트랜잭션이 필요한 메서드를 프록시가 걸리도록 다른 빈으로 뺀 것. 자기 호출로는 새 트랜잭션이 열리지 않는다	ReportHoldInitializer, TerminalFailureJournalReader 등
STOMP	WebSocket 위에서 구독·메시지 프레임을 다루는 텍스트 프로토콜	—
upsert	식별자가 있으면 갱신하고 없으면 추가하는 것	ReportReview.upsertIssue

인프라·운영

용어	뜻	코드 이름
관리 포트	actuator를 API 포트(8080)와 분리해 띄우는 9292 포트. dev·prod에서만 분리하고 외부에는 health·info만 연다	MANAGEMENT_SERVER_PORT (기본 8080)
노드 부트스트랩	커널 설정, 런타임·kubelet 설치, 라벨·taint처럼 노드를 클러스터에 붙이기까지의 작업	—
단일 진실원	배포 파일·설정의 기준은 레포 하나이고 서버에서 직접 고치지 않는다는 원칙	deploy/
드리프트	코드(선언)와 실제 인프라 상태가 어긋난 것. 매니페스트 레포가 관리하는 리소스는 Argo CD가 OutOfSync로 보여 주지만, 레포 밖에서 손으로 바꾼 상태는 아무도 알려 주지 않는다	—
매니페스트 레포	dev 클러스터의 차트·환경별 values·Argo CD Application을 둔 별도 private 레포. Argo CD는 이 레포만 본다	—
모니터링 인스턴스	Prometheus·Grafana·Loki·Tempo가 compose로 도는 dev 관측 전용 EC2	deploy/monitoring/
버퍼 풀 축소	적은 데이터로 디스크 I/O를 재현하려고 RDS shared_buffers 등을 일부러 낮추는 것	—
스키마 명시 규칙	새 테이블·인덱스 마이그레이션에 core.를 붙여야 한다는 규칙	db/migration/V{n}__*.sql
슬로우쿼리 로그	임계 시간(기본 1초)을 넘은 쿼리를 바인드 값 없이 남기는 Hibernate 로그	org.hibernate.SQL_SLOW, SLOW_QUERY_THRESHOLD_MS
시나리오 풀	부하테스트 시드 데이터를 소비 API별로 나눈 묶음(P 제안, D 상담, M 지속, I 검수 대기)	K6ScenarioSeedWriter
시드 러너	부하테스트용 계정·상태 조합 데이터를 기동 때 한 번 채우는 러너. 프로파일과 프로퍼티 두 겹으로 켠다	K6AdjusterSeedRunner, K6ScenarioSeedRunner
컨트롤 플레인	API 서버·etcd·스케줄러가 도는 클러스터 관리 노드. 현재 1대다	—
핫 로우 락	많은 트랜잭션이 같은 행을 갱신하려 해 그 행의 락이 직렬화 지점이 되는 현상. 사건번호 당일 카운터가 이 문제를 냈다	—
Alloy	컨테이너 stdout 로그를 모아 Loki로 보내는 수집 에이전트	—
app-of-apps	root Application 하나가 레포 디렉터리를 읽어 나머지 Application을 만드는 Argo CD 구성	—
app.commit	이미지에 구운 빌드 커밋 해시. /actuator/info로 노출해 배포 반영을 확인한다	app.commit
application 태그	모든 메트릭에 붙는 공통 라벨. 공개 Spring 대시보드가 이 라벨로 대상을 고른다	management.metrics.tags.application
Argo CD	매니페스트 레포를 보고 클러스터를 Sync하는 GitOps 컨트롤러	—
Cilium	eBPF 기반 CNI. kube-proxy를 대체하고 Hubble로 네트워크 플로우를 관측한다. 현재 dev 클러스터의 CNI다	—
CNI	파드 네트워크를 만드는 플러그인. Flannel → Calico → Cilium 순으로 바꿨다	—
core / ai / corpus 스키마	각각 백엔드, AI 엔진, 약관 청킹 파이프라인이 소유하는 PostgreSQL 스키마. 앱은 core만 쓰고 다른 스키마는 GRANT로 받은 범위만 읽는다	—
currentSchema	JDBC URL에서 앱의 기본 스키마 해석 순서(core,public)를 고정하는 파라미터	application.yml datasource URL
derived field	Grafana가 Loki 로그 본문의 traceId를 뽑아 Tempo 트레이스로 잇는 설정	datasource.yml
DLQ	처리에 실패한 메시지를 따로 모으는 SQS 큐. 현재 넣지 않았다	—
eBPF 데이터플레인	iptables 대신 커널 BPF 맵으로 패킷을 처리하는 방식. iptables에 규칙이 안 보이는 게 정상이다	—
ESO (External Secrets Operator)	Secrets Manager 값을 주기적으로 읽어 k8s Secret으로 만드는 오퍼레이터. ECR pull 토큰도 이것으로 발급한다	ExternalSecret
exemplar	메트릭 샘플에 붙은 traceId. 메트릭에서 트레이스로 바로 넘어가게 해 준다	--enable-feature=exemplar-storage
GitOps	Git 레포의 선언 상태에 클러스터를 맞추는 배포 방식. 클러스터에 쓰는 주체는 Argo CD 하나다	—
halfvec	pgvector의 float16 벡터 타입. halfvec(1024)로 쓴다	—
HNSW	그래프 기반 근사 최근접 벡터 인덱스	—
Hubble	Cilium의 플로우 단위 네트워크 관측 도구	—
IMDS hop limit	인스턴스 메타데이터 응답이 넘을 수 있는 네트워크 홉 수. 너무 낮으면 파드가 IMDSv2 토큰을 받지 못한다	http_put_response_hop_limit
JDBC 쿼리 스팬	DataSource 프록시가 쿼리 실행마다 만드는 Observation 스팬·타이머	jdbc.query
k3s	경량 Kubernetes 배포판. 처음에 썼다가 kubeadm으로 바꿨다	—
kube-prometheus-stack	클러스터 안에서 node-exporter·kubelet cAdvisor·kube-state-metrics로 지표를 모으는 수집 스택. 중앙 Prometheus로 remote_write한다	—
kubeadm	etcd·인증서·컨트롤 플레인까지 직접 조립해 클러스터를 세우는 공식 도구. dev 클러스터의 부트스트랩 방식이다	—
local-path PVC	노드 로컬 디스크를 쓰는 볼륨. 처음 만들어진 노드에 묶인다	—
NetworkPolicy	파드 간 허용 통신을 선언하는 k8s 리소스. Flannel은 지원하지 않는다	—
NoData=OK	시계열이 없을 때 알림을 울리지 않는 Grafana 알림 설정	noDataState
percentiles-histogram	타이머에 히스토그램 버킷을 노출해 p95·p99를 계산할 수 있게 하는 Micrometer 설정	management.metrics.distribution.percentiles-histogram
presigned URL	짧은 유효기간으로 서명한 private S3 객체 접근 URL. 업로드·채팅 첨부 서명 유효기간은 모두 5분이다	S3Presigner, S3UploadService, ChatAttachmentUploader
prune	Git에서 빠진 리소스를 클러스터에서도 지우는 Argo CD 옵션. 데이터·CRD 리소스에서는 끈다	—
Reloader	Secret이 바뀌면 그 값을 쓰는 파드를 롤링 재시작하는 컨트롤러	—
remote_write	클러스터 Prometheus가 수집한 시계열을 중앙 Prometheus로 밀어 넣는 방식	--web.enable-remote-write-receiver
selfHeal	클러스터의 수동 변경을 Git 상태로 되돌리는 Argo CD 옵션	—
semantic-release	main push마다 커밋 type으로 다음 버전을 정해 태그·릴리즈 노트를 만드는 도구	.releaserc.json
Server-Side Apply	적용 내용을 어노테이션에 남기지 않는 apply 방식. 256KB를 넘는 큰 CRD에 쓴다	—
SLO 가드레일	성능 목표와 짝을 이루는 오류율 기준. 빠르기만 하고 오류가 많으면 통과가 아니다	—
SSM 배포	SSH 대신 AWS SSM send-command로 서버에 배포 명령을 보내고 결과를 폴링하는 방식. 지금은 prod와 모니터링 인스턴스에만 쓴다	deploy-prod.yml, deploy-dev.yml의 deploy-monitoring job
taint / toleration	노드에 일반 파드가 못 올라오게 막고(taint) 허용할 파드만 예외로 두는(toleration) 장치. GPU 노드 격리에 쓴다	—
time-slicing	GPU 한 장을 여러 파드가 시간 분할로 나눠 쓰는 device plugin 기능. VRAM은 격리되지 않는다	—
Traefik	클러스터 입구 Ingress 컨트롤러. /actuator는 9292로, 나머지는 8080으로 보낸다	—
verify-deploy	dev 배포 후 /actuator/info의 app.commit이 이번 커밋과 같아지는지 확인하는 단계	deploy-dev.yml의 verify-deploy job