DYMF Backend (DY-Microfinance Customer Management)

Nest.js, TypeORM, PostgreSQL로 구축된 마이크로파이낸스 고객 관리 플랫폼의 백엔드 RESTful API 서버입니다.

---

Table of Contents

• Project Overview
• API Modules
• Tech Stack
• Project Structure
• Getting Started
• Team

---

Project Overview

DYMF Backend는 마이크로파이낸스 조직의 운영 관리를 위한 강력한 백엔드 시스템입니다. 고객 관리, 대출 처리, 보증인 추적, 고정자산 관리 등 종합적인 API를 제공합니다.

Key Features

• ✅ Modular Architecture (Nest.js 기반)
• ✅ Database ORM (TypeORM + PostgreSQL)
• ✅ JWT 인증 & 권한 관리
• ✅ RESTful API 설계
• ✅ Redis 캐싱 계층
• ✅ RabbitMQ/Bull 메시지 큐
• ✅ 스케줄 작업 (NestJS Schedule)
• ✅ AWS S3 파일 업로드
• ✅ 타입 안전성 (TypeScript)
• ✅ 종합 로깅 (Winston)
• ✅ 자동화 테스트 (Jest)

---

API Modules

1. Authentication (auth)

• 사용자 로그인/로그아웃
• JWT 토큰 생성 & 검증
• 비밀번호 암호화 (bcryptjs)

2. Customer Management (customer)

• 고객 CRUD 작업
• 고객 검색 & 필터링
• 고객 프로필 관리

3. Loan Management (loan)

• 대출 신청 생성
• 대출 상세 정보 조회
• 대출 상태 추적
• 대출 유형 관리
• 대출 담당자 지정

4. Guarantor Management (guarantee)

• 보증인 정보 등록
• 보증인-대출 연결
• 보증인 검증

5. Fixed Asset Management (fixedassets)

• 고정자산 등록
• 자산 삭제 & 업데이트
• 자산 계산 & 감가상각

6. Collateral Management (collateral)

• 담보 등록
• 담보 평가
• 담보-대출 연결

7. User Management (user)

• 관리자 사용자 생성
• 사용자 삭제
• 사용자 역할 지정

8. Common Utilities (common)

• 예외 처리
• 전역 필터
• 공통 DTO & 인터페이스

9. Configuration (config)

• 환경 기반 설정
• 데이터베이스 설정
• 인증 설정

10. Data Migration (migration)

• 고객 데이터 마이그레이션 스크립트
• 데이터베이스 시딩

11. Personnel (personal)

• 개인 정보 관리
• 대출 담당자 추적

---

Tech Stack

Category	Technology
Runtime	Node.js
Language	TypeScript 5.7.3
Framework	Nest.js 10.0.0
Database	PostgreSQL 8.13.0
ORM	TypeORM 0.3.20
Authentication	JWT + Passport.js
Encryption	bcryptjs 3.0.2
Caching	Redis + ioredis 5.5.0
Cache Manager	cache-manager 5.7.6
Message Queue	RabbitMQ/Bull
Job Queue	Bull 10.2.1
File Upload	AWS S3 SDK
Validation	class-validator 0.14.1
Serialization	class-transformer 0.5.1
Logging	Winston 3.15.0
Documentation	Swagger 11.0.3
Testing	Jest 29.5.0
Code Quality	ESLint, Prettier
Static Files	Serve-static 4.0.2
Scheduled Jobs	NestJS Schedule 4.1.2
AOP	@toss/nestjs-aop 2.1.6

---

Project Structure

src/
├── auth/                    # JWT & Passport 인증
├── customer/                # 고객 CRUD 작업
├── loan/                    # 대출 관리
├── guarantee/               # 보증인 정보
├── fixedassets/             # 고정자산 관리
├── collateral/              # 담보 관리
├── user/                    # 사용자 관리
├── personal/                # 개인 정보
├── common/                  # 공유 유틸리티
│   ├── exceptions/
│   ├── filters/
│   ├── guards/
│   ├── interceptors/
│   └── decorators/
├── config/                  # 설정 관리
├── migration/               # 데이터베이스 마이그레이션
├── app.module.ts            # Root Module
├── app.controller.ts        # Root Controller
└── main.ts                  # Entry Point

test/                       # E2E 테스트
dist/                       # 컴파일된 출력

---

Getting Started

Prerequisites

• Node.js (v18+)
• PostgreSQL (v13+)
• Redis (선택사항, 캐싱용)
• RabbitMQ (선택사항, 메시지 큐용)

Installation

# 저장소 클론
git clone https://github.com/DY-Microfinance-Customer-Management/dymf-back.git
cd dymf-back

# dev 브랜치로 전환
git checkout dev

# 의존성 설치
pnpm install

Environment Setup

루트 디렉토리에 .env 파일 생성:

# Database
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=your_password
DB_NAME=dymf

# JWT
JWT_SECRET=your_jwt_secret
JWT_EXPIRATION=3600

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# AWS S3
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=your_region
AWS_S3_BUCKET=your_bucket_name

# API
API_PORT=3000
NODE_ENV=development

Running the Application

# 개발 모드
pnpm run start:dev

# 프로덕션 모드
pnpm run build
pnpm run start:prod

# 디버그 모드
pnpm run start:debug

Database Migration

# 마이그레이션 실행
pnpm run migrate:customers

# 프로덕션 마이그레이션
pnpm run migrate:customers:prod

Running Tests

# 단위 테스트
pnpm run test

# Watch 모드
pnpm run test:watch

# 커버리지
pnpm run test:cov

# E2E 테스트
pnpm run test:e2e

# 디버그 테스트
pnpm run test:debug

Code Quality

# 린팅
pnpm run lint

# 코드 포맷팅
pnpm run format

---

Authentication

• Method: JWT (JSON Web Tokens)
• Strategy: Passport.js with JWT strategy
• Token Expiration: 설정 가능 (기본값: 1시간)
• Password Encryption: bcryptjs

---

Database Schema

TypeORM으로 관리하는 주요 엔티티:

• User: 관리자 사용자 및 역할
• Customer: 마이크로파이낸스 고객 정보
• Loan: 대출 신청 및 상세 정보
• Guarantee: 보증인 정보
• FixedAsset: 고정자산 기록
• Collateral: 대출과 연결된 담보 정보
• Personal: 직원/스태프 정보

---

Data Flow

Client (Frontend)
    ↓
API Gateway
    ↓
Nest.js Controllers
    ↓
Business Logic (Services)
    ↓
TypeORM (Database Layer)
    ↓
PostgreSQL Database

---

Commit Convention

[Type]: Description

Body (optional)

Types:

• Feat: 새로운 기능
• Fix: 버그 수정
• Refactor: 코드 리팩토링
• Debug: 디버깅
• Test: 테스트 코드
• Chore: 빌드, 의존성
• Docs: 문서화

Examples:

Feat: 대출 담당자 지정 API 추가
Fix: 로그인 검증 오류 수정
Refactor: 고객 서비스 성능 개선
Test: 대출 계산 단위 테스트 추가

---

Code Convention

File & Folder Naming

• Modules: kebab-case (e.g., customer, loan)
• Controllers: *.controller.ts
• Services: *.service.ts
• DTOs: camelCase in dto/ folder
• Entities: PascalCase in entities/ folder
• Tests: *.spec.ts

Variable & Function Naming

• 변수/함수: camelCase
• 클래스/인터페이스: PascalCase

Module Structure

module/
├── dto/                     # Data Transfer Objects
├── entities/                # Database entities
├── module.controller.ts
├── module.service.ts
├── module.module.ts
└── module.spec.ts           # Tests

Service Method Pattern

async create(createDto: CreateModuleDto): Promise<ModuleEntity>
async findAll(query?: QueryDto): Promise<ModuleEntity[]>
async findById(id: string): Promise<ModuleEntity>
async update(id: string, updateDto: UpdateModuleDto): Promise<ModuleEntity>
async delete(id: string): Promise<void>

---

Team Members

Role	Name
Backend	모진영
Backend	박훈일

---

License

UNLICENSED - Private project

---

Support

Issues, feature requests, or questions에 대해서는 GitHub repository에서 issue를 열어주세요.