Access code 관리 API 구현 가이드

개요

1.1 목적

본 문서는 Access Code 도메인의 핵심 기능인 Access code 생성, 검증, 사용 및 일괄 처리 API 구현에 대한 기술적인 가이드라인을 제공합니다. NestJS 기반의 구현 방법과 관련 컴포넌트(Controller, Service, Repository), TimeMachine 통합, 보안 고려사항 등을 상세히 설명합니다.

1.2 범위

• Access code 관련 API 아키텍처 및 주요 컴포넌트 구조
• Access code 생성 API 구현 (단일 및 일괄 처리)
• Access code 검증 및 사용 API 구현
• TimeMachine 기능 통합 방안
• 코드 생성 로직 및 보안 강화 방법
• 성능 최적화 기법 (캐싱, 비동기 처리)
• 테스트 전략 (단위 테스트, 통합 테스트)
• 모니터링 및 로깅 방안

이 문서는 AccessCode 도메인의 Access code 관리 API 구현에 대한 기술적인 가이드를 제공합니다. API는 NestJS 프레임워크를 기반으로 구현되며, TimeMachine 도메인과의 통합 기능을 포함합니다.

2. 아키텍처

2.1 컴포넌트 구조

// Domain Logic (libs/)
libs/
  feature/
    access-code/
      src/
        lib/
          domain/
            services/
              access-code.service.ts
              code-generator.service.ts
              validation.service.ts
              time-machine-integration.service.ts
            repositories/
              access-code.repository.ts
              batch.repository.ts
              usage-history.repository.ts
          # application, infrastructure 등 다른 계층 포함

// API Endpoints (apps/)
apps/
  dta-wide-api/
    src/
      app/
        access-code/
          controllers/
            access-code.controller.ts
            batch.controller.ts # 또는 access-code-management.controller.ts 등

참고: Prisma 스키마 및 관련 구성은 중앙 집중식으로 libs/core/database/prisma/ 경로에서 관리됩니다.

의존성

• TimeMachine 도메인: 가상 시간 관리
• Audit 도메인: 코드 사용 감사 로깅
• Notification 도메인: 코드 전송

3. 데이터 모델

3.1 Prisma 스키마 정의

Access Code 도메인과 관련된 주요 엔티티(AccessCode, UsageHistory, Batch 등)의 상세한 Prisma 스키마 정의는 다음 문서를 참조하세요:

• Access Code 도메인 모델

4. API 구현

4.1 Access code 생성 API (POST /v1/access-codes)

Access code를 생성하는 API 엔드포인트입니다. 단일 코드 생성을 지원합니다.

4.1.1 Controller (예시)

// 파일 경로: apps/dta-wide-api/src/app/access-code/controllers/access-code.controller.ts
@Controller('access-codes')
export class AccessCodeController {
  constructor(
    private readonly commandBus: CommandBus,
    // ... 기타 의존성
  ) {}

  @Post()
  @UseGuards(AuthGuard, RolesGuard) // 역할 기반 접근 제어 예시
  @Roles('OPERATOR', 'ADMIN')
  async generateCode(
    @Body() dto: GenerateCodeDto,
    @User() user: UserDto
  ): Promise<AccessCodeResponseDto> {
    // GenerateCodeCommand 생성 및 실행
    const command = new GenerateCodeCommand(/* ...dto, issuerAccountId: user.accountId */);
    const accessCode = await this.commandBus.execute<GenerateCodeCommand, AccessCode>(command);
    
    // AccessCode 엔티티를 AccessCodeResponseDto로 매핑하여 반환
    // return AccessCodeMapper.toResponseDto(accessCode);
    return { /* ... 매핑된 데이터 ... */ } as AccessCodeResponseDto;
  }
  
  // ... 기타 엔드포인트 ...
}

4.1.2 상세 구현 참조

Access code 생성 요청을 받아 처리하는 상세 로직(코드 값 생성, 유효성 검증, 데이터베이스 저장, 이벤트 발행 등)은 다음 문서를 참조하세요:

• 코드 생성 서비스 구현 가이드

4.2 코드 검증 및 사용 API

Access code의 유효성을 검증하고 사용 처리하는 API의 상세 구현 내용은 다음 문서를 참조하세요:

• 코드 검증 서비스 구현 가이드

4.3 일괄 코드 생성 API

대량의 Access code를 비동기적으로 생성 요청하는 API입니다. 상세 구현 내용은 코드 생성 서비스 가이드 문서를 참조하세요.

• 코드 생성 서비스 구현 가이드

5. TimeMachine 통합 (개요)

Access code 관리 기능은 TimeMachine 도메인과 통합되어 특정 시점의 코드 상태를 조회하거나, 가상 시간을 기준으로 코드를 관리할 수 있습니다.

• 상태 조회: 특정 시점(?asOf=YYYY-MM-DDTHH:mm:ssZ) 파라미터를 사용하여 과거 특정 시점의 코드 상태 및 정보를 조회할 수 있습니다. 이는 주로 디버깅이나 감사 목적으로 활용됩니다.
• 정보 업데이트: TimeMachine이 활성화된 코드의 경우, 특정 정보(예: 만료일) 업데이트 시 현재 실제 시간과 가상 시간 간의 일관성을 고려해야 할 수 있습니다. (상세 로직은 TimeMachine 도메인 정책에 따름)
• 주의: TimeMachine 통합은 주로 조회 기능에 중점을 두며, 과거 상태를 직접 수정하는 것은 일반적으로 허용되지 않습니다.

6. 보안 고려사항

Access code 관리 API는 민감한 정보를 다룰 수 있으므로 다음과 같은 보안 조치가 필수적입니다.

• 접근 제어: NestJS의 Guard (AuthGuard, RolesGuard 등)를 사용하여 API 엔드포인트 접근 권한을 엄격하게 관리합니다. 코드 생성, 수정, 삭제 등의 작업은 특정 관리자 역할(예: ADMIN, OPERATOR)에게만 허용되어야 합니다.
• 데이터 노출 최소화: API 응답 시 불필요한 민감 정보(예: 코드 전체 목록의 상세 정보, 내부 식별자 등) 노출을 최소화하고, 필요한 경우 데이터 마스킹을 적용합니다.
• 입력값 검증: Controller DTO 레벨에서 class-validator 등을 사용하여 모든 입력값(쿼리 파라미터, 요청 본문 등)을 철저히 검증하여 SQL Injection, Cross-Site Scripting (XSS) 등의 공격을 방지합니다.
• 로깅 및 감사: 주요 관리 작업(코드 상태 변경, 만료일 수정 등)에 대한 상세한 감사 로그를 기록하여 추적성을 확보합니다.

7. 성능 최적화

대량의 Access code를 효율적으로 관리하기 위해 다음과 같은 성능 최적화 방안을 고려합니다.

• 페이지네이션: 코드 목록 조회 API (GET /v1/access-codes)는 반드시 페이지네이션(page, limit 파라미터)을 구현하여 한 번에 과도한 데이터를 조회하는 것을 방지합니다.
• 데이터베이스 인덱싱: Prisma 스키마 정의 시 조회 조건으로 자주 사용되는 필드(예: status, type, expirationDate, issuerAccountId, createdAt)에 적절한 데이터베이스 인덱스를 생성하여 조회 성능을 향상시킵니다. 복합 인덱스 사용도 고려합니다.
• 캐싱: 자주 조회되지만 변경 빈도가 낮은 정보(예: 특정 코드의 상세 정보)는 Redis 등의 캐시 저장소를 활용하여 응답 속도를 개선할 수 있습니다. 캐시 무효화 전략을 신중하게 설계해야 합니다.
• 비동기 처리: 일괄 코드 상태 변경 등 시간이 오래 걸릴 수 있는 작업은 비동기 큐(예: BullMQ)를 사용하여 백그라운드에서 처리하고, 사용자에게는 작업 요청 접수 완료를 즉시 응답하는 방식을 고려합니다.

8. 테스트 전략

코드 관리 API의 안정성과 정확성을 보장하기 위해 다음과 같은 테스트를 수행합니다.

• 단위 테스트 (Unit Tests):
  • AccessCodeService (또는 관련 CQRS 핸들러)의 각 메소드가 비즈니스 로직을 올바르게 처리하는지 테스트합니다. (예: 상태 변경 로직, 필터링 로직)
  • Repository Mock 객체를 사용하여 데이터베이스 의존성을 제거하고 서비스 로직 자체에 집중합니다.
  • 값 객체, 유효성 검사 로직 등 도메인 핵심 로직을 철저히 검증합니다.
• 통합 테스트 (Integration Tests):
  • Controller - Service - Repository (또는 CQRS Command/Query Bus) 간의 연동이 올바르게 동작하는지 검증합니다.
  • 실제 데이터베이스(테스트용 DB 또는 Docker 컨테이너 활용)를 사용하여 API 엔드포인트 호출부터 데이터 영속화까지 전체 흐름을 테스트합니다.
  • @nestjs/testing과 supertest를 활용하여 실제 HTTP 요청/응답을 시뮬레이션합니다.
  • 페이지네이션, 필터링, 정렬 등 다양한 조회 옵션에 대한 테스트 케이스를 포함합니다.
• E2E 테스트 (End-to-End Tests): 필요시 전체 시스템 관점에서 주요 코드 관리 시나리오(예: 관리자 로그인 -> 코드 목록 조회 -> 특정 코드 상태 변경 -> 변경 결과 확인)를 테스트합니다.

9. 모니터링 및 로깅

코드 관리 API의 운영 상태를 파악하고 문제를 신속하게 진단하기 위해 모니터링 및 로깅 체계를 구축합니다.

• 메트릭 수집: Prometheus, Datadog 등 모니터링 도구를 사용하여 다음과 같은 메트릭을 수집하고 대시보드를 구성합니다.
  • API 요청 수, 응답 시간 (평균, P95, P99), 오류율 (엔드포인트별, 상태 코드별)
  • 데이터베이스 쿼리 시간 및 처리량
  • 캐시 히트율
  • 비동기 작업 큐의 대기열 길이 및 처리 시간
• 로깅: NestJS의 LoggerService 또는 외부 로깅 라이브러리(예: Winston)를 사용하여 다음과 같은 정보를 로그로 기록합니다.
  • API 요청/응답 정보 (필요시 민감 정보 제외)
  • 서비스 로직의 주요 분기점 및 처리 결과
  • 오류 발생 시 스택 트레이스 및 컨텍스트 정보
  • 감사 로그: 어떤 관리자가 언제 어떤 코드를 어떻게 변경했는지(예: 코드 상태 변경, 만료일 수정) 명확히 추적할 수 있는 감사 로그를 별도로 기록합니다. (Audit 도메인 연동 고려)
• 알림: 특정 오류율 임계값 초과, 응답 시간 지연 등 이상 상황 발생 시 Slack, PagerDuty 등으로 즉시 알림을 받도록 설정합니다.

10. 변경 이력

버전	날짜	작성자	변경 내용
0.1.0	2025-04-25	bok@weltcorp.com	최초 작성
0.2.0	2025-04-31	bok@weltcorp.com	코드 검증 API 섹션 제거 및 참조 링크 추가, 파일 경로 주석 추가, 섹션 재구성
0.3.0	2025-04-31	bok@weltcorp.com	코드 생성 API 상세 구현 제거 및 참조 링크 추가, 일괄 생성 API 참조 추가
0.4.0	2025-04-31	bok@weltcorp.com	TimeMachine 통합, 보안, 성능, 테스트, 모니터링 섹션 내용 보강