VibePackr Enterprise · Part.3

Part.3 · Integration Helper 사용

첫 사용 점검·복귀 지점

시작 지점: A는 선언 전 계획, B와 W1~W4는 Part.4 뒤의 전체 요청 검증입니다. 별도 도구 두 개가 아닌 같은 문서를 두 번 참조합니다.
필요한 준비물: 게시된 대상·호환 Helper를 사용합니다. 구조 계획 입력·소스 Document·전체 합성 요청은 서로 다른 파일입니다.
확인할 실습 결과: 전체 요청 신원과 각 타입 결과를 보존합니다. 명령마다 전체 요청을 평가하며 r2-status는 영구 서버 등록 조회가 아닙니다. 종료 코드 0에도 거부가 포함될 수 있습니다.

실습·다음 단계

실패 시 바로 열기

번호·파일 이름 읽는 법

Part.1~8은 현재 도구별 매뉴얼, W1~W4와 GUI-01 같은 코드는 그 안의 실습입니다. Use Case 1~5는 보존한 작업 안내 번호이며 Part 번호와 다릅니다. Case A~J와 SDK-1·IH-1 같은 코드는 문제 해결 사례입니다. 이전 파일 이름과 pN 절 주소는 기존 북마크용으로 유지하므로 현재 Part는 본문 제목으로 확인합니다.

A · 선언 전: 연동 계획

GAPE의 승인 snapshot과 게시된 대상 Contract·리비전을 먼저 확인합니다. 연결할 기능, 필요한 소스 입출력, 매핑과 구현 공백을 정리한 뒤 Part.4에서 Document를 완성합니다. r2-plan-architecture는 해당 릴리스의 완전한 계획 입력이 있을 때만 사용하며 아래 Custom API 요청과 다른 입력입니다.

다음: Part.4 선언 작성

B · 선언 후: 검증·후보 준비

Part.4에서 완성한 Document·대상·매핑·합성 fixture를 전체 요청에 넣고 아래 W1부터 단계별로 확인합니다. discover → normalize → validate → prepare → status의 타입 결과를 읽고 거부 시 해당 선언으로 돌아갑니다. 구현이 필요할 때만 Part.5로 진행합니다. 구현된 연동은 별도 등록 상태를 확인한 뒤 재사용합니다.

W1: 전체 요청으로 검증 시작 · 구현 필요 → Part.5

실습 파일: 내려받기 전에 용도 확인

JSON은 소스·전체 요청·의도적 오류 예제를 구분합니다. TXT는 사람이 채우는 양식이며 프로필·API 입력·GAPE manifest가 아닙니다. 파일이 브라우저에 열리면 다른 이름으로 저장하고 UTF-8/확장자를 확인하십시오.

전체 Custom 합성 요청 · read-only-custom-api.json

시작 전에: 파일 종류·경로·셸 확인

이 문서 첫머리의 실습 파일을 새 작업 폴더에 저장하고 역할을 확인합니다. TXT 양식은 사람이 작성하는 메모이며 앱 프로필·API 요청·GAPE manifest가 아닙니다. JSON도 소스 Document, 전체 요청, 의도적 오류 예제를 구분합니다.

macOS/Linux는 bash, Windows는 PowerShell 블록을 사용합니다. 프롬프트는 복사하지 않습니다. /absolute/path·C:\absolute\path·대괄호는 실제 제공 값으로 먼저 바꾸고 따옴표를 유지합니다. 변수가 있는 명령은 준비 절과 같은 셸에서 실행합니다. 새 셸이면 경로만 다시 지정하며 기존 결과·로그를 덮지 않습니다. 긴 코드/표는 가로 스크롤할 수 있습니다.

회사별 연결/등록·승인·지원 Pack·게시 대상·승인 manifest가 필요한 단계에서는 실제 제공 자료가 있어야 합니다. 없는 자료의 ID·화면 이름·주소를 만들어 진행하지 않습니다. 각 W 절의 정상 결과와 실패 후 복귀 기준을 모두 읽고 한 단계씩 수행합니다.

W1 · IH-01: 실제 전체 요청 사본으로 discover부터 시작

실습 파일의 read-only-custom-api.json은 SDK에 포함된 완전한 합성 envelope입니다. Helper와 같은 요청 구조를 설명하지만, 내 Helper 릴리스의 대상 지원·정규화 통과를 미리 보증하지 않습니다. 제공된 Helper와 게시 대상이 이 예제를 지원하는지 먼저 대조합니다. 게시 대상이 없으면 소스 읽기/입력 준비까지만 진행합니다.

아래 실행 파일·원본 JSON 경로를 실제 값으로 바꿉니다. helper-practice-01은 아직 없어야 하며 요청 원본을 바꾸지 않습니다.

helper_exe="/absolute/path/packr-integration-helper"
helper_source="/absolute/path/read-only-custom-api.json"
helper_root="$HOME/helper-practice-01"
test -x "$helper_exe" && test -f "$helper_source" || exit 1
test ! -e "$helper_root" || exit 1
umask 077
mkdir -m 700 "$helper_root" || exit 1
cp "$helper_source" "$helper_root/request.json" || exit 1
helper_request="$helper_root/request.json"
"$helper_exe" r2-discover "$helper_request" > "$helper_root/01-discover.json" 2> "$helper_root/01-discover.stderr.txt"
helper_exit=$?
printf 'Process exit: %s\n' "$helper_exit"
cat "$helper_root/01-discover.json"
cat "$helper_root/01-discover.stderr.txt"

$helperExe = 'C:\absolute\path\packr-integration-helper.exe'
$helperSource = 'C:\absolute\path\read-only-custom-api.json'
$helperRoot = Join-Path $env:USERPROFILE 'helper-practice-01'
if (!(Test-Path -LiteralPath $helperExe -PathType Leaf) -or !(Test-Path -LiteralPath $helperSource -PathType Leaf)) { throw 'Executable or full request missing' }
if (Test-Path -LiteralPath $helperRoot) { throw 'Choose a fresh practice path' }
New-Item -ItemType Directory -Path $helperRoot -ErrorAction Stop | Out-Null
$helperRequest = Join-Path $helperRoot 'request.json'
Copy-Item -LiteralPath $helperSource -Destination $helperRequest -ErrorAction Stop
$helperError = Join-Path $helperRoot '01-discover.stderr.txt'
$helperResult = Join-Path $helperRoot '01-discover.json'
& $helperExe r2-discover $helperRequest 2> $helperError | Out-File -LiteralPath $helperResult -Encoding utf8
$helperExit = $LASTEXITCODE
$helperExit
Get-Content -LiteralPath $helperResult -Raw -Encoding UTF8
Get-Content -LiteralPath $helperError

결과에서 읽을 칸	읽는 방법
request_id·correlation_id	사용한 전체 요청과 같은지
operation·lifecycle_stage	지금 요청한 단계와 실제 도달 단계
status·reason	별도 필드입니다. 발견 통과 예시는 status=PASSED·reason=NONE이며 DISCOVERED는 reason이 아닌 lifecycle_stage 값입니다
next_required_actions	다음 요구사항 배열; 단일 next_action 필드가 아님
candidate_digest_sha256	해당 단계가 실제 후보 지문을 반환했을 때만 보관

중요: 이 CLI는 타입 거부 JSON을 출력하면서 종료 코드가 0일 수 있습니다. 종료 코드 0과 파일 생성만으로 다음 단계에 가지 않습니다. JSON이 비었거나 파싱할 수 없으면 stderr와 원래 명령을 확인하고 그 단계에서 중지합니다. 로그 파일은 다음 명령의 요청으로 재사용하지 않습니다.

W2 · IH-02: normalize와 validate를 한 번에 붙여 실행하지 않기

W1의 변수가 남아 있는 같은 셸입니다. 새 셸이면 실제 helper_exe, helper_root, helper_request 또는 PowerShell 변수를 다시 지정하고 기존 파일부터 확인합니다. 기존 root를 다시 만들거나 로그를 덮지 않습니다.

먼저 normalize만:

"$helper_exe" r2-normalize "$helper_request" > "$helper_root/02-normalize.json" 2> "$helper_root/02-normalize.stderr.txt"
helper_exit=$?
printf 'Process exit: %s\n' "$helper_exit"
cat "$helper_root/02-normalize.json"
cat "$helper_root/02-normalize.stderr.txt"

$helperResult = Join-Path $helperRoot '02-normalize.json'
$helperError = Join-Path $helperRoot '02-normalize.stderr.txt'
& $helperExe r2-normalize $helperRequest 2> $helperError | Out-File -LiteralPath $helperResult -Encoding utf8
$helperExit = $LASTEXITCODE
$helperExit
Get-Content -LiteralPath $helperResult -Raw -Encoding UTF8
Get-Content -LiteralPath $helperError

status/reason과 게시된 대상·매핑을 대조합니다. DENIED·UNKNOWN·필수 조치가 남으면 여기서 멈춥니다. 실제 통과가 확인된 경우에만 다음 validate를 실행합니다.

"$helper_exe" r2-validate "$helper_request" > "$helper_root/03-validate.json" 2> "$helper_root/03-validate.stderr.txt"
helper_exit=$?
printf 'Process exit: %s\n' "$helper_exit"
cat "$helper_root/03-validate.json"
cat "$helper_root/03-validate.stderr.txt"

$helperResult = Join-Path $helperRoot '03-validate.json'
$helperError = Join-Path $helperRoot '03-validate.stderr.txt'
& $helperExe r2-validate $helperRequest 2> $helperError | Out-File -LiteralPath $helperResult -Encoding utf8
$helperExit = $LASTEXITCODE
$helperExit
Get-Content -LiteralPath $helperResult -Raw -Encoding UTF8
Get-Content -LiteralPath $helperError

예시 분기: 발견 통과 → 정규화 CONTRACT_INCOMPATIBLE이면 prepare를 실행하지 않고 대상 리비전을 담당자와 확인합니다. required·타입·미지원 변환 거부면 해당 선언을 새 요청 사본에서 수정합니다. 원래 거부와 새 사본·새 로그를 보존하고 영향받은 단계부터 검사합니다.

W3 · IH-03: prepare 출력과 구현 필요를 직접 읽기

validate의 실제 통과를 확인한 뒤에만 아래 prepare를 수행합니다.

"$helper_exe" r2-prepare "$helper_request" > "$helper_root/04-prepare.json" 2> "$helper_root/04-prepare.stderr.txt"
helper_exit=$?
printf 'Process exit: %s\n' "$helper_exit"
cat "$helper_root/04-prepare.json"
cat "$helper_root/04-prepare.stderr.txt"

$helperResult = Join-Path $helperRoot '04-prepare.json'
$helperError = Join-Path $helperRoot '04-prepare.stderr.txt'
& $helperExe r2-prepare $helperRequest 2> $helperError | Out-File -LiteralPath $helperResult -Encoding utf8
$helperExit = $LASTEXITCODE
$helperExit
Get-Content -LiteralPath $helperResult -Raw -Encoding UTF8
Get-Content -LiteralPath $helperError

후보 지문, 실제 단계, result, 다음 요구사항과 scaffold의 구현 필요 여부를 읽습니다. 구현 필요면 해당 담당자에게 인계합니다. prepare가 통과한 같은 요청의 준비 상태를 읽을 때만 다음 status를 사용합니다.

"$helper_exe" r2-status "$helper_request" > "$helper_root/05-status.json" 2> "$helper_root/05-status.stderr.txt"
helper_exit=$?
printf 'Process exit: %s\n' "$helper_exit"
cat "$helper_root/05-status.json"
cat "$helper_root/05-status.stderr.txt"

$helperResult = Join-Path $helperRoot '05-status.json'
$helperError = Join-Path $helperRoot '05-status.stderr.txt'
& $helperExe r2-status $helperRequest 2> $helperError | Out-File -LiteralPath $helperResult -Encoding utf8
$helperExit = $LASTEXITCODE
$helperExit
Get-Content -LiteralPath $helperResult -Raw -Encoding UTF8
Get-Content -LiteralPath $helperError

status는 이 CLI의 준비 결과입니다. 서버에 실제 등록됐다는 뜻이 아닙니다. 출력 예시의 후보 지문을 복사해 기록하지 말고 내 결과의 실제 값을 사용합니다. 01-discover부터 05-status까지 각 파일과 원본 요청 지문을 묶어 보관합니다.

W4 · IH-04: 제출하지 않고도 준비 인계를 완성하기

요청/후보: [실제 지문과 참조]
준비 단계: [실제 반환 단계]
구현 필요: [실제 결과]
등록 경로: [릴리스가 제공한 경로 또는 미제공]
승인 목적·설치 범위: [실제 제공 값]
등록: [실제 결과 또는 미수행]
다음 담당자: [정확한 담당자]

첫 실습에는 r2-submit이 필요하지 않습니다. 신뢰된 등록 전송 경로가 없거나 REQUIRES_AUTHORITY라면 위 기록으로 인계합니다. 실제 등록 결과가 생겨도 바인딩·Work·영수증은 각각 별도입니다. 반복 제출·폴더 복사·자격 증명 복사를 해결책으로 쓰지 않습니다.

추가 용례·체크리스트

이 Part를 읽는 순서

준비물 확인 → 목적에 맞는 용례 선택 → 뒤의 첫 실습·실제 명령 수행 → 결과 읽기 → 수정·반복 → 실패 시 해당 사례로 이동합니다. 숫자 순서가 모든 도구의 필수 설치 순서는 아닙니다. 필요한 도구만 선택하십시오.

시작 조건과 입력

버전이 맞는 Helper 실행 파일, 전체 요청과 게시된 대상·지원 매핑.

온라인과 오프라인을 모두 사용할 수 있습니다. SDK의 선택 Rust 의존성 세트는 폐쇄형 온프렘의 SDK 빌드용이며 전체 제품의 기본값이 아닙니다. 회사별 endpoint·승인·등록 자료가 필요한 용례는 실제 제공 자료를 사용합니다.

실습과 사례 찾아보기

용례	해볼 일
IH-01	전체 요청으로 발견 결과 읽기
IH-02	정규화·의미 검증의 첫 거부 해결
IH-03	후보 준비와 구현 필요를 구분
IH-04	등록 담당자에게 정확한 후보 인계

용례 IH-01 · 전체 요청으로 발견 결과 읽기

실제 입력·단계 열기 →

지원되는 합성 read_quality 요청 한 건을 받았습니다. 소스 발췌를 전체 요청으로 착각하지 않고 발견 단계부터 시작합니다.

진행 순서:

Helper 실행 파일 버전과 게시 대상에 맞는 전체 request.json 사본을 준비합니다.
request_id/correlation_id/draft와 definition/source/mapping/fixture를 확인합니다.
아래 첫 실습의 새 로그 폴더에서 r2-discover를 한 번 실행합니다.
종료 코드와 JSON status/reason/lifecycle_stage/next_required_actions를 각각 기록합니다.

결과를 이렇게 읽습니다: 소스 발견에 대한 타입 결과입니다. 실제 API 연결이나 전체 준비 완료는 아닙니다.

실패·다음 분기: 종료 코드 0이어도 DENIED면 후속 단계로 가지 않습니다. 전체 요청/인코딩 오류는 DOC-2도 확인합니다.

남길 기록: 요청 지문·신원, 제품 리비전, 발견 결과와 원문 최소 사유.

내 연습 기록: 수행 시각·버전·입력 참조·실제로 한 단계·관찰 결과·다음 담당자를 채우십시오. 예시에 적힌 기대 결과를 그대로 성공 기록에 복사하지 않습니다.

용례 IH-02 · 정규화·의미 검증의 첫 거부 해결

실제 입력·단계 열기 →

발견은 PASSED지만 대상 리비전이 맞지 않아 정규화가 거부됩니다. 소스가 읽혔다는 사실과 대상 호환을 분리합니다.

진행 순서:

같은 전체 요청으로 r2-normalize를 실행하고 현재 사유를 보존합니다.
게시된 Contract·어댑터·스키마와 요청 참조를 대조하고 prepare로 넘기지 않습니다.
제공된 올바른 값이 실제 있을 때만 새 요청 사본을 수정하고 영향받은 단계부터 검사합니다.
정규화 후 r2-validate의 required·타입·지원 변환 판정을 확인합니다.

결과를 이렇게 읽습니다: 정확한 요청의 정규화·검증 결과 또는 명시적인 미해결 대상 문제입니다.

실패·다음 분기: Contract ID·지문을 추측하거나 다른 릴리스의 PASS를 재사용하지 않습니다.

남길 기록: 원래 거부, 제공 대상, 변경 요청 지문, 새 단계별 결과.

용례 IH-03 · 후보 준비와 구현 필요를 구분

실제 입력·단계 열기 →

선언은 검증됐지만 생성 scaffold에 구현 필요가 표시될 수 있습니다. 파일 존재만으로 실행 가능한 어댑터라고 판단하지 않습니다.

진행 순서:

검증된 전체 요청의 지문과 검증 결과를 고정합니다.
r2-prepare 결과에서 후보 지문·단계·result와 다음 요구사항을 읽습니다.
REQUIRES_IMPLEMENTATION 표시가 있으면 구현 담당자에게 필요한 인터페이스·범위만 인계합니다.
r2-status로 같은 요청의 현재 준비 결과를 읽되 실제 서버 등록 상태로 해석하지 않습니다.

결과를 이렇게 읽습니다: 준비 후보·미구현 요구·다음 담당자가 구분된 인계입니다.

실패·다음 분기: 미지원 변환은 입력값만 바꿔 해결됐다고 표시하지 않습니다. 실제 API 호출 시험도 별도입니다.

남길 기록: 후보 지문·준비 단계·구현 필요·지원 범위·담당자.

용례 IH-04 · 등록 담당자에게 정확한 후보 인계

실제 입력·단계 열기 →

준비가 끝났고 운영 등록을 요청하려 합니다. CLI에는 신뢰된 등록 전송 경로가 없을 수 있습니다.

진행 순서:

전체 요청 지문·후보 지문·목적·고객/설치 범위를 묶습니다.
릴리스가 제공한 승인·등록 담당자와 실제 제출 경로를 확인합니다.
제출이 제공되고 승인된 경우에만 사용하며 REQUIRES_AUTHORITY는 그대로 인계합니다.
등록 결과·바인딩·Work 승인은 각각 실제 제품 결과가 생겼을 때 따로 기록합니다.

결과를 이렇게 읽습니다: 정확한 후보의 준비 인계와 등록의 실제 상태까지입니다.

실패·다음 분기: 반복 submit·자격 증명 복사·서버 폴더 직접 복사로 등록을 만들지 않습니다.

남길 기록: 후보/요청 지문, 승인 목적, 제출/등록 상태, 다음 담당자.

반복 사용·수정·실패 후 재개

이전 입력·버전·검증·결과를 보존하고 새 입력 또는 새 리비전을 구분합니다. SDK/GAPE 파일 출력은 새 경로를 쓰고, Builder는 제품이 반환한 새 후보 리비전을 기록합니다. Helper는 단계 결과를 다음 명령의 입력으로 바꾸지 않고 같은 전체 요청을 사용합니다. 진행 중이거나 결과가 불명확한 Work는 먼저 기존 ID로 조회합니다.

터미널을 닫았다면 절대 경로와 선택 환경을 다시 지정합니다. 실제 변경의 영향을 받는 단계부터 재확인하고, 회사별 권한·등록·승인이 미완료이면 그 상태로 인계합니다. 지원에는 최소 메시지와 공개 가능한 참조를 사용하며 비밀키·원문 프롬프트·고객 응답·전체 로그를 일괄 전달하지 않습니다.

상세 명령·입력 예제·문제 해결 원본

아래에는 이 Part에 해당하는 기존 상세 안내를 같은 작성 원본에서 이어 싣습니다. 첫 실습, 전체 JSON, OS별 명령, 실제 결과 파일 확인과 증상별 상세 사례를 필요할 때 펼쳐 읽으십시오. 다른 Part의 사례를 참조하는 링크도 해당 매뉴얼로 연결됩니다.

전체 흐름·생략 조건

Integration Helper: 실행 권한 없이 연동 후보 준비

상세 절 목차

Helper는 후보를 준비하고 검사합니다. CLI만으로는 신뢰된 등록 전송 경로가 없습니다. 발견 단계의 PASSED는 제공자 호출·연동 등록·Work 승인을 뜻하지 않습니다. 정확한 릴리스가 제공한 입력과 대상 Contract만 사용하십시오.

첫 준비 실습: 전체 요청 한 건을 단계별로 읽기

준비물: 버전이 맞는 Helper 실행 파일, 완전한 request.json, 공급자가 게시한 대상 참조. SDK와 Helper는 별도 실행 파일입니다. SDK의 발췌 JSON만 저장해 이 요청을 대신하지 않습니다. SDK 전체 예제를 재사용하려면 그 Helper 릴리스에서도 동일한 대상·envelope를 지원하는지 먼저 확인합니다.

제공된 요청 원본을 보존하고 작업용 사본을 만듭니다. request_id, correlation_id, draft 전체와 그 안의 definition/source/mapping/fixture를 확인합니다. 실제 API 토큰은 넣지 않습니다.
아래 실행 파일·요청 경로를 실제 절대 경로로 바꿉니다. helper-first-01은 새 로그 폴더입니다. 첫 명령만 실행하고 결과를 읽습니다.
stdout의 status, reason, lifecycle_stage, next_required_actions, 후보 지문을 확인합니다. next_action이라는 단일 필드가 있다고 가정하지 않습니다. 이 CLI는 타입 거부 결과를 출력하면서 종료 코드 0일 수 있으므로 `$LASTEXITCODE`/종료 코드만으로 다음 단계에 가지 않습니다.
발견이 통과한 경우에만 기존 절의 normalize → validate → prepare → status를 각각 같은 요청 사본으로 실행합니다. 이전 명령의 JSON 결과를 다음 명령의 입력으로 바꾸지 않습니다. 각 명령은 전체 요청을 받습니다.
DENIED, 구현 필요, 권한 필요 또는 모르는 상태면 해당 결과를 보존하고 다음 조치를 읽습니다. 첫 연습에 r2-submit은 필요하지 않습니다. 요청을 수정할 때는 새 사본·새 로그 폴더를 사용합니다.

helper_exe="/absolute/path/packr-integration-helper"
helper_request="/absolute/path/request.json"
helper_logs="$HOME/helper-first-01"
test -f "$helper_exe" && test -f "$helper_request" || exit 1
test ! -e "$helper_logs" || exit 1
mkdir "$helper_logs" || exit 1
"$helper_exe" r2-discover "$helper_request" > "$helper_logs/01-discover.json" 2> "$helper_logs/01-discover.stderr.txt"
helper_exit=$?
cat "$helper_logs/01-discover.json"
cat "$helper_logs/01-discover.stderr.txt"
# helper_exit와 JSON의 status/reason을 별도로 기록합니다.

$helperExe = 'C:\absolute\path\packr-integration-helper.exe'
$helperRequest = 'C:\absolute\path\request.json'
$helperLogs = Join-Path $env:USERPROFILE 'helper-first-01'
if (Test-Path -LiteralPath $helperLogs) { throw 'Choose a fresh log folder' }
New-Item -ItemType Directory -Path $helperLogs -ErrorAction Stop | Out-Null
& $helperExe r2-discover $helperRequest 2> (Join-Path $helperLogs '01-discover.stderr.txt') | Out-File -LiteralPath (Join-Path $helperLogs '01-discover.json') -Encoding utf8
$helperExit = $LASTEXITCODE
Get-Content -LiteralPath (Join-Path $helperLogs '01-discover.json') -Raw -Encoding UTF8
Get-Content -LiteralPath (Join-Path $helperLogs '01-discover.stderr.txt')

위 파일은 로그이며 그 자체를 새 요청으로 제출하지 않습니다. 후속 결과도 02-normalize, 03-validate, 04-prepare, 05-status처럼 구분해 저장합니다. 예상 연습 결과는 단계 판정과 후보 준비 기록이며 실제 API 연결·등록·Work가 아닙니다. 게시된 대상이 없다면 TARGET_NOT_PROVIDED는 담당자의 진행 기록으로 쓰고, 제품이 실제 출력한 reason과 구분하십시오. 아래 IH-1/2에서 거부와 인계 예를 확인합니다.

입력과 담당자

입력	담당자	사용 전 확인
소스 Document 또는 제한된 MCP 기록	고객 연동 담당자	지원 리비전·데이터 최소화
대상 Contract·기능·어댑터 리비전	공급자가 게시한 릴리스 패키지	정확한 식별자·호환성
요청 envelope	릴리스 절차	요청·상관관계 신원과 완전한 draft
등록 승인	권한 있는 제품 담당자	정확한 후보 지문·목적·고객·설치 범위

후보 준비

지원되는 소스 형식으로 읽기 전용 작업부터 설명합니다. 예: status.read의 입력 service 문자열과 출력 service·healthy. 실제 토큰이나 고객 응답은 문서에 붙여넣지 않습니다.
공급자가 게시한 대상 Contract·어댑터 리비전을 확보합니다. 없으면 TARGET_NOT_PROVIDED로 기록하십시오. 비슷해 보이는 표시 이름은 유효한 대상 매칭이 아닙니다.
해당 릴리스가 제공한 완전한 요청 파일을 사용합니다. 포함된 Helper가 r2-discover, r2-normalize, r2-validate, r2-prepare, r2-status를 제공한다면 request.json으로 이 순서대로 진행합니다. 매 단계의 상태·사유·다음 조치를 보존하십시오.
실제 결과가 거부한 필드 또는 매핑만 고칩니다. 제한된 예시 형식은 기본 자료형과 명시적 매핑을 지원합니다. 지원되지 않는 변환이나 매핑되지 않은 필수 필드는 계속 거부됩니다. REQUIRES_IMPLEMENTATION scaffold에는 실제 어댑터 구현이 추가로 필요합니다.
릴리스의 승인된 제출 경로에서만 r2-submit을 사용합니다. 신뢰된 등록 전송 경로가 없는 CLI는 REQUIRES_AUTHORITY를 반환합니다. 정식 등록에는 정확한 후보·목적에 묶인 별도의 유효한 승인이 필요합니다. 등록되어도 Work 바인딩·승인이 자동으로 생기지 않습니다.

재현 가능한 로컬 준비 예시

전달 목록에 Helper 실행 파일과 버전에 맞는 완전한 request.json이 있다면 아래 단계를 하나씩 실행합니다. 각 JSON에서 status·reason·단계·다음 조치를 읽고 진행하십시오. 셸 종료 코드만으로 통과를 판단하지 않습니다. 요청에는 위의 status.read 설명 대신 릴리스가 제공한 지원 대상 참조가 필요합니다.

packr-integration-helper r2-discover request.json > 01-discover.json
packr-integration-helper r2-normalize request.json > 02-normalize.json
packr-integration-helper r2-validate request.json > 03-validate.json
packr-integration-helper r2-prepare request.json > 04-prepare.json
packr-integration-helper r2-status request.json > 05-status.json

판정 예시: 발견 결과가 status=PASSED, reason=NONE, lifecycle_stage=DISCOVERED라도 정규화가 DENIED / CONTRACT_INCOMPATIBLE을 반환할 수 있습니다. 두 결과를 모두 보존하고 prepare 전에 멈춰 게시된 올바른 대상을 확보하십시오. 앞 단계가 거부됐는데 다섯 명령을 무조건 연속 실행하지 마십시오.

예시: 소스는 통과, 대상은 거부

합성 status.read 문서에 대해 r2-discover가 status=PASSED, reason=NONE, lifecycle_stage=DISCOVERED를 반환합니다. 게시된 대상이 묶이지 않아 r2-normalize는 DENIED / CONTRACT_INCOMPATIBLE을 반환합니다. 소스 문서 구조는 받아들여졌지만 연동은 준비되지 않았습니다. 공급자 또는 연동 담당자에게 정확한 대상 참조를 요청하십시오. Contract ID를 임의로 만들거나 표시 이름만 맞춰 통과시키지 않습니다.

예시: 후보 제출 후 등록되지 않음

검증된 후보의 제출 결과가 REQUIRES_AUTHORITY입니다. 후보 지문과 요청한 승인 목적을 기록합니다. 권한 담당자가 정확한 후보를 native 등록 경로에서 평가해야 합니다. CLI 반복 실행이나 옵션 추가로 준비 상태를 등록으로 바꿀 수 없습니다.

완료 증거

입력·대상 리비전, 요청 신원, 단계별 타입 결과, 후보 지문, 미해결 문제와 다음 담당자가 기록되면 준비 단계가 끝납니다. 실제 제공자 연결·등록·바인딩·승인된 Work·영수증에는 각각 별도 증거가 필요합니다. 소스 선언은 Contract & Document를 참고하십시오.

단계별 실제 사용 용례

예를 들어 서비스 상태를 읽는 소스 Document와 공급자가 게시한 대상 참조를 연결합니다. 첫 시도는 합성 데이터로 준비하고 단계마다 상태·사유·다음 조치를 읽습니다. 정규화가 거부되면 그 뒤 prepare·submit으로 넘기지 않습니다. 입력을 고쳤다면 요청 리비전과 지문을 새로 기록하여 이전 거부와 새 결과를 구별합니다.

증상별 확인과 복귀 확인

증상 또는 상황	분리해서 확인할 사실	조치와 다시 확인할 결과
발견 PASS 뒤 정규화 거부	소스 파싱 결과와 정확한 대상 Contract·어댑터 리비전	게시된 호환 대상을 확인하고 변경된 요청을 처음 영향을 받는 단계부터 검증합니다.
필드 매핑이 일부만 채워짐	required 목록·타입·지원 변환과 누락된 필드	미지원 변환은 구현 필요 상태로 보존하고 지원 범위의 선언만 수정합니다.
prepare 결과는 있으나 등록은 없음	후보 지문·제출 경로·정확한 승인 목적	준비 완료와 등록 대기를 구분하고 승인된 등록 담당자에게 인계합니다.

다음 담당자에게 넘길 최소 기록

인계 항목: 전체 요청 지문, 소스·대상 리비전, 요청·상관관계 ID, 각 단계의 타입 결과, 후보 지문, scaffold의 구현 필요 여부, 제출·등록 상태와 다음 담당자. 실제 API 연결 시험은 준비 결과와 구분합니다.

도구별 문제 해결 사례 읽기

다음은 지원되는 입력·명령·권한 경계를 바탕으로 구성한 교육용 사례입니다. 제품의 실제 상태·사유와 함께 읽고, 자신의 실행 기록 없이 예시의 결과를 성공 이력으로 사용하지 않습니다. 온라인과 오프라인 환경 모두에 적용되는 확인 항목과 선택 의존성 경로에만 해당하는 항목을 구별합니다.

상세 예시 IH-1: 발견은 통과했지만 대상 정규화가 거부됨

상황: 합성 소스 Document의 read_quality는 발견됐지만 전체 요청은 다른 Contract·어댑터 리비전을 가리킵니다. 발견 PASS 뒤 prepare까지 무조건 실행하면 첫 거부를 놓칩니다.

관찰을 이렇게 나눠 읽습니다.

발견: status=PASSED, reason=NONE, lifecycle_stage=DISCOVERED는 소스 발견 결과입니다.
정규화: DENIED / CONTRACT_INCOMPATIBLE은 대상 호환 거부입니다.
후보 준비: 아직 완료되지 않았습니다.

확인·조치 순서:

정규화의 상태·사유·다음 조치를 보존하고 후속 prepare·submit을 멈춥니다.
공급자가 게시한 정확한 대상과 전체 요청의 참조를 대조합니다. 이름만 비슷한 대상을 고르지 않습니다.
지원되는 참조를 확보한 뒤 수정 요청의 리비전·지문을 보관하고 영향을 받은 단계부터 검사합니다.

다음 단계로 돌아갈 조건: 해당 요청이 정규화·의미 검증을 통과한 뒤에만 후보 준비 결과를 확인합니다.

해결되지 않았을 때: 게시된 대상이 없으면 ID·스키마 지문을 만들어 맞추지 않고 대상 미제공으로 인계합니다.

상세 예시 IH-2: prepare 산출물은 있지만 제출이 권한을 요구함

상황: 후보 준비 결과가 만들어졌지만 CLI 제출은 REQUIRES_AUTHORITY를 반환합니다. 로컬 후보 파일을 서버 등록 위치에 복사하면 해결되는 문제가 아닙니다.

관찰을 이렇게 나눠 읽습니다.

prepare: 후보 준비 결과입니다.
submit: 신뢰된 등록 경로·정확한 승인 목적을 요구합니다.
Work: 등록·바인딩·실행은 별도입니다.

확인·조치 순서:

후보 지문과 제출 결과·요청·상관관계 ID를 보존합니다.
해당 릴리스가 실제 등록 전송 경로와 담당자를 제공하는지 확인합니다.
정확한 후보·목적·고객·설치 범위에 대한 승인된 등록 절차로 인계합니다.

다음 단계로 돌아갈 조건: 등록 담당자의 실제 결과를 확인한 경우에만 등록으로 기록하고 Work는 따로 확인합니다.

해결되지 않았을 때: CLI 반복 제출이나 자격 증명 복사로 준비 상태를 등록 상태로 바꾸지 않습니다.

설치 후 도구 목록

연결·승인·등록에는 해당 설치에 제공된 실제 자료를 사용하십시오. 이 안내서가 이를 구성하지는 않습니다. 교육용 예시는 고객 실행 증거가 아닙니다. Apple 공식 서명·공증과 고객 활성화·전달은 계속 보류합니다.

가이드와 Part.1–8 연결

가이드에서 목적을 고른 뒤 해당 Part에서 정확한 도구 단계를 확인합니다. 두 문서는 같은 순서·용어·자료 역할을 사용합니다.

목적별 가이드

PoC 공통 가이드
질문을 정하고 범위에 맞는 관찰을 모아 결과를 검토합니다. 보존 기록 독해에는 신규 설치가 필요하지 않습니다.
Google 심사자 가이드
정확한 심사 전달물과 기준 증거를 연결합니다. Cloud 접근·문서 범위·실제 Google 승인은 각각 구분합니다.
온프레미스 가이드
정확한 OS·패키지·네트워크 선택·도구 체인을 준비합니다. 로컬 SDK 준비 요건이 제공된 뒤에만 해당 단축 경로를 사용합니다.
Custom Execution 가이드
지원 작업을 선택합니다. 소스 문서 준비·전체 SDK 후보·실제 Work 및 보고서 확인을 서로 다른 경로로 구분합니다.
가이드 링크는 네트워크가 필요한 공개 웹사이트를 엽니다. 이 오프라인 매뉴얼과 로컬 예제는 네트워크 없이 읽을 수 있습니다.

권장 연동 순서와 단축 경로

Helper B는 구현·새 Pack 필요 여부를 결정하기 전에 완성된 선언을 확인합니다. 구현·선언 변경 후에는 영향을 받은 지원 검사를 다시 수행하고 별도 구현·등록·Pack 승인 경로를 마친 뒤 사용합니다. 생성 후보는 운영 권한을 부여하지 않습니다.

목표에 필요한 경로만 선택합니다. 보존 PoC 독해는 설치 없이 시작할 수 있습니다. 제공된 로컬 SDK 실습은 Part.1 → Part.5를 따르며 새 GAPE 관찰·어플라이언스 계정이 필요하지 않습니다. 기존 승인 Pack은 현재 준비 요건 확인 후 Part.1 → Part.7 → Part.8을 따를 수 있습니다. 새 연동·Pack 작성은 조건부 전체 순서를 따릅니다.

Part 연결과 도구 역할

Part	역할과 기대 범위
Part.1 · 설치·초기 연결	OS 준비·제공 패키지·초기 연결입니다. 설치는 실행된 Work가 아닙니다.
Part.2 · GAPE 관찰·비교·공유	리비전에 고정된 구조 관찰입니다. 워크시트는 승인된 GAPE 입력 매니페스트가 아닙니다.
Part.3 · Integration Helper 사용	A는 Document 작성 전 계획, B는 완성된 전체 요청 확인입니다. 단계마다 타입이 있는 status·reason을 읽습니다.
Part.4 · Contract·Document 작성	소스 Document·매핑을 작성하고 제공된 대상 Contract·리비전을 사용합니다. JSON 구문만으로 의미상 호환성이 확인되지 않습니다.
Part.5 · SDK Engine 실습·연동 후보	로컬 SDK 구현 후보를 생성합니다. 기존 구현·등록·릴리스 호환 연동이 요구를 충족하면 재사용합니다.
Part.6 · Builder·추가 Pack 사용	새 Pack이 필요할 때 Pack 후보를 준비합니다. 목표·설치 범위에 맞는 기존 승인 Pack은 재사용합니다.
Part.7 · PackrGUI·헤드리스 사용	현재 권한·사전 조건에 따라 제공 GUI·헤드리스 경로를 사용합니다. 반환된 Work 식별·결과를 확인합니다.
Part.8 · 운영·문제 해결·지원	동일 Work 산출물·영수증·종결을 비교하며 사람 인수은 실제 기록될 때까지 대기로 유지합니다.

공통 용어

가이드 / Part: 가이드는 목적·역할 경로이고 Part는 도구 설명입니다. 서로 보완하며 경쟁하는 두 번호 순서가 아닙니다.
Contract / 소스 Document: 게시된 대상 Contract는 지원 대상·리비전을 정합니다. 소스 Document는 소스 형식을 선언합니다. 소스 선언은 실행을 승인하지 않습니다.
전체 요청 / 소스 전용 파일: 전체 SDK 요청은 request_id·correlation_id와 definition·source·mapping·fixture가 있는 draft를 포함합니다. status 소스 Document는 한 구성 요소이며 전체 요청이 아닙니다.
Fixture / 실제 관찰: fixture는 선언된 로컬 실습의 합성 값을 제공합니다. 선언 필드는 실제 공급자 호출·현재 연결·고객 결과를 입증하지 않습니다.
SDK 후보 / Pack 후보: SDK 후보에는 README.md·adapter.rs·libadapter.rlib·manifest.json이 있습니다. Builder Pack 후보는 별도 제품 반환 후보이며 자체 검증·승인 경로를 가집니다. 어느 쪽도 자동으로 승인 Pack이 되지 않습니다.
워크시트 / 영수증 / 인수: 워크시트는 사람 기록입니다. 영수증은 제품 실행 기록입니다. 검증 PASSED·자동화 완료와 사람 인수 대기는 함께 존재할 수 있으며 각 필드의 실제 범위를 기록합니다.
Online / Offline: 구성 선택 사항입니다. Offline 제품 개발에는 정확한 선언 의존성 세트·네이티브 도구가 필요하며 오프라인 매뉴얼 ZIP은 문서 열람을 지원합니다.

입력별 올바른 출력 연결

status.read 소스 전용 예제와 read_quality SDK 실습은 서로 다른 예제입니다. 일치하는 전체 요청을 사용하고 status 소스 파일을 quality SDK 전체 요청으로 제출하지 않습니다. 아래 매핑 값은 설명을 위한 기대값이며 새 실행 캡처가 아닙니다.

파일 / 역할	입력	출력 / 확인
`status-document.json` status.read의 소스 전용 CUSTOM_API 선언입니다. 제공된 전체 준비 요청 안에서 사용합니다.	service: string	service: string·healthy: boolean을 선언합니다. 스키마이며 관찰된 서비스 응답이 아닙니다.
`read-only-custom-api.json / custom-api-01.json` 유지관리되는 전체 SDK 기준 요청이며 가이드 사본은 같은 JSON입니다.	fixture.response.component = "fixture-component"; score = "97" (문자열)	STRING_TO_INTEGER는 score를 기대 정수 quality_score 97로 매핑합니다. 문서의 SDK 결과는 로컬 후보입니다.
`custom-api-02.json` fixture 응답 값 두 개만 바꾼 두 번째 전체 SDK 요청입니다.	component = "my-test-component"; score = "88" (문자열)	기대 매핑 component는 "my-test-component", quality_score는 정수 88입니다. 실제 매니페스트·단계를 확인하며 매핑 소스는 같을 수 있습니다.
`custom-api-score-number.json` 정상 기준 예제가 아닌 의도적 오류 입력입니다.	선언된 문자열 스키마에 fixture.response.score = 88 (JSON 숫자) 사용	실제 타입 오류 결과를 보존하며 이 예제를 성공 후보로 기록하지 않습니다.
`Worksheet / SDK artifacts / Work reports` 사람 기록·로컬 컴파일 후보·실제 Work 및 보고서·영수증이라는 서로 다른 산출물 종류입니다.	해당 도구·현재 타깃을 사용하며 워크시트·이전 결과를 다음 전체 요청으로 제출하지 않습니다.	실제 입력·버전·후보 또는 Work 식별에 출력을 연결합니다. 파일 존재·종료 0만으로는 충분하지 않습니다.

연동 역할과 운영 범위

사용자가 제공한 구조 개요입니다. 도구 패널은 필수 실행 순서가 아닌 상호 보완 역할을 설명합니다. 원본의 Legacy SDK planned·릴리스별 문구는 유지되며 현재 SDK 가용성은 Part.5와 실제 제공 패키지로 확인합니다. 이 그림은 권한·런타임 증거가 아닙니다. 현재 표시본은 문서 변경을 반영한 영문 SVG이며, 이전 래스터 원본은 보존합니다.

SVG 그림 원본 크기로 열기