docs: ko excessive-entities page (#894)

Author: Gaic4o

i18n/kr/docusaurus-plugin-content-docs/current/guides/issues/excessive-entities.md

@@ -0,0 +1,162 @@
+---
+sidebar_position: 4
+pagination_next: reference/layers
+---
+
+# Excessive Entities
+
+Feature-Sliced Design에서 `entities` Layer는 하위 Layer에 속하며, 재사용 가능한 도메인(비지니스) 로직을 담는 곳입니다.  
+이 Layer는 접근성이 높아서, `shared`를 제외한 거의 모든 Layer가 `entities`를 참조할 수 있어 접근 범위가 넓습니다.
+
+다만 접근성이 높은 만큼 주의할 점도 있습니다.  
+`entities`에 코드가 추가/수정되거나 파일 경로가 바뀌면, 상위 Layer의 여러 Slice에서 그 변경을 함께 따라가야 할 수 있습니다.   
+그래서 리팩토링 비용이 커지기 전에, `entities`는 특히 경계와 역할을 더 명확하게 정의하고 관리하는 편이 좋습니다.
+
+`entities`에 코드가 불필요하게 많이 쌓이면 보통 다음 문제가 같이 나타납니다.
+
+- **경계가 모호해집니다**: “이 로직을 `entities`에 두는 게 맞나?” 같은 판단이 계속 필요해집니다. 
+- **결합도가 올라갑니다**: 여러 도메인이 서로 얽히면서 수정이 어려워집니다.
+- **Import 딜레마가 생깁니다**: 코드가 동일 Layer의 다른 entity Slice로 흩어지면서, Import가 복잡해지고 선택이 어려워집니다.
+
+## How to keep `entities` Layer clean
+
+### 0. `entities` Layer 없이 시작하는 것도 가능합니다
+
+`entities` Layer를 만들지 않으면 FSD가 아니라고 생각하기 쉽지만, 그렇지 않습니다.  
+애플리케이션에 `entities` Layer가 없어도 FSD 규칙이 깨지지 않습니다.  
+오히려 구조가 단순해지고, 나중에 규모가 커졌을 때 `entities`를 도입할 수 있도록 확장성을 확보할 수 있습니다.
+
+예를 들어 애플리케이션이 **thin client**에 가깝다면, 대부분 `entities` Layer가 필요하지 않습니다.
+
+:::info[What are thick and thin clients?]
+
+thick client와 thin client의 구분은 “데이터 처리와 비즈니스 로직을 어디서 처리하느냐”를 기준으로 합니다.
+
+- **thin client**: 대부분의 처리를 백엔드에서 수행합니다. 클라이언트에서는 비즈니스 로직을 최소화하고, 주로 백엔드와 데이터를 주고받습니다.
+- **thick client**: 클라이언트에서 의미 있는 비즈니스 로직을 많이 처리합니다. 이런 경우 `entities` Layer를 두면 도메인 로직을 구조적으로 정리하기가 더 수월합니다.
+
+이 구분은 딱 둘 중 하나로만 나뉘지 않습니다.  
+같은 애플리케이션이라도 일부는 thick client처럼, 다른 일부는 thin client처럼 동작할 수 있습니다.
+
+:::
+
+### 1. Slice를 처음부터 잘게 나누지 않습니다
+
+FSD 2.1은 Slice를 미리 잘게 쪼개기보다, 필요해졌을 때 분리하는 접근을 권장합니다.   
+이 원칙은 `entities` Layer에도 그대로 적용됩니다.
+
+처음에는 다음처럼 시작해도 됩니다.
+
+1. page 또는 widget/feature Slice의 `model` Segment에 로직을 둡니다.
+2. 요구사항이 어느 정도 안정되고, “이 로직은 여러 곳에서 재사용된다”가 분명해졌을 때 `entities`로 옮기는 리팩토링을 고려합니다. 
+
+여기서 중요한 점은 "언제 옮기느냐"입니다.  
+코드를 `entities`로 옮기는 시점이 늦을수록, 리팩토링 리스크가 줄어듭니다. 
+`entities`의 코드는 `shared`를 제외한 모든 Layer에서 쓰일 수 있어서, 변경이 여러 곳의 동작에 영향을 줄 수 있기 때문입니다.
+
+### 2. 불필요한 Entities를 만들지 않습니다
+
+비즈니스 로직이 있다고 해서 항상 entity를 만들어야 하는 것은 아닙니다.  
+먼저 `shared/api`의 타입을 활용하고, 로직은 현재 Slice의 `model` Segment에 두는 방식을 우선 고려합니다.
+
+재사용 가능한 비즈니스 로직이 정말 필요하다면, 다음처럼 역할을 나누는 편이 좋습니다.
+
+- 데이터 정의(예: 백엔드 응답 타입)는 `shared/api`에 둡니다.
+- 재사용 로직은 entity Slice의 `model` Segment에 둡니다.
+
+
+```plaintext
+📂 entities
+  📂 order
+    📄 index.ts
+    📂 model
+      📄 apply-discount.ts // Business logic using OrderDto from shared/api
+📂 shared
+  📂 api
+    📄 index.ts
+    📂 endpoints
+      📄 order.ts
+```
+
+### 3. CRUD는 `entities`에 두지 않는 편이 좋습니다
+
+CRUD는 필수지만, 많은 경우 비즈니스 의미가 크지 않은 반복 코드가 됩니다.  
+이런 코드가 `entities`에 쌓이면 Layer가 지저분해지고, 중요한 로직이 눈에 잘 띄지 않게 됩니다.
+
+```plaintext
+📂 shared
+  📂 api
+    📄 client.ts
+    📄 index.ts
+    📂 endpoints
+      📄 order.ts // Contains all order-related CRUD operations
+      📄 products.ts
+      📄 cart.ts
+```
+
+대신 CRUD는 `shared/api`에 둡니다.
+
+CRUD가 단순 호출 수준을 넘어, 예를 들어 여러 요청을 묶어서 일관성을 보장해야 하거나, 실패 시 rollback, transaction 같은 처리가 필요한 경우에는 `entities`가 맞는지 다시 판단할 수 있지만, 신중하게 적용하는 편이 좋습니다.
+
+### 4. 인증 데이터는 `shared`에 둡니다
+
+토큰이나 로그인 응답에 포함된 사용자 DTO처럼 인증 과정에서만 쓰이는 데이터는 `user` entity를 만들기보다 `shared`에 두는 편이 좋습니다.  
+이 데이터는 인증 Context에 종속적이며, 인증 범위를 벗어나 재사용될 가능성이 낮습니다.
+
+- 로그인 응답은 상황에 따라 포함하는 정보가 달라질 수 있습니다(예: 공개/비공개 프로필).
+- 이런 데이터를 entity로 올려버리면, 다른 곳에서 재사용하려다가 `shared`와 `entities` 사이 의존 관계가 꼬이거나,   
+cross-import를 표시하기 위한 `@x` 사용이 늘면서 구조가 더 복잡해질 수 있습니다.
+
+따라서 인증과 직접 관련된 데이터는 `shared/auth` 또는 `shared/api`에 두는 방식을 권장합니다.
+
+
+```plaintext
+📂 shared
+  📂 auth
+    📄 use-auth.ts // authenticated user info or token
+    📄 index.ts
+  📂 api
+    📄 client.ts
+    📄 index.ts
+    📂 endpoints
+      📄 order.ts
+```
+
+인증 구현은 [Authentication 가이드](/docs/guides/examples/auth)를 참고하세요.
+
+### 5. Cross-import를 최소화합니다
+
+FSD는 `@x` 표기를 통해 cross-import를 허용하지만, 이 방식은 기술적 문제(예: 순환 의존)를 만들 수 있습니다.  
+이를 피하려면 entity를 서로 섞이지 않게 분리된 도메인 단위로 설계해 cross-import 자체가 필요 없도록 만드는 편이 좋습니다.
+
+예를 들어 주문 아이템, 고객 정보처럼 항상 함께 움직이는 로직이 있다면, 이를 여러 entity로 쪼개기보다 order-info 같은 하나의 entity slice(모듈) 안에 캡슐화하는 방식이 더 낫습니다.
+
+
+**Non-Isolated Business Context (Avoid):**
+
+```plaintext
+📂 entities
+  📂 order
+    📂 @x
+    📂 model
+  📂 order-item
+    📂 @x
+    📂 model
+  📂 order-customer-info
+    📂 @x
+    📂 model
+```
+
+**Isolated Business Context (Preferred):**
+
+```plaintext
+📂 entities
+  📂 order-info
+    📄 index.ts
+    📂 model
+      📄 order-info.ts
+```
+
+이렇게 하면 관련 코드가 한 곳에 모여 구조가 단순해지고, 강하게 결합된 로직이 여러 모듈로 흩어져 생기는 **변경 여파**도 줄일 수 있습니다.   
+또한 강하게 결합된 로직을 외부에서 수정/변경해야 하는 상황을 줄일 수 있습니다.
+