비영리 스타트업의 아키텍처 설계기 — TDD와 DDD로 비즈니스를 코드로 번역하는 여정

┌─────────────────────────────────────────────────────────────────┐
│                    TDD + DDD 선순환                               │
│                                                                 │
│   ┌─────────────┐                      ┌─────────────┐          │
│   │ 비즈니스    │──── 요구사항을 ────►│  테스트             │          │
│   │ 요구사항    │     테스트로 표현    │  (Spec)           │          │
│   └─────────────┘                      └──────┬──────┘          │
│         ▲                                     │                 │
│         │                                     │ 테스트가          │
│         │ 도메인 모델이                          │ 도메인 설계를       │
│         │ 요구사항을 반영                         │ 이끈다            │
│         │                                     ▼                 │
│   ┌─────┴───────┐                      ┌─────────────┐          │
│   │ 도메인        │◄─── 테스트 통과를 ───   │  도메인       │          │
│   │ 모델         │      위한 구현         │  구현         │          │
│   └─────────────┘                      └─────────────┘          │
│                                                                 │
│   "테스트 이름이 곧 비즈니스 명세서다"                                   │
└─────────────────────────────────────────────────────────────────┘

describe('Email Value Object', () => {
  describe('생성', () => {
    it('올바른 이메일 형식이면 Email을 생성한다', () => {
      // Given
      const validEmail = 'user@example.com';
      // When
      const result = Email.create(validEmail);
      // Then
      expect(result.isSuccess).toBe(true);
      expect(result.getValue().value).toBe(validEmail);
    });
    it('이메일 형식이 올바르지 않으면 실패한다', () => {
      // Given
      const invalidEmail = 'not-an-email';
      // When
      const result = Email.create(invalidEmail);
      // Then
      expect(result.isFailure).toBe(true);
      expect(result.getError()).toBe('올바른 이메일 형식이 아닙니다');
    });
    it('이메일이 비어있으면 실패한다', () => {
      const result = Email.create('');
      expect(result.isFailure).toBe(true);
    });
  });
});

1. 테스트 먼저 작성 (TDD)
   └─ 비즈니스 요구사항을 테스트로 표현
2. 도메인 모델 구현
   └─ 테스트를 통과하기 위한 최소한의 구현
3. 유스케이스 구현
   └─ 도메인 모델을 조합한 비즈니스 흐름
4. 인프라 구현
   └─ Repository 구현체, 외부 API 연동 등

// CounselRequest 도메인 모델 (일부)
class CounselRequest {
  private status: CounselRequestStatus;
  // 상태 전이 메서드 - 비즈니스 규칙 캡슐화
  public requestRecommendation(): Result<void, DomainError> {
    if (this.status !== CounselRequestStatus.PENDING) {
      return Result.fail(
        new InvalidStatusTransitionError('PENDING 상태에서만 추천을 요청할 수 있습니다')
      );
    }
    this.status = CounselRequestStatus.RECOMMENDATION_REQUESTED;
    this.addDomainEvent(new RecommendationRequestedEvent(this.id));
    return Result.ok();
  }
  public complete(): Result<void, DomainError> {
    if (this.status !== CounselRequestStatus.IN_PROGRESS) {
      return Result.fail(
        new InvalidStatusTransitionError('진행 중인 상담만 완료할 수 있습니다')
      );
    }
    this.status = CounselRequestStatus.COMPLETED;
    this.addDomainEvent(new CounselCompletedEvent(this.id));
    return Result.ok();
  }
}

describe('CounselRequest 상태 전이', () => {
  it('PENDING 상태에서 추천을 요청하면 RECOMMENDATION_REQUESTED로 전이된다', () => {
    // Given
    const request = CounselRequest.create({ /* ... */ }).getValue();
    
    // When
    const result = request.requestRecommendation();
    
    // Then
    expect(result.isSuccess).toBe(true);
    expect(request.status).toBe(CounselRequestStatus.RECOMMENDATION_REQUESTED);
  });
  it('PENDING이 아닌 상태에서 추천을 요청하면 실패한다', () => {
    // Given
    const request = createMatchedRequest(); // MATCHED 상태
    
    // When
    const result = request.requestRecommendation();
    
    // Then
    expect(result.isFailure).toBe(true);
  });
  it('COMPLETED 상태에서는 취소할 수 없다', () => {
    // Given
    const request = createCompletedRequest();
    
    // When
    const result = request.cancel();
    
    // Then
    expect(result.isFailure).toBe(true);
    expect(result.getError().message).toContain('완료된 상담은 취소할 수 없습니다');
  });
});

Presentation → Application → Domain ← Infrastructure

src/
├── domain/                         # 순수 비즈니스 로직
│   ├── common/
│   │   ├── result.ts              # Result<T, E> 타입
│   │   ├── aggregate-root.ts      # Aggregate Root 베이스
│   │   └── domain-event.ts        # Domain Event 인터페이스
│   ├── user/
│   │   ├── model/
│   │   │   ├── user.ts            # User Aggregate Root
│   │   │   └── value-objects/
│   │   │       ├── email.vo.ts
│   │   │       ├── password.vo.ts
│   │   │       └── user-role.vo.ts
│   │   ├── repository/
│   │   │   └── user.repository.ts # 인터페이스만!
│   │   └── events/
│   │       └── user-registered.event.ts
│   └── counsel-request/
│       ├── model/
│       │   └── counsel-request.ts
│       └── repository/
│           └── counsel-request.repository.ts
│
├── application/                    # 유스케이스
│   ├── auth/
│   │   ├── use-cases/
│   │   │   ├── register-user/
│   │   │   │   ├── register-user.use-case.ts
│   │   │   │   └── register-user.use-case.spec.ts  # 테스트!
│   │   │   └── login/
│   │   │       ├── login.use-case.ts
│   │   │       └── login.use-case.spec.ts
│   │   └── dto/
│   └── counsel/
│       └── use-cases/
│           └── request-recommendation/
│
├── infrastructure/                 # 기술 구현체
│   ├── persistence/
│   │   └── typeorm/
│   │       ├── entity/
│   │       │   └── user.entity.ts # TypeORM Entity
│   │       ├── repository/
│   │       │   └── user.repository.impl.ts  # 구현체
│   │       └── mapper/
│   │           └── user.mapper.ts # Domain ↔ Entity 변환
│   └── external/
│       └── recommendation-ai/
│
└── presentation/                   # API 계층
    ├── auth/
    │   ├── auth.controller.ts
    │   └── auth.module.ts
    └── counsel/

// Domain Layer - 인터페이스
// I prefix 사용 금지 (TypeScript/NestJS 표준)
export interface UserRepository {
  findById(id: UserId): Promise<User | null>;
  findByEmail(email: Email): Promise<User | null>;
  save(user: User): Promise<void>;
}
// Infrastructure Layer - 구현체
// Impl suffix 사용 (Google, Netflix, Uber 표준)
// TypeOrm, Mongo 등 기술명 제외 (프레임워크 독립성)
export class UserRepositoryImpl implements UserRepository {
  constructor(
    @InjectRepository(UserEntity)
    private readonly ormRepository: Repository<UserEntity>,
  ) {}
  async findById(id: UserId): Promise<User | null> {
    const entity = await this.ormRepository.findOne({ 
      where: { id: id.value } 
    });
    return entity ? UserMapper.toDomain(entity) : null;
  }
  
  // ...
}

// 나쁜 예: 원시값 사용
interface UserProps {
  email: string;        // 아무 문자열이나 가능
  password: string;     // 유효성 검증이 어디서?
  phoneNumber: string;  // 형식이 맞는지 어떻게 알지?
}
// 이메일 검증 로직이 여기저기 흩어짐
function validateEmail(email: string): boolean {
  // ...
}
// 컨트롤러에서도 검증
// 서비스에서도 검증
// 어디서 검증 빠뜨리면 버그 발생

// 좋은 예: Value Object
export class Email {
  private readonly _value: string;
  private constructor(value: string) {
    this._value = value;
  }
  // 정적 팩토리 메서드 - 생성 시점에 검증
  public static create(value: string): Result<Email, string> {
    if (!value || value.trim().length === 0) {
      return Result.fail('이메일은 필수입니다');
    }
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    if (!emailRegex.test(value)) {
      return Result.fail('올바른 이메일 형식이 아닙니다');
    }
    return Result.ok(new Email(value.toLowerCase().trim()));
  }
  get value(): string {
    return this._value;
  }
  // 값 객체는 값으로 비교
  public equals(other: Email): boolean {
    return this._value === other._value;
  }
}

describe('Email Value Object', () => {
  // 성공 케이스
  describe('유효한 이메일', () => {
    it('일반적인 이메일 형식이면 생성에 성공한다', () => {
      const result = Email.create('user@example.com');
      expect(result.isSuccess).toBe(true);
    });
    it('이메일을 소문자로 정규화한다', () => {
      const result = Email.create('User@Example.COM');
      expect(result.getValue().value).toBe('user@example.com');
    });
    it('앞뒤 공백을 제거한다', () => {
      const result = Email.create('  user@example.com  ');
      expect(result.getValue().value).toBe('user@example.com');
    });
  });
  // 실패 케이스
  describe('유효하지 않은 이메일', () => {
    it('빈 문자열이면 실패한다', () => {
      const result = Email.create('');
      expect(result.isFailure).toBe(true);
    });
    it('@가 없으면 실패한다', () => {
      const result = Email.create('userexample.com');
      expect(result.isFailure).toBe(true);
    });
    it('도메인이 없으면 실패한다', () => {
      const result = Email.create('user@');
      expect(result.isFailure).toBe(true);
    });
  });
  // 동등성
  describe('동등성 비교', () => {
    it('같은 값이면 동등하다', () => {
      const email1 = Email.create('user@example.com').getValue();
      const email2 = Email.create('user@example.com').getValue();
      expect(email1.equals(email2)).toBe(true);
    });
    it('대소문자가 달라도 동등하다', () => {
      const email1 = Email.create('User@Example.com').getValue();
      const email2 = Email.create('user@example.com').getValue();
      expect(email1.equals(email2)).toBe(true);
    });
  });
});

// 문제점 1: 함수 시그니처만 보고는 실패 가능성을 알 수 없음
function createUser(email: string): User {
  // 어딘가에서 throw new Error() 할 수 있음
  // 호출하는 쪽에서는 모름
}
// 문제점 2: try-catch 지옥
try {
  const user = createUser(email);
  try {
    await saveUser(user);
    try {
      await sendEmail(user);
    } catch (e) {
      // 이메일 에러 처리
    }
  } catch (e) {
    // 저장 에러 처리
  }
} catch (e) {
  // 생성 에러 처리
}

export class Result<T, E = string> {
  private readonly _isSuccess: boolean;
  private readonly _value?: T;
  private readonly _error?: E;
  private constructor(isSuccess: boolean, value?: T, error?: E) {
    this._isSuccess = isSuccess;
    this._value = value;
    this._error = error;
  }
  // 성공 결과 생성
  public static ok<T>(value?: T): Result<T, never> {
    return new Result<T, never>(true, value);
  }
  // 실패 결과 생성
  public static fail<E>(error: E): Result<never, E> {
    return new Result<never, E>(false, undefined, error);
  }
  get isSuccess(): boolean {
    return this._isSuccess;
  }
  get isFailure(): boolean {
    return !this._isSuccess;
  }
  public getValue(): T {
    if (!this._isSuccess) {
      throw new Error('Cannot get value from failed result');
    }
    return this._value as T;
  }
  public getError(): E {
    if (this._isSuccess) {
      throw new Error('Cannot get error from successful result');
    }
    return this._error as E;
  }
}

// 함수 시그니처만 봐도 실패 가능성을 알 수 있음
function createUser(props: CreateUserProps): Result<User, DomainError> {
  // 이메일 생성 (실패 가능)
  const emailResult = Email.create(props.email);
  if (emailResult.isFailure) {
    return Result.fail(emailResult.getError());
  }
  // 비밀번호 생성 (실패 가능)
  const passwordResult = Password.create(props.password);
  if (passwordResult.isFailure) {
    return Result.fail(passwordResult.getError());
  }
  // 모든 검증 통과, User 생성
  return Result.ok(new User({
    email: emailResult.getValue(),
    password: passwordResult.getValue(),
    // ...
  }));
}
// 호출하는 쪽
const result = createUser({ email, password, name });
if (result.isFailure) {
  // 에러 처리 - 어떤 에러인지 명확함
  return response.badRequest(result.getError().message);
}
const user = result.getValue();
// 여기서 user는 항상 유효함

describe('User 생성', () => {
  it('모든 값이 유효하면 User를 생성한다', () => {
    const result = User.create({
      email: 'valid@email.com',
      password: 'ValidP@ss1',
      realName: '홍길동',
      phoneNumber: '010-1234-5678',
      role: 'GUARDIAN',
    });
    expect(result.isSuccess).toBe(true);
    expect(result.getValue()).toBeInstanceOf(User);
  });
  it('이메일이 유효하지 않으면 실패한다', () => {
    const result = User.create({
      email: 'invalid-email',  // 잘못된 이메일
      password: 'ValidP@ss1',
      realName: '홍길동',
      phoneNumber: '010-1234-5678',
      role: 'GUARDIAN',
    });
    expect(result.isFailure).toBe(true);
    expect(result.getError()).toContain('이메일');
  });
});

// Role Guard
@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}
  canActivate(context: ExecutionContext): boolean {
    const requiredRoles = this.reflector.getAllAndOverride<UserRole[]>(
      ROLES_KEY,
      [context.getHandler(), context.getClass()],
    );
    
    if (!requiredRoles) {
      return true;
    }
    const { user } = context.switchToHttp().getRequest();
    return requiredRoles.includes(user.role);
  }
}
// 사용
@Controller('institutions')
export class InstitutionController {
  @Post()
  @Roles(UserRole.ADMIN)  // ADMIN만 기관 생성 가능
  create(@Body() dto: CreateInstitutionDto) {
    // ...
  }
  @Get()
  @Public()  // 누구나 기관 목록 조회 가능
  findAll() {
    // ...
  }
}

┌──────────────────────────────────────────────────────────────────────────┐
│                           User (기본 정보)                                │
│  ┌─────────────────────────────────────────────────────────────────────┐ │
│  │ id | email | password | realName | phoneNumber | role               │ │
│  └─────────────────────────────────────────────────────────────────────┘ │
│           │                    │                    │                    │
│           │ role=GUARDIAN      │ role=COUNSELOR     │ role=INSTITUTION   │
│           ▼                    ▼                    ▼                    │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐          │
│  │ GuardianProfile │  │ CounselorProfile│  │VoucherInstitution│          │
│  │─────────────────│  │─────────────────│  │─────────────────│          │
│  │ userId (FK)     │  │ userId (FK)     │  │ adminUserId(FK) │          │
│  │ organization    │  │ institutionId   │  │ name            │          │
│  │ guardianType    │  │ specialization  │  │ address         │          │
│  │ (PARENT/TEACHER)│  │ licenseNumber   │  │ isActive        │          │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘          │
│                              │                    │                      │
│                              └────────────────────┘                      │
│                                 소속 관계 (N:1)                          │
└──────────────────────────────────────────────────────────────────────────┘

// 보호자 회원가입 Use Case
@Injectable()
export class RegisterGuardianUseCase {
  constructor(
    private readonly userRepository: UserRepository,
    private readonly guardianProfileRepository: GuardianProfileRepository,
    private readonly dataSource: DataSource,
  ) {}
  async execute(dto: RegisterGuardianDto): Promise<Result<void, DomainError>> {
    // 트랜잭션 시작
    const queryRunner = this.dataSource.createQueryRunner();
    await queryRunner.connect();
    await queryRunner.startTransaction();
    try {
      // 1. User 생성
      const userResult = User.create({
        email: dto.email,
        password: dto.password,
        realName: dto.realName,
        phoneNumber: dto.phoneNumber,
        role: UserRole.GUARDIAN,
      });
      if (userResult.isFailure) {
        return Result.fail(userResult.getError());
      }
      const user = userResult.getValue();
      await this.userRepository.save(user, queryRunner.manager);
      // 2. GuardianProfile 생성
      const profileResult = GuardianProfile.create({
        userId: user.id,
        organization: dto.organization,
        guardianType: dto.guardianType,
      });
      if (profileResult.isFailure) {
        await queryRunner.rollbackTransaction();
        return Result.fail(profileResult.getError());
      }
      await this.guardianProfileRepository.save(
        profileResult.getValue(), 
        queryRunner.manager
      );
      // 커밋
      await queryRunner.commitTransaction();
      return Result.ok();
    } catch (error) {
      await queryRunner.rollbackTransaction();
      throw error;
    } finally {
      await queryRunner.release();
    }
  }
}

┌─ User Aggregate ─────────────────────────────────────────────────┐
│  User (Root)                                                     │
│    └── Role-specific Profile (GuardianProfile 등)                │
└──────────────────────────────────────────────────────────────────┘
┌─ Child Aggregate ────────────────────────────────────────────────┐
│  Child (Root)                                                    │
│    └── 아동 관련 정보만 포함                                      │
└──────────────────────────────────────────────────────────────────┘
┌─ CounselRequest Aggregate ───────────────────────────────────────┐
│  CounselRequest (Root)                                           │
│    ├── Recommendation (추천 결과)                                 │
│    ├── CounselSession (상담 세션)                                 │
│    │     └── CounselReport (면담결과지)                          │
│    └── Status 전이 로직                                          │
└──────────────────────────────────────────────────────────────────┘