Glossary

용어집

용어	쉬운 설명
Access Token	API 요청자가 누구인지 짧은 시간 증명하는 JWT
ActorContext	로그인 사용자·Role·Company 정보를 Server 내부에서 안전하게 전달하는 값
ADR	아키텍처 선택, 이유, 대안, 영향을 남기는 결정 기록
Agent	Knowledge와 Prompt를 이용해 업무 후보를 만드는 AI 보조 기능
Agent Router	여러 Agent version으로 트래픽을 나누는 AI 계층 구성요소
AI Runtime	fowoco/ai가 배포하는 별도 서비스. Agent Pipeline과 Provider 호출을 소유
AiRuntimeClient	Server가 AI Runtime을 호출할 때 사용하는 Port
AiRun	AI 요청의 queue·실행·재시도·결과·실패를 Server DB에 보존하는 단위
AiAttempt	같은 AiRun 안의 1회 실행 시도. 오류·시각·version을 수정하지 않고 보존
API Contract	Request·Response·상태·오류·권한을 서비스끼리 약속한 규칙
AuditEvent	누가 언제 무엇을 생성·수정·승인했는지 남긴 변경 불가 기록
Blue/Green	기존 version과 신규 version을 함께 준비해 트래픽을 안전하게 전환하는 배포
Bulkhead	AI 연동 자원을 일반 API와 분리해 장애 확산을 막는 장치
Circuit Breaker	반복 장애 때 외부 호출을 잠시 멈추고 빠르게 실패시키는 장치
Context Pack	Agent가 업무를 이해할 때 사용하는 검증된 지식 묶음
Contract Test	두 서비스의 Request·Response 약속이 호환되는지 확인하는 test
Domain Event	Domain에서 이미 일어난 중요한 사실을 후속 처리에 알리는 message
Durable Event	process가 꺼져도 DB에 남아 재처리할 수 있는 Event
E2E	로그인부터 승인·근로자 응답·완료까지 전체 사용자 흐름 test
Evidence	Task 완료를 증명하는 문서·파일·제출번호 등의 reference
FakeAiRuntimeClient	외부 AI 없이 결정적 결과를 주는 Server test fixture
Flyway	version이 붙은 SQL로 DB 구조 변경을 재현하는 도구
Golden Scenario	제품 가치를 보여주는 대표 사용자 흐름. 모델 평가셋과는 구분
HITL	Human-in-the-loop. AI 결과를 중요한 행동 전에 사람이 검토·승인하는 구조
Idempotency	같은 요청이 반복돼도 결과가 중복 생성되지 않는 성질
Immutable Bundle	배포 뒤 내용을 바꾸지 않고 새 version으로만 교체하는 산출물
Internal API	일반 사용자가 아니라 서비스끼리 호출하는 인증된 API
JSON Schema	JSON 필드·자료형·필수값을 검사하는 규칙
Knowledge Bundle	Context Pack·Workflow Catalog·Intent·용어를 version으로 묶은 산출물
Liveness	process 자체가 살아 있는지 확인하는 상태 검사
LM Studio	fowoco/ai에서 로컬 모델 후보를 실험하는 도구. 최종 데모 의존성이 아님
Masking	값 일부를 가려 전체 개인정보가 보이지 않게 하는 처리
Migration	DB table·column 변경을 순서와 version으로 기록한 작업
Multi-tenancy	여러 사업장이 한 Server를 쓰되 서로의 데이터를 볼 수 없게 격리하는 구조
Observability	Metric·log·trace로 시스템 상태와 장애 원인을 이해하는 능력
OpenAPI	REST API 경로·DTO·오류·인증을 기계와 사람이 읽게 표현하는 표준
Optimistic Lock	version을 비교해 동시 수정이 최신 값을 덮지 않게 하는 방식
Outcome	AI의 업무 판정. NEEDS_INFO, REVIEW_REQUIRED 등
Outbox	Business 변경과 Event record를 같은 DB transaction에 저장하는 패턴
P0 / P1 / P2	최우선 핵심 / 중요 / 보완 우선순위
Port	Domain이 외부 구현 세부에 직접 묶이지 않게 하는 interface
Provider	OpenAI·Gemini 같은 모델 API 제공자. AI Runtime이 호출
Raw workload	두 사람의 상대 작업량을 합산하기 위한 Project 숫자 field
Readiness	DB 등 의존성을 포함해 실제 요청을 받을 준비 상태인지 확인하는 검사
Refresh Token	Access Token을 다시 발급받기 위한 장기 token
RemoteAiRuntimeClient	Server가 별도 AI Runtime Internal API를 호출하는 구현체
Repository Boundary	각 저장소가 소유할 책임과 금지할 책임의 경계
Rollback	문제가 생긴 배포를 이전 정상 version으로 되돌리는 작업
Runbook	실행·점검·장애 복구 절차를 순서대로 적은 문서
S2S	Service-to-Service. 사용자 대신 서비스끼리 인증해 통신하는 방식
Secret	API key·DB 비밀번호처럼 Git과 log에 두면 안 되는 값
Smoke Test	배포 직후 대표 기능이 최소한 동작하는지 빠르게 확인하는 test
Structured Output	모델이 자유 설명 대신 정해진 JSON 구조로 답하는 방식
Task / 업무카드	HR이 해야 할 일, 상태, 조건, 증빙을 구조화한 운영 단위
TaskCandidate	AI가 제안했지만 HR이 아직 실제 Task로 확정하지 않은 후보
Task Workflow	Server가 강제하는 Task 상태·승인·증빙 전이 규칙
Trace ID	Client→Server→AI Runtime→Provider 흐름을 이어 찾는 식별자
Transaction	여러 DB 변경을 함께 성공하거나 함께 실패시키는 처리 단위
Vertical Slice	API·Domain·DB·test를 포함한 한 사용자 흐름을 끝까지 완성하는 방식
Worker Link	근로자가 로그인 없이 제한된 안내·응답만 수행하는 만료 link
Workflow Catalog	업무 유형별 필수정보·checklist·승인·완료 기준의 versioned 지식

자주 혼동하는 구분

Task 상태와 AiRun 상태

Task는 HR 업무의 진행상태입니다. AiRun은 AI 호출의 기술 실행상태입니다. AiRun=SUCCEEDED라도 정보가 부족하면 outcome=NEEDS_INFO이고 Task는 자동 승인되지 않습니다.

Knowledge Workflow와 Server Workflow

Knowledge의 Workflow Catalog는 “어떤 정보와 절차가 필요한가”라는 기준입니다. Server Task Workflow는 “현재 실제 업무를 누가 다음 상태로 옮길 수 있는가”를 강제합니다.

Fake와 장애 fallback

Fake client는 자동 test용입니다. 실제 AI Runtime 장애 때 Fake 후보를 진짜 결과처럼 보여주지 않고 수동 입력·나중 재시도·담당자 검토를 안내합니다.

제품 E2E와 모델 Evaluation

Server의 제품 E2E는 로그인부터 업무 완료까지 검사합니다. AI/Knowledge의 evaluation은 Intent·Slot·후보 품질을 잠긴 dataset으로 측정합니다. 이름이 비슷해도 목적과 소유자가 다릅니다.

원본 파일과 문서 metadata

MVP는 서류 유형·제출 여부·유효기간 같은 metadata를 우선 관리합니다. 원본 파일 저장은 제한적으로 처리하고 FileStorage Port로 분리합니다.