홈으로

인수인계

인수인계

인수인계 사항을 문서화해서 정리해 놓으면 해당 서비스를 구조적으로도 이해하기 쉽고 처음 보느 개발자들에게도 도움이 많이 됩니다. 본인에게 도움이 되고요.

1. 설치

1.1 자격요건

다음이 로컬 PC에 설치되어 있어야 합니다:

  • Node.js 18.2.0 이상
  • Mysql

1.2 개발 서버 실행

변경 사항을 미리 보기 위해 로컬 서버를 실행할 수 있습니다. 다음 명령어들을 순차적으로 입력하세요.

npm install

npm run start

1.3 Build

정적 사이트를 생성하려면 아래 명령어를 실행하세요:

npm run build

생성된 정적 콘텐츠는 /build 폴더에 들어가며, GitHub Pages, Vercel, Netlify 등에 배포할 수 있습니다. 자세한 배포 방법은 배포 카테고리 참고.

2. 설정

이 섹션에서는 커뮤니티 채널, 커뮤니티 브랜딩, 사용자 관리 등 다양한 기능을 관리할 수 있는 관리자(admin) 계정을 생성할 것입니다. 또한, Cloudinary CDN을 사용하여 이미지를 호스팅하고, Mailgun을 통해 이메일을 발송하며, Google Analytics를 통해 주요 지표를 추적하는 기능도 통합할 예정입니다.

2.1 super 어드민 계정 생성

처음 최종 관리자 계정을 만드는 명령어를 기술합니다.

yarn create-super-admin your@email.com

your@email.com을 실제 사용하는 이메일 주소로 바꾸세요. 새 팔로워나 메시지와 같은 알림이 이 이메일로 전송됩니다. 기본적으로 새로 생성된 사용자의 비밀번호는 settlework입니다. 이메일과 이 비밀번호를 사용해 로그인할 수 있습니다.

안내: 로그인한 후에는 '계정 설정(Account Settings)' 페이지에서 프로필 정보와 비밀번호를 변경할 수 있습니다.

2.2 CDN Integration (정적 컨텐츠 불러오기)

사용자가 업로드한 모든 파일(프로필 및 커버 사진, 게시물 이미지, 커뮤니티 로고 등)은 Cloudinary CDN에 업로드되어 더 빠르게 콘텐츠가 전달됩니다.

안내: Cloudinary는 신용카드 정보 없이 무료 요금제를 제공합니다.

Cloudinary 계정을 만든 후, 대시보드에서 Cloud Name, API Key, API Secret을 확인하세요. 해당 값을 packages/orca-api/.env 파일에 아래와 같은 형식으로 입력합니다:

CLOUDINARY_CLOUD_NAME=Your Cloud Name Here
CLOUDINARY_API_KEY=Your API Key Here
CLOUDINARY_SECRET=Your API Secret Here

파일을 저장한 후, 서버를 재시작하면 CDN 업로드 기능이 활성화됩니다.

2.3 Email Service Integration (이메일 서비스 연동)

우리는 계정 인증, 비밀번호 재설정, 알림 전송과 같은 이메일 발송에 Mailgun을 사용합니다.

안내: Mailgun은 비교적 넉넉한 무료 요금제를 제공합니다. 신용카드를 등록하면 월 5,000건의 무료 이메일을 3개월 동안 발송할 수 있습니다. 신용카드 없이 사용할 경우, 인증된 수신자에게만 이메일을 보낼 수 있습니다.

Mailgun 계정을 설정한 후(샌드박스 도메인 또는 커스텀 도메인 사용), 대시보드에서 Private API Key와 Domain Name을 확인하세요. 이 값을 packages/orca-api/.env 파일에 아래와 같은 형식으로 입력합니다:

MAILGUN_API_KEY=Your Private API Key Here
MAILGUN_DOMAIN=Your Domain Name Here

env 바꾸고 서버 재시작 해야 합니다.

2.4 Google Analytics

구글 애널리틱스를 적용하면 사용자 행동 데이터를 분석할 수 있어요. 방문자 수, 트래픽 분석, 어떤 버튼 많이 누르는지, 마케팅 효율을 분석할 수 있어요. 그래서 많이 사용하지 않는 기능은 제거할 수 있고, 많이 사용되는 버튼이나 기능은 연관된 기능을 해당 데이터 기반으로 확장할 수 있어요. 다음 경로에 있는 프론트엔드 설정 파일에서 GOOGLE_ANALYTICS_ID 값만 업데이트하면 됩니다.


GOOGLE_ANALYTICS_ID: 'YOUR TRACKING OR MEASUREMENT ID IN HERE',

3. 프론트 설계

React 셋업은 vite 프레임워크 사용 이유

  1. 빠른 빌드 속도
  2. HMR
  3. 자동 최적화
  4. 물류시스템이 B2C 서비스도 아니고, 서버사이드 랜더링이나 검색엔진최적화를 요구 하는게 아니므로 next를 사용하는 것보단 vite 가 적합하다고 판단

3.1 폴더 구조

my-website
├── blog
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

3.2 디렉터리 설명

  • /blog/ - 블로그 게시물 Markdown 파일. 블로그 플러그인을 비활성화했다면 삭제 가능.
  • /docs/ - 문서 Markdown 파일. sidebars.js로 사이드바 순서를 설정. 비활성화 시 삭제 가능.
  • /src/ - 문서 외 페이지나 커스텀 컴포넌트.
  • /src/pages - 이 디렉터리 내 JSX/TSX/MDX 파일은 자동으로 페이지로 변환됨.
  • /static/ - 정적 파일 디렉터리. 빌드 시 /build 폴더로 복사됨.
  • /docusaurus.config.js - 사이트 전반의 설정 파일.
  • /package.json - 일반적인 React 앱과 동일하게 npm 패키지를 설치해 사용 가능.
  • /sidebars.js - 문서 사이드바 순서를 설정하는 파일.

3.3 데이터 통신

각 화면에서 lib 폴더의 service 폴더의 파일들을 호출합니다.
queryService 의 excuteSQL 호출 : 쿼리헬퍼의 쿼리를 통해 데이터베이스에서 필요한 데이터를 가져옵니다.

3.4 전역 상태관리

recoil 사용

src/common/base/v002/global-state 파일에 사용자 정보, 메뉴 정보, 라우트 정보를 선언 및 할당하고 각각의 필요한 화면에서

import { useRecoilState } from 'recoil';  를 사용해서 조작합니다.

3.5 성능최적화

  1. useMemo : 복잡한 계산을 메모이제이션 -> 필요한 경우만 사용(남발하면 오히려 성능을 악화시키고 가독성을 떨어뜨림 )
  2. useCallback : 리랜더링 방지 -> 필요한 경우만 사용(남발하면 오히려 성능을 악화시키고 가독성을 떨어뜨림 )
  3. useState 설계를 단순화해서 불필요한 상태선언 제거
  4. useState 를 공통 부모컴포넌트로 끌어올려 자식 컴포넌트간 데이터 불일치 방지
  5. 불필요한 DOM 노드 생성 기피 : 무의미한 div 사용 금지
  6. 리스트 렌더링 최적화 -> 배열을 랜더링 할 때 항상 key 식별자에 id를 할당
  7. React DevTools를 사용해 컴포넌트의 렌더링 빈도 분석 -> 불필요한 랜더링 최적화
  8. vite 사용해서 bundle 용량 최적화
  9. 쓰로틀링 및 디바운싱
  10. 캐싱
  11. useEffect 디펜던시 배열 설정을 명확히 해서 필요하지 않는 경우 실행되지 않도록 설계

3.6 에러처리

  1. 404 공통 에러 처리
  2. 400 대 에러 처리
  3. 500 에러 처리 (api retry) TcRouter -> defaultErrorBoundary -> PageError 라우팅

3.7 스타일링

전역 : index.css
개별 : scss

3.8 Tools and utilities

src/lib/v200/util 의 파일들 참조

3.9 hook

useUiGridColumns : 그리드 칼럼 가져오는 훅
useDebounce : 디바운스 처리
useThrottle : throttle 처리
useModal : 공통 모달 처리

3.10 외부 API

주요한 외부 API 리스트

  1. soket.io
  2. chart 라이브러리

4. 백엔드 설계

4.1 폴더구조

.
├── ...
├── src                
│   ├── EMS          # Email MEssaging Service 이메일 메시징 서비스
│   ├── POM          # Production Order Management 생산 주문 관리
│   ├── SQC          # Statistical Quality Control 통계 품질 제어  
│   ├── TMS          # Transport Management System 운송 관리 시스템
│   ├── WMS          # WareHouse Management System 물류창고 관리 시스템
└── ...

 .
├── ...
├── WMS                
│   ├── common          # 공통 폴더
│   ├── rule          
│   ├── server          # 서버 설정 관련  
│   ├── worker          # 실세 api 처리 관련
└── ...

   .
├── ...
├── server                
│   ├── MOM.WMS.PRT.Server.ExtsamKee          # 출력관련 설정
│   ├── MOM.WMS.UIX.Server.Extsamkee          # 화면관련 설정
        ├── app.config                        # 앱 개발 서버 설정
        ├── app.settings.json                 # 프론트 관련 설정
        ├── program.cs                        # 애플리케이션 시작 진입점
        ├── startup.cs                        # 애플리케이션 구성과 요청 처리 로직 설정
└── ...

4.2 설계문서(ERD)

DBMS 툴에서 ERD export 해서
ERD 이미지 링크 첨부
인덱스 현황
프로시저 현황
뷰 현황
잡/스케쥴러 현황
트리거 현황
백업 현황
접근권한 현황

4.3 데이터베이스 접근 정보

항목값 (예시)
DB 이름settlework_db
호스트 (Host)db.settlework.com
포트 (Port)5432
사용자명 (User)settle_admin
비밀번호 (Pass).env 파일 참조 또는 구글 드라이브 참고
DBMS 종류MYSQL
인코딩 방식UTF8

4.4 데이터베이스 흐름 및 비즈니스 로직

  1. 주요 요청 흐름
  • 로그인 → 인증 미들웨어 → 유저 서비스 → DB 조회 → 응답 반환

  1. 주문 처리 로직

  2. 주문 요청 수신

  3. 재고 확인 및 차감

  4. 결제 요청 (외부 PG API)

  5. 주문 상태 업데이트

  6. 주문 완료 응답 반환

  7. 비즈니스 규칙

  • 신규 회원은 첫 주문 시 5,000원 쿠폰 자동 발급
  • 오전 2시~4시 사이 정산 요청은 다음날 처리
  1. 이벤트 흐름
  • 상품 등록 시 → Kafka 메시지 발행 → 검색 서버 인덱싱 트리거
  1. 외부 API 연동
  • 결제 API: POST /payments
  • 물류 연동: GET /shipping-status/{orderId}

4.5 자주 사용되는 쿼리

  • 회원 정보 조회
SELECT user_id, username, email, created_at
FROM users
WHERE user_id = ?;
  • 회원 가입 현황 통계
SELECT DATE(created_at) AS signup_date, COUNT(*) AS num_signups
FROM users
GROUP BY signup_date
ORDER BY signup_date DESC;
  • 최근 접속 사용자 조회
SELECT user_id, username, last_login
FROM users
WHERE last_login >= DATE_SUB(NOW(), INTERVAL 7 DAY)
ORDER BY last_login DESC;
  • 특정 기간 매출 조회
SELECT SUM(amount) AS total_revenue
FROM payments
WHERE payment_date BETWEEN ? AND ?;
  • 서비스 이용 통계
SELECT feature_name, COUNT(*) AS usage_count
FROM feature_usage_logs
GROUP BY feature_name
ORDER BY usage_count DESC;
  • 결제 내역 조회
SELECT payment_id, user_id, amount, payment_date, payment_status
FROM payments
WHERE user_id = ?
ORDER BY payment_date DESC;

4.6 외부 시스템 연동 API

  1. axios
  2. node-fetch
  3. request-promise
  4. superagent
  5. got
  6. socket.io
  7. multer

  • axios HTTP 클라이언트 라이브러리로 비동기식 API 호출에 주로 사용

  • node-fetch Fetch API를 Node.js 환경에서 구현한 라이브러리로 HTTP 요청 처리

  • request-promise Promise 기반 HTTP 요청 라이브러리로 RESTful API 호출에 사용

  • superagent 경량의 HTTP 요청 라이브러리로 간단한 API 호출과 데이터 처리에 활용

  • got 강력하고 유연한 HTTP 요청 라이브러리로 다양한 설정 옵션 제공

  • socket.io 실시간 양방향 통신을 위한 웹소켓 기반 API 라이브러리

  • multer 파일 업로드 처리를 위한 Express 미들웨어

5. 운영 모드

5.1 운영환경에서 빌드

프로젝트의 루트 디렉터리에서 npm run build 명령어를 실행하면 API와 프론트엔드 패키지의 프로덕션 빌드가 생성됩니다. API 빌드는 packages/api/build 디렉터리에 생성되며, 프론트엔드는 packages/frontend/.next 디렉터리에 생성됩니다. 이후, 각 패키지는 npm run start 명령어로 개별적으로 실행할 수 있습니다. 그리고 로컬에서 운영환경처럼 뛰으려면 npm run build && npm run preview 라는 명령어가 있다는 것 참조 바랍니다.

5.2 API

cd packages/api
npm run start

API는 다음 URL에서 실행됩니다: http://localhost:4000

5.3 Frontend

cd packages/frontend
yarn start

프론트엔드는 다음 URL에서 실행됩니다: http://localhost:3000

5.4 PM2

PM2는 Node.js 애플리케이션이 항상 실행 중인 상태로 유지되도록 돕는 프로세스 매니저입니다.

PM2를 사용하려면 전역으로 설치해야 합니다.

npm instal global pm2@latest

PM2는 애플리케이션을 관리하거나 애플리케이션에 대한 정보를 조회할 수 있는 다양한 명령어를 제공합니다.

  • 현재 PM2가 관리 중인 애플리케이션 목록 조회:
pm2 list
  • 애플리케이션 중지 (PM2 앱 이름 또는 ID를 명시):
pm2 stop app-name-or-id
  • 애플리케이션 재시작:
pm2 restart app-name-or-id
  • 특정 애플리케이션의 정보 조회:
pm2 info app-name

6. 배포 가이드

프로젝트를 다양한 방법으로 배포할 수 있습니다. AWS, Google Cloud, Azure와 같은 호스팅 서버에 배포가 가능합니다.

배포 시 앱은 다음 3가지 핵심 서비스로 구성되어 있음을 기억해야 합니다:

  • mysql 데이터베이스
  • API (Express 서버)
  • 프론트엔드 (Next.js 애플리케이션)

API와 프론트엔드 서비스는 Node.js를 지원하는 모든 호스팅 제공업체에 배포할 수 있습니다.

6.1 설정(Configuration)

서비스가 배포된 후 각기 다른 서버, 도메인 또는 포트에서 실행될 수 있으므로, 서로를 참조할 수 있도록 설정 파일을 수정해야 합니다.

6.2 API 설정

API 서비스는 .env 파일에서 다음 환경변수를 수정해야 합니다.

파일 경로: packages/settlework/.env

API_PORT=4000
API_URL=https://api.settlework.org
NODE_ENV=production

FRONTEND_URL=http://localhost:3000

MYSQL_URL=mysql://username:password@localhost:27017/orca?authSource=admin
  • API_PORT: API 서버가 사용할 포트입니다. 일부 호스팅 업체에서는 기본으로 설정되는 PORT 환경변수에 의해 덮어씌워질 수 있습니다.
  • API_URL: API의 URL입니다. 예시로 데모 앱 API 서비스는 https://api.getorca.org에서 실행됩니다.
  • NODE_ENV: 앱이 프로덕션 환경에서 실행 중임을 나타냅니다.
  • FRONTEND_URL: 프론트엔드 앱의 URL입니다. 예시로 데모 앱의 프론트엔드는 https://community.getorca.org에서 실행됩니다.
  • MYSQL_URL: MysqlDB 연결 문자열 URI로, 사용자 이름, 비밀번호, 포트 및 데이터베이스 이름을 포함합니다.

6.3 프론트엔드 설정

프론트엔드 서비스는 앱을 빌드하기 전에 다음 파일에서 API_PRODUCTION_URL 변수만 수정하면 됩니다.

파일 경로: packages/frontend/utils/config.ts

const API_PRODUCTION_URL = 'https://api.getorca.org';
const API_DEV_URL = 'http://localhost:4000';

6.4 PaaS를 이용한 배포

가장 간편한 앱 배포 방법은 PaaS(Platform as a Service) 제공업체를 사용하는 것입니다. PaaS를 사용하면 DevOps 기술이 필요하지 않고 웹서버가 이미 설정되어 있습니다.

  • API 서비스: Heroku, Google App Engine, Digital Ocean App Platform 등 Node.js를 지원하는 플랫폼에서 배포 가능합니다.
  • 프론트엔드 서비스: Next.js 앱이므로 Vercel에서 배포하는 것이 좋습니다.
  • MysqlDB: Amazon RDS 와 같은 DBaaS(Database as a Service)를 사용할 수 있습니다.

대부분의 제공업체는 테스트나 MVP를 위한 무료 플랜을 제공하지만, 보다 본격적인 비즈니스 앱의 경우 무료 플랜의 성능과 한계로 인해 충분하지 않을 수 있습니다.

PaaS 제공업체는 서버 설정과 관리 업무를 대신 처리해주기 때문에 IaaS보다 비용이 높지만, DevOps 기술이 없거나 개발에만 집중하고 싶다면 비용 효율적일 수 있습니다.

6.5 IaaS를 이용한 배포

앱은 AWS, Google Cloud, Microsoft Azure, Digital Ocean 등 모든 IaaS 제공업체에 배포할 수 있지만, 기본적인 DevOps 기술이 필요합니다.

Previous
프론트
Next
API명세서