본문으로 건너뛰기

Access Code 바운디드 컨텍스트

용어 사용 안내: 본 문서에서는 다음과 같이 용어를 통일하여 사용합니다.

  • 일반 텍스트 설명: "접근 코드"
  • 파일명, 경로, URL: "access-code"
  • 클래스명, 애그리게잇, 타입명: "AccessCode"

1. 컨텍스트 정의​

AccessCode 도메인은 일회성 또는 제한된 시간 동안 유효한 접근 코드의 생성, 관리, 검증을 담당하는 바운디드 컨텍스트입니다.

1.1 주요 책임​

  • 접근 코드 생성 및 발급
  • 접근 코드 유효성 검증
  • 접근 코드 만료 관리
  • 접근 코드 사용 이력 관리
  • 접근 코드 정책 관리
  • 대량 접근 코드 관리
  • 보험사 표준 코드 포맷 지원
  • 견본품/데모/개발용 접근 코드 관리
  • 접근 코드 상태 관리 및 철회
  • 접근 코드 조회 서비스 제공
  • 다양한 발급 출처(진료 대시보드, OCR 진료비 서류, 보험사) 관리
  • 코드 입력 형식 검증 및 처리
  • 코드 유형별 관리(일반, 견본품용, 데모용, 개발용)
  • 사용자 인터페이스 지원(하이픈 포함 형식 표시 등)

1.2 도메인 용어​

본 바운디드 컨텍스트에서 사용되는 도메인 용어에 대한 자세한 정의는 Access Code 도메인 용어집을 참조하세요.

주요 핵심 개념:

  • Access Code: 시스템 접근을 위한 일회성 또는 시간 제한 코드
  • Code Status: 코드의 현재 상태 (대기, 활성, 사용됨, 만료됨, 차단됨, 철회됨)
  • Code Type: 코드의 유형 (일반, 견본품용, 데모용, 개발용)
  • Issue Source: 코드 발급 출처 유형(진료 대시보드, OCR 진료비 서류, 보험사 등)
  • Batch: 대량으로 생성된 접근 코드 묶음

2. 컨텍스트 경계​

2.1 상위 컨텍스트​

  • Auth Domain: 인증/인가 처리
  • User Domain: 사용자 관리

2.2 하위 컨텍스트​

  • Notification Domain: 코드 전송
  • Audit Domain: 사용 이력 기록

2.3 외부 시스템​

  • SMS Gateway: SMS를 통한 코드 전송
  • Email Service: 이메일을 통한 코드 전송
  • TimeMachine:
    • 코드 만료 시간 관리
    • 가상 시간 관리
    • 코드 생성 시 가상 시간 시작일 설정
    • 코드 사용 시 사용자 가상 시간 초기화
    • 사용자별 TimeMachine 기능 활성화/비활성화
  • Clinic Dashboard System: 진료 대시보드 시스템
  • OCR Processing Service: 진료비 서류 OCR 처리 서비스
  • Insurance Code Validation API: 보험사 코드 유효성 검증 API

3. 컨텍스트 매핑​

3.1 Auth Domain과의 관계 (Customer-Supplier)​

3.2 Notification Domain과의 관계 (Published Language)​

3.3 보험사 발급 코드의 흐름 (Separate Ways + Anti-corruption Layer)​

3.4 진료 대시보드 발급 코드의 흐름 (Partnership)​

3.5 OCR 진료비 서류 발급 코드의 흐름 (Anti-corruption Layer)​

3.6 코드 입력 및 형식 검증 흐름 (Anti-corruption Layer)​

3.7 TimeMachine과의 관계 (Customer-Supplier)​

4. 발급 출처별 책임 구분​

4.1 접근 코드 발급 책임​

  • 진료 대시보드: 의료진이 환자 정보와 진료 내역을 기반으로 접근 코드 발급
  • OCR 처리 서비스: 사용자가 업로드한 진료비 서류를 분석하여 자동으로 접근 코드 발급
  • 보험사: 자체 시스템에서 접근 코드를 생성하여 사용자에게 제공

4.2 접근 코드 관리 책임​

  • AccessCode 도메인: 모든 출처에서 발급된 코드의 생명주기 관리
  • 운영 매니저: 코드 상태 변경, 만료 관리, 문제 해결 등 수동 관리 작업

4.3 발급 출처별 메타데이터 관리​

  • 진료 대시보드: 진료소 ID, 의사 ID, 환자 ID, 진료 예약 ID
  • OCR 처리 서비스: 진료비 상세내역 ID, 병원명, 진료비 발생일, 진료비 금액
  • 보험사: 보험사 ID, 보험 증권 번호, 보험금 청구 ID

5. 도메인 이벤트​

5.1 발행하는 이벤트​

  • AccessCodeCreated: 새로운 접근 코드 생성
  • AccessCodeActivated: 접근 코드 활성화
  • AccessCodeDeactivated: 접근 코드 비활성화
  • AccessCodeExpired: 접근 코드 만료
  • AccessCodeDeleted: 접근 코드 삭제
  • AccessCodeValidated: 접근 코드 검증 완료
  • AccessCodeRejected: 잘못된 코드 입력
  • AccessCodeUsed: 접근 코드 사용 완료
  • AccessCodeBlocked: 접근 코드 차단
  • AccessCodeUnblocked: 접근 코드 차단 해제
  • AccessCodeRevoked: 접근 코드 철회
  • AccessCodeStatusChanged: 접근 코드 상태 변경
  • InsuranceCodeReceived: 사용자가 보험사 코드 입력
  • InsuranceCodeValidated: 보험사 코드 유효성 검증 완료
  • InsuranceCodeRejected: 보험사 코드 유효성 검증 실패
  • AccessCodeIssuedForSample: 견본품용 코드 발급
  • AccessCodeIssuedForDemo: 데모용 코드 발급
  • AccessCodeIssuedForDevelopment: 개발용 코드 발급
  • AccessCodeBatchCreated: 대량 코드 일괄 생성
  • AccessCodeBulkIssued: 대량 코드 일괄 발급
  • AccessCodeBatchDeactivated: 대량 코드 일괄 비활성화
  • AccessCodePolicyUpdated: 정책 변경
  • AccessCodeStatsUpdated: 사용 통계 업데이트
  • AccessCodeMaxAttemptsExceeded: 최대 실패 횟수 초과
  • AllAccessCodesRetrieved: 모든 코드 조회 완료
  • ActiveAccessCodesRetrieved: 활성 코드 조회 완료
  • UsedAccessCodesRetrieved: 사용 중인 코드 조회 완료
  • AccessCodeIssuedFromClinicDashboard: 진료 대시보드에서 코드 발급
  • AccessCodeIssuedFromOCRInvoice: OCR 진료비 서류에서 코드 발급
  • AccessCodeIssuedByInsurance: 보험사에서 코드 발급
  • ExternalAPICallFailed: 외부 API 호출 실패
  • ExternalAPIResponseInvalid: 유효하지 않은 외부 API 응답
  • AccessCodeMetadataUpdated: 코드 메타데이터 업데이트
  • AccessCodeInputValidated: 코드 입력 형식 검증 완료
  • AccessCodeExpiredRejected: 만료된 코드 거부됨
  • AccessCodeInvalidRejected: 유효하지 않은 코드 거부됨
  • AccessCodeMetadataValidationFailed: 코드 메타데이터 검증 실패
  • AccessCodeIssueDeniedDuringTreatment: 치료 중 접근 코드 발급 거부됨
  • AccessCodeReceivedFromInsurance: 보험사로부터 코드 수신
  • DailyUsageReportGenerated: 일별 사용 보고서 생성
  • WeeklyUsageReportGenerated: 주별 사용 보고서 생성
  • MonthlyUsageReportGenerated: 월별 사용 보고서 생성
  • SourceUsageReportGenerated: 출처별 사용 보고서 생성
  • GroupUsageReportGenerated: 그룹별 사용 보고서 생성
  • IssueSourceUsageReportGenerated: 발급 출처별 사용 보고서 생성
  • ExpiringAccessCodesReportGenerated: 만료 예정 코드 보고서 생성
  • AbnormalAttemptsReportGenerated: 비정상 시도 보고서 생성
  • SuccessFailureRatioReportGenerated: 성공/실패 비율 보고서 생성
  • AccessCodeIssuedNotificationSent: 코드 발급 알림 전송
  • BatchCompletionNotificationSent: 대량 발급 완료 알림 전송
  • AccessCodeExpirationNotificationSent: 만료 예정 코드 알림 전송
  • AbnormalAttemptsNotificationSent: 비정상 시도 알림 전송
  • BatchFailureNotificationSent: 배치 처리 실패 알림 전송
  • AccessCodeCreatedWithTimeMachine: TimeMachine 옵션이 활성화된 접근 코드 생성
  • TimeMachineEnabledForUser: 코드 사용으로 사용자에게 TimeMachine 기능 활성화
  • VirtualTimeInitializedForUser: 코드에 지정된 가상 시간으로 사용자 시간 초기화
  • AccessCodeValidatedWithTimeMachine: TimeMachine 옵션이 활성화된 코드 검증 완료
  • AccessCodeUsedWithTimeMachine: TimeMachine 옵션이 활성화된 코드 사용 완료
  • TimeMachineSettingsChanged: 접근 코드의 TimeMachine 설정 변경

5.2 구독하는 이벤트​

  • UserCreated: 새로운 사용자 생성
  • UserDeactivated: 사용자 비활성화
  • NotificationDelivered: 알림 전송 완료
  • NotificationFailed: 알림 전송 실패
  • GroupUpdated: 그룹 정보 업데이트
  • SiteUpdated: 출처 사이트 정보 업데이트
  • ClinicAppointmentCreated: 진료 예약 생성
  • ClinicAppointmentUpdated: 진료 예약 업데이트
  • ClinicAppointmentCancelled: 진료 예약 취소
  • OCRInvoiceProcessed: OCR 진료비 서류 처리 완료
  • OCRInvoiceValidated: OCR 진료비 서류 검증 완료
  • VirtualTimeCreated: 가상 시간이 생성됨
  • VirtualTimeChanged: 가상 시간이 변경됨
  • TimeMachineEnabled: TimeMachine 기능이 활성화됨
  • TimeMachineDisabled: TimeMachine 기능이 비활성화됨

6. 애그리게잇​

6.1 AccessCode 애그리게잇​

  • 루트: AccessCode
  • 엔티티: AccessCodeMetadata
  • 값 객체: CodeValue, ExpirationTime, UsageCount, SourceSiteId, IssuerAccountId, GroupId, PlanId, TreatmentPeriod, UsagePeriod, IssueSource, VerificationAttemptCount, TimeMachineSettings
  • 불변식:
    • 코드 값은 유일해야 함
    • 만료 시간은 생성 시간보다 이후여야 함
    • 사용 횟수는 음수가 될 수 없음
    • 치료기간은 유효한 기간이어야 함
    • 사용기간은 만료기한을 초과할 수 없음
    • 발급자 계정 ID는 유효한 계정이어야 함
    • 그룹 ID가 지정된 경우, 유효한 그룹이어야 함
    • 플랜 ID가 지정된 경우, 유효한 플랜이어야 함
    • 발급 출처는 유효한 값이어야 함
    • 검증 시도 횟수는 정책 제한을 초과할 수 없음
    • TimeMachine 사용 설정이 true인 경우, 가상 시간 시작일이 지정되어야 함
    • 가상 시간 시작일은 코드 생성일로부터 1년 이내여야 함

6.2 AccessCodeBatch 애그리게잇​

  • 루트: AccessCodeBatch
  • 엔티티: BatchMetadata
  • 값 객체: BatchSize, BatchStatus, SourceSiteId, IssuerAccountId, GroupId, PlanId, CommonExpirationTime, CommonTreatmentPeriod, CommonUsagePeriod, IssueSource
  • 불변식:
    • 배치 크기는 정책 제한을 초과할 수 없음 (최대 10,000개)
    • 모든 코드는 동일한 정책을 따름
    • 발급자 계정 ID는 유효한 계정이어야 함
    • 발급 출처는 유효한 값이어야 함
    • 동일 그룹에 대한 일일 배치 생성 한도를 준수해야 함 (최대 5개)

6.3 AccessCodePolicy 애그리게잇​

  • 루트: AccessCodePolicy
  • 값 객체: ValidationRules, SecurityRules, IssueSourceRules, FormatRules, ExpirationRules, AttemptRules
  • 불변식:
    • 정책 규칙은 일관성을 유지해야 함
    • 보안 규칙은 최소 요구사항을 충족해야 함
    • 발급 출처별 규칙은 명확히 정의되어야 함
    • 형식 규칙은 시스템 전체에서 일관되게 적용되어야 함
    • 만료 규칙은 유효한 기간 제한을 포함해야 함
    • 시도 규칙은 보안 정책에 부합해야 함

6.4 StandardFormatPolicy 애그리게잇​

  • 루트: StandardFormatPolicy
  • 값 객체: FormatPattern, ValidationRules, IssueSourceFormatRules, DisplayFormatRules
  • 불변식:
    • 표준 포맷 정책은 시스템 전체에서 하나만 존재해야 함
    • 포맷 패턴은 정규식으로 검증 가능해야 함
    • 모든 보험사 코드는 표준 포맷 정책을 준수해야 함
    • 발급 출처별 포맷 규칙은 명확히 정의되어야 함
    • 표시 형식 규칙은 사용자 인터페이스에 일관되게 적용되어야 함

6.5 IssueSourceMetadata 애그리게잇​

  • 루트: IssueSourceMetadata
  • 값 객체: IssueSourceType, ClinicMetadata, OCRMetadata, InsuranceCodeMetadata
  • 불변식:
    • 발급 출처 타입은 유효한 값이어야 함
    • 메타데이터는 발급 출처 타입에 맞게 제공되어야 함
    • 진료 대시보드 메타데이터는 필수 필드를 포함해야 함 (진료소 ID, 의사 ID, 환자 ID, 진료 예약 ID)
    • OCR 메타데이터는 필수 필드를 포함해야 함 (진료비 상세내역 ID, 병원명, 진료비 발생일, 진료비 금액)
    • 보험사 코드 메타데이터는 필수 필드를 포함해야 함 (보험사 ID, 보험 증권 번호, 보험금 청구 ID)

6.6 ExternalAPICall 애그리게잇​

  • 루트: ExternalAPICall
  • 값 객체: APIRequestDetails, APIResponseDetails, CallStatus, RetryCount, ErrorDetails
  • 불변식:
    • API 호출은 재시도 정책을 따름
    • 최대 재시도 횟수는 정책을 초과할 수 없음
    • 성공한 호출은 유효한 응답 데이터를 포함해야 함

6.7 CodeInputFormat 애그리게잇​

  • 루트: CodeInputFormat
  • 값 객체: RawInput, NormalizedInput, InputValidationResult
  • 불변식:
    • 정규화된 입력은 표준 형식 규칙을 따라야 함
    • 입력 검증 결과는 명확한 오류 메시지를 포함해야 함
    • 대소문자 구분 없이 처리되어야 함

6.8 ReportGeneration 애그리게잇​

  • 루트: ReportGeneration
  • 엔티티: ReportConfiguration
  • 값 객체: ReportType, ReportPeriod, ReportFilters, ReportFormat
  • 불변식:
    • 보고서 유형은 시스템에서 지원하는 유형이어야 함
    • 보고서 기간은 유효한 날짜 범위여야 함
    • 보고서 형식은 지원되는 형식(PDF, Excel 등)이어야 함

7. 주요 명령​

7.1 코드 관리 명령​

  • CreateAccessCode: 새로운 접근 코드 생성
  • ActivateAccessCode: 접근 코드 활성화
  • DeactivateAccessCode: 접근 코드 비활성화
  • DeleteAccessCode: 접근 코드 삭제
  • ValidateAccessCode: 접근 코드 유효성 검증
  • RevokeAccessCode: 사용 중인 접근 코드 철회
  • ChangeAccessCodeStatus: 접근 코드 상태 변경
  • ResetFailureCount: 실패 횟수 초기화

7.2 코드 검증 명령​

  • VerifyAccessCode: 접근 코드 검증
  • ValidateStandardFormat: 표준 포맷 검증
  • VerifyInsuranceCode: 보험사 코드 검증
  • ValidateInsuranceCodeFormat: 보험사 코드 포맷 검증
  • CallExternalValidationAPI: 외부 API를 통한 보험사 코드 유효성 검증
  • ValidateAccessCodeInput: 사용자 입력 코드 형식 검증
  • NormalizeAccessCodeInput: 코드 입력 정규화(공백 제거, 대소문자 처리)
  • HandleExceededAttempts: 허용 시도 횟수 초과 처리

7.3 코드 발급 명령​

  • IssueAccessCodeForSample: 견본품용 접근 코드 발급
  • IssueAccessCodeForDemo: 데모용 접근 코드 발급
  • IssueAccessCodeForDevelopment: 개발용 접근 코드 발급
  • IssueAccessCodeFromClinicDashboard: 진료 대시보드에서 코드 발급
  • IssueAccessCodeFromOCRInvoice: OCR 인식 진료비 서류에서 코드 발급
  • IssueAccessCodeByInsurance: 보험사에서 코드 발급
  • CheckPatientExistingCodes: 환자의 기존 발급 코드 확인

7.4 배치 관리 명령​

  • CreateBatchAccessCodes: 대량 코드 일괄 생성
  • IssueBulkAccessCodes: 대량 코드 일괄 발급
  • DeactivateBatchAccessCodes: 배치 단위 접근 코드 비활성화
  • UpdateAccessCodePolicy: 접근 코드 정책 업데이트
  • GenerateAccessCodeStats: 접근 코드 통계 생성

7.5 조회 관리 명령​

  • GetAllAccessCodes: 모든 접근 코드 조회
  • GetActiveAccessCodes: 활성 접근 코드 조회
  • GetUsedAccessCodes: 사용된 접근 코드 조회
  • FilterAccessCodesByStatus: 상태별 코드 필터링
  • FilterAccessCodesByIssueSource: 발급 출처별 코드 필터링
  • FilterAccessCodesByGroup: 그룹별 코드 필터링

7.6 보고서 관리 명령​

  • GenerateDailyUsageReport: 일별 사용 보고서 생성
  • GenerateWeeklyUsageReport: 주별 사용 보고서 생성
  • GenerateMonthlyUsageReport: 월별 사용 보고서 생성
  • GenerateSourceUsageReport: 출처별 사용 보고서 생성
  • GenerateGroupUsageReport: 그룹별 사용 보고서 생성
  • GenerateIssueSourceUsageReport: 발급 출처별 사용 보고서 생성
  • GenerateExpiringAccessCodesReport: 만료 예정 코드 보고서 생성
  • GenerateAbnormalAttemptsReport: 비정상 시도 보고서 생성
  • GenerateSuccessFailureRatioReport: 성공/실패 비율 보고서 생성
  • ExportReportToPDF: 보고서 PDF 내보내기
  • ExportReportToExcel: 보고서 Excel 내보내기

7.7 알림 관리 명령​

  • SendAccessCodeIssuedNotification: 코드 발급 알림 전송
  • SendBatchCompletionNotification: 대량 발급 완료 알림 전송
  • SendAccessCodeExpirationNotification: 만료 예정 코드 알림 전송
  • SendAbnormalAttemptsNotification: 비정상 시도 알림 전송
  • SendBatchFailureNotification: 배치 처리 실패 알림 전송
  • ConfigureNotificationPreferences: 알림 설정 구성

7.8 UI 관리 명령​

  • RenderAccessCodeWithHyphens: 하이픈 포함 형식으로 코드 표시
  • DisplayAccessCodeResult: 코드 검증 결과 표시
  • DisplayAccessCodeInputError: 사용자 친화적 오류 메시지 표시
  • DisplayAdminDashboard: 관리자 대시보드 표시
  • PerformBatchOperationConfirmation: 대량 작업 수행 확인 요청
  • DisplayUsageStatistics: 사용 통계 시각화

8. 기술 스택​

  • NestJS
  • TypeScript
  • PostgreSQL (코드 저장 및 관리)
  • Redis (코드 캐싱 및 만료 관리)
  • GCP Pub/Sub (이벤트 메시징)
  • Kubernetes (분산 처리 및 확장성)
  • Elastic Stack (모니터링 및 로깅)
  • Google Cloud Vision API (OCR 처리)
  • RESTful API 및 WebSocket (진료 대시보드 통합)
  • Axios/Fetch (외부 API 통신)
  • Circuit Breaker (외부 API 장애 대응)

9. 핫스팟 및 해결책​

9.1 성능​

  • 대량 생성 시 비동기 및 병렬 처리
  • 검증 작업에 캐시 레이어 도입
  • 복합 인덱스를 통한 조회 쿼리 최적화
  • OCR 처리 결과 캐싱 및 점진적 처리
  • 진료 대시보드 요청 우선순위 부여
  • 외부 API 응답 캐싱
  • 외부 API 타임아웃 최적화

9.2 보안​

  • 코드 암호화 저장 및 접근 로깅
  • Rate Limiting을 통한 무차별 대입 방지
  • RBAC를 통한 발급자 권한 검증
  • 허용된 출처 사이트 화이트리스트 관리
  • OCR 데이터 전송 및 저장 시 암호화
  • 진료 대시보드 통신 TLS 1.3 이상 적용
  • 외부 API 통신 암호화 및 인증 강화
  • API 키 및 시크릿 안전한 관리

9.3 확장성​

  • 분산 락 적용 및 큐 시스템 도입
  • 데이터 샤딩 및 아카이빙
  • 그룹별 제한 관리를 위한 분산 카운터 사용
  • 발급 출처별 독립적 스케일링
  • OCR 처리량 증가에 따른 자동 확장
  • 외부 API 호출 대역폭 관리

9.4 표준 코드 포맷 검증​

  • 고성능 정규식 기반 검증 엔진
  • 패턴 매칭 캐싱
  • 오류 코드별 상세 피드백 제공
  • 발급 출처별 맞춤형 검증 규칙 적용
  • 보험사 코드 포맷 검증 전처리

9.5 코드 관리 UI​

  • 운영 매니저를 위한 관리 대시보드
  • 코드 일괄 관리 인터페이스
  • 실시간 상태 모니터링
  • 코드 사용 현황 통계 시각화
  • 발급 출처별 필터링 및 검색 기능
  • 외부 API 호출 상태 모니터링

9.6 발급 출처 통합​

  • OCR 처리 지연 시 비동기 알림 제공
  • 진료 대시보드 통합 부하 분산
  • 외부 API 장애 시 대체 검증 전략
  • 보험사 코드 입력 오류 자동 수정 지원

9.7 데이터 일관성​

  • 발급 출처 데이터 불일치 감지 및 해결 메커니즘
  • 진료 정보 변경 시 관련 코드 자동 업데이트
  • OCR 데이터 검증 단계 추가
  • 외부 API 응답 데이터 검증 및 정규화

9.8 외부 API 장애 대응​

  • Circuit Breaker 패턴 적용
  • Fallback 메커니즘 구현
  • 재시도 정책 최적화
  • 분산 트레이싱을 통한 장애 지점 식별
  • 외부 API 상태 모니터링 및 알림

10. 변경 이력​

버전날짜작성자변경 내용
0.1.02025-03-16bok@weltcorp.com최초 작성