excel
English시작하기

문서 › 레퍼런스

리포트 형식: result.report, 업로드 본문, 오류 목록

check()의 summary와 report, <excel-82>가 서버로 보내는 본문, CSV·xlsx 오류 목록의 모양.

0.2 규칙으로 check() 하면 결과에 summary(사람이 읽는 요약)와 report(서버에 보낼 기계용 리포트)가 붙습니다. 오류 목록은 CSV나 xlsx 파일로 내려받을 수 있습니다. 어디서든 개인정보는 가려져 있고, 업로드할 rows 만 가리지 않습니다.

import { check, makeErrorReport } from '82excel';
import { makeErrorReportXlsx } from '82excel/report-xlsx';   // 별도 청크

const r = await check(file, { ...rules, readRows: true, locale: 'ko' });
r.report;                                                     // 서버에 보낼 리포트(힌트)
const csv = makeErrorReport(r, 'csv', { locale: 'ko' });      // Blob, UTF-8 BOM
const xlsx = await makeErrorReportXlsx(r, r.rows, { rules, locale: 'ko' });

result.report

필드내용
schemaId, schemaVersion규칙의 id, version
schemaHashrulesHash(rules), sha256:<hex>. 서버가 자기 rules.json 으로 계산한 값과 비교
lib82excel@<버전>
file{ name, size, sha256, sheet, format }. sha256 은 파일 바이트의 해시(16진수)
header{ row, columns: [{ key, source, col }] } 머리글 행 번호와 찾은 열
stats{ rows, errors, warnings } 결과 행 수와 문제 수
issues오류 다음 경고. 개인정보는 가려져 있음
checkedAt검사 시각(ISO 8601)

예시 파일 orders-sample.xlsx 를 홈의 예시 규칙으로 검사한 결과입니다(해시는 줄이고 issue는 두 개만 남김).

{
  "schemaId": "orders-upload",
  "schemaVersion": "3",
  "schemaHash": "sha256:f9cb5021…",
  "lib": "82excel@0.2.0",
  "file": { "name": "orders-sample.xlsx", "size": 12807, "sha256": "4afe7146…", "sheet": "Sheet1", "format": "xlsx" },
  "header": { "row": 1, "columns": [
    { "key": "orderNo", "source": "주문 번호", "col": "A" },
    { "key": "orderDate", "source": "주문일", "col": "B" },
    { "key": "amount", "source": "금액", "col": "C" }, …
  ] },
  "stats": { "rows": 10, "errors": 8, "warnings": 0 },
  "issues": [
    { "code": "CELL_PATTERN", "severity": "error", "message": "Row 3, column A (주문번호): Does not match the required pattern",
      "row": 3, "col": "A", "key": "orderNo", "header": "주문번호", "rule": "pattern", "raw": "ORD-12", "value": "ORD-12" },
    { "code": "CELL_DATE", "severity": "error", "message": "Row 4, column B (주문일): Date does not exist",
      "row": 4, "col": "B", "key": "orderDate", "header": "주문일", "rule": "type", "raw": "2024-13-01", "reason": "invalid" }, …
  ],
  "checkedAt": "2026-10-22T06:44:39.367Z"
}

칸 문제는 { code, severity, message, row, col, key, header, rule, raw, value? } 입니다. row 는 엑셀에서 보이는 행 번호(머리글 포함, 1부터), header 는 규칙의 머리글, raw 는 원래 값(가려짐), value 는 형식은 맞았을 때의 정리된 값입니다.

result.summary

칸 문제를 열과 코드로 묶은 목록입니다. 예시는 행 순서로 최대 3개입니다. 컴포넌트의 요약 목록("C열(금액) 금액이 올바르지 않습니다 120건 — 3행 '1천원', 7행 '-'")이 이것으로 그려집니다.

[
  { "key": "orderNo", "col": "A", "header": "주문번호", "code": "CELL_PATTERN", "severity": "error", "count": 1,
    "examples": [{ "row": 3, "raw": "ORD-12" }] },
  { "key": "orderDate", "col": "B", "header": "주문일", "code": "CELL_DATE", "severity": "error", "count": 1,
    "examples": [{ "row": 4, "raw": "2024-13-01" }] }, …
]

업로드 본문

0.2 규칙을 쓰는 <excel-82 upload=…> 의 기본(upload-as="json") 본문입니다. Content-Type: application/json.

{
  "fileName": "orders.xlsx",
  "sheet": "Sheet1",
  "schema": { "id": "orders-upload", "version": "3", "hash": "sha256:…" },
  "columns": ["orderNo", "date", "phone", "amount"],
  "rows": [{ "$row": 2, "orderNo": "AB000001", "date": "2024-01-05", "phone": "010-1234-5678", "amount": 12000 }],
  "report": { "schemaHash": "sha256:…", "lib": "82excel@0.2.0", "file": { "sha256": "…" }, "…": "…" }
}
  • rows 는 정리된 값이고 마스킹하지 않습니다. $row 는 엑셀 행 번호입니다. upload-report="off" 면 report 키가 없습니다.
  • upload-file="include": multipart/form-data, 필드 file(이름은 upload-field, 기본 file), data(위 JSON에서 report 를 뺀 문자열), report(리포트 JSON 문자열).
  • upload-as="file": multipart, file 과 report 필드.
  • 서버는 validate(body.rows, rules) 로 다시 검사합니다(서버 2차 검수).

CSV 오류 목록

makeErrorReport(result, 'csv', { locale? }) 는 UTF-8 BOM이 붙은 CSV Blob 을 돌려줍니다. 열은 행, 열, 머리글, 원래 값, 메시지, 코드, 등급이고, 오류 다음 경고 순서입니다. 엑셀에서 수식으로 실행될 수 있는 값은 앞에 ' 를 붙입니다. 값은 이미 가려져 있습니다. 서버의 422 응답에도 쓸 수 있습니다(validate() 결과에는 columnLetters 옵션을 줄 때만 열 글자가 있습니다).

Row,Column,Header,Original value,Message,Code,Severity
3,A,주문번호,ORD-12,"Row 3, column A (주문번호): Does not match the required pattern",CELL_PATTERN,error
4,B,주문일,2024-13-01,"Row 4, column B (주문일): Date does not exist",CELL_DATE,error
5,C,금액,1천원,"Row 5, column C (금액): Invalid amount",KR_AMOUNT,error

xlsx 오류 목록

  • makeErrorReportXlsx(result, rows, { rules?, locale?, sheetName? })(82excel/report-xlsx)는 데이터 시트에서 오류 칸은 빨간색, 경고 칸은 노란색으로 칠하고 메모를 단 뒤, "오류" 시트를 덧붙인 xlsx Blob(Promise)을 돌려줍니다.
  • rules 를 주면 데이터 값도 같은 규칙으로 가립니다(주지 않으면 주민번호로 보이는 값만). 원본 서식은 보존하지 않습니다.
  • CDN에서는 82excel.report-xlsx.min.js(전역 Excel82ReportXlsx)입니다. <excel-82 error-report="xlsx"> 는 버튼을 처음 누를 때 이 파일을 CDN 파일 옆에서 불러옵니다(report-xlsx-src 로 바꿀 수 있음). 시트·열 이름은 영어와 한국어만 있습니다.