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
수황 Updated by 수아 황 21 days ago
- Status changed from New to In Progress
2026-10-27 — PoC-04 착수 조사 및 구현 준비
[결과 / 결정]
기존 Source 관리 자산 조사에 착수하여 정적 코드 검토와 Manifest 메타데이터 대조를 완료했습니다. 본 일감은 In Progress로 전환합니다. 전체 기능 구현·검증 완료를 의미하지 않습니다. 전체 진척률 산정 기준이 없어 진척도 수치는 임의로 올리지 않습니다.
[조사 기준]
GitHub main 스냅샷: 97feab0d8631efb6e360907f88c67aaa63d87ba5
PoC-01 최종 보고서·Gap Matrix·병렬 개발계획과 기존 MCP 서버, PoC-05 SourceResolver 임시 구현을 확인했습니다.
[실제 검증 결과]
공식 Identity Manifest T1 156 + T2 206 + 보고서 15 = 377행을 로컬 스냅샷에서 독립 대조했습니다. 아래 8개 검사를 실제 실행하여 모두 통과했습니다.
- 총 377행
- relative_path 키 중복 없음
- 프로젝트별 수량 일치
- Identity 경로에 절대경로·상위 경로 이탈 표기 없음
- Evidence 경로가 Identity에 포함됨
- Evidence 키 중복 없음
- Evidence SHA-256 형식 정상
- 파일 크기 메타데이터가 비음수 정수
기록된 SHA-256은 88개이며 289개는 미기록입니다. 원본 377개 파일의 실제 SHA 재계산·무결성 검증은 미실행입니다.
[재사용 / 보완]
- 공식 data/manifests 및 Source Version/Final Policy 재사용. Manifest 등재와 최종 설계승인 분리 유지.
- 기존 build_source_inventory_manifest.py는 workspaces/w1 Draft 및 workspaces/w0 Evidence를 입력으로 사용하므로 그대로 실행하지 않고 공식 Manifest를 읽는 adapter로 보완합니다.
- src/solar_mcp/cad/sources.py의 SourceResolver/ResolvedSource와 접근 gate를 재사용하되 poc04-stub.v1을 확장합니다. PoC-05 호환 유지가 필요합니다.
- list_sources/get_source_info, 필터·페이지 처리, stable Source ID 및 Revision 이력 계약을 추가해야 합니다.
[산출물]
로컬 검토본 3종 작성 및 JSON 읽기 검사 완료:
- poc04-reuse-audit-20261027.json
- poc04-implementation-checklist-20261027.json
- poc04-metadata-results-20261027.json
현재 산출물은 로컬 검토본이며 GitHub PR/공유 저장소 게시 전입니다. 위 핵심 검사 결과와 재사용 판단을 본 댓글에 기록합니다.
[미완료 / 한계]
Source 조회 기능 신규 구현, MCP 실제 호출, 접근 차단·무결성 통합 테스트, pytest 회귀, PR 및 PM 검토는 미완료입니다. 로컬 Python 3.12.10 확인; mcp/pytest/ezdxf는 현재 조사 환경에 미설치입니다. 고객 원본 설계자료 열람·수정, Autodesk APS 호출·외부 업로드는 수행하지 않았습니다.
[다음 행동]
공식 Manifest read-only loader → Source Registry/Revision 계약 → 공통 SourceResolver 확장 → list_sources/get_source_info → 합성 fixture 단위·보안 테스트 → 기존 MCP 연결·회귀 → Evidence/PR 검토 순서로 진행합니다.
현재 등록된 완료일 2026-11-06을 유지합니다. 상세 구현 소요시간과 완료 예상은 첫 구현·테스트 후 재산정합니다.
[근거]
https://github.com/GilbertMoon/icn-solar-cad-agent/blob/97feab0d8631efb6e360907f88c67aaa63d87ba5/docs/poc01-parallel-development-plan-20261026.md
https://github.com/GilbertMoon/icn-solar-cad-agent/blob/97feab0d8631efb6e360907f88c67aaa63d87ba5/src/solar_mcp/cad/sources.py
수황 Updated by 수아 황 21 days ago
2026-10-27 — 공식 Manifest 로더 구현·검증 및 Draft PR
[완료한 범위]
공식 T1/T2/보고서 Identity CSV 3개와 Version Evidence를 읽는 read-only 로더를 구현했습니다. 불변 SourceRecord/SourceInventory, 안정적인 Source ID 제안, 근거 row locator, 메타데이터 SHA 기록을 포함합니다.
중복·Windows 대소문자/Unicode 별칭, 잘못된 CSV/크기/SHA, 경로 이탈 문자열, 고아 Evidence·메타데이터 불일치·알 수 없는 버전 상태를 거부합니다. 실제 CAD/문서 파일은 열지 않습니다.
[실제 테스트]
Python 3.12.10 / 표준 unittest 30개 PASS, 실패 0, 오류 0, skip 0.
공식 Manifest 377개(T1 156/T2 206/보고서 15), 기록 SHA 88개·미기록 289개 확인.
Version 327 VERIFIED / 46 CANDIDATE / 4 VERSION_REVIEW 확인.
377개 모두 final_status=NOT_ASSESSED, integrity_status=NOT_CHECKED, access_status=NOT_EVALUATED. Revision 미확정 유지.
GitHub 기준 CSV blob 바이트와 일치 확인 및 실행 전후 입력 SHA 불변 확인.
[산출물 / PR]
Draft PR: https://github.com/GilbertMoon/icn-solar-cad-agent/pull/192
브랜치: task/w1/poc04-manifest-loader-20261027
기준 main: 97feab0d8631efb6e360907f88c67aaa63d87ba5
구현 commit: fc6e24e377ce4e4f1df2c2b7ce037e57e5e61d7e
새 파일 6개: src/solar_mcp/sources/ 모듈 2개, 단위 테스트, 실행 runner, README, result.json.
재현 명령: python pocs/poc_04_manifest_loader/run_checks.py
검증 Evidence: https://github.com/GilbertMoon/icn-solar-cad-agent/blob/task/w1/poc04-manifest-loader-20261027/pocs/poc_04_manifest_loader/result.json
[미완료 / 검토 필요]
이번 PASS는 Manifest 로더 단계에 한정합니다. 전체 PoC-04는 In Progress이며 PM 승인·main 병합 전입니다.
Source ID 형식(SRC- + relative_path SHA256 앞 32자리)은 제안이며 PoC-05 기존 synthetic ID를 자동 대체하지 않습니다.
Source Registry/Revision/ACL, list_sources/get_source_info, PoC-05 bridge, 실제 MCP 호출, 실제 원본 SHA 검증은 다음 단계입니다. 기존 MCP/PoC-05 코드는 이번 PR에서 변경하지 않았습니다.
[다음 행동]
Draft PR의 메타데이터·Source ID 계약 검토 → Registry/Revision/ACL 계약 및 조회 도구 구현 → 합성 입력 보안 테스트와 MCP 연결·회귀.
담당·일정·전체 진척도 수치는 유지합니다. 로더 단계 결과를 근거로 남기며 전체 PoC 완료로 보고하지 않습니다.
수황 Updated by 수아 황 21 days ago
2026-10-28 — PoC-04 후속 구현 및 검증 현황
[로더 정정 및 병합]
이전 #3의 327 VERIFIED 및 테스트 30개는 수정 전 결과입니다. PM 요청에 따라 Evidence 없는 289개를 UNVERIFIED로 수정했습니다. 최종 38 VERIFIED / 289 UNVERIFIED / 46 CANDIDATE / 4 VERSION_REVIEW, 로더 unittest 31/31 PASS (실패·오류·skip 0)입니다. PR #192는 로더 단계 승인 후 main에 병합되었습니다.
https://github.com/GilbertMoon/icn-solar-cad-agent/pull/192
[Registry 후속 Draft]
PR #194에서 합성 자료 전용 Registry, read/none 접근 제어, revision/history SHA 검사, list_sources/get_source_info 및 PoC-05 Reader 직접 연결을 구현했습니다. #192 병합 후 기준 브랜치를 main으로 변경하고 중복 diff를 정리했습니다. Draft 상태로 PM 최종 승인은 보류 중입니다.
https://github.com/GilbertMoon/icn-solar-cad-agent/pull/194
[검증 및 제한]
기존 실행 Evidence: 선택 회귀 181 PASS / 0 FAIL / 7 SKIP, 기존 async 7개 제외. 직접 함수 호출 및 PoC-05 Reader 직접 bridge는 PASS입니다. 실제 MCP stdio 3건은 당시 sandbox socketpair timeout으로 HOLD, 실제 링크 생성 관련 4건은 권한 제한으로 SKIP입니다. 이전 결과이며 main 기준 재검증 및 실제 MCP 통신 검증 완료를 의미하지 않습니다. 실제 L2 원본 자료는 실행하지 않았습니다.
[다음 단계]
정상 Windows 환경에서 실제 stdio 3건 및 링크 4건을 검증하고, 불가 항목은 사유와 후속 방안을 기록합니다. PoC-05 실제 통신 연동과 관련 회귀 결과를 PASS/FAIL/SKIP/HOLD, 실행 명령 및 SHA와 함께 셀프 검사표로 제출한 후 PM 검토를 받습니다. 전체 PoC-04는 In Progress입니다.
수황 Updated by 수아 황 21 days ago
2026-10-28 — PoC-04 재검증
PR #194는 main 기준 Draft이며 충돌 없이 후속 변경 12개 파일로 정리했습니다. HEAD cba2e5cf37c99c0f54e4a34324f5a994e0f03840.
Python 3.12.10 로컬 파일 스냅샷에서 선택 회귀 재실행: 184 PASS / 0 FAIL / 4 SKIP, 기존 async 7건 제외. 네트워크 권한 부여 후 실제 MCP stdio 3건은 통과했습니다. 링크 생성 관련 4건은 실행 환경 권한 제한으로 SKIP이므로 전체 판정은 HOLD입니다. 실행 스냅샷과 PR HEAD 전체 동일성은 추가 확인이 필요합니다. 고객 원본은 사용하지 않았습니다.
남은 일: PR HEAD 기준 재현 및 링크 검증 가능한 Windows 환경에서 4건 재검증 또는 PM 범위 결정, PoC-05 회귀 및 셀프 검사표 제출. In Progress 유지.
PR 기록: https://github.com/GilbertMoon/icn-solar-cad-agent/pull/194#issuecomment-6457969935
수황 Updated by 수아 황 21 days ago
- File poc04_pr194_exact_head_evidence_20261028.zip poc04_pr194_exact_head_evidence_20261028.zip added
2026-10-28 — PR #194 고정 HEAD 재검증 및 셀프 검사표
RESULT=HOLD
HEAD_SHA=cba2e5cf37c99c0f54e4a34324f5a994e0f03840
PR=https://github.com/GilbertMoon/icn-solar-cad-agent/pull/194
[이번에 해소한 항목]
별도 Git clone의 detached HEAD에서 추적 파일 779개 전부를 Git blob 원본 바이트와 대조했습니다. Windows 줄바꿈 자동 변환을 제거한 검증 복사본이며 실행 전 불일치 0개입니다. 제품 코드·테스트·fixture는 수정하지 않았습니다.
환경: Windows / Python 3.12.10 / mcp 2.3.0 / ezdxf 1.4.4 / pytest 9.1.1.
[실제 실행 결과]
- PR 원본 run_registry_checks.py: 186 PASS / 0 FAIL / 2 SKIP, 기존 async 7개 제외. 코드·입력 지문 불변이며 runner가 생성하는 JSON/XML 2개만 변경됐습니다.
- 필터 없는 전체 pytest tests: 201 PASS / 0 FAIL / 2 SKIP, 24 subtests PASS. 선택 회귀와 중첩하므로 합산하지 않습니다. 전체 회귀 중 추적 파일 변경 0개입니다. 기존에 제외했던 async 검사도 전체 실행에 포함했습니다.
- 실제 PoC-04 MCP stdio 3/3 PASS: 도구 목록·list/info·PoC-05 bridge, stdout 오염 검사, 잘못된 registry 계약 시작 거부.
- 실제 hardlink 및 Windows junction 거부 검사 PASS. 예전 4 SKIP 중 이 2건은 해소됐습니다.
- PoC-05 run_cases.py 새 실행: 실제 stdio 22/22 사례 PASS, failed_checks=[]; 단, 최종 automated_status=FAIL / pytest gate=DISALLOWED_SKIPS입니다. 전체 JUnit에 포함된 새 PoC-04 symlink SKIP이 기존 PoC-05 허용 목록에 없기 때문입니다. 이를 전체 PoC-05 PASS라고 보고하지 않으며 허용 목록을 임의 수정하지 않았습니다.
[남은 2 SKIP / Blocker]
- tests.unit.test_poc04_registry::test_actual_symlink_denied_if_available
- tests.unit.test_poc05_sources::test_symlink_inside_root_is_rejected
Windows가 실제 symlink 생성을 허용하지 않아 실행하지 못했습니다. 모의 reparse 분기 검사를 실제 링크 생성 검증으로 대체하지 않습니다. 보안 설정이나 권한 정책은 변경하지 않았습니다.
[재현 명령 — 저장소 루트 / 동일 HEAD]
python pocs/poc_04_manifest_loader/run_registry_checks.py
python -m pytest tests -q -p no:cacheprovider --junitxml=<외부결과폴더>/full-regression-junit.xml
python pocs/poc_05_dxf_read/run_cases.py --junit <외부결과폴더>/full-regression-junit.xml --out <외부결과폴더>/poc05-result.json
runner 종료코드 0과 최종 PASS를 구분해야 합니다.
[Evidence]
첨부 poc04_pr194_exact_head_evidence_20261028.zip: 셀프 검사표, 고정 HEAD 대조 결과, 선택/전체 JUnit, PoC-05 결과, 환경 버전, 재현 harness 및 파일별 SHA256 포함. JUnit은 로컬 경로/호스트명 제거본이며 원본 JUnit은 로컬에 보존합니다.
ZIP SHA256=cbbe6b7491ef81d010a30037f68f59f09834c0ee365f26938ac883cc5cbed9a9
[PM 결정 / 다음 행동]
이미 symlink 생성이 허용된 Windows 환경에서 2건을 실제 재검증하거나, PM이 1차 합성 PoC 범위 제외 여부와 후속 검증 조건을 명시적으로 결정해야 합니다. 결정 전 전체 PoC-04 HOLD / In Progress 및 PR Draft를 유지합니다. 다음 일감 착수·main 병합·Closed 처리하지 않았습니다. 합성 fixture만 사용했으며 고객 실제 Source 접근은 NOT_RUN입니다. 담당·마감·진척도 숫자는 유지합니다.
수황 Updated by 수아 황 21 days ago
- Related to Feature #1196: [PoC-04 후속] Ubuntu 배포환경 MCP Source 접근·파일시스템 보안 검증 added
수황 Updated by 수아 황 21 days ago
- Status changed from In Progress to Closed
- % Done changed from 0 to 100
PM 지시(2026-10-28 10:54 KST)에 따라 1차 합성 PoC 일감을 100% / Closed로 처리합니다. 검증 결과는 201 PASS / 0 FAIL / 2 SKIP이며 심볼릭 링크 2건은 NOT_VERIFIED / DEFERRED_TO_UBUNTU입니다. Ubuntu 배포 전 필수 후속 보안 Gate는 #1196에서 추적하고 #916 선행조건으로 연결했습니다. 고객 CAD·Source 접근은 해당 Gate 완료 전 금지입니다. PR #194는 현재 Draft / 미병합이며 최종 PR 검토·병합은 별도 확인 필요합니다. PoC-05 증빙 판정 DISALLOWED_SKIPS FAIL은 변경하지 않았습니다.
PM 지시: https://ax-2-hq.slack.com/archives/C0CC11MLTEE/p1793152483887539?thread_ts=1793150991.431999
PR: https://github.com/GilbertMoon/icn-solar-cad-agent/pull/194
수황 Updated by 수아 황 21 days ago
2026-10-28 — PR #194 검증 증빙 보완 및 재검토 요청
Redmine 첨부 ZIP과 내부 파일 SHA256을 확인하고 고정 HEAD 테스트 증빙, 정제 JUnit, 셀프 체크 및 SHA 목록을 PR 브랜치에 커밋했습니다. 테스트 대상 cba2e5cf37c99c0f54e4a34324f5a994e0f03840, 현재 문서·증빙 추가 HEAD a082c546cfdc241da9e876c3a64ad74ec9265708. 새 HEAD에서 테스트를 다시 실행한 것은 아닙니다.
기존 전체 결과 201 PASS / 0 FAIL / 2 SKIP, PoC-05 판정기 FAIL / DISALLOWED_SKIPS를 그대로 기록했습니다. 두 symlink 검사는 NOT_VERIFIED / DEFERRED_TO_UBUNTU이며 Ubuntu 필수 Gate #1196은 미수행입니다. 고객 원본 접근은 Gate 완료 전 금지입니다.
PR은 Draft / 미병합이며 PM 재검토를 요청했습니다. #871 Closed / 100% 유지.
https://github.com/GilbertMoon/icn-solar-cad-agent/pull/194#issuecomment-6459841881
영조 Updated by 영우 조 14 days ago
- Related to Feature #1313: [PoC-13 후속] 운영 Registry·MCP 연계 및 승인된 L1 도면 검증 added