frontend/apps/_template/src/entities/README.md

Entities Layer

Entities는 프로젝트가 다루는 실제 비즈니스 개념을 나타내는 레이어입니다. 비즈니스에서 제품을 설명할 때 사용하는 용어들(예: User, Product, Order)이 주로 엔티티가 됩니다.

목적

• 비즈니스 엔티티의 데이터 모델 및 타입 정의
• 엔티티 관련 API 요청 함수 관리
• 엔티티의 시각적 표현 제공 (재사용 가능한 UI)
• 여러 페이지에서 동일한 외관을 재사용할 수 있도록 지원

구조

각 엔티티 슬라이스는 다음 세그먼트로 구성됩니다:

entities/
└── [entity-name]/
    ├── model/         # 데이터 저장소, 검증 스키마, 상태 관리
    ├── api/           # 엔티티 관련 API 요청 함수
    ├── ui/            # 엔티티 시각적 표현 (선택적)
    ├── lib/           # 엔티티 관련 유틸리티 (선택적)
    ├── @x/            # 다른 엔티티로부터의 cross-import용 Public API (선택적)
    └── index.ts       # Public API

세그먼트 설명

• model: 데이터 모델, 타입 정의, 상태 저장소 (Zustand 등)
• api: 백엔드 API 호출 함수
• ui: 엔티티를 표시하는 UI 컴포넌트 (완전한 UI 블록이 아니라 재사용 가능한 표현)
• lib: 엔티티 관련 유틸리티 함수
• @x: 다른 엔티티가 이 엔티티를 import할 때 사용하는 명시적 cross-import API
• index.ts: 슬라이스의 Public API (외부에서 사용할 수 있는 것만 export)

예시

// entities/user/model/user.ts
export interface User {
  id: string;
  name: string;
  email: string;
  role: 'admin' | 'user';
}

// entities/user/api/get-user.ts
import type { User } from '../model/user';

export async function getUser(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  return response.json();
}

// entities/user/ui/user-card.tsx
import type { User } from '../model/user';

interface UserCardProps {
  user: User;
  onClick?: () => void;
}

export function UserCard({ user, onClick }: UserCardProps) {
  return (
    <div onClick={onClick}>
      <h3>{user.name}</h3>
      <p>{user.email}</p>
    </div>
  );
}

// entities/user/index.ts
export { type User } from './model/user';
export { getUser } from './api/get-user';
export { UserCard } from './ui/user-card';

엔티티 간 관계

엔티티가 서로 연결되어 있을 때는 @x 표기법을 사용하여 명시적으로 cross-import를 관리하는 것이 권장됩니다:

// entities/artist/model/artist.ts
import type { Song } from 'entities/song/@x/artist';

export interface Artist {
  name: string;
  songs: Array<Song>;
}

// entities/song/@x/artist.ts
export type { Song } from '../model/song';

@x 폴더를 사용하면 엔티티 간 연결을 명확하게 만들어 함께 리팩터링이 필요한 코드를 쉽게 찾을 수 있습니다.

레이어 의존성 규칙

✅ 허용되는 의존성:

• shared 레이어의 모듈
• 같은 엔티티 슬라이스 내의 다른 세그먼트
• 다른 엔티티 슬라이스 (필요한 경우, @x 표기법 권장)

❌ 금지된 의존성:

• features 레이어
• widgets 레이어
• pages 레이어
• app 레이어

주의사항

1. UI 컴포넌트는 완전한 비즈니스 로직을 포함하지 않음: UI는 주로 props나 slots를 통해 다양한 비즈니스 로직을 연결할 수 있도록 설계
2. 엔티티 간 비즈니스 로직은 상위 레이어에: 엔티티 간 상호작용의 비즈니스 로직은 Features나 Pages 레이어에서 처리
3. 데이터 관리에 집중: 복잡한 비즈니스 로직보다는 데이터 모델, 검증, 저장에 집중