Report → PXFLOW input mapping 계약

Python SDK에서는 connection = report.connect_flow(...)로 Connected Flow handle을 받은 뒤 connection.bind(...)를 호출합니다. 이 호출 또는 Report Workbench에서 만든 연결은 Report 파일의 flowConnections[].inputMappings에 저장됩니다. Flow는 flow.input(...)으로 public input을 공개하고, Report는 그 input에 전달할 값의 위치를 기록합니다.

점선은 `.pxreport`가 소유하는 Report↔Flow mapping이고, 실선은 `.pxflow`와 `flow.connect(...)`가 소유하는 Flow 내부 연결입니다. Report 연결을 만들어도 Flow Python source는 바뀌지 않습니다.

Report와 Flow의 편집 책임은 다음과 같이 나뉩니다.

편집 대상	저장 owner	편집 화면
Report 본문, 작성값, 표	.pxreport block·cell	px.Report 또는 Report Workbench
Report 위치 → Flow public input	.pxreport flowConnections[].inputMappings	Connected Flow handle의 .bind() 또는 Report Workbench
Flow public input	.pxflow 또는 SDK의 flow.input(...)	PXFLOW Studio 또는 Python source
Flow 내부 port 연결	.pxflow 또는 SDK의 flow.connect(...)	PXFLOW Studio 또는 Python source

inputMapping

다음 예제는 Report 본문의 span 값을 girder_check Flow의 span input에 연결합니다.

{
  "connectionKey": "girder_check",
  "mappingGeneration": 1,
  "flowTarget": {
    "scope": {
      "kind": "project",
      "workspaceKey": "structural_team",
      "projectKey": "bridge_design"
    },
    "flowKey": "girder_check",
    "revisionRef": "sha256:flow-revision-digest"
  },
  "inputMappings": [
    {
      "mappingKey": "span_input",
      "portKey": "span",
      "source": {
        "kind": "reportValue",
        "blockKey": "design_basis",
        "fieldKey": "span"
      }
    }
  ],
  "resultMappings": [],
  "runPolicy": "manual"
}

• connectionKey는 Report 안에서 이 Flow 연결을 찾는 stable semantic key입니다.
• mappingKey는 connection 안에서 mapping 하나를 계속 찾는 stable key이고, mappingGeneration은 mapping 집합이 바뀔 때 증가합니다.
• flowTarget은 Project, Flow와 exact revisionRef를 고정합니다.
• portKey는 Flow가 공개한 exact input key입니다.
• source는 Report가 소유하는 typed value 위치입니다.

같은 연결의 여러 inputMappings는 한 번의 ordinary Flow Run에 함께 전달됩니다.

source 종류

V1 source는 세 종류를 사용합니다.

작성값

{
  "kind": "reportValue",
  "blockKey": "design_basis",
  "fieldKey": "span"
}

본문의 이름 있는 값이나 Record field를 가리킵니다. 주소로는 blockKey와 fieldKey를 쓰므로, 화면 label을 바꾸거나 주변 문장을 편집해도 같은 값을 계속 가리킵니다.

표 영역

{
  "kind": "reportTableSelection",
  "tableKey": "load_cases",
  "rowKeys": ["uls_01", "uls_02", "sls_01"],
  "rowKey": {
    "sourceFieldKey": "case_key",
    "inputFieldKey": "case_key"
  },
  "fields": [
    {
      "sourceFieldKey": "design_moment",
      "inputFieldKey": "design_moment"
    }
  ]
}

선택한 행, row key와 field mapping을 각각의 key로 저장합니다. Flow public input이 List<T>나 Table<Record>이면 선택 영역이 값 하나로 묶여 Flow Run 한 번에 전달됩니다.

Report 선택	Flow public input	Run 동작
cell 하나	scalar	값 하나로 Run 1회
여러 행의 field 하나	List<T>	list 하나로 Run 1회
여러 행과 여러 field	Table<Record>	table 하나로 Run 1회
여러 행	scalar	shape 진단 후 compatible input 또는 Batch Run 선택

행을 고르는 것만으로 실행 횟수가 늘어나는 대신, 여러 case를 각각 실행할 때는 Run → New batch로 Batch Run을 만들어 실행 대상을 확정합니다.

첨부 자료

{
  "kind": "reportAttachment",
  "attachmentKey": "analysis_model"
}

Report가 가진 파일이나 artifact를 artifact public input에 전달합니다. 파일 경로 문자열 대신 권한을 검사한 참조를 보내므로, 받는 쪽에서도 접근 권한이 그대로 확인됩니다.

Type·unit·shape 검증

Apply 전에 Report source와 Flow input 계약을 함께 검사합니다.

• scalar, Record, List, Table과 artifact shape
• numeric type과 unit dimension
• required field와 nullability
• 표의 stable row key와 field key
• exact Flow revisionRef와 portKey
• 같은 input을 둘 이상의 source가 동시에 소유하는 충돌

호환 가능한 unit conversion은 적용 전에 변환식을 보여 주고 Run provenance에 남깁니다.

실행과 결과 위치

저장된 Report revision을 실행하면 다음 순서로 처리합니다.

저장된 Report connection 실행

1. 1Connection 검증mapping · exact Flow revision
2. 2Input materializeReport source를 typed payload로 변환
3. 3Flow Runexact revision의 ordinary Run 1회
4. 4Immutable Resultnamed result와 provenance 저장
5. 5Report projectionresultMappings가 지정 위치에 표시

Input mapping과 result mapping은 같은 connectionKey와 Flow Run을 공유합니다. 결과 위치의 계약은 Report ↔ Flow 연결 명세에서 이어집니다.

변경과 복구

변경	Report Workbench 동작
Flow input key 또는 type 변경	영향받는 mapping과 새 계약을 나란히 표시
Flow revision 변경	기존 exact revision과 후보 revision을 비교한 뒤 선택
Report block·field rename	semantic rename transaction으로 mapping을 함께 갱신
source 값 변경	기존 result를 Stale로 표시하고 Run again 제공
권한 변경	연결 위치를 보존하고 Request access 제공

비슷한 label의 input으로 자동 재연결하지 않습니다. 사용자가 exact port와 revision을 검토한 뒤 새 mapping을 저장합니다.

AI·MCP command

AI와 MCP도 Report Workbench와 같은 typed command를 사용합니다.

SetReportFlowInputSource
SetReportFlowResultTarget
RemoveReportFlowMapping
RunReportFlowConnection
RunReportFlowBatch

Preview에는 Report source, Flow input, type·unit·shape, exact revisionRef와 영향받는 Report 위치를 표시합니다. Apply는 현재 draft에 command를 반영하고, Save가 expected generation을 검사한 뒤 새 .pxreport revision을 만듭니다.

불변식

1. Report input mapping의 owner는 .pxreport입니다.
2. Flow source는 Report block key, 표 좌표와 .pxreport path를 저장하지 않습니다.
3. flow.connect(...)는 현재 Flow 안의 port-to-port 연결을 표현합니다.
4. 표 collection은 typed input 하나로 Flow Run 한 번에 전달합니다.
5. 여러 scalar 실행은 사용자가 만든 explicit Batch Run으로 표현합니다.
6. Result는 immutable snapshot에 남고 Report 위치에는 읽기 전용으로 표시합니다.

이어서 보기

• Report Workbench
• Report와 Flow 연결
• Report ↔ Flow 연결 명세
• SDK와 PXFLOW Studio