vpd-permission-poc/docs/design/424-spring-boot-vpd-backoffice/fn-runProbe.md

함수 설계서: runProbe (#424)

부모 설계서: ./README.md · 상태: Draft 작성: [AI] Architect · 구현: OrdsProbeService.runProbe · 테스트: OrdsProbeServiceTest

1. 시그니처

ProbeResult runProbe(ProbeCommand command)

2. 책임 (단일 책임, 1줄)

선택된 Bearer Token과 보호 객체 whitelist를 사용해 ORDS 검증 호출을 실행하고 결과 또는 오류를 분류한다.

3. 입력

파라미터	타입	제약/검증	설명
command.keyId	long	활성 token이어야 함	사용할 Bearer Token
command.objectId	long	활성 보호 객체	ORDS 호출 대상
command.limit	int	1 이상 500 이하	조회 행 제한

4. 출력

• 반환: ProbeResult
  • status: 성공/차단/오류 분류
  • columns: 반환 컬럼
  • rows: 결과 행
  • rowCount: 행 수
  • maskedColumns: NULL 또는 마스킹으로 판단된 컬럼
  • errorCode, errorMessage: 오류 시 분류 정보
• 부수효과: ORDS HTTP 호출, audit insert

5. 동작 / 알고리즘

1. keyId로 token 상태를 조회한다.
2. token이 만료 또는 회수 상태면 ORDS 호출 없이 실패 결과를 반환한다.
3. objectId로 보호 객체를 조회하고 활성 상태를 확인한다.
4. ORDS URL은 설정된 base URL과 보호 객체의 ords_path로 만든다.
5. 요청 timeout과 행 제한 parameter를 적용한다.
6. Authorization: Bearer <token> 헤더로 ORDS를 호출한다.
7. 2xx 응답이면 JSON을 파싱해 컬럼과 행 수를 계산한다.
8. 민감 컬럼이 모두 NULL인 경우 Redaction 적용 표시를 만든다.
9. 비 2xx 또는 Oracle 오류 body이면 classifyProbeError로 분류한다.
10. audit log를 저장한다.
11. 화면 표시용 ProbeResult를 반환한다.

6. 에러 & 실패 모드

조건	처리	반환/예외
token 없음	ORDS 호출 안 함	TOKEN_NOT_FOUND
token 만료/회수	ORDS 호출 안 함	TOKEN_INACTIVE
보호 객체 없음/비활성	ORDS 호출 안 함	OBJECT_DISABLED
ORDS timeout	audit 후 오류 반환	ORDS_TIMEOUT
ORA-20002	잘못된 key로 분류	INVALID_TOKEN
ORA-00942 / ORA-01031	객체 권한 없음으로 분류	OBJECT_NOT_ACCESSIBLE
2xx + 빈 rows	VPD deny 가능성 표시	VPD_DENY_EMPTY_RESULT
알 수 없는 오류	원문 일부만 표시	UNKNOWN_ERROR

7. 엣지케이스

• 응답이 JSON이 아니면 성공으로 보지 않고 INVALID_ORDS_RESPONSE로 분류한다.
• 결과가 500행을 넘지 않도록 limit 기본값과 최대값을 둔다.
• audit에는 token 원문을 저장하지 않고 key_id, key_prefix만 저장한다.
• ORDS 응답 body 전체를 audit에 저장하지 않고 오류 코드와 짧은 메시지만 저장한다.

8. 복잡도 / 성능

• 네트워크 I/O가 지배적이다.
• 기본 timeout은 10초다.
• 화면 검증 호출이므로 자동 재시도는 하지 않는다.

9. 의존성

• BearerTokenMapper
• ProtectedObjectMapper
• RestClient 또는 WebClient
• ProbeErrorClassifier
• AuditService
• Clock

10. 테스트 케이스

• 정상: 2xx JSON 응답에서 컬럼과 행 수 추출
• 정상: 빈 rows를 VPD deny 가능성으로 표시
• 정상: 민감 컬럼 NULL을 masked column으로 표시
• 실패: 만료 token이면 ORDS 호출하지 않음
• 실패: 비활성 객체이면 ORDS 호출하지 않음
• 실패: ORA-20002 분류
• 실패: timeout 분류

11. 추적성

• 인수조건: #424의 "ORDS 호출 검증 화면에서 Bearer Token과 보호 객체를 선택하면 ORDS 호출 결과, 반환 컬럼, 행 수, 오류 유형을 확인할 수 있다."
• 관련 ADR: 없음