# #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 스크립트와 특정 애플리케이션의 관계가 무엇인지

## 목표 구조

```text
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` | 실험 번호 제거 |

## 경로 규칙

1. 저장소 루트에는 애플리케이션 프레임워크의 `src`나 `pom.xml`을 두지 않는다.
2. 각 애플리케이션은 자신의 소스, 의존성 선언, 테스트 진입점을 가진다.
3. DB 스크립트는 `database`를 Git 원본으로 사용하고 Spring JAR는 해당 경로를
   리소스로 포함한다.
4. 배포 설정은 `deploy/<application>`에서 새 소스 경로를 참조한다.
5. 과거 경로를 유지하는 심볼릭 링크나 복제본은 만들지 않는다. 잘못된 경로가 다시
   사용되면 테스트가 실패하도록 한다.
6. 운영 중인 환경변수와 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 모듈명은 새 구조를 사용한다.

## 검증

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

## 롤백

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