refs #741 #742: reorganize repository by application

docs/design/742-application-oriented-repository-layout/README.md

@@ -0,0 +1,112 @@
+# #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 스키마와 운영 데이터는 이 구조 변경에서 수정하지 않는다.