Project

General

Profile

Actions

Feature #909

open
길문 상이

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

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

[INT-04] 통합 오류·HOLD·복구 및 재실행 검증

Feature #909: [INT-04] 통합 오류·HOLD·복구 및 재실행 검증

Added by 길래 문 22 days ago. Updated 22 days ago.

Status:
New
Priority:
High
Assignee:
Start date:
02/11/2027
Due date:
02/16/2027 (Due in about 3 months)
% Done:

0%

Estimated time:

Description

INT-04. 통합 오류·HOLD·복구 및 재실행 검증

1. 작업 개요

본 작업은 MCP 기반 태양광 CAD 자동설계 플랫폼에서 오류, 부분 실패, 승인 보류 및 중복 요청이 발생했을 때 안전하게 처리 과정을 중단하고 기존 데이터의 무결성을 유지하면서 복구 또는 재실행할 수 있는지 검증하는 통합 작업이다.

INT-01의 인터페이스 계약, INT-02의 MCP 통합 호출, INT-03의 L1 End-to-End 시나리오를 기준으로 검증한다.

주요 목표는 다음과 같다.

  • 오류 유형별 처리 정책 표준화
  • 필수 승인 Gate 실패 시 후속 실행 차단
  • 재시도 가능한 오류와 재시도하면 안 되는 오류 구분
  • 동일 요청 재실행 시 중복 CAD 객체 생성 방지
  • Source 원본 및 기존 검증 산출물 보존
  • 오류 발생 후 추적 가능한 복구 및 재실행

GitHub Issue: https://github.com/GilbertMoon/icn-solar-cad-agent/issues/170

상위 Redmine 일감: #867

담당: 이상재

PM 및 검토: 문길래

협력: 황수아, 조영우

계획 기간: 2027-02-11 ~ 2027-02-16

선행 작업: INT-01~03, PoC-25

2. 세부 작업

STEP 1. 통합 실행 상태 및 복구 대상 조사

  • INT-01~03 통합 실행 계약 확인
  • MCP Tool Chain 및 실행 단계 조사
  • Run ID와 Request ID 관리 방식 확인
  • 단계별 입력·출력 및 산출물 경로 확인
  • PASS/FAIL/HOLD 상태 전달 구조 확인
  • 장애 발생 시 기존 산출물에 미치는 영향 분석

STEP 2. 오류 유형 및 처리 정책 정의

오류 유형 처리 방향
일시적 네트워크 오류 제한적 재시도
MCP Timeout 원인 확인 후 조건부 재시도
Tool 실행 실패 해당 단계 중단 및 로그 기록
JSON Schema 오류 입력 수정 전까지 HOLD
Source Revision 변경 무결성 재검증 후 판단
Knowledge 승인 철회 즉시 HOLD
좌표계·단위 불명확 자동 추정 금지 및 HOLD
Solver 계산 실패 오류 기록 및 Candidate 생성 중단
DXF Audit 실패 출력 승격 차단
Authorized Delta 승인 누락 변경 적용 차단
API 권한·비용 승인 없음 외부 API 호출 차단

STEP 3. 통합 실행 상태 전이 정의

다음 상태를 관리한다.

  • NOT_STARTED
  • RUNNING
  • PASS
  • FAIL
  • HOLD
  • NEEDS_REVIEW
  • VISUAL_PENDING
  • RETRY_PENDING
  • RECOVERED

상태 전이별 실행 주체와 허용 조건을 명시한다.

필수 승인 Gate가 HOLD인 상태에서 다음 단계가 자동으로 실행되지 않도록 한다.

STEP 4. 재시도 정책 정의

  • 재시도 가능한 오류 유형 식별
  • 재시도할 수 없는 승인·데이터 오류 구분
  • 최대 재시도 횟수 정의
  • 재시도 간격 및 Backoff 정책 정의
  • 재시도 전 Source·Rule·Approval 상태 확인
  • 타임아웃 및 중단 조건 정의
  • 재시도 횟수와 결과 로그 기록

승인 누락이나 Source 불일치는 단순 재시도로 해결되는 오류로 처리하지 않는다.

STEP 5. 중복 실행 및 Idempotency 검증

다음 상황을 검증한다.

  1. 동일 MCP Request 반복
  2. 동일 Solver 실행 재요청
  3. 동일 Layout Candidate 재사용
  4. 동일 DXF Candidate 재생성
  5. 동일 Authorized Delta 반복 적용
  6. Quantity Report 중복 생성
  7. 실행 도중 중단 후 다시 실행

동일 요청을 반복했을 때 모듈 객체나 승인된 변경사항이 중복 적용되지 않아야 한다.

STEP 6. Source 및 승인 상태 재검증

재실행 전에 다음 항목을 확인한다.

  • Source ID / SHA-256 / Revision
  • Engineering Knowledge 승인 및 효력 상태
  • Approved Rule Version
  • L1 Site Geometry 및 좌표계
  • Authorized Delta 승인 범위
  • API 접근 및 비용 승인 여부

이전 실행에서 승인되었다는 사실만으로 변경된 Source나 철회된 규칙을 다시 사용하지 않는다.

STEP 7. 부분 실패 및 중간 산출물 처리

  • 미완료 DXF 파일 격리
  • 불완전한 Layout Candidate 구분
  • 실패한 Delta 결과 승격 방지
  • 검증된 기존 산출물 보존
  • 중간 산출물 재사용 가능성 판단
  • 결과 파일 충돌 방지
  • 복구 불가능 상태의 HOLD 처리

Source 원본이나 이미 승인된 결과물을 임의로 덮어쓰지 않는다.

STEP 8. 장애 주입 및 Golden Fixture 테스트

다음 테스트를 수행한다.

  1. MCP 서버 연결 끊김
  2. Tool 호출 Timeout
  3. 잘못된 JSON 응답
  4. Source Revision 불일치
  5. 승인 철회된 Engineering Knowledge
  6. Solver 실행 실패
  7. DXF 파일 쓰기 실패
  8. DXF Audit 오류
  9. 미승인 Authorized Delta
  10. BOQ 수량 불일치
  11. DWG/PDF 시각 검증 미완료
  12. 동일 Request 중복 호출

장애 주입은 합성 Golden Fixture 또는 격리된 테스트 환경에서 수행한다.

STEP 9. 장애 복구 및 재실행 테스트

  • 오류 발생 전 실행 단계 확인
  • 중단 위치 및 실패 원인 식별
  • 원본과 기존 산출물 무결성 확인
  • 재실행 가능 여부 판단
  • 필요한 승인 Gate 재확인
  • 허용된 단계에서 재실행
  • 실행 결과 및 중복 여부 비교
  • 복구 과정과 Evidence 기록

STEP 10. 복구 실행 이력 및 로그 구조 정의

다음 정보를 기록한다.

  • Run ID
  • Request ID
  • Failed Stage
  • Error Code
  • Error Category
  • Retry Count
  • Recovery Action
  • Previous Status
  • Current Status
  • Source SHA / Revision
  • Rule ID / Version
  • Candidate ID
  • Output SHA
  • Recovery Evidence
  • Responsible Owner

민감한 Source 내용이나 인증정보는 로그에 기록하지 않는다.

STEP 11. 통합 복구 정책 및 보고서 작성

예상 산출물:

  • recovery_policy.md
  • recovery_scenario_matrix.csv
  • recovery_test_report.md

내용:

  • 장애 유형 및 분류 기준
  • 단계별 중단·재시도 정책
  • 승인 Gate 검증 정책
  • 중복 실행 방지 방법
  • 중간 산출물 관리 정책
  • 테스트 및 복구 결과
  • 미해결 결함 및 담당자
  • INT-05 후속 검증에 전달할 사항

STEP 12. GitHub 반영 및 결과 제출

  • MCP 오류·상태 처리 코드 검증
  • 필요한 최소 복구 기능 보완
  • Fault Injection Fixture 작성
  • Idempotency 테스트 구현
  • pytest 및 통합 회귀 테스트
  • 실제 MCP 호출과 Mock 결과 구분
  • Windows PowerShell 재실행 가이드 작성
  • GitHub PR 생성
  • 개발자별 검토 및 PM 판정
  • main 병합 후 INT-05로 인계

3. 업무분장

담당자 역할
이상재 MCP 실행 상태·오류·재시도·복구 및 CAD 출력 안전성 검증
황수아 Source·Engineering Knowledge 승인 Gate와 재검증
조영우 Solver·Layout Candidate·Quantity·Delta 중복 처리 검증
문길래 복구 정책·품질·안전 Gate·GitHub PR 최종 검토

4. 제출 산출물

  1. 통합 오류 유형 및 복구 정책
  2. 실행 상태 전이표
  3. 재시도·중단·HOLD 처리 기준
  4. MCP 오류 복구 및 중복 실행 방지 테스트
  5. Source·Knowledge·Delta 승인 상태 재검증 결과
  6. 부분 실패 및 중간 산출물 보호 검증
  7. Golden Fault Injection Fixture
  8. recovery_policy.md
  9. recovery_scenario_matrix.csv
  10. recovery_test_report.md
  11. 재현 가능한 실행 Evidence
  12. INT-05 인계 및 GitHub PR

5. 완료 기준 (PASS)

  • 통합 실행 상태 및 단계별 Side Effect 확인
  • 오류 유형별 처리 정책 정의
  • PASS/FAIL/HOLD/RETRY 등 상태 전이 정의
  • 일시적 오류와 필수 Gate 오류 구분
  • 최대 재시도·Backoff·Timeout 정책 정의
  • 동일 요청 중복 실행 방지
  • 동일 Authorized Delta 중복 적용 방지
  • Source 원본 SHA 불변
  • 기존 검증 산출물 보존
  • 재실행 전 Source·Rule·Approval 재검증
  • 미승인 Knowledge·Delta 적용 차단
  • 부분 실패 및 불완전한 출력물 격리
  • 주요 장애·경계 시나리오 10건 이상 검증
  • 복구 Evidence와 책임자 기록
  • 실제 MCP 호출·CLI·Mock 결과 구분
  • Golden Fixture 및 pytest PASS
  • 개발자별 전문 영역 교차검토
  • PM 최종 판정 및 GitHub PR 병합
  • INT-05 후속 작업 인계 완료

6. 개발 및 검증 원칙

  • 장애 복구를 위해 승인 Gate를 우회하지 않는다.
  • 미승인 Source·Knowledge·Delta를 자동 적용하지 않는다.
  • 일시적 장애와 데이터·승인 오류를 구분한다.
  • 동일 요청의 반복 실행이 중복 결과를 만들지 않아야 한다.
  • 원본 CAD 및 기존 승인 산출물을 덮어쓰지 않는다.
  • 복구 불가능한 상태를 임의로 PASS 처리하지 않는다.
  • 고객자료를 승인 없이 외부 전송하지 않는다.
  • 승인되지 않은 APS 유료 API를 호출하지 않는다.
  • 합성 테스트와 실제 고객자료 검증을 구분한다.
  • 복구 기능 검증 PASS를 최종 설계·운영 승인으로 간주하지 않는다.

7. 참고 문서

GitHub Issue

https://github.com/GilbertMoon/icn-solar-cad-agent/issues/170

INT-01 통합 계약

https://github.com/GilbertMoon/icn-solar-cad-agent/issues/167

INT-02 MCP 통합 실행

https://github.com/GilbertMoon/icn-solar-cad-agent/issues/168

INT-03 신규 L1 E2E 검증

https://github.com/GilbertMoon/icn-solar-cad-agent/issues/169

PoC-25 End-to-End 통합

https://github.com/GilbertMoon/icn-solar-cad-agent/issues/166

8. 후속 작업

INT-04의 장애·복구 검증 결과를 기반으로 다음 통합 단계에서는 실패 이력, 실행 Evidence 및 통합 품질 지표를 활용하여 전체 시스템의 안정성과 검증 가능성을 확대한다.

Actions

Also available in: PDF Atom