Feature #906
openFeature #866: [MASTER] ICN Solar CAD Agent — Autodesk MCP 및 L2→L1 태양광 자동설계 시스템 구축
Feature #867: Phase 1 — MCP 기반 태양광 CAD 자동설계 플랫폼 구축 및 통합 검증
[INT-01] 통합 계약 및 인터페이스 검증
0%
Description
INT-01. 통합 계약 및 인터페이스 검증¶
1. 작업 개요¶
본 작업은 PoC-01~25에서 구현한 L2 Source 분석, Engineering Knowledge, 신규 L1 사이트 분석, 태양광 패널 자동배치, CAD 도면 생성 및 QA 기능을 하나의 플랫폼으로 연결하기 위해 모듈 간 데이터 구조, 인터페이스, 오류 처리 및 승인 정책을 검증하는 통합 작업이다.
각 개발자가 독립적으로 구현한 기능이 올바른 입력을 받고, 일관된 형식의 결과를 반환하며, 오류 또는 미승인 상태가 발생했을 때 다음 단계로 잘못 전달되지 않도록 검증한다.
GitHub Issue: https://github.com/GilbertMoon/icn-solar-cad-agent/issues/167
상위 Redmine 일감: #867
총괄 담당: 문길래
공동 수행: 황수아, 이상재, 조영우
계획 기간: 2027-02-01 ~ 2027-02-04
선행 작업: PoC-25 및 관련 PoC 결과
2. 세부 작업¶
STEP 1. 기존 PoC 산출물 및 인터페이스 조사¶
- PoC-01~25 개발 결과 조사
- 실제 코드 및 JSON Schema 확인
- MCP Tool 입력·출력 구조 조사
- Source 및 Knowledge 데이터 계약 확인
- Solver 및 DXF Writer 데이터 계약 확인
- CAD QA 및 보고서 출력 구조 확인
- 구현 완료·부분 완료·미구현·HOLD 상태 구분
STEP 2. 모듈 간 인터페이스 매트릭스 작성¶
| 생산 모듈 | 소비 모듈 | 주요 데이터 |
|---|---|---|
| Source Manager | CAD/문서 Reader | Source ID·SHA·Revision |
| CAD/BOQ Analyzer | Knowledge Extractor | Observation·Evidence |
| Knowledge Registry | Applicability Gate | Approved Rule·Version |
| L1 Site Analyzer | Solver | Site Geometry |
| Constraints Analyzer | Solver | Exclusion·Setback |
| ModuleSpec Manager | Solver | 모듈 규격·배치 파라미터 |
| Solver | DXF Writer | Module Position·Footprint |
| DXF Writer | Delta Validator | DXF Candidate |
| Delta Validator | Quantity/QA | Delta Manifest·Diff |
| Quantity Analyzer | Report | 수량·BOQ 영향 |
| QA Validator | MCP Client | 검증 결과·Evidence |
각 인터페이스의 입력·출력, 필수값, 형식, 버전 및 담당자를 기록한다.
STEP 3. 공통 데이터 Envelope 정의¶
예상 산출물: e2e-envelope.schema.json
주요 필드:
- Run ID
- Request ID
- Tool ID / Version
- Schema Version
- Source ID / SHA-256 / Revision
- Rule ID / Version
- Input / Output Reference
- Validation Status
- Evidence Locator
- Warning 및 Error
- Execution Timestamp
- Stage Status
전체 처리 흐름에서 데이터의 출처와 검증 상태를 일관되게 추적한다.
STEP 4. JSON Schema 및 버전 호환성 검증¶
- 필수 필드 및 선택 필드 확인
- 데이터 타입 및 단위 통일
- 좌표계·Geometry 표현 방식 확인
- Schema Version 관리
- 기존 버전과 신규 버전의 호환성 검증
- 잘못된 필드 및 누락값 처리
- 지원하지 않는 버전의 입력 차단
STEP 5. 승인 및 보안 Gate 연결¶
- Source 접근 권한 검증
- Source Revision 및 SHA 확인
- Engineering Knowledge 승인 상태 확인
- 규칙 적용 가능성 확인
- Authorized Delta 승인 범위 확인
- 외부 API 호출 승인 여부 확인
- 필수 Gate 실패 시 다음 단계 실행 차단
STEP 6. 오류 및 상태 처리 표준화¶
다음 상태를 통일한다.
| 상태 | 의미 |
|---|---|
| PASS | 필요한 검증 통과 |
| FAIL | 검증 실패 |
| HOLD | 필수 조건 미충족 |
| NEEDS_REVIEW | 전문가 또는 PM 검토 필요 |
| VISUAL_PENDING | CAD 시각 검증 미완료 |
단계별 오류 코드와 처리 주체, 재시도 가능 여부 및 후속 실행 차단 기준을 정의한다.
STEP 7. 계약 테스트 자동화¶
다음 테스트를 수행한다.
- 정상 입력·출력 계약
- 필수 필드 누락
- 잘못된 데이터 타입
- Schema Version 불일치
- 좌표계 및 단위 불일치
- Source Revision 불일치
- 미승인 Knowledge 입력
- 권한 없는 Source 접근
- 중복 Request ID
- 후속 모듈의 오류 반환
- 미확정 CAD QA 상태
pytest와 JSON Schema Validator 등을 이용하여 자동 검증한다.
STEP 8. 통합 인터페이스 문서 작성¶
예상 산출물:
interface-contract-v1.mdinterface-matrix.csve2e-envelope.schema.jsonint-01-contract-validation-report.md
실제 저장 경로는 기존 레포지토리 구조와 일치하도록 조정한다.
문서에는 모듈별 담당자, 생산·소비 데이터, 버전, 오류 정책, 테스트 결과를 포함한다.
STEP 9. 개발자별 교차검토¶
황수아
- L2 Source 및 Knowledge 계약 확인
- Evidence 및 승인 데이터 구조 검토
이상재
- FastMCP 및 CAD Reader/Writer 계약 확인
- DXF·Authorized Delta·QA 데이터 구조 검토
조영우
- L1 Site 및 Solver 입력·출력 검토
- 배치 결과와 수량 보고서 구조 검토
문길래
- 전체 인터페이스 연결 및 품질 기준 검토
- 미검증 항목과 후속 조치 결정
STEP 10. GitHub 반영 및 결과 제출¶
- 인터페이스 명세 작성
- JSON Schema 및 계약 테스트 추가
- 검증 Evidence 기록
- 미완료·HOLD 항목 정리
- 통합 인터페이스 매트릭스 작성
- GitHub PR 생성
- PM 검토 후 main 병합
- INT-02 이후 통합 작업으로 인계
3. 업무분장¶
| 담당자 | 역할 |
|---|---|
| 문길래 | 전체 통합 계약·검증 기준·최종 승인 |
| 황수아 | Source·Engineering Knowledge 인터페이스 |
| 이상재 | MCP·CAD·DXF·QA 인터페이스 |
| 조영우 | L1 Site·Solver·수량 분석 인터페이스 |
4. 제출 산출물¶
- 통합 인터페이스 계약서
- Producer/Consumer 인터페이스 매트릭스
- 공통 데이터 Envelope JSON Schema
- 오류 및 HOLD 상태 처리 표준
- Schema 버전 호환성 검증 결과
- 인터페이스 자동 테스트
- 미완료·불일치 항목 목록
- 개발자별 교차검토 결과
- INT-02~10 인계 자료
- GitHub PR 및 PM 검토 결과
5. 완료 기준 (PASS)¶
- PoC-01~25 관련 인터페이스 조사
- 모듈별 입력·출력 계약 매핑
- 데이터 생산자·소비자 및 담당자 지정
- 공통 Envelope Schema 정의
- Source·Rule·Candidate Version 관리 기준 확인
- 단위·좌표계·Geometry 데이터 계약 검증
- PASS/FAIL/HOLD/REVIEW 상태 정의
- 승인 및 보안 Gate 연결
- 오류·중복 요청·재시도 정책 문서화
- 정상·오류·경계조건 계약 테스트 PASS
- 실제 구현 계약과 미구현 계약 구분
- 개발자 3명 교차검토 완료
- PM 최종 판정
- GitHub PR 제출 및 main 병합
- INT-02 인계 완료
6. 개발 및 검증 원칙¶
- 실제 구현된 인터페이스와 계획 단계의 인터페이스를 구분한다.
- 입력·출력 계약 불일치를 임의 데이터 보정으로 숨기지 않는다.
- 승인되지 않은 Engineering Knowledge를 후속 단계에 전달하지 않는다.
- Source SHA 및 Revision 추적을 유지한다.
- Authorized Delta 범위 위반을 허용하지 않는다.
- 필수 Gate 실패 시 후속 작업을 자동 실행하지 않는다.
- 고객자료의 무단 외부 업로드 및 유료 API 호출을 수행하지 않는다.
- 기존 기능 전체를 불필요하게 재개발하지 않는다.
- 본 단계의 계약 검증 PASS와 전체 E2E 또는 최종 설계 승인을 구분한다.
7. 참고 문서¶
GitHub Issue
https://github.com/GilbertMoon/icn-solar-cad-agent/issues/167
PoC-25 통합 작업
https://github.com/GilbertMoon/icn-solar-cad-agent/issues/166
전체 PoC 로드맵
팀 업무 및 Knowledge 통합계획
8. 후속 작업¶
INT-01에서 확정한 인터페이스 계약을 기준으로 다음 통합 작업을 진행한다.
후속 단계에서는 실제 MCP 요청부터 신규 L1 설계 결과까지 데이터가 올바르게 전달되는지 통합 실행과 오류 검증을 확대한다.
No data to display