Access Code 도메인 용어집
용어 표기 규칙
본 프로젝트에서는 접근 코드 관련 용어를 다음과 같이 일관되게 사용합니다:
- 접근 코드: 일반 텍스트 설명에서 사용 (한글 문서)
- access-code: 파일명, 경로, URL, 기술적 식별자로 사용 (케밥 케이스)
- AccessCode: 클래스명, 애그리게잇, 타입명으로 사용 (파스칼 케이스)
이 규칙은 모든 문서와 코드에 일관되게 적용됩니다.
핵심 개념
| 용어 | 정의 | 관련 컨텍스트 | 동의어 |
|---|---|---|---|
| 접근 코드(Access Code) | 시스템 접근을 위한 일회성 또는 시간 제한이 있는 코드. 16자리 영문 대문자와 숫자 조합으로 구성 | 코드 생성, 코드 검증, 코드 관리 | 인증 코드 |
| 코드 상태(Code Status) | 접근 코드의 현재 상태를 나타내는 값(대기, 활성, 사용됨, 만료됨, 차단됨, 철회됨) | 코드 관리, 코드 검증 | 상태 |
| 코드 형식(Code Format) | 접근 코드의 표준 형식 규칙 | 코드 생성, 코드 검증 | 형식 |
| 코드 유형(Code Type) | 접근 코드의 용도별 분류(일반, 견본품용, 데모용, 개발용) | 코드 생성, 코드 관리 | 타입 |
| 만료기한(Expiration Time) | 접근 코드가 유효한 마지막 날짜와 시간 | 코드 관리, 코드 검증 | 유효기간 |
| 배치(Batch) | 대량으로 한 번에 생성된 접근 코드 그룹 | 대량 코드 관리 | 코드 그룹 |
| 검증(Verification) | 입력된 접근 코드의 유효성을 확인하는 과정 | 코드 검증 | 유효성 검사 |
| 운영 매니저(Operational Manager) | 접근 코드 관리 권한을 가진 관리자 | 코드 관리, 권한 관리 | 관리자 |
| 발급 출처(Issue Source) | 접근 코드가 발급된 원천 시스템이나 채널 | 코드 생성, 코드 관리 | 출처, 소스 |
| 진료 대시보드(Clinic Dashboard) | 의료진이 환자 정보를 관리하고 접근 코드를 발급하는 시스템 | 코드 발급, 의료 연동 | 클리닉 대시보드 |
| OCR 진료비 서류(OCR Invoice) | 광학 문자 인식을 통해 처리된 진료비 관련 문서 | 코드 발급, 문서 처리 | 진료비 영수증 |
| 보험사 코드(Insurance Code) | 보험사에서 제공한 접근 코드 | 코드 검증, 외부 연동 | 보험 접근 코드 |
| 외부 검증(External Validation) | 외부 시스템을 통해 코드의 유효성을 확인하는 과정 | 코드 검증, 외부 연동 | 외부 확인 |
| 검증 시도 횟수(Verification Attempt Count) | 코드 검증을 시도한 횟수 | 코드 검증, 보안 | 시도 횟수 |
| 진료 메타데이터(Clinic Metadata) | 진료 대시보드 관련 메타데이터(진료소 ID, 의사 ID, 환자 ID, 진료 예약 ID) | 코드 발급, 의료 연동 | 클리닉 데이터 |
| OCR 메타데이터(OCR Metadata) | OCR 관련 메타데이터(진료비 상세내역 ID, 병원명, 진료비 발생일, 진료비 금액) | 코드 발급, 문서 처리 | OCR 데이터 |
| 보험사 메타데이터(Insurance Metadata) | 보험사 관련 메타데이터(보험사 ID, 보험 증권 번호, 보험금 청구 ID) | 코드 발급, 외부 연동 | 보험 데이터 |
| 코드 입력 형식(Code Input Format) | 사용자가 입력한 코드의 형식(공백, 하이픈 포함 여부 등) | 코드 검증 | 입력 형식 |
| 정규화 입력(Normalized Input) | 공백 제거, 대소문자 처리 등을 통해 정규화된 코드 입력 | 코드 검증 | 표준화 입력 |
| 보고서(Report) | 코드 사용 현황, 통계 등을 보여주는 문서 | 모니터링, 분석 | 리포트 |
| 알림(Notification) | 특정 이벤트 발생 시 전송되는 메시지 | 사용자 알림, 관리자 알림 | 통지 |
엔티티
| 엔티티 | 정의 | 식별자 | 주요 속성 |
|---|---|---|---|
| 접근 코드(AccessCode) | 시스템 접근을 위한 코드 | codeId | 코드값, 상태, 유형, 만료기한, 발급출처, 검증시도횟수 |
| 배치(Batch) | 대량으로 생성된 코드 그룹 | batchId | 생성일, 코드 수, 공통 만료기한, 발급출처 |
| 사용 이력(UsageHistory) | 코드 사용에 관한 기록 | historyId | 코드ID, 사용일시, 사용자정보 |
| 발급자(Issuer) | 코드 발급 주체 | issuerId | 이름, 유형, 권한 |
| 출처 사이트(SourceSite) | 코드 발급 요청 사이트 | siteId | 이름, URL, 설명 |
| 발급 출처(IssueSource) | 코드가 발급된 출처 | issueSourceId | 유형, 메타데이터 |
| 코드 입력(CodeInput) | 사용자가 입력한 원본 코드 | inputId | 원본값, 정규화값, 검증결과 |
| 보고서 구성(ReportConfiguration) | 보고서 생성 설정 | configId | 보고서유형, 기간, 필터, 형식 |
| 외부 API 호출(ExternalAPICall) | 외부 API 요청/응답 내역 | callId | 요청상세, 응답상세, 호출상태, 재시도횟수 |
값 객체
| 값 객체 | 정의 | 불변 속성 | 동등성 기준 |
|---|---|---|---|
| 코드 상태(CodeStatus) | 접근 코드의 현재 상태 | 상태 코드(대기, 활성, 사용됨, 만료됨, 차단됨, 철회됨), 설명 | 상태 코드 |
| 코드 유형(CodeType) | 접근 코드의 용도 분류 | 유형 코드, 설명, 접두사(일반, 'S-', 'D-', 'DEV-') | 유형 코드 |
| 만료기한(ExpirationTime) | 코드 만료 일시 | 일시 | 일시 |
| 코드 형식(CodeFormat) | 코드의 형식 규칙 | 길이, 문자 집합, 패턴 | 모든 속성 |
| 그룹 ID(GroupId) | 코드 그룹화 식별자 | ID 값 | ID 값 |
| 치료 기간(TreatmentPeriod) | 코드 관련 치료 서비스 기간 | 시작일, 종료일 | 모든 속성 |
| 발급 출처 유형(IssueSourceType) | 코드 발급 출처의 유형 | 유형 코드, 설명 | 유형 코드 |
| 진료 정보(ClinicInfo) | 진료 관련 정보 | 클리닉ID, 의사ID, 환자ID, 예약ID, 방문일 | 모든 속성 |
| OCR 정보(OCRInfo) | OCR 처리된 진료비 서류 정보 | 인식ID, 병원명, 치료일, 신뢰도 점수, 비용 항목 | 모든 속성 |
| 보험 정보(InsuranceInfo) | 보험 관련 정보 | 보험사ID, 보험증번호, 청구번호, 검증결과 | 모든 속성 |
| 원본 입력(RawInput) | 사용자가 입력한 원본 코드 값 | 입력 문자열 | 입력 문자열 |
| 정규화 입력(NormalizedInput) | 정규화된 코드 입력 값 | 정규화된 문자열 | 정규화된 문자열 |
| 입력 검증 결과(InputValidationResult) | 코드 입력 검증 결과 | 유효성, 오류 메시지 | 모든 속성 |
| 보고서 유형(ReportType) | 보고서의 종류 | 유형 코드, 설명 | 유형 코드 |
| 보고서 기간(ReportPeriod) | 보고서 데이터 조회 기간 | 시작일, 종료일 | 모든 속성 |
| 보고서 필터(ReportFilters) | 보고서 데이터 필터링 조건 | 필터 조건 목록 | 모든 속성 |
| 보고서 형식(ReportFormat) | 보고서 출력 형식 | 형식(PDF, Excel 등) | 형식 |
| API 요청 상세(APIRequestDetails) | 외부 API 요청 상세 정보 | URL, 헤더, 바디, 메서드 | 모든 속성 |
| API 응답 상세(APIResponseDetails) | 외부 API 응답 상세 정보 | 상태 코드, 헤더, 바디 | 모든 속성 |
| 호출 상태(CallStatus) | API 호출의 상태 | 상태 코드, 설명 | 상태 코드 |
| 오류 상세(ErrorDetails) | 오류 발생 시 상세 정보 | 오류 코드, 메시지, 발생 시간 | 모든 속성 |
집계
| 집계 | 정의 | 루트 엔티티 | 포함된 엔티티/값 객체 |
|---|---|---|---|
| 접근 코드 관리(AccessCodeManagement) | 접근 코드 생명주기 관리 | AccessCode | CodeStatus, ExpirationTime, UsageHistory, IssueSource, VerificationAttemptCount |
| 배치 관리(BatchManagement) | 대량 코드 생성 및 관리 | Batch | AccessCode, CodeType, GroupId, IssueSource |
| 코드 검증(CodeVerification) | 코드 유효성 검증 프로세스 | AccessCode | CodeStatus, CodeFormat, ExpirationTime |
| 발급 출처 관리(IssueSourceManagement) | 코드 발급 출처 관리 | IssueSource | IssueSourceType, ClinicInfo, OCRInfo, InsuranceInfo |
| 코드 입력 형식(CodeInputFormat) | 사용자 코드 입력 처리 | CodeInput | RawInput, NormalizedInput, InputValidationResult |
| 보고서 생성(ReportGeneration) | 보고서 생성 관리 | ReportConfiguration | ReportType, ReportPeriod, ReportFilters, ReportFormat |
| 외부 API 호출(ExternalAPICall) | 외부 API 통신 관리 | ExternalAPICall | APIRequestDetails, APIResponseDetails, CallStatus, RetryCount, ErrorDetails |
도메인 이벤트
| 이벤트 | 정의 | 트리거 | 처리자 |
|---|---|---|---|
| AccessCodeGenerated | 새로운 접근 코드 생성됨 | 코드 생성 요청 | 코드 관리 서비스 |
| AccessCodeActivated | 접근 코드가 활성화됨 | 시작일 도래 | 코드 상태 관리자 |
| AccessCodeUsed | 접근 코드가 사용됨 | 코드 사용 요청 | 코드 관리 서비스, 사용 이력 서비스 |
| AccessCodeExpired | 접근 코드가 만료됨 | 만료일 도래 | 코드 상태 관리자 |
| AccessCodeBlocked | 접근 코드가 차단됨 | 여러 실패한 검증 시도 | 보안 서비스 |
| AccessCodeRevoked | 접근 코드가 철회됨 | 운영자 요청 | 코드 관리 서비스 |
| BatchCreated | 새로운 코드 배치 생성됨 | 배치 생성 요청 | 배치 관리 서비스 |
| CodeVerificationFailed | 코드 검증 실패 | 잘못된 코드 입력 | 보안 서비스, 코드 검증 서비스 |
| AccessCodeIssuedFromClinic | 진료 대시보드에서 코드 발급됨 | 의사의 코드 발급 요청 | 코드 생성 서비스, 클리닉 연동 서비스 |
| OCRProcessingCompleted | OCR 처리 완료됨 | 진료비 서류 업로드 | OCR 서비스, 코드 생성 서비스 |
| InsuranceCodeVerified | 보험사 코드 검증됨 | 보험사 코드 검증 요청 | 외부 검증 서비스 |
| ExternalValidationSucceeded | 외부 검증 성공 | 검증 API 호출 | 코드 검증 서비스 |
| ExternalValidationFailed | 외부 검증 실패 | 검증 API 호출 오류 | 코드 검증 서비스 |
| AccessCodeInputValidated | 코드 입력 형식 검증 완료 | 사용자 코드 입력 | 코드 검증 서비스 |
| AccessCodeMaxAttemptsExceeded | 최대 검증 시도 횟수 초과 | 반복된 검증 실패 | 보안 서비스 |
| AccessCodeExpiredRejected | 만료된 코드 거부됨 | 만료된 코드 사용 시도 | 코드 검증 서비스 |
| AccessCodeInvalidRejected | 유효하지 않은 코드 거부됨 | 유효하지 않은 코드 입력 | 코드 검증 서비스 |
| AccessCodeIssueDeniedDuringTreatment | 치료 중 코드 발급 거부됨 | 환자의 기존 코드 확인 | 코드 발급 서비스 |
| DailyUsageReportGenerated | 일별 사용 보고서 생성됨 | 보고서 생성 요청 | 보고서 생성 서비스 |
| WeeklyUsageReportGenerated | 주별 사용 보고서 생성됨 | 보고서 생성 요청 | 보고서 생성 서비스 |
| MonthlyUsageReportGenerated | 월별 사용 보고서 생성됨 | 보고서 생성 요청 | 보고서 생성 서비스 |
| AccessCodeIssuedNotificationSent | 코드 발급 알림 전송됨 | 코드 발급 완료 | 알림 서비스 |
| ExpiringAccessCodesReportGenerated | 만료 예정 코드 보고서 생성됨 | 스케줄된 작업 | 보고서 생성 서비스 |
서비스
| 서비스 | 정의 | 책임 | 의존성 |
|---|---|---|---|
| 코드 생성 서비스(CodeGenerationService) | 접근 코드 생성 기능 제공 | 단일/대량 코드 생성 | CodeRepository, FormatPolicy |
| 코드 관리 서비스(CodeManagementService) | 코드 생명주기 관리 | 상태 변경, 만료 처리 | CodeRepository, StatusPolicy |
| 코드 검증 서비스(CodeVerificationService) | 코드 유효성 검증 | 형식, 상태, 만료 검증 | CodeRepository, SecurityService |
| 배치 관리 서비스(BatchManagementService) | 배치 작업 관리 | 배치 생성, 관리, 조회 | BatchRepository, CodeGenerationService |
| 사용 이력 서비스(UsageHistoryService) | 코드 사용 이력 관리 | 이력 기록, 조회 | HistoryRepository |
| 보안 서비스(SecurityService) | 코드 보안 관련 기능 | 차단, 무차별 시도 방지 | SecurityRepository |
| 발급 출처 서비스(IssueSourceService) | 발급 출처 관련 기능 | 출처 검증, 메타데이터 관리 | IssueSourceRepository |
| 클리닉 대시보드 연동 서비스(ClinicDashboardIntegrationService) | 진료 대시보드 연동 | 의료진 검증, 코드 발급 | ClinicRepository, CodeGenerationService |
| OCR 처리 서비스(OCRProcessingService) | 진료비 서류 OCR 처리 | 이미지 처리, 텍스트 추출 | OCRProcessor, CodeGenerationService |
| 외부 검증 서비스(ExternalValidationService) | 외부 시스템 검증 연동 | 외부 API 호출, 검증 결과 처리 | ApiGateway, SecurityService |
| 코드 입력 처리 서비스(CodeInputProcessingService) | 사용자 코드 입력 처리 | 정규화, 형식 검증 | CodeFormatPolicy |
| 보고서 생성 서비스(ReportGenerationService) | 다양한 보고서 생성 | 데이터 수집, 보고서 형식 | CodeRepository, UsageHistoryRepository |
| 알림 서비스(NotificationService) | 알림 생성 및 전송 | 알림 처리, 전송 대상 관리 | NotificationGateway |
정책
| 정책 | 정의 | 규칙 | 영향 |
|---|---|---|---|
| 코드 형식 정책(CodeFormatPolicy) | 코드 생성 형식 규칙 정의 | 16자리, 영문 대문자와 숫자만 허용 | 코드 생성 |
| 코드 상태 정책(CodeStatusPolicy) | 코드 상태 관리 규칙 정의 | 상태 전이 규칙, 자동 만료 | 코드 생명주기 |
| 코드 유효기간 정책(ExpirationPolicy) | 코드 유효기간 관리 규칙 | 기본 1년, 최대 기간 제한 | 코드 만료 |
| 코드 사용 정책(UsagePolicy) | 코드 사용 규칙 정의 | 일회용, 재사용 불가 | 코드 검증 |
| 검증 시도 정책(VerificationAttemptPolicy) | 검증 시도 제한 규칙 | 5회 실패 시 차단 | 코드 보안 |
| 배치 크기 정책(BatchSizePolicy) | 배치 크기 제한 규칙 | 최대 10,000개 코드 | 배치 생성 |
| 발급 출처 정책(IssueSourcePolicy) | 출처별 발급 규칙 정의 | 출처 유형별 필수 메타데이터 | 코드 발급 |
| OCR 신뢰도 정책(OCRConfidencePolicy) | OCR 처리 신뢰도 규칙 | 85% 이상 신뢰도 필요 | OCR 처리 |
| 의료진 검증 정책(MedicalStaffVerificationPolicy) | 의료진 권한 검증 규칙 | 활성 상태 의사 ID 필요 | 클리닉 코드 발급 |
| 보험사 코드 검증 정책(InsuranceCodeValidationPolicy) | 보험사 코드 검증 규칙 | 외부 API 연동 필수 | 보험사 코드 검증 |
| 입력 정규화 정책(InputNormalizationPolicy) | 코드 입력 처리 규칙 | 공백 제거, 대소문자 무시 | 코드 입력 처리 |
| 표시 형식 정책(DisplayFormatPolicy) | UI에서 코드 표시 규칙 | 4자리마다 하이픈 추가 | 사용자 인터페이스 |
| 배치 생성 한도 정책(BatchCreationLimitPolicy) | 일일 배치 생성 제한 | 그룹별 일일 최대 5개 배치 | 배치 관리 |
| 보고서 생성 정책(ReportGenerationPolicy) | 보고서 생성 관련 규칙 | 생성 주기, 데이터 범위 제한 | 보고서 생성 |
| 알림 전송 정책(NotificationDeliveryPolicy) | 알림 전송 관련 규칙 | 전송 시간, 채널 선택, 재전송 | 알림 관리 |
변경 이력
| 버전 | 날짜 | 작성자 | 변경 내용 |
|---|---|---|---|
| 0.1.0 | 2025-03-30 | bok@weltcorp.com | 최초 작성 |