부록
개발주의사항
개발주의사항들 입니다.
1. 프론트엔드 개발 주의사항
| 항목 | 설명 |
|---|---|
| DOM 로딩 시점 | JS가 DOM보다 먼저 실행되지 않도록 DOMContentLoaded 또는 useEffect 등 적절한 타이밍에 실행 |
| 비동기 처리 | API 호출 후 상태 업데이트 시 loading 처리, 에러 핸들링 필수 |
| 상태 관리 | 컴포넌트 단위에서 과도한 상태 사용은 피하고, 공통 상태는 전역 관리 도구 사용 (예: Redux, Zustand) |
| 반응형 디자인 | 모바일/태블릿/PC 화면 크기별 테스트 필수 (media query, flex, grid 활용) |
| 접근성 | 버튼에 aria-label, alt, tabIndex 등의 기본 접근성 속성 처리 |
| 브라우저 호환성 | 다양한 브라우저에서 정상 작동하는지 확인 (특히 IE 지원 여부 확인 필요 시 polyfill) |
| 컴포넌트 재사용성 | 같은 패턴의 UI는 재사용 가능한 컴포넌트로 분리해서 중복 방지 |
| 불필요한 렌더링 방지 | React.memo, useMemo, useCallback 등으로 성능 최적화 |
2. 백엔드 개발 주의사항
| 항목 | 설명 |
|---|---|
| 에러 핸들링 | 모든 비동기 함수에 try-catch 사용, 응답 코드와 에러 메시지 구분 명확히 (e.g. 400, 500) |
| 모듈 분리 | 라우터, 서비스, DB 레이어 분리하여 유지보수성 높이기 |
| 환경 변수 관리 | 비밀번호, 키값은 .env 파일로 관리하고 Git에 올리지 않기 |
| 입력값 검증 | 요청 바디나 쿼리 파라미터는 Joi, Zod, express-validator 등으로 검증 |
| 로그 작성 | 콘솔이 아닌 winston, pino 등으로 로그 처리, 에러 로그와 액세스 로그 구분 |
| 보안 | CORS 설정, Helmet, rate limiting, SQL injection/XSS 대비 등 기본 보안 설정 필수 |
| API 명세 작성 | Swagger, Postman 등으로 API 명세 공유 및 테스트 가능하게 하기 |
3. 데이터베이스(DB) 개발 주의사항
| 항목 | 설명 |
|---|---|
| 정규화 vs 성능 | 무조건 정규화보다는 성능 고려하여 일부 비정규화도 검토 |
| 인덱싱 | 자주 조회되는 조건(WHERE)에 해당하는 컬럼은 적절히 인덱싱 |
| 트랜잭션 관리 | 데이터 정합성이 중요한 작업은 트랜잭션으로 처리 (BEGIN → COMMIT/ROLLBACK) |
| NULL 처리 | NULL 값의 조건 처리 주의 (특히 = 대신 IS NULL 사용) |
| 데이터 타입 | 숫자, 날짜, 문자열 타입을 정확히 정의하고 불필요한 TEXT 사용 지양 |
| JOIN 시 유의 | 불필요한 JOIN 사용 자제, 반드시 필요한 테이블만 JOIN |
| 쿼리 테스트 | 대량 데이터 기준으로 쿼리 성능 테스트 (EXPLAIN, 실행 시간 확인 등) |
| SQL Injection 방지 | ORM 사용하거나 prepared statement로 파라미터 바인딩 처리 |
4. 인프라/배포 주의사항
| 항목 | 설명 |
|---|---|
| 배포 자동화 | CI/CD 도입으로 빌드, 테스트, 배포 자동화 |
| 환경 구분 | dev / staging / production 환경 구분하여 설정 관리 |
| 무중단 배포 | 서비스 중단 없이 업데이트 가능한 방식 고려 (e.g. blue-green, rolling) |
| 백업 전략 | DB 정기 백업, 로그 보존 정책 수립 |
| 모니터링 | 서버 상태, 에러, API 응답 속도 등을 실시간으로 확인 가능한 시스템 구축 (e.g. Grafana, Sentry) |
| 보안 인증서 | HTTPS 적용, SSL 인증서 만료 체크 |
| 리소스 제한 | 메모리/CPU 사용량 제한, Docker 리소스 할당 확인 |
| 비용 최적화 | 클라우드 인프라 사용량 주기적 점검 (불필요한 인스턴스 종료 등) |
5. 테스트 주의사항
| 항목 | 설명 |
|---|---|
| 단위 테스트(Unit Test) | 함수 단위로 입력/출력 테스트 (Jest, Mocha 등 사용) |
| 통합 테스트(Integration Test) | 실제 DB/API 등과 통합하여 전체 흐름 테스트 |
| E2E 테스트 | Cypress, Playwright 등을 활용하여 사용자 흐름 전체 테스트 |
| 목(mock) 처리 | 외부 API 등은 mock 처리하여 테스트 격리 |
| 테스트 데이터 분리 | 테스트용 DB, 테스트 데이터 세트 분리 운영 |
| 자동 테스트 실행 | GitHub Actions, GitLab CI 등으로 PR 시 테스트 자동 실행 |
| 테스트 커버리지 | 커버리지 확인 툴(Istanbul 등)로 테스트 범위 확인 및 부족한 부분 보완 |
6. 인수인계 주의사항
| 항목 | 설명 |
|---|---|
| 문서화 | README, API 명세, 기능 설명서, DB 구조 문서 등 필수 작성 |
| 환경 세팅 가이드 | 로컬 개발 환경 세팅 방법 .env 예시, dependency 설치법 등 정리 |
| 권한 전달 | 서버 접근 권한, 레포지토리 권한, CI/CD 권한 모두 이전 |
| 코드 정리 | 사용되지 않는 주석, 테스트 코드, 임시 파일 등 제거 후 마무리 |
| 운영 매뉴얼 | 배포 방법, 장애 대응 방법, 주기적인 유지보수 항목 등 공유 |
| Q&A 기간 확보 | 인수자가 질문할 수 있는 기간 확보하고, 문서에 FAQ로 정리 |
| 비즈니스 로직 이해 공유 | 단순 코드 설명뿐 아니라 "왜 이렇게 만들었는가"에 대한 배경 설명 포함 |
7. 항상 DB에 넣어둬야 하는 데이터
| 유형 | 예시 | 설명 |
|---|---|---|
| 기준 테이블 마스터 데이터 | 국가코드, 공장 코드, 부서 목록, 제품군 코드 등 | 거의 변하지 않고 시스템 전반에서 참조되는 값들 |
| 권한/역할(Role) 정의 | admin, user, manager 등 역할 구분 | 시스템 접근 권한 처리에 필수 |
| 초기 계정/설정값 | 기본 관리자 계정, 설정값 등 | 시스템 설치 또는 초기화 시 필요 |
| Dev/QA 환경 동기화 데이터 | 운영에서 추출한 일부 샘플 데이터 | 테스트/개발 시 실제 데이터 기반 테스트용 |
이런 데이터는 초기 마이그레이션 스크립트 또는
seed작업으로 자동 실행되게 구성하면 좋습니다.
8. 주기적으로 돌려야 하는 배치/잡(Scheduled Job)
| 유형 | 예시 | 설명 |
|---|---|---|
| 공장별 데이터 생성 | 하루 1번, 공장 A/B/C 별로 생산계획, 입출고 데이터를 생성 | 공장 PK 기반으로 분기 처리 가능 |
| 운영 → 개발 DB 동기화 | 매주 또는 수동 실행, 운영 DB에서 마스킹된 데이터 추출하여 개발용 DB에 이관 | 개인정보 익명화 후 이관 |
| 리포트/통계 집계 | 매일 00:00에 전일자 매출, 생산량 통계 저장 | 프론트에서 빠르게 보기 위해 별도 테이블에 저장 |
| 로그 정리/백업 | 오래된 로그 삭제, 주기적 DB 백업 | 디스크 공간 확보 및 보안 향상 |
| 알림/푸시 발송 | 예약된 알림/마케팅 푸시 등 발송 처리 | 정해진 시간에 맞춰 배치로 처리 |
| 외부 시스템 연동 | API 통해 외부 데이터 수집 및 DB에 저장 | 날씨, 환율, 출하 시스템 등 연동 |
9. 히스토리를 꼭 남겨야 하는 데이터 유형
| 데이터 유형 | 이유 / 목적 |
|---|---|
| 사용자 정보 변경 | 이름, 이메일, 권한 등이 바뀔 때 누가 언제 바꿨는지 추적 필요 |
| 주문 상태 변경 | 주문 → 결제완료 → 배송중 → 배송완료 등 단계별 상태 추적 |
| 재고 수량 변경 | 입고/출고에 따라 수량이 바뀌면 정확한 입출 기록 필요 |
| 설정값 변경 | 시스템 설정이 바뀌면 나중에 되돌리거나 이유 확인 가능 |
| 결재/승인 상태 | 문서가 누구에게 승인 받았는지 이력 관리 |
| 공정 처리 이력 | 생산공정, 검사공정에서 언제 어떻게 처리되었는지 추적 |
| 로그인/접속 로그 | 보안 및 사용자 행동 기록 목적 |
| 배포/코드 변경 기록 | 배포 이력, 테이블 변경 이력 등 시스템 레벨에서도 필요 |
| 계약/요금 변경 이력 | 고객별 요금제, 계약 내용이 바뀌는 경우를 추적 |
10. 히스토리 저장 방식
| 방식 | 설명 | 예시 |
|---|---|---|
| 이력 테이블 별도 분리 | UsersHistory, OrdersHistory 처럼 별도 테이블 운영 | 모든 변경사항 INSERT로 기록 |
| Soft Delete + Timestamp | 실제 데이터는 삭제 안 하고, is_deleted, deleted_at 필드만 업데이트 | 기존 테이블에서 관리 가능 |
| Trigger 활용 | 테이블에 AFTER UPDATE 트리거를 걸어서 자동으로 이력 테이블에 저장 | DB단 자동 처리 |
| Version 관리 | row별로 version 필드 추가하여 변경 시 새 버전 삽입 | 예: Wiki, Notion 등의 문서 이력처럼 |
| JSON 변경 기록 | 변경 필드를 JSON으로 로그에 남기는 방법 | 유연하지만 쿼리/검색은 어려움 |