동블

그래프 뷰

2026-05-29-CODEX

10 min read

2026-05-29 CODEX 작업 기록

Status: Historical

이 문서는 2026-05-29 당시의 작업 기록입니다. 현재 ZIP:ON의 제품 기준은 /docs/product/PRODUCT_OVERVIEW.md와 /docs/product/MVP_SCOPE.md를 따르고, persistence 기준은 MyBatis Mapper + Flyway migration입니다.

작성자: CODEX

오늘 작업한 내용

  • ZIP:ON 백엔드 Spring MVC 골격을 구성했다.
  • ZIP:ON 프론트엔드 Vue 3 골격과 초기 UI를 구성했다.
  • Controller, Service, 당시 Repository 후보, Domain, DTO, Config, Exception, Common 계층을 만들었다.
  • View, Component, Layout, Router, API module 구조를 만들었다.
  • 학습용 주석을 추가해서 빈 로직을 나중에 직접 채울 수 있게 했다.
  • 프로젝트 구조, 관례, 개선 방법, API와 함수 매핑, 성장 로드맵 문서를 작성했다.
  • 개인별 날짜 기록 폴더를 추가했다.

오늘 배운 점과 설계 판단

1. 프로젝트명은 화면과 문서에서는 ZIP:ON, 코드 식별자에서는 ZipOn 또는 zipon을 쓴다

ZIP:ON의 콜론은 브랜드 표기에는 좋지만 Java package, class, 일부 경로 이름에는 적합하지 않다.

그래서 아래 기준을 세웠다.

브랜드 표기: ZIP:ON
Java class: ZipOnApplication
Java package: com.zipon
Maven artifact/name 후보: zipon 또는 ZIP:ON
프론트 package name: zipon-frontend

2. 초기 골격이어도 규모를 작게 설계하면 안 된다

사용자는 최종적으로 부동산 관련 최고의 서비스를 만들고 싶다고 했다. 따라서 오늘은 로직을 비우더라도 도메인 경계는 작게 접지 않았다.

현재부터 분리한 도메인:

Search
Region
Property
Transaction
Map
Environment
Favorite
Community
User
Admin 후보
Recommendation 후보
Report 후보
Alert 후보

3. Controller는 Service로 위임하는 흐름을 유지해야 한다

/api/environment/facilities는 처음에 Controller에서 바로 List.of()를 반환했다. 하지만 다른 API와 달리 Service를 거치지 않으면 학습 흐름이 어긋난다.

해결:

EnvironmentController.getFacilityList()
-> EnvironmentService.getFacilityList()
-> frontend environmentApi.getFacilityList()

이렇게 맞춰서 Controller → Service → Front API 함수 대응이 유지되도록 수정했다.

트러블 슈팅 기록

1. 문제: 기존 이름 EstatePro가 남아 있으면 팀원이 헷갈릴 수 있음

원인:

초기 요청에는 EstatePro라는 이름이 있었지만, 이후 사용자가 프로젝트명은 ZIP:ON이라고 정정했다.

해결:

rg -n "EstatePro|estatepro|ESTATEPRO" .

검색으로 잔여 이름을 확인했고, 소스 기준으로 ZIP:ON / zipon / ZipOn만 남도록 정리했다.

다음에 같은 문제가 생기면:

프로젝트명 변경은 class, package, pom, package.json, README, 화면 문구, 테스트 경로까지 함께 검색한다.

2. 문제: 백엔드 기본 8080 포트가 이미 사용 중일 수 있음

원인:

작업 환경에 다른 Java 서비스가 8080 포트를 쓰고 있었다.

해결:

ZIP:ON 백엔드는 8082를 사용하도록 두고, README에도 개발 포트를 명시했다.

다음에 같은 문제가 생기면:

포트 충돌은 서버 오류라기보다 실행 환경 문제일 수 있으므로, 먼저 사용 중인 포트와 실행 중인 세션을 확인한다.

3. 문제: 빌드 산출물에 예전 이름이 남아 있을 수 있음

원인:

backend/target에는 이전 컴파일 결과나 테스트 리포트가 남을 수 있다. 소스에서는 이름을 바꿔도 산출물에는 예전 문자열이 잠시 남는다.

해결:

./mvnw clean test

clean으로 산출물을 삭제한 뒤 다시 테스트해서 예전 흔적을 제거했다.

다음에 같은 문제가 생기면:

소스 검색과 산출물 검색을 구분한다. 산출물 문제라면 clean build가 먼저다.

4. 문제: 문서가 많아지면서 개인 기록과 프로젝트 참고 문서가 섞임

원인:

처음에는 docs 루트에 구조 설명 문서를 바로 두었다. 이후 사용자가 docs 안에 우동균, 손정민, CODEX 기록 폴더가 필요하다고 요청했다.

해결:

프로젝트 참고 문서는 docs/archive/CODEX_README.md로 옮기고, 날짜별 작업 기록은 각자 폴더에 두는 방식으로 정리했다.

다음에 같은 문제가 생기면:

docs에는 목적이 다른 문서가 섞이기 쉽다. 개인 기록, 팀 참고 문서, API 명세, 회의록은 폴더 기준을 먼저 정한다.

5. 문제: “초기 골격”과 “큰 서비스”라는 요구가 충돌해 보일 수 있음

원인:

초기 골격이라고 하면 흔히 기능을 줄이고 파일 수도 줄이려고 한다. 하지만 사용자는 이후 수많은 API와 기능을 합칠 계획이다.

해결:

오늘은 비즈니스 로직은 비우되 도메인과 API 자리는 넓게 잡았다. 또한 /docs/product/ROADMAP.md에 장기 확장 후보를 기록했다.

다음에 같은 문제가 생기면:

작게 만드는 것과 비워두는 것은 다르다. 학습 단계에서는 로직은 비우되, 확장 가능한 자리와 이름은 충분히 잡는다.

오늘 추가한 문서

  • /docs/architecture/BACKEND_STRUCTURE.md
  • /docs/api/API_FUNCTION_MAP.md
  • /docs/architecture/CONVENTIONS.md
  • /docs/operations/IMPROVEMENT_CHECKLIST.md
  • /docs/LEARNING_PATH.md
  • /docs/product/ROADMAP.md
  • docs/우동균/2026-05-29.md
  • docs/손정민/2026-05-29.md
  • docs/CODEX/2026-05-29.md

현재 상태 메모 (2026-06-12): 이 목록은 당시 작업 기록이다. 현재 checkout에는 docs/우동균/2026-05-29.md와 docs/손정민/2026-05-29.md가 없으므로, 현재 문서 탐색은 루트 README.md와 /docs/README.md를 기준으로 한다.

다음에 기록할 것

  • 더미 데이터 연결 시 domain object와 DTO 변환 과정
  • MyBatis Mapper 메서드 이름과 SQL 책임을 정하는 기준
  • API 응답 형식을 바꾸게 되는 이유
  • Vue에서 View와 Component 책임을 나누는 기준
  • 실제 오류가 발생했을 때 원인 추적 순서

추가 작업 기록: study 폴더 구축

문제

사용자가 docs와 별도로 개념별 학습 자료가 필요하다고 요청했다. 특히 Spring Boot를 깊게 배우고 싶고, 학습 자료는 공식 문서급 정확도를 가져야 한다고 했다.

판단

docs는 날짜별 작업 기록과 트러블 슈팅 공간으로 이미 역할이 정해졌다. 따라서 개념별 교재는 study 폴더로 분리하는 것이 좋다고 판단했다.

해결

아래 주제별 폴더를 만들었다.

study/Spring
study/Web
study/Vue
study/Database
study/Architecture
study/BuildTools

각 학습 파일에는 개념 정의, 필요한 이유, ZIP:ON 연결 지점, 실습 미션, 공식 출처를 포함했다.

현재 상태 메모 (2026-06-12): 현재 checkout에서 확인되는 study 문서는 docs/study/Architecture/03-how-to-add-feature.md이다. study/Spring, study/Web, study/Vue, study/Database, study/Architecture, study/BuildTools 경로는 현재 루트에 존재하지 않는다.

공식 출처 기준

당시에는 Spring, Spring Boot, Spring Data JPA를 docs.spring.io 공식 문서 기준으로 정리했다. 현재 persistence 학습 경로는 MyBatis와 Flyway 기준으로 바뀌었으므로, 최신 학습 자료는 docs/study/Database/README.md와 docs/study/SOURCES.md를 따른다.

다음에 같은 요구가 생기면

날짜별 기록은 docs, 개념별 학습 자료는 study, 프로젝트 구조 참고 문서는 docs/archive/CODEX_README.md처럼 문서의 사용 목적을 먼저 나눈다.

추가 검증

학습 자료에 들어간 공식 출처 링크가 깨지면 자료 신뢰도가 떨어지므로, study, README.md, CODEX 기록에 포함된 URL을 모아 HTTP 상태를 확인했다.

결과:

Spring 공식 문서 링크 200
Spring Data JPA 공식 문서 링크 200 (당시 기록)
Spring Framework 공식 문서 링크 200
MDN HTTP 문서 링크 200
Vue 공식 문서 링크 200
Vue Router 공식 문서 링크 200
Vite 공식 문서 링크 200
Axios 문서 링크 200

다음에 같은 작업을 할 때도 자료 작성 후 링크 검증을 함께 수행한다.

관련 문서

백링크