Feature #909
openFeature #866: [MASTER] ICN Solar CAD Agent — Autodesk MCP 및 L2→L1 태양광 자동설계 시스템 구축
Feature #867: Phase 1 — MCP 기반 태양광 CAD 자동설계 플랫폼 구축 및 통합 검증
[INT-04] 통합 오류·HOLD·복구 및 재실행 검증
0%
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 검증¶
다음 상황을 검증한다.
- 동일 MCP Request 반복
- 동일 Solver 실행 재요청
- 동일 Layout Candidate 재사용
- 동일 DXF Candidate 재생성
- 동일 Authorized Delta 반복 적용
- Quantity Report 중복 생성
- 실행 도중 중단 후 다시 실행
동일 요청을 반복했을 때 모듈 객체나 승인된 변경사항이 중복 적용되지 않아야 한다.
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 테스트¶
다음 테스트를 수행한다.
- MCP 서버 연결 끊김
- Tool 호출 Timeout
- 잘못된 JSON 응답
- Source Revision 불일치
- 승인 철회된 Engineering Knowledge
- Solver 실행 실패
- DXF 파일 쓰기 실패
- DXF Audit 오류
- 미승인 Authorized Delta
- BOQ 수량 불일치
- DWG/PDF 시각 검증 미완료
- 동일 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.mdrecovery_scenario_matrix.csvrecovery_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. 제출 산출물¶
- 통합 오류 유형 및 복구 정책
- 실행 상태 전이표
- 재시도·중단·HOLD 처리 기준
- MCP 오류 복구 및 중복 실행 방지 테스트
- Source·Knowledge·Delta 승인 상태 재검증 결과
- 부분 실패 및 중간 산출물 보호 검증
- Golden Fault Injection Fixture
recovery_policy.mdrecovery_scenario_matrix.csvrecovery_test_report.md- 재현 가능한 실행 Evidence
- 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 및 통합 품질 지표를 활용하여 전체 시스템의 안정성과 검증 가능성을 확대한다.