Feature #875
openFeature #866: [MASTER] ICN Solar CAD Agent — Autodesk MCP 및 L2→L1 태양광 자동설계 시스템 구축
Feature #867: Phase 1 — MCP 기반 태양광 CAD 자동설계 플랫폼 구축 및 통합 검증
PoC-08. L2 계산서·수량산출서·BOQ 정보 추출
0%
Description
PoC-08. L2 계산서·수량산출서·BOQ 정보 추출¶
1. 작업 개요¶
본 PoC는 기존 L2 태양광 설계 프로젝트의 설계계산서, 수량산출서, 공사비내역서(BOQ)에서 주요 설계 수치와 수량·단위·계산 근거를 추출하여 구조화하는 기능을 구축하는 작업이다.
PoC-07의 CAD 모듈 배치 분석과 병렬로 진행하며, 이후 도면과 산출물 간 정합성을 검증하고 Engineering Knowledge를 도출하기 위한 문서 분석 기반을 확보한다.
기존 저장소에 구현된 PDF/Excel 분석 및 Evidence 관리 기능을 우선 조사하고 재사용한다.
GitHub Issue: https://github.com/GilbertMoon/icn-solar-cad-agent/issues/149
상위 Redmine 일감: #867
담당: 황수아
PM 및 검토: 문길래
협력: 조영우, 이상재
계획 기간: 2026-11-09 ~ 2026-11-20
선행 작업: PoC-01 기존 자산 조사, PoC-04 Source 조회·무결성 검증
2. 세부 작업¶
STEP 1. 기존 L2 설계 산출물 조사¶
다음과 같은 대표 자료를 우선 분석한다.
- 직병렬 계산서(PDF)
- 태양광 부하 계산서(XLSX)
- 전기분야 수량산출서(XLSM)
- 공사비내역서(XLSX)
- 기타 승인된 설계계산 및 수량 관련 자료
각 파일의 Source ID, SHA-256, Revision, 승인 상태와 접근 권한을 확인한다.
기존 Source Manifest에 등록되었다는 사실만으로 해당 문서를 최종 승인본으로 확정하지 않는다.
STEP 2. 기존 문서 분석 기능 확인¶
- PDF 표 및 텍스트 추출 관련 코드 조사
- Excel Workbook·Sheet·Cell 분석 기능 확인
- 기존 수량산출·BOQ 처리 코드 조사
- 데이터 출처 및 검증 Evidence 관리 방식 확인
- 재사용 가능한 기능과 신규 구현 필요 기능 구분
STEP 3. 설계계산서 정보 추출¶
설계계산서에서 분석 가능한 주요 항목을 추출한다.
- 태양광 모듈 사양
- 모듈 수량
- 직렬·병렬 연결 관련 값
- 전력용량 및 단위
- 인버터 관련 정보
- 계산식과 계산 결과
- 구역별 또는 설비별 계산 조건
문서에 실제로 존재하는 항목만 추출하며 확인되지 않은 값은 임의로 생성하지 않는다.
STEP 4. 수량산출서 및 BOQ 정보 추출¶
다음 항목을 구조화한다.
| 추출 항목 | 주요 내용 |
|---|---|
| 공종·품목 | 자재 또는 설비 구분 |
| 규격 | 모델, 크기, 용량 등의 정보 |
| 수량 | 산출된 품목 수량 |
| 단위 | EA, m, kW 등 |
| 단가 | 확인 가능한 자재·작업 단가 |
| 금액 | 품목별 금액 및 합계 |
| 산출 근거 | 계산식 또는 참조 셀 |
| 적용 범위 | 구역, 설비 및 집계 범위 |
소계·합계와 개별 품목 수량을 중복 집계하지 않도록 처리한다.
STEP 5. Excel 수식 및 데이터 검증¶
- Workbook 및 Sheet 구조 확인
- 데이터가 있는 Cell과 Range 탐색
- 원본 수식과 계산 결과 구분
- 수식의 Cached Value 확인
- 병합 셀 및 숨김 Sheet 처리
- 숫자·문자열·단위 해석
- 누락값과 오류값 구분
주의: Excel 수식 원문이 있다는 이유만으로 계산 결과가 검증되었다고 판단하지 않는다. 수식 캐시가 없거나 실제 계산 확인이 불가능하면 미검증으로 기록한다.
STEP 6. 데이터 표준화 및 출처 관리¶
추출 데이터를 공통 JSON 구조로 정리한다.
예상 산출물: document_observations.json
주요 필드:
- Source ID
- Source SHA-256 및 Revision
- 문서 유형
- Sheet / Cell / Page / Table Locator
- 품목 또는 설계 항목
- 원본 값
- 정규화 값
- 단위
- 계산식
- 적용 구역 및 범위
- 추출 상태
- 검증 상태 및 Warning
후속 PoC에서 원본 문서의 정확한 위치로 추적할 수 있도록 설계한다.
STEP 7. 오류 및 불확실성 처리¶
다음 상황을 구분한다.
- 파일 누락 또는 손상
- 지원하지 않는 파일 형식
- Excel 수식 캐시 누락
- PDF 표 추출 오류
- 단위 불명확
- 품목명 또는 규격 불일치
- 소계·합계의 중복 가능성
- 구역 및 집계 대상 불명확
- Source Revision 또는 최종 승인 상태 미확정
근거가 부족한 값은 REVIEW 또는 HOLD로 분류한다.
STEP 8. 자동 테스트 및 결과 검증¶
- 합성 PDF/Excel Golden Fixture 분석
- 표·셀·계산식 추출 결과 비교
- 단위 및 정규화 처리 검증
- 합계·중복 수량 처리 테스트
- 오류 및 누락 자료 처리 테스트
- Source 원본 SHA-256 변경 여부 확인
- 허가된 실제 L2 문서 분석 결과 검토
실제 문서의 추출 결과와 합성 데이터의 테스트 결과를 구분한다.
STEP 9. GitHub 반영 및 결과 제출¶
- 기존 문서 분석 코드 재사용 또는 확장
- 데이터 추출 모듈 및 JSON Schema 작성
- pytest 자동 테스트 작성
- 실제 실행 결과 및 Evidence 기록
- Windows PowerShell 실행 가이드 작성
- GitHub 작업 브랜치 및 PR 생성
- PM 검토 후 main 병합
3. 업무분장¶
| 담당자 | 역할 |
|---|---|
| 황수아 | 계산서·수량산출서·BOQ 분석 및 데이터 추출 구현 |
| 조영우 | 수량·단위·집계 범위 및 후속 L1 설계 연계 검토 |
| 이상재 | CAD 객체와 문서 데이터 간 참조 규격 협의 |
| 문길래 | 데이터 신뢰성·검증 기준 검토 및 PR 승인 |
4. 제출 산출물¶
- L2 설계계산서 주요 데이터 추출 기능
- 수량산출서·BOQ 항목 추출 기능
- Excel 수식 및 계산 결과 구분 기능
- PDF/Excel 출처 추적 구조
document_observations.json및 JSON Schema- 합성 Golden Fixture 및 pytest 테스트
- 실제 문서 분석 실행 Evidence
- 오류·불확실성 검증 보고서
- Windows 실행 가이드 및 GitHub PR
5. 완료 기준 (PASS)¶
- 기존 PDF/Excel/BOQ 분석 코드 및 재사용 자산 조사
- 설계계산서 주요 항목 추출
- 수량산출서의 품목·규격·수량·단위 추출
- BOQ 항목 및 금액 정보 추출
- Sheet·Cell·Page 등 정확한 출처 위치 기록
- Excel 수식과 Cached Value 구분
- 원본 값과 표준화 값을 분리하여 저장
- 단위·범위·집계 수준 불확실성 처리
- 누락·손상·형식 오류 처리 검증
- Source 원본 변경 없음
- 합성 Golden Fixture 테스트 PASS
- 허가된 실제 L2 자료 분석 결과 확인
-
document_observations.json및 Schema 작성 - PoC-09 연계 입력·출력 계약 작성
- GitHub PR 제출 및 PM 검토 완료
- main 병합 및 후속 PoC 연계 준비 완료
6. 개발 및 검증 원칙¶
- 기존 문서 분석 자산을 우선 재사용한다.
- 설계계산서와 수량산출서의 값이 다르더라도 즉시 설계 오류로 확정하지 않는다.
- 서로 다른 구역·집계 범위의 수량을 무조건 비교하지 않는다.
- Excel 수식과 계산 결과를 혼동하지 않는다.
- 미확인 값을 AI가 임의로 생성하거나 보정하지 않는다.
- 기존 Source 및 원본 문서를 수정하지 않는다.
- 고객 자료를 외부 클라우드에 업로드하지 않는다.
- Autodesk APS 및 유료 API를 사용하지 않는다.
- 모든 분석 결과에 검증 가능한 출처 정보를 유지한다.
7. GitHub 관련 문서¶
GitHub Issue
https://github.com/GilbertMoon/icn-solar-cad-agent/issues/149
25개 PoC 상세 로드맵
전체 업무계획서
업무분장 및 시스템 통합계획
8. 후속 개발 연계¶
다음 작업: PoC-09 — CAD 도면과 계산서·BOQ 간 Evidence 연결
PoC-07에서 생성한 CAD 모듈 배치 관찰 데이터와 PoC-08에서 생성한 설계계산서·수량산출서·BOQ 데이터를 연결한다.
동일한 장비 및 집계 범위로 확인된 항목만 비교하고, 설계 불일치 후보와 미확정 관계를 구분하여 검증한다.
수황 Updated by 수아 황 19 days ago
- Status changed from New to In Progress
[PoC-08 착수 / 2026-10-29]
[완료한 첫 작업]
- 기존 PDF/Excel 분석 및 Source gate 코드를 조사했습니다(고객 자료는 열거나 실행하지 않음).
- 공통 관찰 결과 형식(poc08.observations.v1), JSON Schema, 합성 기록 예시, Windows 실행 가이드를 작성했습니다.
- Source ID/SHA/Revision, 페이지·표 또는 시트·셀, 항목·원문 값·단위·구역·수식·저장 계산값을 분리합니다.
- 수식 캐시 누락은 null/HOLD, 동일 출처·위치·항목 중복은 HOLD로 남깁니다. 합계/소계 및 상세 행 모두 현 단계에서는 집계 불가이며, 숨김 시트·병합 셀·버전/단위/구역 미확인은 검토 경고로 표시합니다.
[검증 / 산출물]
- 합성 기록 단위 테스트: 29 passed. 예시 JSON 재검증 및 생성 Schema 일치 확인 완료.
- 로컬 브랜치: task/poc08-document-contract-20261029
- 로컬 커밋: 2ce9311 (기준 main: efd8b502525a1741b8568b0f862ab6f392009392)
- 주요 파일: src/solar_mcp/documents/observations.py, tests/test_poc08_observations.py
- 실행/조사 기록: pocs/poc_08_document_observations/README.md
- 예시/Schema: 같은 폴더의 examples/document_observations.json 및 document_observations.schema.json
- 테스트 기록: 같은 폴더의 contract-tests.junit.xml
- 현재 로컬 커밋 단계로, 원격 push/PR 제출/PM 검토/병합은 아직 진행하지 않았습니다.
[범위 / 남은 일]
- 이번 검증은 합성 기록의 결과 형식과 보수적 검토 규칙에 한정합니다. 실제 PDF/XLSX/XLSM 파서 연결, 합성 파일 추출, 실제 읽은 바이트의 SHA 검증·원본 불변 검증을 완료했다는 의미는 아닙니다.
- 고객 CAD/Source 보안 승인 전까지 SYNTHETIC_ONLY, R01=NOT_RUN 유지. SHA가 64자리 0인 예시는 파일 없는 합성 기록의 표식이며 실제 무결성 검증 근거가 아닙니다.
- 다음: 합성 엑셀을 Source ID gate로 읽어 수식/캐시를 분리하는 경로 연결 → 누락·손상·숨김·병합·오류·외부 참조 및 SHA 불변 검증 → PDF 추출/PoC-09 계약/PR 검토.
실제 코드 작업에 착수하여 상태를 In Progress로 변경합니다. 완료율 산정 근거가 아직 없어 진척률은 0%로 유지하며, 기존 담당자·계획일·완료 조건은 유지합니다.
수황 Updated by 수아 황 17 days ago
게시일 2026-10-31 / 아래는 2026-10-29 완료한 검증 결과의 지연 기록입니다.
[PoC-08 합성 XLSX/XLSM 읽기 구현·검증 / 2026-10-29]
[완료한 범위]
- 기존 T9 Excel 어댑터의 수식/캐시 분류 함수를 documents/cells.py로 분리하여 재사용했습니다. 기존 스크립트도 같은 함수를 호출하며, 고객 자료 예제는 실행하지 않았습니다.
- PoC-05 SourceResolver의 합성 Source ID·권한·허용 경로 gate와 SHA 검사를 적용한 명시적 셀 읽기 경로를 구현했습니다.
- 같은 바이트 스냅샷에서 수식/캐시를 분리하고 숫자·문자·빈칸·오류·불리언을 구분합니다. 캐시 누락은 null/HOLD이며 실제 0/false는 보존합니다.
- hidden/veryHidden 시트, 병합 범위와 자식 셀, 외부 참조/링크 부품, VBA 부품 존재를 표시합니다. 외부 참조는 HOLD이며 외부 파일을 가져오지 않습니다. 매크로 실행·수식 재계산·원본 저장을 하지 않습니다.
- 소계/합계 제외 경고, 중복 출처·위치·항목 HOLD를 적용했습니다. 상세/소계/합계 구분은 명시적 매핑이며 자동 판별한 사실이 아닙니다. 모든 관찰은 현 단계에서 집계 불가입니다.
- 허용되지 않은 ID/접근/고객 자료/경로 이탈/파일 누락/읽기 거부/잘못된 SHA/지원 불가·손상·빈 파일/형식 MIME 불일치를 거부합니다. ZIP/XML 자원 제한과 DTD·ENTITY 차단도 확인했습니다.
- 파싱 후 gate와 원본 SHA를 다시 확인하며, 읽는 중 파일 변경 시 결과 전체를 차단합니다.
[검증 근거]
- 코드 커밋: ec66668a46c0d079fd7d0964e4c3f11590b6a9b9 (로컬)
- 브랜치: task/poc08-document-contract-20261029 (원격 push/PR 미진행)
- 최종 검증: 91 passed, failures=0, errors=0, skipped=0.
- 직접 선언한 18개 셀 기대값을 XLSX/XLSM 각각 비교했습니다. 숫자·문자·빈칸·오류·수식 캐시/누락/0/false·합계·외부 참조·병합·숨김 상태를 포함합니다.
- 합성 입력 SHA 전후 동일:
- XLSX: d644601b3b0acdf80986f5405ad45536229fad58ce82a42cce600c5239600da9
- XLSM: 36fbd9bae92dc9249353f0b09dda262e0e6461298ca59898558f0bfb637aa699
- 추가 Source gate 회귀 확인: 93 passed, 1 skipped (위 91개와 기존 source 테스트 포함; Windows 심볼릭 링크 생성 권한 관련 1개 제외). 최종 PoC-08 증빙 실행 자체는 91개 모두 통과/제외 없음.
- 주요 코드: src/solar_mcp/documents/workbooks.py, cells.py
- 테스트: tests/test_poc08_workbooks.py, test_poc08_observations.py
- 합성 입력/독립 기대값: pocs/poc_08_document_observations/fixtures/
- 실행 가이드: pocs/poc_08_document_observations/WORKBOOK_READER.md
- 로컬 증빙 폴더: outputs/poc08_workbook_evidence_20261029 (ai_project_expert_kit 기준; 원격 공유 경로 아님)
- 증빙: document_observations.json, syn-xlsx.json, syn-xlsm.json, Schema 2개, junit.xml, pytest.txt, result.json.
[제한 / 남은 작업]
- SYNTHETIC_ONLY / R01=NOT_RUN 유지. 고객 CAD/Source 자료는 사용하지 않았습니다.
- 합성 캐시는 OOXML에 선언한 상수이며 실제 Excel 재계산 증거가 아닙니다. XLSM 정상 입력에는 VBA 코드가 없고, VBA 부품 존재 테스트는 실행 불가능한 합성 sentinel로 수행했습니다. 실제 매크로 호환성을 확인한 결과가 아닙니다.
- 현재는 명시적으로 지정한 셀과 검토 전 매핑을 읽는 단계입니다. 일반 계산서·수량산출서·BOQ 자동 항목/규격/단위/구역/집계 판별은 미완료입니다.
- 다음: 합성 PDF 추출 연결 → 항목/범위/PoC-09 계약 협의 → 검토용 PR/PM 검토/병합. 운영 Source registry 통합과 고객 자료 Gate는 별도입니다.
- 상태 In Progress, 진척률 0% 유지 요청. 완료율·Closed 변경 없음.
수황 Updated by 수아 황 14 days ago
[2026-11-03 기존 PoC-08 합성 XLSX/XLSM 재검증]
기존 작업 폴더 outputs/poc08_work의 verify_poc08_workbooks.py를 새 실행 환경에서 직접 실행했습니다. 결과: 91 tests / failures=0 / errors=0 / skipped=0, passed=true, input_unchanged=true, R01=NOT_RUN. 기존 구현의 합성 엑셀 추출·계약 검사 재현이며 신규 PDF 구현이나 실제 고객 자료 분석 결과가 아닙니다.
증빙 로컬 위치: C:/Users/hjmo-/.codex/visualizations/2026/11/03/01a19fd0-fe53-7ec0-aed7-74e2d5eac393/poc08-recheck (공유 URL 아님).
SYNTHETIC_ONLY 유지. 남은 작업: 합성 PDF 추출 연결, 항목/범위 및 PoC-09 계약, 검토용 PR. 일반 BOQ 자동 판별·실제 Excel 재계산·운영 Registry 연계·고객 자료 검증은 미완료입니다. 상태·진척률·담당·일정은 변경하지 않습니다.
수황 Updated by 수아 황 14 days ago
[2026-11-03 합성 PDF 읽기 구현 및 검토용 PR 제출]
PR: https://github.com/GilbertMoon/icn-solar-cad-agent/pull/209 (Draft·미병합)
PDF 텍스트 단어와 선으로 구획된 표 셀을 읽고 페이지·좌표·표/행/열 위치를 기록합니다. 기존 Excel과 공통 관찰 계약을 재사용하며, 빈칸/텍스트 없는 페이지는 null/HOLD, 나머지도 REVIEW·집계 불가입니다.
검증 코드 SHA 992184e0d870806355b78ee63f4d2ad25a8a65e1의 깨끗한 트리에서 106 PASS / 0 FAIL / 0 SKIP (PDF 15 + 기존 Excel/계약 91). 합성 PDF SHA 전후 동일, 렌더 이미지 육안 확인 완료. 증빙 커밋 9b54ba6의 pocs/poc_08_document_observations/pdf-evidence에 연습 PDF, 독립 기대값, 출력 JSON/schema, JUnit, 로그·환경을 기록했습니다.
SYNTHETIC_ONLY / R01=NOT_RUN. 고객 자료 미사용. OCR, 일반 BOQ 의미 자동 판별, 복잡한 무테/병합/회전 표, 운영 Registry/MCP 연결, 실제 Excel 재계산 및 고객 자료 검증은 미완료입니다. Python 어댑터이며 새 MCP endpoint는 추가하지 않았습니다.
실행 가이드: pocs/poc_08_document_observations/PDF_READER.md. 이번 요청 범위 구현·검증 및 PR 준비 완료이며 #875 전체 완료가 아닙니다. 상태·진척률·일정 변경 없음. 다음은 PR 검토·PoC-09 계약/일반 항목 해석 협의입니다.