실행·결과·오류 복구
Flow의 입력과 연결을 Validate하고, 검증된 내용을 Save한 뒤 Run을 선택합니다. 현재 지원되는 Function과 product-built first-party Node만 이 일반 Run 흐름을 따릅니다. 안전한 inactive quarantine이 없는 current V1에서 production third-party Component install admission과 activation은 구현된 exact ProjectScope data-path isolation에 Project authorization과 execution-trust closure가 더해질 때까지 차단하며 Validate / Run을 거부합니다. 후속 V2 Canvas UI는 host-owned component.declarative@2만 사용하고 settings를 component-declared-settings@1로 선언당 최대 8개까지 받고 host control registry가 그리며, rich surface는 RFC-016의 component-rich-surface-declaration@1이 소유합니다.
Home에서 로그인과 복귀 안내
정식 로그인 서비스에 연결된 Home에서는 로그인이 필요하거나 세션의 인증 토큰이 만료되면 로그인 버튼이 표시됩니다. 버튼을 누르면 로그인을 시작합니다. 상태 조회 실패는 안내로 표시하며 계산을 자동으로 다시 실행하지 않습니다. 로컬·샘플 화면에는 이 버튼이 제공되지 않습니다.
로그인 복귀 중 원래 문서나 선택 Run을 확인하지 못하면 Home에서 이유를 안내합니다. 안내를 닫아도 다른 주소 정보는 유지됩니다. 안내가 표시됐다는 사실 자체가 문서 접근 권한을 뜻하지는 않습니다. 한국어와 영어를 지원합니다. 공개 서비스 제공 여부는 해당 서비스의 로그인 설정과 배포 상태에 따릅니다.
Flow·Report에서 편집을 유지하며 로그인하기
원래 문서의 정확한 위치와 버전이 확인된 서비스 화면에서는 새 탭에서 로그인을 선택할 수 있습니다. 로그인 후 새 탭에서 같은 저장 리비전과 선택 Run을 엽니다. 미저장 초안은 원래 탭에 남습니다. 새 탭으로 초안을 복사하거나 기존 계산·저장을 자동으로 재시도하지 않습니다. 원래 탭으로 돌아오면 로그인 상태를 다시 확인합니다. 로그인 확인이 표시돼 있으면 선택해 재확인할 수도 있습니다. 이는 문서 권한 확인이나 저장 완료를 대신하지 않으며, 저장 오류·미확정 결과는 기존 복구 안내를 따릅니다.
새 탭이 차단되면 이 사이트의 새 탭 열기를 허용하고 다시 시도하세요. Project 목록에서 문서를 열다가 로그인이 필요해 위치 조회가 중단된 경우에도 새 탭에서 로그인으로 이어서 열 수 있습니다. 이미 열었던 문서 버전·Run이 주소에 있으면 그대로 유지합니다. 아직 문서를 읽지 못했다면 로그인 후 접근 권한을 확인한 첫 조회의 버전을 엽니다. 문서가 삭제됐거나 권한이 없으면 다른 문서로 바꾸지 않고 Home에서 안내합니다. 원래 catalog Workspace도 유지됩니다.
복귀할 Project가 지정된 경우 로그인 후 권한을 다시 확인해 그 위치를 유지합니다. 문서에서 Home으로 돌아오면 해당 Project를 선택하고 펼칩니다. 목록 첫 페이지에 없어도 찾습니다. 다른 Project의 Flow 결과를 보고 있어도 복귀 위치는 유지됩니다. Project가 없어졌거나 권한이 없으면 Home에서 안내하고 다른 Project를 자동 선택하지 않습니다. 조회 중 직접 다른 Project를 선택했다면 그 선택을 유지합니다. 복귀 Project가 지정되지 않은 링크는 기존 Home으로 돌아옵니다.
같은 Run을 Flow와 Report에서 확인하기
SDK가 저장한 Flow의 공개 결과를 선택한 Run에서 읽습니다. 계산 Node, 결과를 보여 주는 뷰어, Report에 반영할 위치는 서로 다른 역할입니다.
| 역할 | SDK 선언 | 화면에서 확인할 것 |
|---|---|---|
| 입력과 계산 | flow.input(), flow.node(), flow.connect() | 공개 입력과 typed 포트, 계산 대상 |
| 공개 결과 | flow.result() | Run이 반환한 이름 있는 값·표·파일 |
| Flow 뷰어 | flow.viewer() | 같은 선택 Run의 표·PNG, 결과 선택과 출처 |
| Report 출력 위치 | result_table() 또는 artifact_slot() + connection.show() | 적용된 Report 리비전의 결과와 파일 |
- 저장된 Flow를 열고 실행에 사용할 입력을 확인합니다. SDK에서 뷰어를 선언했거나 기존 Flow에 뷰어 편집을 적용했다면 캔버스에 결과 뷰어가 나타납니다. 실행 전에는 결과 없음 안내를 표시합니다.
- Run을 실행하거나 기존 Run을 선택합니다. Data/Results와 캔버스 뷰어는 같은 Run을 읽습니다. PNG·표의 결과 선택, 뷰어 이동·복제·확대는 계산을 제출하지 않습니다.
- Report에 결과를 넣으려면 저장된 connection을 실행합니다. 계산 성공과 Report 반영은 별개이며, SDK에서는
run.state와run.projection.state를 각각 확인합니다. 반영 상태는pending,applied,refused로 구분됩니다. 충돌로 반영이 거절돼도 생성 결과는 해당 Run에서 다시 읽을 수 있습니다. - 반영이 완료되면 실행 패널의 적용된 Report 열기 동작으로 해당 리비전을 확인합니다. 수정 중인 본문을 자동으로 교체하지 않습니다. 같은 Run을 Flow에서 여는 연결도 재계산 없이 실행 당시 Flow 리비전과 Run의 소유 Project를 유지합니다. Home 목록에서 위치가 확인된 문서는 이 이동 후에도 같은 Workspace·Project로 돌아갑니다.
- 입력을 바꾸어 다시 실행하면 새 Run이 생깁니다. 이전 Run을 선택하면 그 입력·snapshot·PNG를 다시 읽으며, 현재 입력 초안과 다르다는 표시가 이전 결과를 삭제하지는 않습니다.
서비스에 연결된 화면에서 특정 리비전을 지정한 Report 링크를 열면, 이후 새 저장본이 생겼어도 지정된 리비전을 읽습니다. 해당 리비전이 없거나 읽기 권한이 거절되면 최신 저장본이나 예제 화면으로 대체하지 않습니다. 이 주소 지원과 로그인 후 원래 화면으로 자동 복귀하는 기능은 별도 연결입니다.
sectionproperties 예제
저장소의 pipelineXlab_pxflow/sdk/python/examples/section_properties_analysis.py는 I형 단면을 계산합니다. 준비된 Worker 환경에서 sectionproperties가 properties 표와 geometry, mesh, centroids PNG를 생성합니다. 그림 세 개는 하나의 Flow 뷰어에서 선택하고, 수치표는 별도 뷰어로 읽습니다. Report는 같은 결과를 수치표와 PNG 슬롯 세 곳에 연결합니다. 화면에 표시할 예제 이미지나 수치를 별도로 넣지 않습니다.
이미 성공한 예제 Run을 SDK로 확인할 때는 그 Run의 workspace·project와 실제 key를 사용합니다. 서비스에 접속하는 경우에는 해당 Client의 접속 인자도 필요합니다.
import json
from pipelinexlab import px
with px.Client(workspace="examples", project="i_section_trial") as client:
run = client.get_run("saved_run_key") # 실행 후 받은 실제 Run key로 바꿉니다.
properties = json.loads(run.read_result("properties", max_bytes=8192))
geometry_png = run.read_result("geometry", max_bytes=4 * 1024 * 1024)
print(properties)예제의 선택 의존성은 Worker 실행 환경에 준비합니다. SDK를 사용하는 터미널에 라이브러리를 설치하는 것만으로 기존 Runtime 환경이 바뀌지 않으며, 뷰어를 여는 동작이 패키지를 설치하지도 않습니다. 환경 준비와 실행 명령은 예제 옆 section-properties/README.md에 있습니다.
운영용 준비 도구는 pxflow-prepare-python-environment이며 Linux/glibc x86-64 CPython을 지원합니다. 운영자는 실제 서버 실행 파일에 맞춰 환경을 준비하고 PXL_SERVER_PYTHON_ENVIRONMENT_FILE로 등록합니다. 자세한 명령과 교체 절차는 저장소의 pipelineXlab_pxflow/ops/PYTHON_WORKER_ENVIRONMENT.md를 따릅니다. 패키지 설치는 운영자가 준비 도구로 수행합니다. SDK API와 브라우저는 준비된 환경을 사용합니다.
미리보기 한도와 서비스 조건
PNG 자동 미리보기는 파일 8 MiB와 8,388,608픽셀 상한을 적용합니다. 상한을 넘으면 안내를 표시하며 원본 파일이나 저장된 리비전을 바꾸지 않습니다. 원본은 허용된 Run 다운로드·SDK 읽기 또는 Report 내보내기 경로로 확인합니다. 표도 제한된 미리보기이며 전체 결과와 구분합니다.
Run 조회·실행 host와 Project 권한이 연결된 화면에서 이 흐름을 사용할 수 있습니다. 연결되지 않은 기능은 사용 불가 이유를 표시합니다. 공개 URL별 실행 서비스 제공 여부는 해당 배포에서 확인하세요. 예제는 Linux 실행을 검증했으며, 다른 OS와 새 배포 wheel은 별도 검증이 필요합니다.
Run·Result 화면
| UI 위치 | 확인할 것 | 가능한 동작 |
|---|---|---|
| 상단 Validate | required input, type, unit과 연결 문제 | 문제 위치로 이동 |
| Run·Result | 현재 Flow의 Run 상태와 이름 있는 Result | Run, Cancel, Retry, 이력 열기 |
| Canvas Node | Node별 진행·경고·실패 | Node detail 열기 |
| Result detail | 값, unit, 사용한 Flow revision과 입력값 | 복사, artifact 열기, 이전 Result 비교 |
| Project Activity | 현재 Project의 background Run | 진행 확인, Cancel, 해당 Flow 열기 |
Run 시작하기
- Validate에서 오류가 없는지 확인합니다.
- Flow를 Save합니다.
- Run을 누릅니다.
- 실행할 Flow revision과 input을 확인합니다.
- Project Activity에서 진행 상태를 보고, 완료되면 Result를 엽니다.
현재 저장 Run 뷰어는 명시적으로 Run을 제출할 때 계산합니다. 입력 필드를 바꾸는 동작은 초안만 수정하며 Run을 시작하거나 선택 Run의 저장 입력을 바꾸지 않습니다. 새 결과가 필요하면 수정한 입력으로 다시 실행하고, 앞선 Run은 비교할 수 있도록 유지합니다.
실행 전 검증
Validate는 다음 순서로 문제를 보여 줍니다.
- required input 누락
- type·unit·nullable·shape 불일치
- 연결할 수 없는 port 또는 cycle
- missing Component dependency·Function·Flow target
- 권한·license·실행 정책
- resource 상한
각 진단은 문제가 있는 Node·port·setting의 정확한 위치와 복구 동작을 함께 표시합니다.
진행 상태
| 상태 | 의미 | 이때 하면 되는 일 |
|---|---|---|
| Created | Run 기록이 만들어짐 | 기다립니다 |
| Validating | revision·input·dependency를 검사하는 중 | 기다립니다 |
| Queued | 실행 자원이 나기를 기다리는 중 | 기다립니다 |
| Running | 계산이 진행 중 | 진행 상태를 보고, 필요하면 Cancel |
| Cancelling | 취소 요청을 처리하는 중 | 종료될 때까지 기다립니다 |
| Succeeded | 사용할 수 있는 Result가 만들어짐 | Result와 생성 근거를 확인합니다 |
| Partial success (Batch) | Batch 중 일부 child Run의 Result만 사용할 수 있음 | 실패한 child Run을 찾아 그 입력을 수정합니다 |
| Failed | Result 없이 종료됨 | 아래 오류 위치에서 원인을 열고 수정한 뒤 새 Run |
| Cancelled | 취소가 확정되어 종료됨 | 필요하면 새 Run을 시작합니다 |
| Indeterminate | 외부 실행 상태를 확정할 수 없음 | 기존 Run을 새로고침하고 제공된 진단을 확인합니다. 새 계산을 자동 제출하지 않습니다 |
새로고침하거나 화면을 다시 열어도 서버에 남아 있는 실행 기록에서 상태와 완료된 Result를 복원합니다. 브라우저를 닫아도 진행 중인 Run은 계속됩니다.
Partial success는 Run → New batch로 만든 Batch에만 나타나는 요약 상태입니다. 한 번 실행한 Run은 Succeeded, Failed, Cancelled 중 하나를 가지며, Batch 안의 각 child Run도 그 셋 중 하나를 따로 유지합니다.
Flow·Report 결과 영역의 안내
Flow Results, 캔버스 뷰어, Report 실행 패널은 선택한 Run의 상태를 같은 의미로 표시합니다. Created·Validating·Queued·Running은 결과 대기, Failed는 계산 실패, Cancelled는 취소, Indeterminate는 계산 결과를 확정할 수 없다는 뜻입니다. 실패·취소·불확정 상태를 결과 대기로 안내하지 않으며, 이 상태에서 결과 파일을 요청하거나 계산을 자동으로 다시 제출하지 않습니다.
Succeeded여도 결과 파일 조회는 실패할 수 있습니다. 이때 같은 Run을 새로고침해 읽기를 재시도할 수 있으며 계산을 다시 실행하는 것과는 다릅니다. Report 반영의 대기·완료·거절은 계산 상태와 별도로 확인합니다. Indeterminate의 새로고침이 결과를 확정해 준다고 보장하지 않습니다.
Result와 근거 확인
- Run·Result에서 완료된 Run을 선택합니다.
- Result의 이름, 값, unit과 생성 시점을 확인합니다.
- Provenance에서 사용한 Flow revision, 입력값 식별 정보, dependency와 실행 환경을 확인합니다.
- 이전 Result와 비교하려면 두 snapshot을 선택합니다.
Result는 읽기 전용입니다. 값이 달라져야 하면 input, Node setting 또는 Flow source를 수정해 새 Run을 시작합니다. 작은 값은 inline으로, 큰 Table·PDF·image·model은 summary와 resource link로 표시합니다.
SDK/API 기술 참고 · ResultSnapshot
immutable 결과 객체는 ResultSnapshot입니다. 한 snapshot은 exact Run과 execution digest를 가리키며 다른 Run의 값을 섞어 current Result를 만들지 않습니다.
지원되는 first-party Node의 artifact
product와 함께 build·review한 first-party Node가 artifact를 만들면 일반 named Result와 같은 영역에 표시합니다. 이 절은 first-party Node의 artifact만 다루며, installed third-party Component 실행은 Project authorization과 execution-trust closure를 닫은 뒤에 엽니다.
artifact detail에는 producing Node, source Run, format, 크기와 열기·저장 동작이 표시됩니다. third-party Component artifact는 Project authorization과 execution-trust closure가 승인되기 전에는 생성 경로를 열지 않습니다.
오래된 Result
Flow source, input, Node setting 또는 dependency가 Result 생성 뒤 바뀌면 Stale로 표시합니다.
이전 snapshot은 삭제하지 않고 이력과 audit를 위해 유지합니다.
Table 결과와 행별 진단
typed Table input은 값 하나로 전달되어 Flow Run 한 번을 시작합니다. Function의 public result contract가 행별 상태나 진단 column을 제공하면 Result 표에서 그 값을 확인합니다.
| 상태 | 다음 동작 |
|---|---|
| 모든 행 정상 | Table result와 provenance 확인 |
| 일부 행에 업무 진단 | 진단 code와 해당 rowKey를 확인해 input Table 수정 |
| Node 실행 실패 | Node detail에서 오류를 확인한 뒤 새 Run |
새 실행에는 수정한 Table 전체와 exact Flow revision이 함께 기록됩니다.
오류 위치와 해결 방법
| 표시 위치 | 예 | 다음 동작 |
|---|---|---|
| Node header | missing target, 실행 실패 | Node detail 또는 dependency 열기 |
| input port | type·unit·required 오류 | 연결·input 수정 |
| connection | 방향·shape·cycle 오류 | 연결 교체 또는 제거 |
| Run detail | worker·resource·external API 오류 | Retry 조건과 로그 확인 |
| Result block | stale·partial·missing artifact | 원본 Run 또는 Flow 열기 |
SDK/API 기술 참고 · Diagnostic
기술 객체는 Diagnostic이며 severity, code, exact path, expected/current 정보와 현재 허용되거나 successor로 명시된 recovery action을 가집니다. UI 문구가 달라도 code와 path 의미는 같습니다.
상황별 복구
| 상황 | 먼저 확인 | 복구 |
|---|---|---|
| Component dependency required | exact 7-field ComponentRef, raw settings, usage-derived partial ports | 현재 read-only unsupported; Add required package는 post-closure successor |
| Contract mismatch | port·setting diff | Review update |
| 권한 만료 | Project·dependency access | Review access |
| 실행 취소 | terminal Cancelled 여부 | 필요하면 새 Run |
| 앱 종료·연결 끊김 | durable Run 상태 | 다시 열어 이어서 확인 |
| worker 응답 불명 | Indeterminate detail | reconcile 후 Retry |
비슷한 이름의 target으로 자동 교체하지 않습니다. replacement preview에서 impact를 확인하고 Apply로 확정합니다.
dependency를 복구해도 third-party Component는 구현된 exact ProjectScope data-path isolation만으로 Validate와 Run을 통과하지 않으며, Project authorization과 execution-trust closure가 필요합니다. 현재 recovery는 original package bytes를 package artifact owner가 실제로 보존한 경우에만 별도 evidence로 사용합니다. Flow/current reader가 유지하는 값은 exact 7-field ComponentRef, raw settings와 usage-derived partial ports뿐입니다. full/last-verified port snapshot이나 안전한 inactive quarantine은 존재한다고 가정하지 않습니다.
Save와 Run의 차이
- Apply: 검토한 edit plan을 현재 draft에 반영합니다.
- Save: Flow와 기존 V1 Node-local setting을 새 revision으로 저장합니다. V2 settings를
component-declared-settings@1로 선언당 최대 8개까지 받고 host control registry가 그립니다. - Run: 저장한 Flow revision과 input으로 계산을 시작합니다.
- Result: Run이 만든 읽기 전용 값·artifact와 실행 근거입니다.
Run 객체
Run은 사용한 Flow revision과 입력값, 상태, 작업 시도와 감사 기록을 보존하는 실행 기록입니다. SDK에서는 client = px.Client(workspace="...", project="...")를 만든 뒤 Flow 자체는 client.run(flow, **inputs), Report에 저장한 connection은 client.run(connection)으로 실행합니다. PXFLOW의 Run과 MCP pxflow_run도 같은 Run 계약을 사용합니다.