# Project Validation Report

`README.md`에서 분리한 검증 상세 기록입니다. "무엇을 만들었는지"가 아니라 **"어떻게 검증했는지"**를 다룹니다.

---

## 1. Validation Scope

| # | 프로젝트 | 검증 방식 |
|---|---|---|
| 01 | VOC 멀티에이전트 QA 파이프라인 | pytest 전체 실행 |
| 02 | AI 품질 평가 플랫폼 | pytest 전체 실행(LLM 호출 Mock) |
| 04 | QA 문서 산출물 | 문서 전용 — 실행 대상 아님 |
| 05 | RaiT 평가 시스템 | Mock LLM Judge로 파이프라인 직접 실행 |
| 06 | 팀 프로젝트 — AI 챗봇 QA | pytest 전체 실행 |
| 07 | RAG 챗봇 | 모듈 import 검증(전체 파이프라인은 API 키 필요) |
| 08 | AI Agent 모니터링 대시보드 | 서버 기동 + 기능 테스트 스크립트 실행 |
| 09 | 풀스택 웹앱 | `node:test` 단위 테스트와 Jest 통합 테스트 실행 |
| 10 | LangGraph 챗봇 | Python 모듈 import 검증(Node 구현부는 정적 검토) |

**수집 메모**: 수집일 2026-08-05. 교육과정에서 진행한 프로젝트 중 웹으로 보여줄 수 있는 것을 골라 `01`~`10`으로 재배치했습니다(원래 과정 번호는 08·12·13·16 등으로 흩어져 있었음). 03(AI 챗봇 QA 파이프라인)은 06과 같은 팀 프로젝트의 초기 버전이라 06으로 통합하고 이 저장소에서 제외했습니다.

## 2. Test Environment

- Windows 11, Python(`venv` 격리) — 7개 프로젝트(01·02·05·06·07·08·10)는 프로젝트별 `.venv` 생성 후 `pip install -r requirements.txt`로 실행 환경을 재구성해 검증했습니다.
- `venv`·`node_modules`는 다른 환경에서 그대로 동작하지 않아 저장소에 포함하지 않았습니다(`.gitignore` 처리). 실행하려면 위 방식으로 새로 만들어야 합니다.
- 09는 Node.js 환경에서 `node:test` 5건과 Jest 4건을 실행했습니다. 10의 Node 구현부는 당시 정적 코드 검토만 진행했습니다.
- 01·02·06·07·10은 LLM API 키가 필요합니다. 실제 `.env`는 저장소에 포함하지 않았고 `.env.example`만 제공합니다.

## 3. Automated Tests

실행 환경이 갖춰진 항목에서, 직접 돌려 통과를 확인한 자동 테스트는 다음과 같습니다.

| 항목 | 결과 |
|---|---|
| 01 · `unittest` (`tests/`) | 98건 통과 |
| 01 · 품질 스위트 (`quality_diagnosis/`, pytest) | 32건 통과 |
| 02 · pytest | 84건 통과 (LLM 호출 전부 Mock — 실제 API 호출·과금 없음) |
| 06 · pytest | 53건 통과 |
| 09 · `node:test` (단위) | 5건 통과 |
| 09 · Jest (통합) | 4건 통과 |
| **합계** | **276건**, 중복 없이 각각 별도 실행 |

그 외:
- 08은 실제 서버(FastAPI)를 기동한 상태에서 기능/성능 테스트 스크립트를 실행해 4개 시나리오 전부 PASS를 확인했습니다.
- 05는 별도의 pytest 스위트가 없어, Mock LLM Judge(`use_mock=True`)로 평가 파이프라인 전체를 직접 실행해 4가지 집계 방식(simple/weight/cutoff/hybrid)과 도메인별 정책이 각각 다른 PASS/FAIL을 내는지 확인했습니다.
- 07·10(Python)은 실 API 키 없이 전체 모듈 import가 정상 동작하는 것까지 확인했고, 파이프라인 전체 실행은 API 키가 있어야 합니다.

## 4. Test Results

- 위 표의 자동 테스트는 실행 환경이 갖춰진 항목에서 전부 PASS했습니다.
- **테스트 통과가 곧 배포 승인은 아니라는 사례(PRJ_01)**: 내부 파이프라인 자체 평가로는 100점(배포 가능) 판정이 나온 케이스에서도, 별도로 붙인 독립 LLM Judge는 정책 구체성 축을 0점으로 매겨 68~74점으로 재평가했습니다. 라이브 E2E 18건은 18/18 PASS·평균 90.9점이었지만, 독립 Judge 평균은 81.2점으로 배포 기준(95점)에 못 미쳐 최종 판정은 배포 보류(HOLD)였습니다. `pytest 32건 PASS`와 `독립 Judge 평균 81.2점 미달`이 동시에 성립한다는 것 자체가, 자동 테스트 통과와 실제 배포 판정 기준이 다른 층위라는 것을 보여주는 근거로 남겼습니다.

## 5. Validation Findings

공개 포트폴리오의 `Validation Findings · 7`은 아래 7건을 뜻합니다. 제품 코드 결함뿐 아니라 신규 환경에서 재현된 의존성·테스트 용이성·보안 이슈를 포함합니다.

| # | 위치 | 발견 내용 | 처리 결과 |
|---:|---|---|---|
| 1 | 제외한 실습 프로젝트 2개 | `.env.example`에 실제 API 키가 남아 있었음 | 키 값을 제거하고 해당 프로젝트를 공개 범위에서 제외. 저장소 재검색으로 잔여 키 0건 확인 |
| 2 | 01 · `requirements.txt` | `mcp>=1.2`가 호환되지 않는 2.x를 설치해 `fastmcp` import 실패 | `mcp>=1.2,<2.0`으로 제한 후 품질 스위트 32건 PASS |
| 3 | 06 · `requirements.txt` | `chromadb==0.5.23`이 Windows·Python 3.12에서 빌드 실패 | 호환 범위로 조정 후 설치 및 pytest 53건 PASS |
| 4 | 05 · 설정 로더 | 실행 위치에 따라 정책 파일을 못 찾으면 기본 가중치로 조용히 대체되어 점수가 달라짐 | `__file__` 기준 경로와 명시적 예외 처리 적용, 다른 CWD에서 재검증 |
| 5 | 08 · `requirements.txt` | 서버·대시보드·테스트 실행에 필요한 의존성 4종 누락 | 의존성 추가 후 서버·`/metrics`·기능 테스트 재검증 |
| 6 | 09 · `package.json` | `node --test`가 Jest 스펙까지 로드해 `npm test` 실패 | 단위·통합 러너 범위 분리 후 9/9 PASS |
| 7 | 02 · `app/service_agent.py` | LLM 호출을 Mock해도 생성자가 API 키를 먼저 검사해 키 없이 7건 실패 | 더미 키 환경에서 84건 PASS 확인. 키 검사 시점 개선은 Known Limitation으로 유지 |

README 경로 정리, UTF-8 BOM 적용, 중복 산출물 제거, `.gitignore` 보강, Docker 실행 명령 보완은 저장소 정리·재현성 개선으로 별도 수행했으며 위 7건에는 중복 집계하지 않았습니다.

## 6. Fixes Applied

- 의존성 범위를 실행 환경과 호환되는 버전으로 조정
- 노출된 자격 증명 값을 제거하고 공개 범위에서 제외
- 05 설정 로더를 `__file__` 기준 경로와 명시적 예외 처리로 수정
- 08의 누락 의존성을 보강하고 서버·메트릭·기능 테스트 재검증
- 09의 `test:unit`(node:test)과 `test:integration`(Jest)을 분리해 9/9 PASS 확인
- 02는 더미 키 환경에서 Mock 테스트 84건을 검증했으며, 생성자의 키 검사 시점은 미해결 제한으로 명시
- README 경로, 파일 인코딩, 중복 산출물, `.gitignore`, Docker 실행 명령을 별도 정리

## 7. Re-test Results

수정을 적용한 뒤 관련 항목을 다시 실행해 전부 PASS를 재확인했습니다. `Automated Tests` 표의 수치가 이 재검증 이후의 최종 결과입니다.

## 8. Known Limitations

- 02는 LLM 호출을 Mock해도 `ServiceAgent` 생성 시 API 키를 먼저 검사합니다. 이번 84건은 더미 키를 주입해 실행했으며, 키 검사를 실제 호출 시점으로 늦추는 구조 개선은 아직 적용하지 않았습니다.
- 10의 Node 구현부(`edubot.js`)는 당시 정적 코드 검토로 대체했습니다. 09는 이후 Node.js 환경에서 9건을 실행해 전부 통과했습니다.
- 02의 모니터링 스택(Prometheus/Grafana/k6)과 01·06의 Docker Compose 구성은 이번 검증에서 컨테이너로 직접 기동하지 않았습니다.
- 07·10은 실 LLM API 키가 있어야 전체 파이프라인을 끝까지 실행할 수 있어, 모듈 단위 검증까지만 진행했습니다.

## 9. Not Measured

다음 항목은 이 포트폴리오에서 실제로 측정하지 않았고, 임의로 수치를 추정해 넣지 않았습니다.

- PRJ_01 — 수작업 검수 대비 시간 단축률 (수작업 검수 시간 기준선이 없어 비교 불가)
- PRJ_01 — LLM Judge와 사람 평가자 간 일치율 (사람 채점 기준선이 없어 비교 불가)
- PRJ_05 — 실서비스 대량 채점 정확도 (Mock LLM Judge로 파이프라인 동작만 검증했고, 실서비스에 붙여 대량 채점을 돌린 적은 없음)