1. 코드 생성 규칙
1.1 코드 형식
- 코드 길이: 16자리
- 문자셋: 영문 대소문자, 숫자 조합
- 특수문자 제외
1.2 유효성 규칙
- 발급된 날로부터 1년 동안 사용 가능
- 사용된 코드는 재사용 불가
- 코드 값은 시스템 내에서 유일해야 함
- 동일한 코드 값을 중복 생성 불가
- 기본적으로 코드 생성 날짜부터 사용 가능
- 특정 사용 시작일을 지정한 경우, 해당 날짜부터 사용 가능하며 그 날로부터 1년간 유효
- TimeMachine 사용 옵션이 활성화된 경우, 가상 시간 시작일은 현재 날짜로부터 최대 1년 이내로 설정 가능
- TimeMachine 사용 옵션이 활성화된 코드는 코드 생성 메타데이터에 useTimeMachine 플래그와 virtualTimeStartDate 값 포함
1.3 코드 유형별 패턴
- 일반 코드: 표준 패턴 적용
- 견본품용 코드: 접두사 'S-'로 시작 (내부적으로는 제외하고 16자리 유지)
- 데모용 코드: 접두사 'D-'로 시작 (내부적으로는 제외하고 16자리 유지)
- 개발용 코드: 접두사 'DEV-'로 시작 (내부적으로는 제외하고 16자리 유지)
1.4 코드 생성 제약사항
- 모든 코드는 생성 시 ActiveAccessCode 레지스트리에 등록
- 발급자 계정 ID는 유효한 계정이어야 함
- 출처(Source Site) ID는 등록된 유효한 사이트여야 함
- 코드 생성 시 그룹 ID가 지정된 경우, 해당 그룹은 유효해야 함
- 코드 생성 시 플랜 ID가 지정된 경우, 해당 플랜은 유효해야 함
- 그룹과 플랜은 독립적으로 지정 가능 (둘 다, 하나만, 또는 둘 다 없을 수 있음)
1.5 발급 출처별 규칙
- 모든 코드는 발급 출처(Issue Source)를 반드시 포함해야 함
- 발급 출처는 CLINIC_DASHBOARD, OCR_INVOICE, INSURANCE, SYSTEM, OTHER 중 하나여야 함
- 발급 출처에 따라 관련 메타데이터를 필수로 제공해야 함
1.5.1 진료 대시보드 출처 규칙
- 발급 출처가 CLINIC_DASHBOARD인 경우 다음 정보가 필수: 사이트 ID, 의사 ID, 환자 ID
- 진료 대시보드에서 발급된 코드는 진료 예약 ID와 연결될 수 있음
- 의사 프로필이 유효하고 활성 상태일 때만 코드 발급 가능
- 진료 대시보드에서는 한 번에 최대 10개의 코드만 발급 가능
- 동일 환자에 대해 30일 이내 중복 발급 시 경고 표시
- 발급된 코드는 환자의 진료 기록과 연결되어야 함
1.5.2 OCR 진료비 서류 출처 규칙
- 발급 출처가 OCR_INVOICE인 경우 다음 정보가 필수: 진료비 상세내역 ID, 병원명, 진료비 발생일
- OCR 인식 신뢰도가 85% 이상인 경우에만 자동 코드 발급
- 신뢰도가 70%~85%인 경우 운영자 확인 후 발급
- 신뢰도가 70% 미만인 경우 코드 발급 불가, 수동 처리 필요
- 인식된 진료비 내역이 유효한 항목을 포함할 때만 코드 발급
- 동일 영수증으로 중복 코드 발급 방지
- OCR 데이터는 코드 메타데이터로 저장되어야 함
1.5.3 보험사 코드 규칙
- 보험사 코드는 사용자가 보험사로부터 직접 받아 시스템에 입력
- 모든 보험사 코드는 외부 검증 API를 통해 유효성을 확인해야 함
- 외부 API 응답이 유효한 경우에만 코드 사용 허용
- 외부 API 연결 실패 시 임시 사용 허용 가능하나, 24시간 이내 재검증 필요
- 보험사 코드는 표준 형식을 준수해야 함
- 잘못된 형식의 보험사 코드 입력 시 교정 제안 제공
2. 코드 사용 규칙
2.1 수명주기 규칙
- 기본적으로 발급된 날로부터 1년 동안 유효 (기본 만료 기간)
- 특정 시작일이 지정된 경우, 해당 시작일부터 1년 동안 유효
- 시작일 이전의 코드는 '대기(pending)' 상태로 관리되며, 시작일이 되면 자동으로 '활성(active)' 상태로 변경
- 특정 코드의 경우 만료 기간을 별도 설정 가능
- 만료된 코드는 자동으로 비활성화 처리
- 사용된 코드는 '사용됨(used)' 상태로 변경되며 재사용 불가
2.2 검증 규칙
- 코드 검증 시 대소문자 구분
- 입력된 코드에서 공백은 자동 제거
- 16자리가 아닌 코드는 즉시 거부
- 코드 형식이 잘못된 경우 (특수문자 포함 등) 즉시 거부
- 코드 입력 실패 시 오류 메시지는 보안을 위해 구체적이지 않게 제공
- 발급 출처에 따라 검증 절차를 다르게 적용할 수 있음
- 코드 검증은 다음 순서로 진행:
- 형식 검증(공백 제거, 대소문자 정규화, 16자리 확인)
- 존재 검증(발급된 코드인지 확인)
- 상태 검증(활성 상태인지 확인)
- 만료 검증(유효기간 내인지 확인)
- 시도 횟수 검증(최대 시도 횟수 초과 여부 확인)
- 검증 단계에서 하나라도 실패하면 즉시 실패로 처리하고, 이후 단계는 진행하지 않음
- 검증 성공 시 해당 코드의 상태는 '사용됨'으로 자동 변경됨(일회용 코드의 경우)
- 검증 과정에서 코드 자체의 유효성만 확인하며, 사용자 정보는 확인하지 않음
- 접근 코드 검증 결과는 단순히 유효 또는 무효의 이진 결과로만 반환됨
2.3 상태 관리 규칙
- 코드 상태: pending(대기), active(활성), used(사용됨), expired(만료됨), blocked(차단됨), revoked(철회됨)
- 대기 상태의 코드는 지정된 시작일에 도달하기 전까지 사용 불가
- 활성 상태의 코드만 사용 가능
- 사용됨 상태의 코드는 추가 사용 불가
- 만료된 코드는 사용 불가 및 재활성화 불가
- 차단된 코드는 관리자에 의해 해제 가능
- 철회된 코드는 더 이상 사용할 수 없으며 상태 변경 불가
2.4 보안 규칙
- 동일 Device ID에 대해서 5회 이상 잘못된 코드 입력 시 해당 IP 일시 차단 (30분)
- 특정 코드에 대해 5회 이상 검증 실패 시 해당 코드 일시 차단
- 차단된 코드는 운영 매니저만 해제 가능
- 모든 코드 사용 시도는 로깅 처리
- 발급 출처별 보안 검증 수준을 달리 적용할 수 있음
2.5 Auth Domain 연동 규칙
- AccessCode Domain은 Auth Domain에게 코드 검증 결과만 제공함
- Auth Domain은 AccessCode Domain으로부터 받은 검증 결과에 따라 사용자 접근 권한을 관리함
- AccessCode Domain은 사용자의 접근 권한을 직접 부여하거나 거부하지 않음
- Auth Domain만이 User Domain과 직접 통신함
- Auth Domain은 코드 검증 시 AccessCode Domain에 사용자 정보를 제공하지 않음
- AccessCode Domain은 독립적으로 코드 검증을 수행하며, 다른 도메인의 컨텍스트에 의존하지 않음
3. 대량 관리 규칙
3.1 배치 생성 규칙
- 단일 배치 최대 크기: 10,000개
- 배치 내 모든 코드는 동일한 만료 기간 적용
- 배치 생성 시 고유한 배치 ID 부여
- 배치 내 모든 코드는 동일한 출처(Source Site) 적용
- 동일 그룹에 대한 일일 배치 생성 한도: 5개 배치
- 배치 생성 시 발급 출처 정보 필수 포함
- 배치 내 모든 코드는 동일한 그룹 ID와 플랜 ID 적용 (지정된 경우)
3.2 대량 발급 규칙
- 대량 발급은 비동기적으로 처리
- 대량 발급 진행 상태 실시간 확인 가능
- 발급 오류 발생 시 부분적 롤백 지원
- 대량 발급 결과는 이메일로 통지 가능
- 발급 출처별 대량 발급 제한 설정 가능
3.3 대량 비활성화 규칙
- 특정 배치 ID로 전체 비활성화 가능
- 특정 출처나 그룹 ID로 필터링하여 대량 비활성화 가능
- 비활성화 작업은 트랜잭션으로 처리
- 이미 사용된 코드는 비활성화 대상에서 제외
- 발급 출처별 비활성화 권한 레벨 설정 가능
4. 조회 및 관리 규칙
4.1 조회 권한 규칙
- 운영 매니저만 전체 코드 조회 가능
- 사용자는 자신에게 발급된 코드만 조회 가능
- 상태별 필터링 조회 지원
- 발급 출처별 필터링 조회 지원
- 의료진은 자신이 발급한 진료 대시보드 코드만 조회 가능
4.2 보고서 생성 규칙
- 일별/주별/월별 코드 사용 통계 제공
- 출처별/그룹별 코드 사용 현황 보고서 생성
- 만료 예정(30일 이내) 코드 목록 자동 생성
- 비정상 시도(차단된 코드, 반복 실패) 보고서 일일 생성
- 발급 출처별 성공/실패 비율 보고서 생성
- OCR 인식 신뢰도 분포 보고서 생성 (주간/월간)
- 진료 대시보드 발급 통계 보고서 생성 (의사별, 진료소별)
4.3 관리자 작업 규칙
- 코드 상태 변경은 감사 로그 남김
- 운영 매니저의 모든 코드 관리 작업 기록
- 대량 작업은 작업 전 확인 단계 필수
- 중요 작업(대량 삭제 등)은 2단계 승인 필요
- 발급 출처별 관리 권한 설정 가능
5. 표준 포맷 규칙
5.1 보험사 코드 규칙
- 표준 코드 형식을 모든 보험사가 준수
- 보험사 코드 확인 시 표준 형식 적용하여 검증
- 포맷 불일치 시 사용자에게 적절한 안내 메시지 제공
- 외부 API를 통한 유효성 검증 필수
- 유효하지 않은 보험사 코드 입력 시 최대 3번까지 재시도 허용
5.2 코드 표현 규칙
- UI 표시 시 4자리마다 하이픈으로 구분 (예: ABCD-1234-EFGH-5678)
- 내부 저장 시 하이픈 없이 16자리로 저장
- 출력물에는 가독성을 위해 하이픈 포함 형태로 표시
- 사용자 입력 시 하이픈 유무 모두 허용
5.3 출처별 형식 규칙
- 진료 대시보드 발급 코드: Site 식별자를 메타데이터에 포함
- OCR 인식 코드: 원본 진료비 상세내역 문서 ID와 OCR 신뢰도 점수를 메타데이터에 포함
- 보험사 코드: 보험사 식별자와 외부 API 검증 결과를 메타데이터에 포함
5.4 발급 책임 구분 규칙
- AccessCode Domain은 코드 생성 및 관리만 담당하며, 코드 전달은 책임지지 않음
- 진료 대시보드는 의료진이 환자 정보와 진료 내역을 기반으로 접근 코드 발급을 요청함
- OCR 처리 서비스는 업로드된 진료비 서류를 분석하여 접근 코드 발급을 요청함
- 보험사는 자체 시스템에서 접근 코드를 생성하여 사용자에게 직접 제공함
- 발급 출처에 관계없이 모든 코드는 AccessCode Domain에서 관리됨
- 코드 발급 결과 통지는 Notification Domain의 책임임
5.5 코드 검증 흐름 규칙
- 앱은 Auth Domain에 코드 검증을 요청함
- Auth Domain은 내부적으로 AccessCode Domain에 검증을 요청함
- AccessCode Domain은 코드 검증 결과를 Auth Domain에게만 반환함
- Auth Domain은 AccessCode Domain의 검증 결과에 따라 앱에게 적절한 응답을 제공함
- 검증 과정에서 User Domain과 AccessCode Domain 간의 직접적인 상호작용은 발생하지 않음
- 모든 검증 요청 및 결과는 감사 목적으로 로깅되어야 함
6. 외부 시스템 연동 규칙
6.1 진료 대시보드 연동 규칙
- 진료 대시보드 시스템에서 코드 발급 요청 시 TLS 1.3 이상 암호화 통신 사용
- 모든 요청은 JWT 인증 후 처리
- 진료 대시보드 시스템의 요청 비율은 분당 최대 60회로 제한
- 의사 ID는 유효한 의사 프로필과 일치해야 함
- 발급 요청 시 필수 필드: 진료소 ID, 의사 ID, 환자 ID, 진료 날짜
- 응답 시간은 2초 이내여야 함
6.2 OCR 처리 규칙
- OCR 처리 시스템은 진료비 상세내역 이미지만 처리 가능
- OCR 인식 결과에는 최소한 병원명, 진료일, 환자명, 진료비 항목이 포함되어야 함
- OCR 처리는 업로드 후 10초 이내 완료되어야 함
- OCR 결과 신뢰도 점수를 메타데이터에 기록
- 유효하지 않은 OCR 결과는 별도 저장소에 보관하여 학습 데이터로 활용
- OCR 처리 과정에서 민감 정보(주민번호 등)는 마스킹 처리
6.3 외부 API 연동 규칙
- 외부 API 호출 시 타임아웃은 3초로 설정
- 외부 API 호출 실패 시 최대 3회 재시도
- API 호출 간격은 지수 백오프 알고리즘 적용 (첫 재시도 500ms, 두번째 재시도 1000ms)
- 모든 API 호출과 응답은 로깅 처리
- API 키는 암호화하여 저장
- 외부 API 서비스 장애 시 대체 검증 경로 제공
- Circuit Breaker 패턴을 적용하여 외부 API 서비스 과부하 방지
6.4 UI 및 사용자 경험 규칙
- 코드 입력 화면은 직관적이고 사용하기 쉬워야 함
- 검증 결과는 명확하게 표시되어야 함
- 오류 메시지는 사용자 친화적이면서도 보안을 고려해야 함
- 코드 입력란은 입력된 공백을 자동으로 제거해야 함 (대소문자는 변환하지 않음)
- 입력 오류 발생 시 사용자에게 즉각적인 피드백 제공
- 코드 입력 화면에는 도움말 및 지원 정보가 포함되어야 함
- 접근성 표준(WCAG)을 준수하여 다양한 사용자가 이용할 수 있어야 함
7. TimeMachine 연동 규칙
7.1 코드 생성 시 TimeMachine 설정 규칙
- 코드 생성 시 TimeMachine 사용 유무를 선택할 수 있어야 함
- TimeMachine 사용으로 설정된 경우, 가상 시간 시작일을 필수로 지정해야 함
- 가상 시간 시작일은 현재 날짜로부터 최대 1년 이내로 제한됨
- TimeMachine 관련 설정은 코드 메타데이터에 저장되어 코드 검증 시 함께 반환됨
- 기본 설정은 TimeMachine 미사용(false)임
7.2 코드 검증 시 TimeMachine 연동 규칙
- 코드 검증 결과에는 TimeMachine 사용 유무와 가상 시간 시작일 정보가 포함됨
- 앱은 코드 검증 결과에 포함된 TimeMachine 설정에 따라 시간 정보 처리 방식 결정
- TimeMachine 사용 설정이 true인 경우, 앱은 시스템의 TimeMachine 서비스에서 제공하는 가상 시간을 사용
- TimeMachine 사용 설정이 false인 경우, 앱은 디바이스의 로컬 시간을 사용
- 코드 검증 API 응답에는 useTimeMachine 플래그와 virtualTimeStartDate 필드 포함
7.3 사용자 등록 시 TimeMachine 적용 규칙
- TimeMachine 설정이 활성화된 코드로 사용자 등록 시, 해당 사용자 계정에 TimeMachine 기능 자동 활성화
- 사용자 계정 생성 시, 코드에 지정된 가상 시간 시작일이 해당 사용자의 초기 가상 시간으로 설정됨
- 가입 완료일, 계정 생성일 등 사용자와 관련된 모든 타임스탬프는 설정된 가상 시간을 기준으로 기록됨
- 시스템은 사용자 생성 시 TimeMachine 서비스에 가상 시간 설정 이벤트를 발행해야 함
- 사용자 등록 완료 후, 프론트엔드는 TimeMachine 기능 활성화 정보를 사용자에게 알려야 함
7.4 TimeMachine 상태 관리 규칙
- 사용자 계정의 TimeMachine 활성화 상태는 User Domain과 TimeMachine Domain에서 동기화되어야 함
- 코드를 통해 TimeMachine이 활성화된 사용자는 앱에서 TimeMachine 기능을 비활성화할 수 있음
- TimeMachine 비활성화 시, 현실 시간 이후의 모든 데이터는 자동으로 삭제됨
- TimeMachine 상태 변경은 이력으로 기록되어야 함
- PROD 환경에서는 일반 사용자에게 TimeMachine 기능이 노출되지 않아야 함
- 개발 및 테스트 환경에서는 코드와 관계없이 TimeMachine 기능 활성화 가능
7.5 TimeMachine 이벤트 처리 규칙
- 코드 사용으로 인한 TimeMachine 활성화 시, TimeMachine 활성화 이벤트가 발행되어야 함
- 이벤트에는 사용자 ID, 가상 시간 시작일, 이벤트 발생 시간이 포함되어야 함
- TimeMachine 상태 변경 이벤트는 GCP Pub/Sub을 통해 관련 시스템에 전파되어야 함
- 이벤트 처리 실패 시 재시도 메커니즘을 통해 데이터 일관성 보장
- 모든 TimeMachine 관련 이벤트는 감사 목적으로 로깅되어야 함
8. 변경 이력