admin/front 분리

docs/codebase-notes.md

@@ -1,15 +1,43 @@
 # 현재 코드베이스 메모
 
-## 현재 특히 주의할 점
-- `README.md`와 `docs/*.md`는 코드 변경 후 같이 갱신해야 한다. 의심되는 항목은 Controller, `SecurityConfig`, 설정 파일을 기준으로 다시 확인한다.
-- 예시 스케줄러 코드에는 깨진 문자열과 과도한 반복 로그가 보일 수 있으니 관련 수정 시 인코딩과 로그 정책을 함께 점검한다.
-- 테스트 코드가 충분하지 않을 수 있으므로 기능 변경 시 필요한 테스트를 보강한다.
-- 일부 Java 소스와 주석, Swagger 설명에 인코딩이 깨진 문자열이 있으므로 표시 문자열 수정은 영향 범위를 보고 묶어서 처리한다.
-- `application-local.yaml` 은 로컬 실행값이 직접 들어가 있으므로 공유하거나 커밋할 때 민감정보 노출 여부를 한 번 더 확인한다.
-- 파일 업로드는 두 흐름으로 분리되어 있다. `file` 모듈의 단순 업로드는 DB에 기록하지 않고 `uploadPath`, 파일명, 확장자, contentType, size, image width/height 정도만 반환한다. 각 업무 테이블 저장은 호출 측에서 처리한다.
-- SunEditor 이미지 업로드는 API로 파일을 저장하되 응답 URL은 `file.upload.view.file-domain + uploadPath` 로 만든다. 에디터 본문에 저장되는 URL은 admin/user 토큰에 의존하지 않는 file-domain URL이어야 한다.
-- TUS 업로드는 `tusFile` 모듈에서 DB master/detail 기록, upload token 발급, tusd hook 반영, 상태 조회, view/download/delete를 담당한다.
-- TUS 인증 경로는 `/tus/file/upload/auth`, hook 경로는 `/tus/file/hook` 이다. nginx `/_upload_auth`, Spring Security 공개 경로, `tus-file.upload.tus-endpoint` 를 함께 맞춘다.
-- 단순 파일 API는 `/file/upload`, `/file/suneditor/upload`, `/file/view`, `/file/download` 를 사용한다. `/admin/files/...` 또는 `/files/...` 예전 표기가 남아 있으면 최신 경로로 정리한다.
-- file-domain nginx 는 `/uploads/` 를 공개 정적 파일로 열고 `/uploads/tmp/` 는 404로 막는다. TUS 임시 디렉터리는 파일 시스템에서는 사용하지만 URL로 직접 노출하지 않는다.
-- Admin 로그인 상태 확인은 `/admin/auth/loginChecked` 를 사용한다. `/admin/auth/refresh` 는 토큰을 재발급하므로 새로고침 상태 확인용으로 쓰지 않는다.
+## 멀티모듈 이관 상태
+
+- 기존 단일 모듈의 업무 API 이관을 완료하고, 레거시 소스는 저장소에서 제거했습니다.
+- core/admin/front 모듈은 각각 독립 bootJar로 빌드·배포합니다.
+- 이후 신규 기능도 core standard/bespoke와 admin/front 업무 Service 경계를 기준으로 추가합니다.
+
+## 이관 원칙
+
+- 범용적인 단일 테이블 데이터 처리는 `core.modules.standard`에 둡니다.
+- JOIN·집계·복합 SQL 데이터 처리는 `core.modules.bespoke`에 둡니다.
+- admin/front는 Controller, 업무 Service, Form, 화면 VO를 소유합니다.
+- admin/front 업무 Service가 업무 정책과 트랜잭션을 소유하며 core standard/bespoke Service를 조합합니다.
+- Mapper는 core standard/bespoke에 통합하고, Controller는 core Service 또는 Mapper를 직접 호출하지 않습니다.
+- core VO는 내부 업무·조회 결과를 표현하고, admin/front 업무 Service가 필요한 필드만 화면/API 응답 VO로 조립합니다.
+- 비밀번호, refresh token 등 민감 정보는 일반 core VO와 외부 응답 VO에 포함하지 않습니다.
+- core는 화면 전용 VO나 Controller를 소유하지 않습니다.
+
+## 파일과 TUS
+
+- 단순 파일 업로드는 DB 기록 없이 파일을 저장하고 uploadPath를 반환합니다.
+- 일반 file Controller는 admin/front 양쪽에 둘 수 있으며, 저장 구현은 core 공통 기능으로 이관합니다.
+- TUS는 `02-api-admin/modules/tus`의 admin 전용 기능입니다. front에는 TUS Controller나 `tus-file.*` 설정을 두지 않습니다.
+- TUS Controller는 요청 바인딩과 응답만 담당하고, `TusFileService`가 core standard/bespoke Service를 조합합니다.
+- `FILE_MASTER`, `FILE_DETAIL`, 업로드·다운로드 이벤트 로그의 단일 테이블 처리는 core standard를 사용합니다. 토큰 소유권, 완료 파일 목록·조회, 파일 이동 대상 조회, 마스터 집계는 core bespoke `fileDetailTusFile`, `fileMasterTusFile`에 둡니다.
+- 완료 파일의 최종 저장 루트는 일반 업로드와 같은 `file.storage.root-path`입니다. TUS 임시 파일은 admin의 `tus-file.upload.tmp-root`를 사용합니다.
+- TUS 업로드 인증 경로와 Hook 경로만 admin SecurityConfig에서 비인증으로 열고, 나머지 TUS API는 ADMIN 권한을 요구합니다.
+- tusd 실제 Hook, 임시 파일 이동, nginx 파일 제공은 tusd와 file-domain 설정이 준비된 환경에서 통합 검증합니다.
+
+## CORS 동기화
+
+- Dynamic CORS 필터와 캐시는 core를 통해 admin/front 양쪽 JVM에서 동작합니다.
+- CORS 관리 API는 admin에만 둡니다.
+- 허용 Origin 목록은 Redis `alist:cors:allow-origins` 키에 JSON 목록으로 저장합니다.
+- admin에서 정책을 변경하면 트랜잭션 커밋 후 Redis Pub/Sub 채널 `alist:cors:allow-origins:changed`로 갱신 이벤트를 발행합니다.
+- 각 JVM은 해당 채널을 구독해 즉시 Redis 목록을 다시 읽고, 예외 상황에 대비해 60초 주기 Redis 재조회도 수행합니다.
+
+## 주의 사항
+
+- `application-local.yaml`에 민감정보가 있을 수 있으므로 공유와 커밋 전에 확인합니다.
+- Mapper 인터페이스, XML namespace, XML id, DTO resultType/parameterType은 이관 시 함께 변경합니다.
+- 파일 경로 변경은 nginx alias, tusd 경로, API 환경 설정을 함께 확인합니다.