가이드북

테마

AI로 기존 엑셀과 CSV 자료 준비하기 ​

이럴 때 씁니다 ​

기존 제품대장의 열 이름이 인피리움 입력과 다를 때, AI로 열을 분석하고 어떤 값이 어디에 들어갈지 확인합니다. 아래 합성 예제는 품번·제품명 두 열을 PartType Information으로 준비하는 연습입니다.

자료 준비에서 등록까지

  1. 연결

    소유자가 프로그램을 등록하고 필요한 도구 사용에 동의합니다.

  2. 분석

    예제 파일이나 준비한 자료의 열과 입력 규격을 확인합니다.

  3. 매핑

    어떤 열을 어떤 입력 항목에 넣을지 확인하고 결과를 미리 봅니다.

  4. 초안

    검토한 행을 선택해 초안으로 저장합니다.

  5. 사람 검토

    조직 소유자가 웹에서 등록할 내용과 범위를 검토하고 승인합니다.

  6. 등록

    승인한 범위의 등록을 요청하고 단계별 결과를 확인합니다.

시작하기 전에 ​

AI·프로그램 연결을 마칩니다. 미리보기까지는 프로그램 허용 목록에 data:read, data:prepare가 필요하며 이번 로그인에서도 두 기능에 동의합니다. 초안 저장까지 따라 하려면 처음 프로그램을 등록할 때 data:templates, data:drafts도 포함한 4개를 선택합니다. 실제 동의는 각 단계에 필요한 기능만 요청합니다. 목표별 허용 목록을 확인하세요. 현재 연결은 허용된 개발 환경에서 사용합니다.

예제 제품대장 CSV 다운로드 — 고객 자료가 없는 합성 데이터입니다. Excel에서 한글을 열기 편하도록 UTF-8 BOM을 포함합니다. .csv로 저장한 뒤 Excel 또는 텍스트 편집기에서 아래 두 행을 확인하세요.

품번제품명
DEMO-001예제 알루미늄 브래킷
DEMO-002예제 스틸 커버

이 예제에는 인증·탄소배출·BOM·사업장 정보가 없습니다. 파일에 없는 값은 추가 자료로 확인하며 시스템 발급 ID는 원본 열에 만들지 않습니다.

따라 하기 ​

1. 파일과 입력 규격을 확인합니다 ​

다운로드한 파일을 연결한 AI 프로그램의 파일 입력으로 제공하고 다음을 요청합니다. 파일을 MCP 분석 입력으로 전달할 수 없는 프로그램이라면 설정 담당자가 도구 입력 형식을 구현해야 합니다.

text
첨부한 example-products.csv는 합성 연습 자료야.
infirium_analyze_product_files로 includeFullValues=true, responseFormat=structured로 분석해 줘.
part-type-information, catalogVersion 3, purpose registration의 입력 규격을 조회해 줘.
파일의 시트·영역·열·데이터 행 수와 필수 입력을 알려 줘.
분석에서 반환한 source와 layoutSignature, 실제 region ID를 다음 단계에 유지해 줘.
아직 초안 저장이나 등록은 하지 말아 줘.

예상 결과: 품번·제품명 두 열과 데이터 2행이 보입니다. 분석의 source.completeness는 full이며 필수 입력에 제조사 품번과 제조사 제품명이 표시됩니다. PartType Information의 catenaXId는 시스템 관리 필드로 구분됩니다. 데이터 행에 헤더를 포함하지 않았는지 확인하세요.

2. 어떤 열을 어디에 넣을지 확인합니다 ​

이 예제에서 담당자가 확인할 매핑은 다음과 같습니다. 열 번호는 1부터 시작합니다.

원본 열의미인피리움 대상 경로
1: 품번제조사가 부여한 품번partType.partTypeInformation.manufacturerPartId
2: 제품명제조사 제품명partType.partTypeInformation.nameAtManufacturer
text
품번 열은 제조사 품번, 제품명 열은 제조사 제품명으로 확인했어.
위 매핑을 infirium_suggest_data_mapping의 proposed 후보로 전달해 줘.
rule.targetPath에 대상 경로를 쓰고 evidence는 문자열 배열로 넣어 줘.
열·값·원본 셀 출처와 모호성을 보여 주고 확인을 기다려 줘.

예상 결과: 두 대상 경로에 대한 후보와 근거가 나옵니다. 후보는 제안이므로 원본 셀의 DEMO-001과 제품명을 직접 대조합니다. 비슷한 열 이름을 AI가 선택했다는 이유만으로 확정하지 않습니다.

개발자용: 실제 스키마의 명시적 후보 예

아래는 proposed 배열의 후보 한 개입니다. <실제 region ID>를 분석 결과에서 가져오며, source는 전체 분석 결과의 source를 그대로 전달합니다. 요구사항의 fieldPath를 rule의 키로 사용하지 않습니다. 두 번째 후보는 columnIndex: 2, targetPath: "partType.partTypeInformation.nameAtManufacturer"로 만듭니다.

json
{
  "rule": {
    "regionId": "<실제 region ID>",
    "columnIndex": 1,
    "targetPath": "partType.partTypeInformation.manufacturerPartId",
    "transforms": [{ "op": "copy" }],
    "acceptFormulaCache": false,
    "expandMerged": false
  },
  "confidence": "semantic",
  "evidence": ["담당자가 품번 열을 제조사 품번으로 확인함"],
  "sourceRefs": []
}

sourceRefs에는 분석 결과의 실제 셀 참조를 사용할 수 있습니다. 예제의 빈 배열은 출처를 새로 만들어내지 않는 형식 예이며, 미리보기에서는 실제 provenance를 확인합니다. 전체 입력에는 source, selection: {profileKey, catalogVersion, purpose}, proposed가 필요합니다. 최신 입력은 tools/list에서 확인합니다.

3. 미리보기로 값과 누락을 확인합니다 ​

text
두 열 매핑을 확인했어. 확인한 매핑만 recipe의 rules로 사용해 줘.
분석의 layoutSignature와 실제 rootRegionId, recordKeyColumn=1을 유지하고
infirium_preview_prepared_data를 호출해 줘.
두 제품의 품번·제품명·원본 셀 출처·누락과 오류를 표로 보여 줘.
미리보기 뒤에는 저장하지 말고 기다려 줘.

예상 결과: 제품 2개의 후보와 품번·제품명의 셀 출처가 보입니다. 분석 결과의 영역이 A1:B3이라면 첫 제품의 출처는 A2/B2입니다. 실제 주소와 값을 대조합니다. 이 합성 예제는 ready_for_preview와 시스템 ID 발급 대기 이슈 system_value_pending 2개가 나올 수 있습니다. readiness와 issues를 함께 읽고, 누락·단위·조건부 입력이 있으면 원본 사양서나 ERP 담당자에게 확인합니다.

미리보기는 저장하지 않습니다. 예제 두 열의 매핑 성공을 고객의 다른 양식·복잡한 배열·계산 필드에 대한 정확도로 해석하지 않습니다.

4. 선택한 행을 초안으로 저장합니다 ​

여기부터 저장 기능이 필요합니다. 등록된 프로그램 허용 목록에 앞의 조회·분석 2개와 data:templates, data:drafts가 있는지 확인하고, 이 단계에서 사용할 4개 scope로 다시 로그인해 동의합니다. 허용 목록이 부족하면 새 프로그램을 등록해 설정을 교체한 뒤 진행합니다. 기존 client/grant에 묶인 검토·승인을 새 연결에서 재사용하지 않습니다.

text
미리보기에서 확인한 두 행을 초안으로 준비하고 싶어.
확인한 recipe로 매핑 템플릿을 만들고, 응답의 template.id를 templateId로,
반환된 revision을 revision으로 사용해 intake plan을 만들어 줘.
계획의 선택 행·제품 표시 이름·누락·저장 동작을 먼저 보여 주고 내 확인을 기다려 줘.

예상 결과: 매핑 템플릿의 ID·revision과 초안 생성 계획의 id, decisionDigest, items가 반환됩니다. items의 행·이름·action을 확인하고 저장 가능한 create_draft 행을 선택합니다. 계획의 행과 이름이 맞으면 다음처럼 명확히 지시합니다.

text
방금 확인한 계획의 DEMO-001, DEMO-002 행을 초안으로 저장해 줘.
계획의 items에서 내가 확인한 두 행 중 action이 create_draft인 행의 recordKey만
selectedRecordKeys에 넣어 줘. 계획의 id를 planId로 사용하고,
반환된 decisionDigest를 그대로 confirmedDecisionDigest에 넣어 줘.
이번 실행의 idempotencyKey를 유지해 줘. 저장된 초안 ID와 결과를 알려 줘.
정식 등록은 실행하지 말아 줘.

프로그램은 계획 응답의 id를 planId, 검토한 items[].recordKey를 selectedRecordKeys, 응답의 decisionDigest를 변경 없이 confirmedDecisionDigest로 전달합니다. source와 displayNames도 계획을 만들 때 사용한 값 그대로 infirium_execute_intake_drafts에 보냅니다. 키는 프로그램이 생성한 안정적인 UUID이며 응답이 불명확할 때 같은 실행 내용을 유지합니다. 예상 결과: 선택 행의 저장 결과와 초안 ID를 확인할 수 있습니다. 오류 행은 결과대로 보완합니다.

5. 등록은 소유자가 웹에서 따로 검토합니다 ​

초안은 정식 등록·공개·계약 체결과 다릅니다. 정식 등록까지 진행할 프로그램은 처음 허용 목록에 앞의 4개와 data:updates, products:register도 포함해야 합니다. 등록 검토를 만들기 전에 필요한 scope로 다시 로그인·동의합니다. 목록이 부족하면 새 프로그램으로 연결을 교체하고, 기존 client/grant에 묶인 등록 검토·승인은 다시 준비합니다. 등록하려면 개발자 등록 절차에 따라 준비 상태와 정책을 확인하고 등록 검토 링크를 만듭니다. 원래 요청한 조직 소유자가 웹에서 제품·공개 범위·실제 정책을 읽고 승인합니다. AI 프로그램의 도구 실행 허용은 이 업무 승인을 대신하지 않습니다.

합성 제품 DEMO-001의 제품 정보와 정책을 확인하고 승인 체크박스를 선택하기 전 등록 검토 화면
예제 데이터를 넣은 화면입니다. 승인 대기 상태이며 정식 등록 완료 화면이 아닙니다. 원본 크기로 보기

승인 후에도 실행 권한과 준비된 서버 설정이 필요합니다. 프로그램은 반환된 다음 단계를 하나씩 요청하고 최종 게시 결과를 확인합니다.

끝나면 이렇게 보입니다 / 안 되면 ​

첫 연습의 완료 기준은 원본 2행 → 확인한 매핑 → 셀 출처가 있는 미리보기입니다. 저장을 선택했다면 초안 ID를 추가로 확인합니다.

상황다음 행동
값이 일부만 보임includeFullValues=true로 다시 분석하고 새 source·layoutSignature 사용
열이 잘못 연결됨실제 열 의미를 확인하고 명시적 매핑 수정 후 미리보기
단위·필수값이 없음사양서·ERP·공급자 자료로 확인. 원본에 없는 값을 추측해 확정하지 않음
초안 도구가 없음프로그램 허용 목록의 4개 기능과 이번 동의·현재 권한 확인. 허용 목록이 부족하면 새 프로그램 등록·설정 교체
파일 제한 오류식별 관계를 유지해 파일 분할. 전체 파일 파싱 상한은 영역 축소로 우회되지 않음

CSV/XLSX 최대 5개·디코딩 파일 합계 7 MiB·전체 50,000셀 등 자세한 한도는 오류·제한에 있습니다. PDF·이미지는 고급 로컬 추출에서 별도 준비하며 OCR 결과도 검토해야 합니다.

이 안내서는 현재 저장소에 구현된 화면을 기준으로 작성합니다.