Part.2 · GAPE 관찰·비교·공유

GAPE: 리비전에 묶인 아키텍처 관찰 검토

첫 관찰 실습: 입력 준비, 실행, 결과 열기

먼저 받은 파일을 확인합니다. 승인된 snapshot과 뷰어만 받은 사람은 제공된 HTML 뷰어를 브라우저에서 열어 snapshot ID·소스 리비전·공개 등급을 읽고 노드 하나를 선택합니다. 소스나 매니페스트를 새로 만들 필요가 없습니다. 실행 파일과 승인 manifest를 받은 담당자는 아래 로컬 관찰을 진행할 수 있습니다. 일반 소스 Document나 SDK input.json을 GAPE 매니페스트로 사용하지 않습니다.

실행할 파일과 새 출력 경로 지정

gape_exe/$gapeExe는 제공된 실행 파일, manifest/$gapeManifest는 실제 승인 매니페스트의 절대 경로로 바꿉니다. 그 매니페스트가 지정한 소스 위치와 리비전도 존재해야 합니다. 새 출력의 부모 폴더만 준비하고 gape-observation-01은 만들지 않습니다. 경로를 추측해 소스 범위를 넓히지 않습니다.

gape_exe="/absolute/path/packr-gape"
gape_manifest="/absolute/path/approved-manifest.json"
gape_output="$HOME/gape-observation-01"
test -f "$gape_exe" && test -f "$gape_manifest" || exit 1
test ! -e "$gape_output" || exit 1
"$gape_exe" snapshot "$gape_manifest" "$gape_output" || exit 1
"$gape_exe" validate-snapshot "$gape_output/gape-architecture-snapshot.json" || exit 1
ls -la "$gape_output"

$gapeExe = 'C:\absolute\path\packr-gape.exe'
$gapeManifest = 'C:\absolute\path\approved-manifest.json'
$gapeOutput = Join-Path $env:USERPROFILE 'gape-observation-01'
if (!(Test-Path -LiteralPath $gapeExe -PathType Leaf) -or !(Test-Path -LiteralPath $gapeManifest -PathType Leaf)) { throw 'Executable or approved manifest missing' }
if (Test-Path -LiteralPath $gapeOutput) { throw 'Choose a fresh output path' }
& $gapeExe snapshot $gapeManifest $gapeOutput
if ($LASTEXITCODE -ne 0) { throw 'Snapshot failed' }
& $gapeExe validate-snapshot (Join-Path $gapeOutput 'gape-architecture-snapshot.json')
if ($LASTEXITCODE -ne 0) { throw 'Snapshot validation failed' }
Get-ChildItem -LiteralPath $gapeOutput

무엇을 읽나: snapshot 명령의 JSON에는 snapshot ID와 노드·관계·finding 수, execution_authority: NONE이 표시됩니다. finding 수가 0일 것이라고 가정하지 않습니다. 검사 결과와 실제 생성 파일을 보존하고, 동봉된 뷰어가 있으면 그 파일을 엽니다. 뷰어가 없다면 snapshot JSON을 편집기에서 읽습니다. HTML 파일 이름을 임의로 추측하지 않습니다.

짧은 과제: 노드 하나의 이름·소스 리비전·연결된 관계·관찰 한계를 기록합니다. 이전 snapshot과 비교하려면 두 원본을 보존하고 제공된 compare before.json after.json 명령의 지원 여부를 릴리스에서 확인합니다. 관찰 밖의 동작은 추정하지 않습니다. 내부 엔지니어링 snapshot은 외부 공유하지 않고 승인된 PUBLIC_SAFE 투영을 사용합니다.

막히면: 실행 파일 없음은 설치 준비, 소스 경로/리비전 없음은 승인 입력 준비, snapshot 검사 실패는 관찰 검사 단계로 기록합니다. 아래 GAPE-1/2로 이동하며 임의 manifest 작성으로 관찰 범위를 확대하지 않습니다.

사용할 때

연동 담당자가 제안한 작업이 어느 구성요소와 인터페이스에 의존하는지 파악할 때 사용합니다. 해당 릴리스가 GAPE 도구와 승인된 입력 매니페스트를 제공하는지 확인하십시오. 일반 소스 폴더·스크린샷·아키텍처 인포그래픽은 매니페스트가 아닙니다.

관찰 준비

1. 승인된 소스 버전, 관찰할 폴더, 제외 대상, 예상 규칙과 공유 범위를 기록합니다. GAPE 결과는 선택한 저장 버전에 대한 관찰입니다. 저장하지 않은 변경이나 실제 실행 중의 동작은 결과에 포함되지 않을 수 있습니다.
2. 구성요소 목록에 packr-gape와 승인된 매니페스트가 있다면 새 출력 폴더에서 packr-gape snapshot manifest.json new-output-folder를 실행합니다. 둘 중 하나가 없다면 지원되는 관찰 절차를 문의하십시오.
3. 해당 명령이 제공된 경우 packr-gape validate-snapshot gape-architecture-snapshot.json으로 생성 결과를 확인합니다. 이는 snapshot의 구조·출처 검사이지 실제 런타임 동작 검증이 아닙니다.
4. 승인된 오프라인 뷰어에서 노드·관계 하나를 선택하고 소스 리비전과 관찰 한계를 적습니다. 별도 Contract 또는 소유자 규칙과 대조하십시오. UNRESOLVED·STALE은 그대로 이슈로 남기며 뷰어를 고쳐 일치처럼 표시하지 않습니다.
5. 허용된 곳에는 PUBLIC_SAFE 투영만 공유합니다. 엔지니어링 입력·내부 경로·소스 위치·상세 판정은 승인된 엔지니어링 환경에 보관합니다.

실제 릴리스가 GAPE를 제공할 때의 명령 예시

아래 명령은 설치 목록에 packr-gape와 조회 권한이 있는 소스용 승인 매니페스트가 모두 있을 때만 사용하십시오. 출력 폴더는 새로 만들어야 합니다. validate-snapshot은 snapshot 검사이며 실행 중인 어플라이언스 검사가 아닙니다.

packr-gape snapshot approved-manifest.json new-observation-folder
packr-gape validate-snapshot new-observation-folder/gape-architecture-snapshot.json

실제 릴리스가 생성한 파일명이 다르면 그 이름을 사용합니다. 매니페스트 지문·소스 리비전·snapshot ID·검사 결과와 execution_authority: NONE을 기록하십시오. 실행 파일이나 승인 매니페스트가 없으면 이 경로를 중지하고 이번 릴리스에서 미제공으로 기록합니다.

예시: 도표에 어댑터 연결이 보임

운영자가 GAPE snapshot에서 PackrGUI와 연동 어댑터 사이의 관계를 봅니다. 이 관계는 STATIC_SOURCE입니다. 실제 고객 런타임은 다른 기능 구성으로 동작할 수 있고 동적 호출은 저장된 소스 관찰 범위 밖일 수 있습니다. snapshot에 표시된 정확한 소스 버전을 기록하고 담당자에게 제공된 Contract와 연결 증거를 확인하십시오. 배포 기록에 “연결됨”이나 “승인됨”이라고 쓰지 않습니다.

예시: 관찰과 예상 규칙이 다름

snapshot에 인터페이스 연관은 있지만 예상 소유자 규칙이 없거나 다른 리비전의 규칙입니다. GAPE는 UNRESOLVED 또는 STALE을 표시합니다. 매니페스트 신원·snapshot 지문·판정·정확한 리비전을 보존하십시오. 담당자가 Contract와 소스를 별도로 대조해야 하며 그림을 새로 그리는 일은 복구가 아닙니다.

완료 증거

매니페스트, snapshot 검증 결과, 선택한 투영, 리비전, 공개 등급, 관찰 한계와 미해결 판정이 기록되면 관찰이 끝납니다. 연동 등록과 Work는 별도 절차입니다. Integration Helper 또는 Contract & Document 안내로 이어가십시오.

단계별 실제 사용 용례

예를 들어 새 연동 요청 전에 담당자가 데이터가 어느 구성요소를 거치는지 검토합니다. 승인된 매니페스트의 저장 리비전을 고정하고 노드 하나와 그 관계를 추적합니다. 관찰 출처와 확인되지 않은 동적 경로를 함께 적고, 다른 리비전의 문서와 비교할 때는 두 리비전을 모두 표시합니다. 운영 장애 원인을 이 그림만으로 확정하지 않습니다.

증상별 확인과 복귀 확인

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

인계 항목: 소스 리비전, 매니페스트 지문, snapshot 지문, 관찰 범위, 공개 등급, 선택한 노드·관계, 미해결 항목과 다음 확인 담당자. snapshot 검증 결과와 실제 런타임 증거는 별도로 기록합니다.

도구별 문제 해결 사례 읽기

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

상세 예시 GAPE-1: 코드는 변경됐지만 예전 snapshot을 검토함

상황: 담당자가 현재 설계와 다르다고 보고한 그림은 이전 저장 리비전의 snapshot입니다. 현재 소스, 승인 매니페스트와 관찰 결과의 리비전을 먼저 구별합니다.

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

• 그림: 특정 snapshot ID·소스 리비전을 가집니다.
• 현재 소스: 저장되지 않은 변경은 관찰에 포함되지 않을 수 있습니다.
• 검증: snapshot 구조 검사는 런타임 검증이 아닙니다.

확인·조치 순서:

1. 매니페스트 지문·snapshot 생성 시점·정확한 저장 리비전을 대조합니다.
2. 새 관찰이 필요하면 승인된 입력과 제공된 명령으로 새 출력 폴더를 사용합니다.
3. 이전·새 결과를 함께 보존하고 변경된 관계와 관찰 한계를 표시합니다.

다음 단계로 돌아갈 조건: 현재 검토 대상 리비전과 검증된 snapshot이 맞으면 그 범위의 관찰 검토를 계속합니다.

해결되지 않았을 때: 매니페스트나 리비전이 미확인이면 그림을 고쳐 일치시키지 않고 해당 관찰을 미확인으로 남깁니다.

상세 예시 GAPE-2: 필터 또는 관찰 범위 때문에 노드가 보이지 않음

상황: 검색에서 구성요소가 나오지 않아 기능이 없다고 생각합니다. 하지만 선택한 필터·매니페스트 제외 규칙·지원 언어에 따라 표시와 관찰 범위가 달라질 수 있습니다.

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

• 검색 결과 없음: 화면의 선택 범위에 대한 결과입니다.
• 매니페스트: 관찰 폴더·제외 규칙을 정합니다.
• 구현 부재: 이 화면만으로 확정할 수 없습니다.

확인·조치 순서:

1. 검색어·필터를 확인하고 원래 관찰의 범위·리비전·제외 목록을 읽습니다.
2. 다른 범위가 필요하면 승인된 입력을 가진 담당자에게 요청합니다. 내부 자료를 공개 뷰에 추가하지 않습니다.
3. 관찰 밖·표시 필터·실제 미확인을 구별해 기록하고 필요한 소스 근거를 담당자에게 인계합니다.

다음 단계로 돌아갈 조건: 해당 리비전과 범위의 관계를 확인한 경우에만 그 관찰을 인용합니다.

해결되지 않았을 때: 소스 근거가 없으면 미구현·기능 없음으로 단정하지 않습니다.

설치 후 도구 목록