Project

General

Profile

Actions

Feature #906

open
길문 길문

Feature #866: [MASTER] ICN Solar CAD Agent — Autodesk MCP 및 L2→L1 태양광 자동설계 시스템 구축

Feature #867: Phase 1 — MCP 기반 태양광 CAD 자동설계 플랫폼 구축 및 통합 검증

[INT-01] 통합 계약 및 인터페이스 검증

Feature #906: [INT-01] 통합 계약 및 인터페이스 검증

Added by 길래 문 23 days ago.

Status:
New
Priority:
High
Assignee:
Start date:
01/01/2027
Due date:
01/04/2027 (Due in 48 days)
% Done:

0%

Estimated time:

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. 계약 테스트 자동화

다음 테스트를 수행한다.

  1. 정상 입력·출력 계약
  2. 필수 필드 누락
  3. 잘못된 데이터 타입
  4. Schema Version 불일치
  5. 좌표계 및 단위 불일치
  6. Source Revision 불일치
  7. 미승인 Knowledge 입력
  8. 권한 없는 Source 접근
  9. 중복 Request ID
  10. 후속 모듈의 오류 반환
  11. 미확정 CAD QA 상태

pytest와 JSON Schema Validator 등을 이용하여 자동 검증한다.

STEP 8. 통합 인터페이스 문서 작성

예상 산출물:

  • interface-contract-v1.md
  • interface-matrix.csv
  • e2e-envelope.schema.json
  • int-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. 제출 산출물

  1. 통합 인터페이스 계약서
  2. Producer/Consumer 인터페이스 매트릭스
  3. 공통 데이터 Envelope JSON Schema
  4. 오류 및 HOLD 상태 처리 표준
  5. Schema 버전 호환성 검증 결과
  6. 인터페이스 자동 테스트
  7. 미완료·불일치 항목 목록
  8. 개발자별 교차검토 결과
  9. INT-02~10 인계 자료
  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 로드맵

https://github.com/GilbertMoon/icn-solar-cad-agent/blob/main/docs/autodesk-mcp-l2-l1-poc-roadmap-20261025.md

팀 업무 및 Knowledge 통합계획

https://github.com/GilbertMoon/icn-solar-cad-agent/blob/main/docs/autodesk-mcp-l2-l1-team-knowledge-integration-plan-20261025.md

8. 후속 작업

INT-01에서 확정한 인터페이스 계약을 기준으로 다음 통합 작업을 진행한다.

후속 단계에서는 실제 MCP 요청부터 신규 L1 설계 결과까지 데이터가 올바르게 전달되는지 통합 실행과 오류 검증을 확대한다.

No data to display

Actions

Also available in: PDF Atom