🛠️ 협업에서 마주한 문제 & 해결 과정

---

🐳 1. Docker 컨테이너화를 도입한 이유 & 최적화 과정

---

🛑 문제 상황

1️⃣ 팀원 간 개발 환경이 일관되지 않음

• 나는 MacOS, 다른 팀원들은 Windows 환경에서 개발.
• Python 버전 차이, 패키지 설치 문제, OS 환경 차이로 인해 코드 실행 오류 발생.

2️⃣ 로컬에서 잘 되던 코드가 다른 환경에서는 실행되지 않음

• 내 환경에서는 정상적으로 실행되지만, 다른 팀원이 실행할 때 환경 차이로 인한 오류 발생.
• pip install 할 때 패키지 충돌 문제 발생.

3️⃣ 배포 시 실행 환경을 맞추는 과정이 번거로움

• 서버 환경과 로컬 개발 환경이 다르다 보니, 배포 후 실행 오류가 종종 발생.
• 환경 변수를 다루는 방식도 OS마다 차이가 있어서 관리가 어려움.

---

✅ 해결 방법 - Docker 컨테이너화 도입

1) Docker를 사용해 모든 팀원이 동일한 환경에서 개발 가능하도록 설정

• Dockerfile을 만들어서, 어떤 환경에서도 동일하게 실행되도록 설정.
• Python, FAISS, PostgreSQL 등 필요한 라이브러리를 Docker 환경에 통합하여 실행 환경 통일.

# 1. Python 환경을 기반으로 이미지 생성
FROM python:3.9

# 2. 작업 디렉토리 설정
WORKDIR /app

# 3. 필요한 패키지 설치
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 4. 코드 복사 후 실행
COPY . .
CMD ["python", "app.py"]

📌 결과
✅ 어떤 환경에서도 동일한 개발 환경을 유지할 수 있음.
✅ 로컬과 서버의 실행 환경이 일치하므로 배포 오류 감소.

2) Docker Compose로 전체 서비스 구성 자동화

• PostgreSQL, FAISS, Flask 백엔드 등을 함께 실행할 수 있도록 docker-compose.yml 작성.
• 한 줄 명령어로 모든 서비스 실행 가능! (docker-compose up -d)

version: '3.8'
services:
  db:
    image: postgres
    restart: always
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: inflow_chat
    ports:
      - "5432:5432"

  backend:
    build: .
    depends_on:
      - db
    environment:
      DATABASE_URL: postgresql://admin:secret@db:5432/inflow_chat
    ports:
      - "8000:8000"

📌 결과
✅ 데이터베이스 + 백엔드를 한 번에 실행할 수 있음.
✅ 로컬 환경에서도 배포 환경과 동일한 환경에서 실행 가능.

---

🔥 Docker 도입 후 얻은 이점 & 배운 점

✅ 개발 환경 차이 해결 → "내 환경에서는 잘 되는데?" 문제 해결!
✅ 서버 배포가 간단해짐 → 한 줄로 실행 가능 (docker-compose up -d)
✅ 협업이 쉬워짐 → 모든 팀원이 동일한 환경에서 개발 가능.
✅ 배포 후 오류 감소 → 개발 환경과 배포 환경이 동일하므로 실행 오류 최소화.

---

📌 최종 정리 (TL;DR)

• 기존에는 팀원 간 환경 차이, 배포 시 실행 오류, 패키지 충돌 문제가 있었음.
• ✅ Docker 컨테이너화를 통해 개발 & 배포 환경을 통일.
• ✅ Docker Compose를 활용해 데이터베이스 & 백엔드 실행 자동화.
• ✅ 결과적으로 개발 속도 & 협업 효율이 향상됨!
• 🚀 이제 "내 환경에서는 잘 되는데?" 문제는 없다!

---

📄 2. API 문서화 - Swagger 도입 & 개발 경험 개선

---

🛑 문제 상황

1️⃣ Postman을 사용하여 API 테스트 진행했으나, 협업 시 불편함 발생

• 프론트엔드 개발자들이 API 명세를 보려면 Postman 공유 링크를 받아야 함.
• Postman에서 개별적으로 API를 실행하고 확인해야 해서 한눈에 API 구조를 보기 어려움.

2️⃣ API 개발 진행 상황을 직관적으로 볼 수 있는 방법이 필요함

• Postman으로 테스트는 가능하지만, API가 늘어날수록 진행 상황을 한눈에 보기 어려웠음.
• 자동화된 문서화 도구가 필요하다고 판단!

3️⃣ Flask에서 Swagger(FastAPI처럼 기본 지원 X)를 사용하기 위해 리팩토링 필요

• 기존 Flask 프로젝트에서 Blueprint 기반 개발을 진행하고 있었음.
• 하지만 Swagger를 적용하려면 Flask-RESTX의 Namespace 구조로 변경해야 함.

---

✅ 해결 방법 - Swagger 도입 및 API 리팩토링

1) Swagger (Flask-RESTX) 적용

💡 Swagger를 사용하면 API 문서가 자동으로 생성되며, 개발자들이 바로 API를 실행할 수 있음!

• Swagger를 통해 API 문서화 진행 → 프론트엔드 개발자들과의 협업 편리해짐.
• 기존 Postman 공유 방식 대신, Swagger UI에서 실시간으로 API 확인 가능.

📌 결과:
✅ API 실행과 동시에 Swagger UI에서 자동으로 문서가 생성됨.
✅ 프론트엔드 개발자가 API 테스트를 Swagger에서 직접 실행 가능!

2) 기존 Blueprint 방식 → Namespace 방식으로 리팩토링

💡 기존 Blueprint 방식에서는 Swagger 문서를 자동 생성하기 어려웠음.
📌 그래서 API를 Flask-RESTX의 Namespace 방식으로 변경!

🔄 리팩토링 과정에서 얻은 이점:

• ✅ 코드를 더 모듈화하고 API별 역할을 명확하게 분리할 수 있었음.
• ✅ API 문서가 자동 생성되면서 "이 API는 어디에 쓰는 거지?"라는 질문이 사라짐.
• ✅ 코드를 다시 한번 점검할 기회가 되어, 불필요한 엔드포인트나 중복 코드를 정리할 수 있었음.

---

🛠️ Swagger 도입 후 얻은 이점

📌 API 협업이 훨씬 쉬워짐!

• ✅ 프론트엔드 개발자들이 API 문서를 따로 요청할 필요 없이 Swagger에서 바로 확인 가능.
• ✅ API 요청을 직접 테스트할 수 있어 프론트-백엔드 간의 소통이 원활해짐.

📌 개발 진행 상황을 한눈에 볼 수 있음!

• ✅ Postman에서는 각 API를 개별적으로 실행해야 하지만,
• ✅ Swagger UI에서는 모든 API가 정리되어 있어 개발 진행 상황을 한눈에 파악 가능!

📌 리팩토링을 통한 코드 개선 효과

• ✅ 기존 Flask Blueprint 방식에서 Flask-RESTX Namespace 방식으로 변경하며 코드 구조가 더 명확해짐.
• ✅ 기존 API 설계 방식에 대해 한 번 더 고민할 기회가 되었음.

---

🔥 Swagger 도입 후 배운 점 & 느낀 점

✅ Swagger는 API 협업을 위한 필수 도구!
✅ Postman도 유용하지만, 문서화 & 협업을 위해서는 Swagger가 더 강력함.
✅ Flask-RESTX로 변경하면서 코드 모듈화 및 API 문서 자동화를 함께 진행할 수 있었음.
✅ 리팩토링 과정에서 불필요한 코드 정리를 하면서, API 설계에 대한 고민을 더 깊이 할 수 있었음.

---

📌 최종 정리 (TL;DR)

• 기존 Postman 방식 → Swagger(FastAPI 스타일) 문서화 도입!
• ✅ API 문서를 자동 생성 & 실시간 테스트 가능.
• ✅ 프론트엔드 개발자들과 협업이 더 쉬워짐.
• ✅ API 설계를 다시 점검하면서, 코드 리팩토링도 진행!
• 🚀 결과적으로 개발 효율 + 협업 편의성이 대폭 향상됨!

---

🚀 3. Git 브랜치 전략 도입 - 협업 효율성 개선

---

🛑 문제 상황

1️⃣ 팀원 간 Git 브랜치 전략이 없어서 코드 충돌 발생

• 나는 GitHub을 활용한 브랜치 전략 (Issue → Feature Branch → PR → Review → Merge)에 익숙했음.
• 하지만 팀원들은 개인 프로젝트에서만 개발해왔기 때문에, 협업 시 Git 규칙을 따르는 것이 익숙하지 않음.

2️⃣ 브랜치 관리 미숙으로 인해 강제 Merge 발생 → 코드 충돌 & 버그 증가

• 일부 개발자가 main 브랜치에서 직접 개발 후 강제 Merge 진행 → 코드가 꼬이고 충돌 발생.
• 코드 리뷰 없이 Merge하면서 불안정한 코드가 main에 포함되는 문제가 발생.

3️⃣ 브랜치가 꼬여서 최악의 경우 레포를 새로 생성해야 했던 상황

• Git 규칙을 따르지 않는 개발자가 많아지면서 브랜치가 관리되지 않음.
• 브랜치 이력 복잡화 + 충돌 해결 어려움 → 결국 레포를 삭제하고 새로 생성.

---

✅ 해결 방법 - Git 브랜치 전략 도입 및 규칙 설정

💡 1) 협업을 위한 Git 브랜치 전략을 도입 (Feature Branch Workflow 적용)

• GitHub Issue 생성 → Issue 번호를 기반으로 Feature 브랜치 생성.
• 개발 완료 후 PR을 생성하여 코드 리뷰 후 Merge 진행.

📌 Git 브랜치 전략

- main (배포 브랜치)
- develop (개발 브랜치)
  ├── feature/{issue-number}-feature-name (기능 개발 브랜치)
  ├── bugfix/{issue-number}-bug-description (버그 수정 브랜치)

📌 예제 브랜치 관리 방법

# 1. 새로운 기능 개발 시
git checkout -b feature/12-add-auth-system

# 2. 개발 완료 후 커밋 & Push
git commit -m "Add authentication system (#12)"
git push origin feature/12-add-auth-system

# 3. PR 생성 후 코드 리뷰 요청
# 4. 리뷰 완료 후 Merge & 브랜치 삭제

💡 2) 강제 Merge 방지를 위해 Git 규칙 수립
✅ PR 없이 main에 직접 Push 금지 (Branch Protection 설정)
✅ 모든 PR은 최소 1명 이상의 코드 리뷰 후 Merge
✅ Merge 전에 반드시 develop 브랜치에서 Pull 후 Conflict 해결

📌 Branch Protection 설정 예시 (GitHub 설정)

• main 브랜치에 직접 Push 불가능하도록 설정.
• PR을 통해서만 Merge 가능하도록 제한.
• 최소 1명 이상의 코드 리뷰를 필수로 설정.

💡 3) Git 커밋 메시지 및 브랜치 네이밍 규칙 통일
✅ Issue 번호 기반 브랜치 네이밍
✅ 커밋 메시지 규칙 설정 → feat:, fix:, docs:, refactor: 등의 Prefix 사용

📌 예제

feat: Add authentication system (#12)
fix: Resolve login bug (#23)
docs: Update API documentation (#30)

---

🛠️ 브랜치 전략 도입 후 얻은 이점

📌 협업이 훨씬 쉬워짐!

• ✅ 각 기능별 브랜치가 명확해져 코드 관리가 체계화됨.
• ✅ Git 브랜치 이력이 깨끗해지고, 코드 충돌이 감소.
• ✅ 레포를 날리는 최악의 상황을 방지할 수 있었음.

📌 코드 품질 개선!

• ✅ PR을 통한 코드 리뷰 과정이 필수화됨 → 코드 품질 향상.
• ✅ 강제 Merge 방지를 통해 코드 안정성 유지.

📌 팀원들의 Git 사용 능력 향상

• ✅ GitHub 활용 능력이 부족했던 개발자들도 Git 브랜치 전략을 따르면서 협업 역량 상승.
• ✅ Git 규칙을 지키지 않으면 협업이 불가능하다는 점을 인식하게 됨.

---

🔥 Git 전략 도입 후 배운 점 & 느낀 점

✅ Git 브랜치 전략이 없으면 협업이 불가능하다!
✅ 혼자 개발할 때는 필요 없지만, 팀 프로젝트에서는 Git 전략이 필수다.
✅ PR을 통한 코드 리뷰 과정이 코드 품질을 크게 향상시킨다.
✅ 강제 Merge는 최악의 결과를 초래할 수 있다 → 반드시 브랜치 보호 설정이 필요하다.
✅ 레포를 새로 파는 일은 없어야 한다 → Git 관리가 곧 협업의 기본이다.

---

📌 최종 정리 (TL;DR)

• 기존에는 Git 브랜치 전략이 없어서 강제 Merge, 코드 충돌, 협업 문제 발생.
• ✅ Feature Branch Workflow 도입 → 브랜치 구조 및 Merge 프로세스 정립.
• ✅ PR을 통한 코드 리뷰 필수화 → 코드 품질 향상.
• ✅ Branch Protection 설정 → 강제 Merge 방지.
• 🚀 결과적으로 협업 효율이 대폭 향상되었고, 안정적인 Git 관리가 가능해짐!

---