#742 애플리케이션 단위 저장소 구조 개편

문제

현재 저장소 루트의 pom.xml, src/main, src/test는 실제로 하나의 Spring Boot 백오피스지만 제품 폴더 없이 저장소 전체 애플리케이션처럼 보인다. Streamlit 앱은 poc4_active_source_20260714라는 날짜 스냅샷 폴더에 있고 내부에서도 poc3, poc4, agent_console, 단독 Python 모듈이 서로 참조한다.

이 구조에서는 다음 내용을 파일 경로만 보고 알 수 없다.

어떤 파일이 실제 배포 애플리케이션인지
Spring Boot와 Streamlit의 빌드·테스트 경계가 어디인지
poc3, poc4가 제품명인지 과거 실험 번호인지
DB 스크립트와 특정 애플리케이션의 관계가 무엇인지

목표 구조

vpd-permission-poc/
├── vpd-backoffice/              Spring Boot VPD·권한 관리 백오피스
│   ├── pom.xml
│   ├── src/main/
│   └── src/test/
├── ai-web-agent-console/        Streamlit AI 업무 에이전트
│   ├── app.py
│   ├── ai_web_agent_console/    단일 Python 패키지
│   ├── config/
│   ├── tests/
│   └── requirements.txt
├── dds-backoffice/              별도 DDS 백오피스
├── database/
│   ├── adb/
│   └── source/
├── deploy/                      제품별 배포 설정
├── docs/                        설계·운영·검증 문서
├── scripts/                     저장소 공통 자동화
└── README.md

이동 매핑

기존	변경	처리
`pom.xml`	`vpd-backoffice/pom.xml`	Maven 프로젝트 경계 명시
`src/main`	`vpd-backoffice/src/main`	Spring 애플리케이션 소스
`src/test`	`vpd-backoffice/src/test`	Spring 단위·통합 테스트
`sql/adb`	`database/adb`	Oracle/ADB 스크립트
`sql/source`	`database/source`	외부 원천 DB 스크립트
`poc4_active_source_20260714`	`ai-web-agent-console`	날짜·PoC 번호 제거
`apps/poc4/mcp_discovery_ui.py`	`ai-web-agent-console/app.py`	명확한 Streamlit 진입점
`src/agent_console/*`	`ai-web-agent-console/ai_web_agent_console/*`	단일 제품 패키지
`src/poc3/model_registry.py`	`ai-web-agent-console/ai_web_agent_console/model_registry.py`	실험 번호 제거
`src/poc3/questions.py`	`ai-web-agent-console/ai_web_agent_console/questions.py`	실험 번호 제거
`src/poc4/scenarios.py`	`ai-web-agent-console/ai_web_agent_console/scenarios.py`	실험 번호 제거
`src/poc4/query_contracts.py`	`ai-web-agent-console/ai_web_agent_console/query_contracts.py`	실험 번호 제거
`src/mcp_*.py`, `src/oci_genai_sdk.py`	`ai-web-agent-console/ai_web_agent_console/`	앱 전용 공용 모듈 통합
`config/poc3_model_profiles.json`	`ai-web-agent-console/config/model_profiles.json`	실험 번호 제거

경로 규칙

저장소 루트에는 애플리케이션 프레임워크의 src나 pom.xml을 두지 않는다.
각 애플리케이션은 자신의 소스, 의존성 선언, 테스트 진입점을 가진다.
DB 스크립트는 database를 Git 원본으로 사용하고 Spring JAR는 해당 경로를 리소스로 포함한다.
배포 설정은 deploy/<application>에서 새 소스 경로를 참조한다.
과거 경로를 유지하는 심볼릭 링크나 복제본은 만들지 않는다. 잘못된 경로가 다시 사용되면 테스트가 실패하도록 한다.
운영 중인 환경변수와 SQLite 테이블명은 데이터 호환을 위해 이번 변경에서 유지한다. 폴더·패키지·실행 경로에서만 PoC 명칭을 제거한다.

Maven 변경

vpd-backoffice/pom.xml의 SQL 리소스 경로는 ../database/adb를 사용한다. 루트 자동화는 mvn -f vpd-backoffice/pom.xml을 사용하며 앱 디렉토리 안에서는 기존처럼 mvn test가 동작해야 한다.

Java 테스트에서 파일을 직접 여는 경로는 앱 디렉토리를 기준으로 유지한다. 따라서 vpd-backoffice에서 실행한 테스트와 루트에서 -f로 실행한 테스트를 모두 확인한다.

Python 변경

ai-web-agent-console/app.py는 자신의 부모 폴더를 애플리케이션 루트로 사용한다. 모든 import는 ai_web_agent_console.<module> 형식으로 통일한다. 테스트도 같은 공개 패키지 경로만 사용한다.

model_profiles.json 안의 default_for_poc3 속성은 default_for_console로 바꾸고 로더·검증 코드도 함께 변경한다. 배포된 비밀정보 파일과 대화 DB는 Git 이동 대상이 아니다.

배포 변경

Spring 배포 빌드는 vpd-backoffice/pom.xml과 vpd-backoffice/target을 사용한다.
Streamlit 실행은 streamlit run app.py를 사용한다.
인증 게이트웨이는 python -m ai_web_agent_console.auth_gateway를 사용한다.
기존 운영 디렉토리 /opt/hmm-poc4는 무중단 전환을 위해 물리 경로로 유지할 수 있지만, 서비스의 Git 소스 경로와 Python 모듈명은 새 구조를 사용한다.

검증

git status --short에서 기존 #741 변경이 새 경로에 남아 있는지 확인한다.
mvn -f vpd-backoffice/pom.xml test를 실행한다.
Python 전체 소스에 compileall을 실행한다.
unittest discover -s ai-web-agent-console/tests를 실행한다.
rg로 운영 코드의 src.poc3, src.poc4, src.agent_console, poc4_active_source_20260714, apps/poc4 참조가 0건인지 확인한다.
배포 스크립트의 dry-run 또는 정적 경로 검증을 수행한다.

롤백

모든 이동은 한 Git 커밋으로 추적한다. 문제가 생기면 해당 커밋을 revert하여 이전 경로와 import를 함께 복구한다. DB 스키마와 운영 데이터는 이 구조 변경에서 수정하지 않는다.