Feature #911
openFeature #866: [MASTER] ICN Solar CAD Agent — Autodesk MCP 및 L2→L1 태양광 자동설계 시스템 구축
Feature #867: Phase 1 — MCP 기반 태양광 CAD 자동설계 플랫폼 구축 및 통합 검증
[INT-06] Validation & Reporting — CAD·수량·Knowledge Evidence 통합 검증
0%
Description
INT-06. Validation & Reporting — CAD·수량·Knowledge Evidence 통합 검증¶
1. 작업 개요¶
본 작업은 ICN Solar CAD Agent에서 생성한 신규 L1 태양광 자동설계 결과를 Geometry, CAD Entity, 패널 수량, BOQ, Engineering Knowledge 및 Evidence 관점에서 종합 검증하고 사용자·관리자용 보고서를 생성하는 기능을 통합하는 작업이다.
PoC-17~22의 Solver·도면·수량·QA 기능과 INT-05의 CAD Backend Adapter를 활용한다.
핵심 목표는 각 검증 단계의 결과를 일관된 기준으로 통합하고, 검증하지 못한 항목을 PASS로 표시하지 않으며, 문제가 발생했을 때 원인·출처·담당자 및 후속 조치를 명확히 제공하는 것이다.
GitHub Issue: https://github.com/GilbertMoon/icn-solar-cad-agent/issues/172
상위 Redmine 일감: #867
담당: 조영우
PM 및 검토: 문길래
협력: 이상재, 황수아
계획 기간: 2027-02-17 ~ 2027-02-23
선행 작업: INT-01, INT-03, INT-05 및 관련 PoC
2. 세부 작업¶
STEP 1. 기존 Validation 및 Reporting 기능 조사¶
- PoC-17~18 Solver Geometry Validator 확인
- PoC-19 DXF 객체·좌표 검증 기능 확인
- PoC-20 Authorized Delta 검증 기능 확인
- PoC-21 수량·BOQ 영향 분석 기능 확인
- PoC-22 CAD 정량·시각 QA 결과 확인
- PoC-12/16 Engineering Knowledge 승인·적용성 검증 확인
- INT-05 CAD Backend 검증 결과 확인
- 기존 기능의 REUSE / EXTEND / NEW / HOLD 분류
STEP 2. 통합 Validation Gate 정의¶
다음 검증 영역을 구성한다.
| 검증 Gate | 검증 내용 |
|---|---|
| SOURCE | Source 접근권한·SHA·Revision |
| KNOWLEDGE | 승인 규칙·Version·적용 범위 |
| SITE_GEOMETRY | 경계·좌표계·단위 |
| PLACEMENT | 모듈 좌표·간격·간섭 |
| CAD_ENTITY | Layer·Block·Entity·Audit |
| AUTHORIZED_DELTA | 원본 보존 및 허용된 변경 |
| QUANTITY_BOQ | 모듈 수량·BOQ 정합성 |
| VISUAL_QA | DWG/PDF 렌더링 및 도면 표현 |
| SECURITY_COST | 외부 전송·API 비용 승인 |
각 Gate의 PASS 조건, 실패 조건, 미확정 상태 및 Evidence를 정의한다.
STEP 3. 공통 Validation Result 데이터 모델 정의¶
각 검증 결과에 다음 정보를 포함한다.
- Validation ID
- Run ID
- Gate ID
- Source ID / SHA-256 / Revision
- Layout Candidate ID
- Applied Rule ID / Version
- Expected Value
- Observed Value
- Validation Tolerance
- Validation Status
- Evidence Locator
- Reviewer
- Validation Timestamp
- Error / Warning
- Recommended Action
STEP 4. Geometry 및 자동배치 검증 통합¶
- Site Boundary 유효성
- 좌표계 및 단위 일치
- 모듈 Footprint의 설치 후보 영역 포함 여부
- 모듈 간 중복·충돌
- 장애물 및 설치 제외영역 침범
- 이격거리 및 배치 간격 준수
- 모듈 Rotation 유효성
- Solver와 DXF 좌표 정합성
- Geometry 허용오차 적용
STEP 5. CAD Entity 및 원본 보존 검증 통합¶
- DXF 재열기 및 Audit
- Layer·Block·Entity 수량 검증
- 모듈 객체 수와 Solver 결과 비교
- CAD 좌표·치수·회전각 비교
- Controlled Blank 원본 SHA 불변
- 보호된 기존 CAD 객체 보존
- Authorized Delta 허용 범위 검증
- 승인되지 않은 변경사항 0건 확인
STEP 6. 패널 수량 및 BOQ 검증 통합¶
- Solver 모듈 수량 집계
- DXF 모듈 객체 수 비교
- Authorized Delta 적용 수량 비교
- Baseline 대비 수량 증감 확인
- Zone·ModuleSpec별 집계
- BOQ 관련 품목과 수량 비교
- Source Revision·단위·집계 범위 확인
- 검증 불가능한 금액·수량 구분
단가와 비용의 근거가 없으면 금액을 임의로 생성하지 않는다.
STEP 7. Engineering Knowledge Evidence 검증¶
다음 정보를 확인한다.
- Rule ID 및 Version
- 승인 상태 및 승인자
- Human Approval Evidence
- Source 및 Revision
- 적용 가능한 사이트 조건
- 적용된 설계 파라미터
- 반례 및 검증 이력
- 철회·대체된 규칙 여부
- 신규 L1 사이트 적용성
승인되지 않았거나 적용 조건이 맞지 않는 규칙은 PASS로 표시하지 않는다.
STEP 8. DWG/PDF 시각 QA 결과 통합¶
- DWG/PDF 변환 결과 확인
- 실제 렌더링 및 Viewer 검증 상태 조회
- 객체 누락 및 잘림 여부
- 선·Layer·Text·Annotation 표시 검토
- 도면 전체 및 주요 구역 확인
- 시각 QA Evidence 연결
- 미실행 또는 미확정 상태 표시
실제 시각 검증을 수행하지 않았다면 VISUAL_PENDING으로 기록한다.
STEP 9. 통합 QA 상태 및 판정 로직 정의¶
다음 상태를 사용한다.
- PASS
- FAIL
- HOLD
- NEEDS_REVIEW
- VISUAL_PENDING
- NOT_APPLICABLE
통합 PASS 기준
- 필수 Gate 모두 PASS
- Source 및 Rule 근거 확인
- CAD Geometry·Entity 검증 통과
- Authorized Delta 위반 없음
- 수량 및 BOQ 검증 기준 충족
- 필수 시각 검증 완료
- 필수 Evidence 확보
필수 Gate 중 하나라도 미확정이면 전체 PASS를 선언하지 않는다.
STEP 10. 통합 Validation Report 구현¶
예상 산출물: integrated_validation_report.json
주요 필드:
- Report ID
- Run ID
- Site ID
- Layout Candidate ID
- Source SHA / Revision
- Applied Rule IDs / Versions
- Geometry Validation
- CAD Entity Validation
- Authorized Delta Validation
- Quantity / BOQ Validation
- Knowledge Evidence Validation
- Visual QA Validation
- Security / Cost Gate
- Overall Status
- Warning / HOLD
- Evidence Reference
- Recommended Actions
STEP 11. 사용자·관리자 보고서 구현¶
JSON 보고서를 기반으로 사람이 읽을 수 있는 Markdown 또는 HTML 요약 보고서를 생성한다.
사용자 보고서
- 설계 대상 사이트
- 사용한 모듈 및 규칙
- 배치된 패널 수량
- 생성된 CAD 도면
- 검증 통과 및 미확정 항목
- 검토가 필요한 문제
관리자 보고서
- 단계별 검증 결과
- Source·Rule·Candidate Version
- Geometry 및 CAD 불일치
- BOQ 차이
- HOLD 및 오류 사유
- 담당자 및 후속 조치
- Evidence Locator
STEP 12. 자동 테스트 및 Golden Fixture¶
다음 사례를 검증한다.
- 정상 전체 PASS
- 승인되지 않은 Knowledge
- 철회된 Engineering Rule
- 모듈 간 겹침
- 설치 제외영역 침범
- DXF Entity 누락
- Solver·DXF 수량 불일치
- Unauthorized Delta
- BOQ 비교 범위 불일치
- DWG/PDF 시각 검증 미완료
- Source Evidence 누락
- JSON Schema 불일치
- 모듈 0개 배치
- Source Revision 불일치
미검증 항목에 대해 잘못된 PASS가 발생하지 않는지 집중적으로 검증한다.
STEP 13. 통합 테스트 및 Evidence 작성¶
- pytest 자동 테스트 실행
- 실제 구현된 모듈과 Mock 결과 구분
- Golden Fixture 검증 Evidence 작성
- Source SHA 및 Rule Version 추적
- 보고서 JSON과 HTML/Markdown 내용 일치 확인
- 미해결 결함·HOLD 항목 분류
- Windows PowerShell 재현 가이드 작성
STEP 14. GitHub 반영 및 결과 제출¶
- 통합 Validation 모듈 작성
- 보고서 JSON Schema 작성
- Markdown/HTML 보고서 생성 기능
- Evidence Crosswalk 작성
- Golden Fixture 및 pytest 테스트
- 실행 결과와 미완료 항목 기록
- GitHub 작업 브랜치 및 PR 생성
- 개발자 3명 교차검토
- PM 검토 후 main 병합
- INT-07에 사용자·관리자 조회 계약 인계
3. 업무분장¶
| 담당자 | 역할 |
|---|---|
| 조영우 | Geometry·수량·BOQ 검증 및 통합 보고서 구현 |
| 이상재 | CAD Entity·DXF Audit·Authorized Delta·DWG/PDF QA 연계 |
| 황수아 | Engineering Knowledge 승인·Source·BOQ Evidence 검증 |
| 문길래 | Validation Gate·품질 기준·최종 보고서 및 PR 검토 |
4. 제출 산출물¶
- 통합 Validation Gate 및 판정 정책
- Geometry·CAD·Quantity·Knowledge 검증 연결 기능
integrated_validation_report.json- 통합 보고서 JSON Schema
- 사용자용 Markdown/HTML 보고서
- 관리자용 상세 QA 보고서
- Evidence Crosswalk
- HOLD·FAIL·REVIEW 및 후속 조치 목록
- Golden Fixture 및 pytest 결과
- 실행 Evidence와 Windows 재현 가이드
- INT-07 조회 데이터 계약
- GitHub PR 및 PM 검토 결과
5. 완료 기준 (PASS)¶
- 기존 QA 및 Reporting 기능 재사용 범위 확인
- 통합 Validation Gate 정의
- 공통 Validation Result Schema 작성
- Geometry·Placement 검증 통합
- CAD Entity 및 DXF Audit 연계
- Authorized Delta 및 원본 보존 검증
- Solver·DXF·Delta 수량 정합성 확인
- BOQ 비교 범위·단위·Revision 검증
- Approved Knowledge·Evidence 연결
- 실제 DWG/PDF 시각 QA 결과 연결
- PASS/FAIL/HOLD/REVIEW/VISUAL_PENDING 상태 처리
- 필수 검증 미완료 시 false PASS 0건
- JSON 및 Markdown/HTML 보고서 생성
- 보고서와 원본 검증 데이터 정합성 확인
- Golden Fixture 및 자동 테스트 PASS
- Source·Rule·Run ID·Evidence 추적
- 담당자별 교차검토 완료
- GitHub PR 제출 및 PM 승인
- main 병합 및 INT-07 인계 완료
6. 개발 및 검증 원칙¶
- 검증하지 않은 항목을 PASS로 처리하지 않는다.
- 승인되지 않은 Knowledge를 적용하지 않는다.
- Source·Rule·Candidate의 Revision과 Evidence를 보존한다.
- Geometry 오류나 수량 불일치를 임의로 숨기지 않는다.
- 실제 DWG/PDF 시각 검증 없이 시각 QA PASS를 선언하지 않는다.
- 승인되지 않은 CAD 변경을 허용하지 않는다.
- 원본 CAD 및 설계자료를 변경하지 않는다.
- 근거 없는 비용·수량을 생성하지 않는다.
- 고객자료를 승인 없이 외부로 전송하지 않는다.
- 승인 없는 Autodesk APS 유료 호출을 수행하지 않는다.
- 기술 QA PASS를 최종 설계 전문가 승인으로 간주하지 않는다.
7. 참고 문서¶
GitHub Issue
https://github.com/GilbertMoon/icn-solar-cad-agent/issues/172
전체 통합 계획
INT-05 CAD Backend Adapters
https://github.com/GilbertMoon/icn-solar-cad-agent/issues/171
PoC-25 End-to-End 통합
https://github.com/GilbertMoon/icn-solar-cad-agent/issues/166
8. 후속 작업¶
INT-07 — User Workflow / Admin
INT-06의 통합 검증 결과를 사용자가 쉽게 확인할 수 있도록 실행 상태, 오류, 승인대기, CAD 도면 파일, Evidence 및 Knowledge 버전 조회 기능을 구현한다.
사용자 화면과 관리자 화면에서는 자동설계 기술 검증 결과와 실제 설계 전문가 승인 상태를 명확히 구분한다.