Feature #910
openFeature #866: [MASTER] ICN Solar CAD Agent — Autodesk MCP 및 L2→L1 태양광 자동설계 시스템 구축
Feature #867: Phase 1 — MCP 기반 태양광 CAD 자동설계 플랫폼 구축 및 통합 검증
[INT-05] CAD Backend Adapters — 로컬 DXF·선택적 APS/변환기 통합
0%
Description
INT-05. CAD Backend Adapters — 로컬 DXF·선택적 APS/변환기 통합¶
1. 작업 개요¶
본 작업은 ICN Solar CAD Agent에서 사용하는 CAD 처리 엔진을 공통 인터페이스로 통합하는 작업이다.
로컬 Python·ezdxf 기반 CAD 엔진을 기본 백엔드로 사용하고, Autodesk Platform Services(APS)와 로컬 DWG/PDF 변환기는 필요한 기능과 보안·비용 승인 조건에 따라 선택적으로 사용할 수 있도록 설계한다.
목표는 MCP 서버 및 설계 Workflow가 개별 CAD 엔진의 구현 방식에 직접 의존하지 않고, 동일한 입력·출력 계약을 통해 도면 생성과 검증을 수행하도록 하는 것이다.
GitHub Issue: https://github.com/GilbertMoon/icn-solar-cad-agent/issues/171
상위 Redmine 일감: #867
담당: 이상재
PM 및 검토: 문길래
협력: 조영우, 황수아
계획 기간: 2027-02-15 ~ 2027-02-19
선행 작업: PoC-05/06/19/20/22/23/24, INT-01
2. 세부 작업¶
STEP 1. 기존 CAD 처리 기능 조사¶
- Python·ezdxf DXF Reader/Writer 확인
- CAD Layer·Block·Entity 분석 기능 확인
- DXF Candidate 생성 기능 확인
- DXF Audit 및 Geometry Validator 확인
- 기존 Authorized Delta 처리 기능 검토
- DWG/PDF 변환 및 시각화 도구 확인
- Autodesk APS PoC-23/24 검증 결과 확인
- REUSE / EXTEND / NEW / HOLD 분류
STEP 2. CAD Backend 공통 Interface 설계¶
다음 기능을 표준화한다.
| 인터페이스 기능 | 설명 |
|---|---|
| Inspect / Read | CAD 구조 및 Geometry 조회 |
| Generate Candidate | 신규 배치 Candidate DXF 생성 |
| Validate | CAD 구조·좌표·수량 검증 |
| Convert / Render | 지원되는 경우 DWG/PDF 변환·렌더링 |
| Capabilities | 엔진별 지원 기능 조회 |
| Health / Status | 백엔드 사용 가능 여부 및 오류 상태 |
각 기능은 공통 요청·응답 형식을 사용하며, 지원되지 않는 기능은 명확하게 반환한다.
STEP 3. 공통 입력·출력 JSON Schema 정의¶
입력 항목
- Run ID / Request ID
- Source ID / SHA-256 / Revision
- Layout Candidate ID
- 적용 Rule ID / Version
- CAD 좌표계·단위
- 요청 작업
- 대상 CAD Backend
- 출력 형식
- 승인 및 보안 정책
출력 항목
- Backend ID / Version
- 실행 상태
- Candidate DXF 경로 및 SHA
- 생성된 Entity 및 Module 수
- Geometry Validation Status
- CAD Audit Status
- Rendering Status
- Error Code
- Evidence Locator
- Warning / HOLD Reason
STEP 4. LocalDXFBackend 구현¶
기본 백엔드는 Python·ezdxf를 활용한다.
- DXF 읽기
- Layer·Block·Entity 분석
- Module Position/Footprint 변환
- 신규 Candidate DXF 생성
- DXF 재열기 및 Audit
- 모듈 수량·좌표·Rotation 검증
- Source 및 Controlled Blank 원본 불변 확인
- 검증 결과 Manifest 작성
LocalDXFBackend는 필수 기능으로 정의한다.
STEP 5. APSBackend 선택적 연계¶
PoC-23/24에서 확인된 API만 대상으로 한다.
- APS 인증 및 Scope 확인
- 지원되는 CAD API 기능 조회
- API 비용 및 사용량 Gate 확인
- 고객자료 외부 전송 승인 확인
- 승인된 합성 테스트 자료 처리
- API 결과를 공통 Schema로 변환
- 인증·호출·비용 오류 처리
- 선택적 사용 및 비활성화 설정
APS 기능이 필요하지 않거나 승인 조건을 충족하지 못하면 로컬 백엔드로 처리하거나 HOLD한다.
비승인 고객자료 업로드 및 유료 API 호출은 금지한다.
STEP 6. CAD Converter / Renderer Adapter 검토¶
로컬에서 허용되는 CAD 변환 도구가 있는 경우 공통 Adapter를 정의한다.
- DXF → DWG 변환 가능 여부 확인
- DXF/DWG → PDF 출력
- CAD Renderer 실행
- 출력 파일 생성 및 SHA 기록
- 변환 전후 객체 및 Geometry 검증
- 시각 QA 결과 연결
- 도구 미설치·라이선스 문제 처리
시각 검증을 수행할 수 없는 경우 VISUAL_PENDING으로 반환한다.
STEP 7. Backend 선택 및 Fallback 정책 정의¶
기본 정책:
- LocalDXFBackend 우선 사용
- 요청 기능이 로컬에서 지원되는지 확인
- 미지원 기능은 승인된 대체 Backend 검토
- APS 사용 시 인증·비용·보안 Gate 확인
- Backend 장애 시 허용된 대체 경로 선택
- 대체 경로가 없으면 HOLD
- Backend 선택과 실행 근거 기록
Fallback을 위해 승인 Gate를 우회하지 않는다.
STEP 8. 오류 및 상태 코드 표준화¶
주요 상태:
- PASS
- FAIL
- HOLD
- NOT_SUPPORTED
- NOT_CONFIGURED
- BACKEND_UNAVAILABLE
- UNSUPPORTED_FORMAT
- MISSING_APPROVAL
- INVALID_SOURCE
- UNKNOWN_UNITS
- AUDIT_FAIL
- VISUAL_PENDING
상태 코드와 오류 메시지는 MCP Client에 일관되게 전달되어야 한다.
STEP 9. CAD Backend 검증 테스트¶
다음 테스트를 수행한다.
- 정상 DXF 읽기
- 정상 Candidate DXF 생성
- 사각형 및 부정형 Site
- 회전된 모듈
- 복수 Layer·Block 구조
- 모듈 0개 배치
- 좌표계·단위 미확정
- Source Revision 불일치
- 미승인 Authorized Delta
- APS 인증 미설정
- 승인되지 않은 외부 전송 요청
- Converter 사용 불가
- DXF Audit 실패
- Backend 실행 장애 및 Fallback
STEP 10. 기능 지원 Matrix 작성¶
예상 산출물: backend_capability_matrix.csv
포함 항목:
- Backend 이름 및 Version
- CAD 입력 형식
- CAD 출력 형식
- DXF Reader 지원
- DXF Writer 지원
- DWG 변환 지원 여부
- PDF 렌더링 지원 여부
- 승인 및 비용 조건
- 보안 요구사항
- 테스트 결과
- 제한사항
STEP 11. 검증 및 운영 정책 문서 작성¶
예상 산출물:
cad_backend_interface.mdbackend_capability_matrix.csvbackend_selection_policy.mdcad_backend_validation_report.md
실제 경로는 저장소 구조에 맞춰 결정한다.
STEP 12. GitHub 반영 및 결과 제출¶
- CAD Backend 공통 인터페이스 구현
- LocalDXFBackend 연결
- 선택적 APS/Converter Adapter 구현 또는 조건부 계약 작성
- 공통 JSON Schema 작성
- Golden Fixture 및 pytest 테스트
- 실제 DXF 생성·검증 Evidence 기록
- Windows PowerShell 실행 가이드 작성
- GitHub 작업 브랜치 및 PR 생성
- PM 검토 후 main 병합
3. 업무분장¶
| 담당자 | 역할 |
|---|---|
| 이상재 | CAD Backend 인터페이스 및 Local/APS/Converter Adapter 개발 |
| 조영우 | Solver Layout Candidate 입력 및 Geometry 결과 검증 |
| 황수아 | Source·Knowledge Provenance 및 데이터 접근 정책 검토 |
| 문길래 | 백엔드 선택·비용·보안 정책 및 GitHub PR 최종 검토 |
4. 제출 산출물¶
- CAD Backend 공통 인터페이스
- LocalDXFBackend 필수 구현
- 선택적 APSBackend 계약 또는 승인된 연결 구현
- CAD Converter/Renderer Adapter
- 공통 입력·출력 JSON Schema
- Backend Capability Matrix
- Backend 선택 및 Fallback 정책
- CAD 구조·Geometry·수량 검증 결과
- Golden Fixture 및 pytest 테스트
- 실행 Evidence 및 기술 검증 보고서
- Windows 실행 가이드 및 GitHub PR
5. 완료 기준 (PASS)¶
- 기존 CAD 처리 엔진 및 코드 재사용 범위 확인
- 공통 CAD Backend 인터페이스 정의
- LocalDXFBackend 필수 기능 연결
- DXF 생성 및 재열기 Audit PASS
- 모듈 좌표·Footprint·Rotation 검증
- 원본 Source SHA 및 CAD 객체 보존
- APS/Converter 사용 가능 범위 확인
- 선택적 Backend의 공통 Schema 호환성 검증
- Backend 선택 및 Fallback 정책 정의
- 미지원 기능은 NOT_SUPPORTED로 구분
- 미승인 API 호출 및 외부 전송 차단
- CAD Backend 오류·HOLD 처리
- Golden Fixture 및 계약 테스트 PASS
- 실행 Provenance 및 Evidence 기록
- INT-06 연계 입력·출력 계약 작성
- GitHub PR 제출 및 PM 검토 완료
- main 병합 및 후속 작업 인계 완료
6. 개발 및 검증 원칙¶
- 로컬 DXF 백엔드를 기본 경로로 유지한다.
- Autodesk APS 사용을 필수로 강제하지 않는다.
- 실제 API 미검증 상태를 연동 성공으로 표시하지 않는다.
- CAD 엔진별 지원 기능 차이를 명확히 표시한다.
- 원본 CAD를 변경하거나 덮어쓰지 않는다.
- 비승인 Authorized Delta를 적용하지 않는다.
- 고객자료를 승인 없이 외부 클라우드로 전송하지 않는다.
- PM 승인 없는 유료 API 호출을 수행하지 않는다.
- 시각 검증 미완료 상태를 PASS로 표시하지 않는다.
- 기술 검증 PASS와 설계 전문가의 최종 승인을 구분한다.
7. 참고 문서¶
GitHub Issue
https://github.com/GilbertMoon/icn-solar-cad-agent/issues/171
전체 통합 계획
PoC-22 CAD 품질 검증
https://github.com/GilbertMoon/icn-solar-cad-agent/issues/163
PoC-23 APS 보안·비용 검증
https://github.com/GilbertMoon/icn-solar-cad-agent/issues/164
PoC-24 CAD 엔진 비교
https://github.com/GilbertMoon/icn-solar-cad-agent/issues/165
8. 후속 작업¶
INT-06 — Validation & Reporting 통합
INT-05에서 표준화한 CAD Backend 결과를 기반으로 Geometry·CAD Entity·수량·BOQ·Knowledge Evidence를 통합 검증하고, 사용자 및 관리자용 품질 보고서를 생성한다.