docs(agent): v2 신규 코드 구조 규칙을 보완한다

This commit is contained in:
2026-05-30 16:01:58 +09:00
parent 1ee3b3864c
commit 29a7b8d918
2 changed files with 13 additions and 0 deletions

View File

@@ -25,6 +25,18 @@
### 4) 패키지/코드 배치 규칙
- 기존 로직을 수정하는 경우에는 기존 패키지 구조를 따른다.
- 기존 로직 수정이 아닌 신규 API나 하위 코드는 `kr.co.vividnext.sodalive.v2` 패키지 하위에 작성한다.
- 신규 도메인 또는 신규 기능 패키지 생성 시 `kr.co.vividnext.sodalive.v2` 바로 아래에 도메인 패키지를 먼저 만들고, 그 아래에 경량 헥사고날 아키텍처를 적용한다.
- 클라이언트 공개 API의 화면/클라이언트 맞춤 조립 계층은 `kr.co.vividnext.sodalive.v2.api.{기능}` 하위에 둘 수 있다.
- 여러 API나 내부 기능에서 재사용될 수 있는 도메인 기능은 `kr.co.vividnext.sodalive.v2.{도메인}` 하위에 별도 패키지로 둔다.
- 공개 API 조립 패키지가 재사용 도메인 패키지를 호출하는 방향은 허용하지만, 재사용 도메인 패키지가 공개 API 조립 패키지에 의존하지 않는다.
- 신규 도메인 또는 신규 기능의 기본 패키지 구조는 `application`, `domain`, `port`, `adapter`, `dto`를 사용한다.
- `application`에는 use case, orchestration service, 트랜잭션 경계를 둔다.
- `domain`에는 순수 정책, 점수 계산, 값 객체, 도메인 모델, 스냅샷 모델처럼 인프라 의존이 없는 코드를 둔다.
- `port`에는 application이 필요로 하는 입력/출력 인터페이스를 둔다. 단순 내부 호출까지 억지로 port로 만들지 않는다.
- `adapter`에는 web controller, JPA/QueryDSL persistence, cache, scheduler 등 외부 입출력 구현을 둔다.
- `dto`에는 API 요청/응답 DTO와 adapter 경계에서 사용하는 DTO를 둔다.
- 기존 패키지를 수정하는 작업에는 헥사고날 패키지 구조를 강제로 적용하지 않는다.
- 기존 `kr.co.vividnext.sodalive.v2` 하위 코드가 이미 다른 구조로 작성되어 있으면 해당 작업의 범위 안에서만 기존 구조를 유지하고, 신규 도메인부터 헥사고날 구조를 적용한다.
### 5) 타입/널 처리
- Kotlin 타입 시스템을 활용하고 nullable(`?`)를 명시한다.