AccessCode API 요구사항 명세서

관련 문서

TBD

1. 개요

AccessCode API는 WELT 앱 등록 및 인증을 위한 코드를 생성, 검증, 관리하는 API입니다. 이 API를 통해 관리자는 코드를 생성하고, 사용자는 발급받은 코드를 통해 앱을 등록할 수 있습니다.

2. 기능 요구사항

2.1 권한 관리

2.1.1 사용자 유형별 권한 (ACC-FR-BE-001)

• System Admin

  • 모든 Access Code 정책 관리 권한
  • 전체 Access Code 생성 및 관리 권한
  • 모든 이력 조회 권한
  • 긴급 Access Code 발급 권한
  • 권한 위임 및 회수 권한

• IAM Admin

  • 할당된 범위 내 Access Code 관리 권한
  • 범위 내 코드 생성 및 재발급 권한
  • 범위 내 코드 상태 관리 권한
  • 범위 내 이력 조회 권한

• Service Account

  • Access Code 검증 권한
  • 코드 상태 조회 권한
  • 대량 코드 검증 권한

• Regular User

  • 자신의 Access Code 관리 권한
  • 코드 요청 및 사용 권한
  • 개인 이력 조회 권한

2.1.2 권한 범위 관리 (ACC-FR-BE-002)

• 글로벌 범위: 전체 시스템
• 조직 범위: 특정 조직 내
• 팀 범위: 특정 팀 내
• 개인 범위: 개인 리소스만

2.2 코드 생성

백엔드 요구사항

• ACC-FR-BE-003: 시스템은 관리자가 치료용, 시험용, 데모용 코드를 생성할 수 있어야 한다.
• ACC-FR-BE-004: 시스템은 코드를 고유하고 안전한 방식으로 생성해야 한다.
• ACC-FR-BE-005: 시스템은 생성되는 Access Code가 16자리의 영문 대소문자와 숫자로 구성되도록 해야 한다.
• ACC-FR-BE-006: 시스템은 코드 생성 시 만료 기간을 설정할 수 있어야 한다.
• ACC-FR-BE-007: 시스템은 일괄 코드 생성 기능을 제공해야 한다.
• ACC-FR-BE-008: 시스템은 코드 생성 시 TimeMachine 사용 유무를 지정할 수 있어야 한다.
• ACC-FR-BE-009: 시스템은 TimeMachine 사용 옵션이 활성화된 경우, 가상 시간의 시작일을 지정할 수 있어야 한다.
• ACC-FR-BE-010: 시스템은 가상 시간 시작일로 설정 가능한 기간을 현재부터 최대 1년 이내로 제한해야 한다.
• ACC-FR-BE-011: 시스템은 TimeMachine 사용 옵션이 활성화된 코드 사용 시 모든 시간 관련 정보(가입 완료일, 사용자 계정 생성일 등)가 지정된 가상 시간을 사용하도록 해야 한다.
• ACC-FR-BE-012: 시스템은 코드 생성 시 선택적으로 특정 그룹 ID(groupId)와 플랜 ID(planId)를 지정할 수 있어야 한다.
  • (설명): groupId는 해당 코드를 통해 가입하는 사용자가 초기에 소속될 그룹을 의미한다. planId는 해당 사용자가 초기에 할당받을 플랜을 의미한다. Group과 Plan은 독립적인 개념으로, 그룹은 조직/기능적 권한을, 플랜은 서비스 수준 권한을 제공한다. 사용자는 가입 이후 IAM 기능을 통해 추가적인 그룹이나 플랜에 할당될 수 있다. 이 방식은 초기 설정을 명확히 하고 권한 지정의 모호성을 방지한다.
• ACC-FR-BE-013: 시스템은 코드 생성 이력을 기록하고 추적할 수 있어야 한다.
• ACC-FR-BE-014: 시스템은 각 코드 생성 요청에 대해 고유한 식별자를 부여해야 한다.

Access Code 생성 시 이메일 처리

• ACC-FR-BE-015: 시스템은 Access Code 생성 API (POST /v1/access-codes) 요청 시, email 필드를 선택적으로 수신할 수 있다.
• ACC-FR-BE-016: 이 email 필드는 생성된 Access Code를 사용자에게 전달하기 위한 수단(예: 이메일 발송)으로 사용된다. 이는 API 명세서의 deliveryMethod 필드와 함께 고려될 수 있다.
• ACC-FR-BE-017: email 주소는 Access Code 자체의 핵심 속성이 아니므로, AccessCode 도메인 모델 및 관련 데이터베이스 테이블에는 직접 저장되지 않는다.
• ACC-FR-BE-018: 이는 개인정보 보호 원칙을 준수하기 위함이며, 이메일 주소는 코드 전달 프로세스 내에서만 사용되거나 필요한 경우 별도의 보안 스키마(private 스키마) 내에서 관리된다.

프론트엔드 요구사항

• ACC-FR-FE-001: TBD

2.3 코드 검증

백엔드 요구사항

• ACC-FR-BE-019: 시스템은 코드의 유효성을 검증할 수 있어야 한다.
• ACC-FR-BE-020: 시스템은 디바이스 정보와 함께 코드 검증을 수행해야 한다.
• ACC-FR-BE-021: 시스템은 만료된 코드를 사용할 수 없도록 해야 한다.
• ACC-FR-BE-022: 시스템은 이미 사용된 코드를 재사용할 수 없도록 해야 한다.
• ACC-FR-BE-023: 시스템은 코드 검증 결과를 기록하고 추적할 수 있어야 한다.
• ACC-FR-BE-024: 시스템은 유효하지 않은 코드에 대해 명확한 오류 메시지를 제공해야 한다.
• ACC-FR-BE-025: 시스템은 대량 코드 검증을 위한 배치 API를 제공해야 한다.
• ACC-FR-BE-026: 시스템은 코드 검증의 결과에 TimeMachine 사용 유무와 사용으로 설정된 경우 가상의 시간값을 앱에게 제공해야 한다.

프론트엔드 요구사항

• ACC-FR-FE-002: TBD

2.4 코드 사용

백엔드 요구사항

• ACC-FR-BE-027: 시스템은 검증된 코드를 특정 사용자와 디바이스에 연결해야 한다.
• ACC-FR-BE-028: 시스템은 코드 사용(회원 가입 완료) 시, 인증(Auth) 도메인에서 요구하는 필수 동의 항목들이 정상적으로 수신되었는지 확인해야 한다. (상세 동의 항목 및 처리는 Auth 도메인 책임)
• ACC-FR-BE-029: 시스템은 코드 사용 시, 해당 Access Code에 특정 그룹 ID(groupId)와/또는 플랜 ID(planId)가 지정되어 있다면, 생성된 사용자를 해당 초기 그룹과 플랜에 자동으로 할당해야 한다. (그룹/플랜 할당 로직은 IAM 도메인과 연계)
  • (설명): 사용자는 이후 시스템 로직이나 관리자에 의해 추가적인 그룹이나 플랜에 할당될 수 있다.
• ACC-FR-BE-030: 만약 코드에 특정 그룹 ID가 지정되지 않았다면, 시스템은 코드 유형이나 기타 정책에 따라 기본 그룹(Default Group)을 사용자에게 할당해야 한다. (기본 그룹 정책 정의 필요 - TBD)
• ACC-FR-BE-031: 만약 코드에 특정 플랜 ID가 지정되지 않았다면, 시스템은 코드 유형이나 기타 정책에 따라 기본 플랜(Default Plan)을 사용자에게 할당해야 한다. (기본 플랜 정책 정의 필요 - TBD)
• ACC-FR-BE-032: 시스템은 코드 사용 시 TimeMachine 서비스와 연동되어야 한다.
• ACC-FR-BE-033: 시스템은 코드 생성 시 TimeMachine 사용 옵션이 활성화된 경우, 해당 코드로 가입 완료한 사용자에게 자동으로 TimeMachine 기능을 활성화해야 한다.
• ACC-FR-BE-034: 시스템은 코드에 지정된 가상 시간 시작일을 사용자 계정의 초기 가상 시간으로 설정해야 한다.
• ACC-FR-BE-035: 시스템은 사용자 계정과 관련된 모든 시간 데이터를 설정된 가상 시간을 기준으로 기록해야 한다.
• ACC-FR-BE-036: 시스템은 코드 사용 이력을 기록하고 추적할 수 있어야 한다.
• ACC-FR-BE-037: 시스템은 코드 사용 시 해당 코드의 상태를 'USED'로 업데이트해야 한다.
• ACC-FR-BE-038: 시스템은 코드 사용 완료 후 적절한 권한과 리소스 접근을 사용자에게 부여해야 한다.

프론트엔드 요구사항

• ACC-FR-FE-003: TBD

2.5 개인정보 처리

백엔드 요구사항

• ACC-FR-BE-039: 시스템은 GDPR과 개인정보보호법을 준수해야 한다.
• ACC-FR-BE-040: 시스템은 개인정보 처리에 대한 동의를 관리해야 한다.
• ACC-FR-BE-041: 시스템은 데이터 주체의 권리를 보장해야 한다.
• ACC-FR-BE-042: 시스템은 개인정보 처리 이력을 기록하고 추적할 수 있어야 한다.
• ACC-FR-BE-043: 시스템은 필요한 경우 개인정보를 익명화하거나 가명화할 수 있어야 한다.
• ACC-FR-BE-044: 시스템은 개인정보 유출 방지를 위한 보안 조치를 구현해야 한다.

프론트엔드 요구사항

• ACC-FR-FE-004: TBD

3. 비기능 요구사항

3.1 성능

• ACC-NFR-001: 시스템은 권한 검증에 대해 50ms 이내의 응답시간을 제공해야 한다.
• ACC-NFR-002: 시스템은 코드 생성에 대해 500ms 이내의 응답시간을 제공해야 한다.
• ACC-NFR-003: 시스템은 코드 검증에 대해 200ms 이내의 응답시간을 제공해야 한다.
• ACC-NFR-004: 시스템은 코드 사용에 대해 300ms 이내의 응답시간을 제공해야 한다.
• ACC-NFR-005: 시스템은 일괄 코드 생성을 초당 100개 처리할 수 있어야 한다.
• ACC-NFR-006: 시스템은 초당 최소 50개의 코드 검증 요청을 처리할 수 있어야 한다.
• ACC-NFR-007: 시스템은 동시에 최소 500명 이상의 사용자가 코드를 사용할 수 있어야 한다.

3.2 보안

• ACC-NFR-008: 시스템은 모든 API에 인증을 적용해야 한다.
• ACC-NFR-009: 시스템은 모든 요청에서 권한 검증을 수행해야 한다.
• ACC-NFR-010: 시스템은 IAM 정책 기반 접근 제어를 구현해야 한다.
• ACC-NFR-011: 시스템은 권한 변경 이력을 추적하고 감사할 수 있어야 한다.
• ACC-NFR-012: 시스템은 관리자 API에 추가 인증을 적용해야 한다.
• ACC-NFR-013: (공통 정책 참조) 개인정보 암호화는 Platform 표준을 따른다 - PLT-SEC-001, PLT-SEC-003
• ACC-NFR-014: 시스템은 API 요청/응답 로깅 시 민감정보를 마스킹해야 한다.
• ACC-NFR-015: 시스템은 코드 생성 및 관리에 대한 감사 로그를 유지해야 한다.
• ACC-NFR-016: 시스템은 정기적인 보안 취약점 검사를 지원해야 한다.

3.3 가용성

• (공통 정책 참조) 가용성/복구/백업/무중단 배포는 Platform 도메인 기준을 따른다: PLT-NFR-004, PLT-NFR-005, PLT-NFR-006, PLT-NFR-007
• ACC-NFR-017: 시스템은 API 가용성 99.9% 이상을 유지해야 한다.
• ACC-NFR-021: 시스템은 장애 시 자동 복구 메커니즘을 구현해야 한다.

3.4 확장성

• (공통 정책 참조) 확장성 원칙은 Platform 도메인 기준을 따른다: PLT-NFR-001, PLT-NFR-003
• ACC-NFR-023: 시스템은 수평적 확장이 가능한 설계를 구현해야 한다.
• ACC-NFR-024: 시스템은 새로운 코드 유형을 쉽게 추가할 수 있어야 한다.
• ACC-NFR-025: 시스템은 다국어 지원이 가능한 구조를 갖추어야 한다.
• ACC-NFR-026: 시스템은 사용자 증가에 따른 성능 저하 없이 확장할 수 있어야 한다.
• ACC-NFR-027: 시스템은 데이터 증가에 따른 성능 저하를 최소화해야 한다.
• ACC-NFR-028: 시스템은 다양한 환경(개발, 테스트, 스테이징, 프로덕션)에서 일관되게 동작해야 한다.

3.5 운영 품질 속성(Platform 연계)

• (공통 정책 참조) 가용성/복구/백업/무중단 배포는 Platform 기준을 따른다: PLT-NFR-004, PLT-NFR-005, PLT-NFR-006, PLT-NFR-007
• (공통 정책 참조) 관찰 가능성 표준(메트릭/로깅/트레이싱)은 Platform 기준을 따른다: PLT-NFR-008, PLT-NFR-009, PLT-NFR-010

3.6 규제 준수(감사 추적)

• (교차참조) 도메인 데이터 및 설정의 중요 변경은 Audit 기준을 준수한다: AUD-NFR-023, AUD-NFR-024, AUD-NFR-026

4. 제약사항

4.1 기술적 제약

• ACC-CR-001: 시스템은 NestJS 프레임워크를 사용하여 구현되어야 한다.
• ACC-CR-002: 시스템은 TypeScript strict 모드를 적용해야 한다.
• ACC-CR-003: 시스템은 PostgreSQL 데이터베이스를 사용해야 한다.
• ACC-CR-004: 시스템은 Redis 캐싱을 구현해야 한다.
• ACC-CR-005: 시스템은 Docker 컨테이너화가 가능해야 한다.
• ACC-CR-006: 시스템은 Kubernetes 환경에서 운영될 수 있어야 한다.
• ACC-CR-007: 시스템은 CI/CD 파이프라인을 통한 자동 배포를 지원해야 한다.

4.2 비즈니스 제약

• ACC-CR-008: 시스템은 코드 유효기간을 최대 1년으로 제한해야 한다.
• ACC-CR-009: 시스템은 동일 사용자당 활성 코드를 1개로 제한해야 한다.
• ACC-CR-010: 시스템은 일괄 생성을 한 번에 최대 1000개까지로 제한해야 한다.
• ACC-CR-011: 시스템은 IAM Admin이 자신의 범위를 벗어난 권한을 위임할 수 없도록 해야 한다.
• ACC-CR-012: 시스템은 Service Account가 권한을 위임할 수 없도록 해야 한다.
• ACC-CR-013: 시스템은 Regular User가 자신의 리소스만 접근할 수 있도록 제한해야 한다.
• ACC-CR-014: 시스템은 특정 코드 유형에 따른 비즈니스 규칙을 적용해야 한다.

4.3 규제 제약

• ACC-CR-015: 시스템은 GDPR을 준수해야 한다.
• ACC-CR-016: 시스템은 개인정보보호법을 준수해야 한다.
• ACC-CR-017: 시스템은 의료기기 규제를 준수해야 한다.
• ACC-CR-018: 시스템은 데이터 보관 및 폐기에 관한 법적 요구사항을 준수해야 한다.
• ACC-CR-019: 시스템은 관련 규제에 따른 감사 및 보고 요구사항을 충족해야 한다.

5. 용어 정의

5.1 코드 상태

• UNUSED: 미사용 상태의 코드
• USED: 사용이 완료된 코드
• EXPIRED: 유효기간이 만료된 코드
• REVOKED: 관리자에 의해 취소된 코드

5.2 코드 유형

• WELT: 치료 목적 코드
• CLINICAL_TRIAL: 임상시험용 코드
• DEMO: 데모용 코드

5.3 권한 관련 용어

• Scope: 권한의 적용 범위 (글로벌, 조직, 팀, 개인)
• Permission: 특정 작업을 수행할 수 있는 권한
• Role: 권한들의 집합
• Resource: 접근 제어의 대상이 되는 자원

6. API 데이터 구조

6.1 AccessCode

interface AccessCode {
  id: string;
  code: string;
  type: AccessCodeType;
  status: CodeStatus;
  expiresAt: Date;
  userId?: string;
  deviceId?: string;
  creatorId: string;
  groupId?: string;
  planId?: string;
  createdAt: Date;
  updatedAt: Date;
  usedAt?: Date;
  scope: string;
  permissions: string[];
  useTimeMachine: boolean;
  virtualTimeStartDate?: Date;
}

6.2 AccessCodePermission

interface AccessCodePermission {
  id: string;
  accessCodeId: string;
  scope: string;
  permissions: string[];
  grantedBy: string;
  grantedAt: Date;
  expiresAt?: Date;
}

7. GDPR 컴플라이언스 (개인정보 보호)

7.1 액세스 코드 개인정보

백엔드 요구사항

• ACC-FR-BE-045: 시스템은 액세스 코드 관련 개인정보를 보호해야 한다.
  • 코드 생성자 정보 보호
  • 코드 사용 이력 암호화
  • 코드-사용자 연결 정보 최소화
  • 코드 만료 후 자동 삭제
• ACC-FR-BE-046: 시스템은 코드 배포 시 개인정보를 관리해야 한다.
  • 이메일 주소 임시 사용 후 삭제
  • 배포 이력 익명화
  • 코드 전달 채널 보안
  • 개인정보 수집 최소화

8. ISO27001 정보보호 관리

8.1 코드 보안

백엔드 요구사항

• ACC-NFR-029: 시스템은 코드 생성 알고리즘을 보호해야 한다.
  • 예측 불가능한 코드 생성
  • 코드 해싱 저장
  • 무차별 대입 공격 방지
  • 코드 유효성 검증 강화
• ACC-NFR-030: 시스템은 코드 사용을 모니터링해야 한다.
  • 비정상 사용 패턴 탐지
  • 코드 남용 방지
  • 실시간 사용 감사
  • 의심스러운 활동 차단

9. 변경 이력

버전	날짜	작성자	변경 내용
0.1.0	2025-03-16	bok@weltcorp.com	최초 작성
0.2.0	2025-08-07	bok@weltcorp.com	요구사항 ID 체계 적용 - ACC 도메인 코드 적용 (ACC-FR-BE-xxx, ACC-FR-FE-xxx, ACC-NFR-xxx, ACC-CR-xxx)
0.3.0	2025-08-12	bok@weltcorp.com	GDPR 및 ISO27001 컴플라이언스 요구사항 추가 (섹션 7, 8) - 액세스 코드 개인정보, 코드 보안