Feature #871
closedFeature #866: [MASTER] ICN Solar CAD Agent — Autodesk MCP 및 L2→L1 태양광 자동설계 시스템 구축
Feature #867: Phase 1 — MCP 기반 태양광 CAD 자동설계 플랫폼 구축 및 통합 검증
[PoC-04] Source 파일 목록 조회·접근 권한 및 무결성 검증
100%
Description
PoC-04. Source 파일 목록 조회·접근 권한 및 무결성 검증¶
1. 작업 개요¶
본 PoC는 기존 인천공항 L2 태양광 설계자료를 안전하게 조회하고 관리하기 위한 Source Inventory 조회 및 파일 무결성 검증 기능을 구축하는 작업이다.
기존 GitHub 저장소에 구축된 Source Manifest, Version Policy 및 SHA-256 검증 자산을 최대한 재사용한다.
향후 Engineering Knowledge 추출 및 신규 L1 자동설계에 활용할 수 있도록 각 Source의 출처·버전·승인 상태와 파일 무결성을 확인하는 공통 기반을 확보한다.
GitHub Issue: https://github.com/GilbertMoon/icn-solar-cad-agent/issues/145
상위 Redmine 일감: #867
담당: 황수아
PM 및 검토: 문길래
협력: 이상재, 조영우
계획 기간: 2026-11-02 ~ 2026-11-08
선행 작업: PoC-01 기존 Source 관리 자산 분석 및 PoC-02 MCP 서버 연결 계약 확인
2. 세부 작업¶
STEP 1. 기존 Source 관리 기능 조사¶
- 기존 Official Source Inventory 및 Manifest 구조 확인
- Source Version / Final Policy 조사
- SHA-256 기반 원본 파일 무결성 검증 방식 확인
- 파일별 Source ID, 경로, 유형, 버전 및 상태 확인
- 기존 기능의 재사용 가능 범위 분석
STEP 2. Source 조회 기능 구현¶
다음 기본 기능을 구현한다.
① list_sources
- 허용된 Source 파일 목록 조회
- 프로젝트, 파일 유형, 상태 등에 따른 필터링
- 대량 목록의 페이지 단위 조회
- Source ID 및 기본 메타데이터 반환
② get_source_info
- Source ID 기반 단일 파일 정보 조회
- 파일 유형 및 버전 정보 확인
- Source SHA-256 및 검증 상태 조회
- 최종 승인 상태와 미확인 정보 구분
STEP 3. 파일 접근 권한 및 보안 검증¶
- 지정된 허용 Source 폴더만 접근 가능하도록 제한
- 상대경로 및 상위 디렉터리 접근 차단
- 심볼릭 링크 등을 통한 허용 범위 우회 방지
- 허용되지 않은 파일 및 디렉터리 접근 거부
- 원본 파일의 읽기 전용 처리
- 파일 내용과 민감 경로의 불필요한 노출 방지
STEP 4. SHA-256 무결성 검증¶
- Manifest에 기록된 파일 해시값 조회
- 실제 파일의 SHA-256 재계산
- 저장된 해시값과 실제 파일 해시값 비교
- 정상·불일치·누락·검증 불가 상태 구분
- 무결성 검증 전후 원본 파일 변경 여부 확인
중요: Source Manifest에 등록되었다는 사실이 해당 파일의 최종 설계 승인 또는 공식 납품 가능 상태를 의미하지 않도록 구분한다.
STEP 5. 오류 및 예외 처리 테스트¶
다음 테스트를 수행한다.
- 정상 Source 파일 조회
- 존재하지 않는 Source ID 조회
- 접근 권한이 없는 파일 조회
- Source 파일 누락
- SHA-256 불일치
- 잘못된 경로 및 허용 범위 우회 시도
- 버전 또는 최종 승인 상태 미확정
각 테스트 결과를 PASS, FAIL, HOLD 또는 확인 필요 상태로 기록한다.
STEP 6. MCP Tool 및 후속 PoC 연동¶
- PoC-02에서 구축한 MCP 서버와 조회 기능 연결
list_sources및get_source_infoTool 계약 정의- 조회 결과의 JSON 응답 구조 검증
- 후속 PoC에서 Source ID로 CAD 분석 대상을 지정할 수 있도록 구성
- PoC-05~08에서 재사용할 수 있는 입력·출력 규격 문서화
STEP 7. GitHub 반영 및 검토¶
- 기존 코드 재사용 및 신규 개발 범위 문서화
- pytest 기반 테스트 코드 작성
- 실제 조회 및 무결성 검증 Evidence 기록
- Windows 개발환경 실행 방법 작성
- GitHub 작업 브랜치와 PR 생성
- PM 검토 후 main 병합
3. 업무분장¶
| 담당자 | 역할 |
|---|---|
| 황수아 | Source Inventory, Manifest, 파일 조회 및 무결성 기능 구현 |
| 문길래 | 보안·검증 기준 및 결과 검토, PR 승인 |
| 이상재 | MCP Tool 연결 및 후속 CAD 분석 기능과의 연계 검토 |
| 조영우 | 신규 L1 Site 입력 및 Source 관리 연계 요구사항 검토 |
4. 제출 산출물¶
- Source 목록 및 단일 파일 정보 조회 기능
- MCP Tool 2개 (
list_sources,get_source_info) - Source 접근 통제 및 오류 처리 기능
- SHA-256 파일 무결성 검증 결과
- Tool 입력·출력 JSON Schema 및 샘플
- pytest 및 실제 MCP 실행 테스트 Evidence
- 개발·실행 가이드 및 GitHub PR
5. 완료 기준 (PASS)¶
- 기존 Source 관리 기능 조사 및 재사용 범위 확정
- 허용된 Source 파일 목록 정상 조회
- Source ID 기반 단일 파일 정보 정상 조회
- 프로젝트·파일 유형·상태 필터링 정상 동작
- 허용되지 않은 경로 및 파일 접근 차단
- SHA-256 일치·불일치·파일 누락 상태 구분
- Source 원본 변경 없음
- Version 상태와 Final 승인 상태를 분리하여 표시
- MCP 서버에서 Source 조회 Tool 정상 호출
- 정상·오류·보안 테스트 PASS
- 실행 Evidence 및 기술문서 작성
- GitHub PR 생성 및 PM 검토 완료
- main 병합 후 후속 PoC 연동 준비 완료
6. 개발 및 보안 원칙¶
- 기존 Approved Source와 Manifest를 임의로 변경하지 않는다.
- 모든 Source 파일은 원칙적으로 읽기 전용으로 처리한다.
- Source 등록 여부와 최종 설계 승인 여부를 혼동하지 않는다.
- Source ID 및 검증된 경로를 통해서만 파일을 조회한다.
- 고객 DWG/DXF 파일을 외부 클라우드에 업로드하지 않는다.
- Autodesk APS 및 유료 API는 사용하지 않는다.
- 테스트 성공은 실제 실행 결과와 무결성 Evidence를 기준으로 판단한다.
7. GitHub 관련 문서¶
GitHub Issue
https://github.com/GilbertMoon/icn-solar-cad-agent/issues/145
25개 PoC 상세 로드맵
전체 업무계획서
업무분장 및 시스템 통합계획
8. 후속 개발 연계¶
다음 작업: PoC-05 — L2 DXF 파일 읽기 및 오류 처리 자동화
PoC-04에서 검증한 Source ID, 접근 권한 및 무결성 검증 기능을 기반으로, 허용된 DXF 파일을 안전하게 읽고 CAD 객체 분석 단계로 연결한다.
Files