Wevo Backend

팀원들의 흩어진 의견을 AI가 정리하고 조율해 하나의 결과물로 완성하는 협업 워크스페이스

Wevo는 제안서와 발표 자료를 만드는 과정에서 팀원들의 의견을 실시간으로 수집하고, AI가 의견 사이의 충돌과 공백을 찾아 근거가 추적되는 초안을 생성하도록 돕습니다. 팀 검토와 확정 과정을 거쳐 최종 결과물까지 하나의 흐름으로 관리하는 것이 목표입니다.

핵심 흐름

프로젝트 생성 → 의견 수집 → AI 퍼실리테이션 → 검토·확정 → 결과물 출력

주요 기능

도메인	주요 역할
인증·팀·프로젝트	Google·Kakao 로그인, 회원 및 팀 관리, 프로젝트와 섹션 생성
의견 수집·실시간 협업	의견 작성·제출, 수집 상태 관리, 상태 변화 실시간 공유
AI 퍼실리테이터	Provider 중립 AI gateway 기반 쟁점 감지, 의견 종합, 근거가 포함된 초안 생성
검토·확정·결과물	팀·외부 검토, 수정 요청, 섹션 확정, 결과물 내보내기
인프라·공통·DevOps	공통 응답, 전역 예외 처리, API 문서, 로컬·배포 환경 관리

대표 기능과 API는 MVP 개발 과정에서 변경될 수 있습니다.

기술 스택

• Java 21
• Spring Boot, Spring Data JPA
• PostgreSQL 16, Redis 7
• Docker Compose
• Swagger / Springdoc OpenAPI
• Gradle, JUnit

구현 단계에서는 Spring Security·JWT·Google/Kakao OAuth, SSE 또는 WebSocket/STOMP와 서버 검증을 거치는 AI JSON 구조화 출력을 적용합니다.

AI Provider

현재 실행 가능한 AI Provider는 OpenAI 하나이며, 기본 모델은 gpt-5.6-luna, 기본 reasoning_effort는 medium이다. 기능 서비스는 Provider 중립 gateway 계약을 사용하고 구조화 출력은 Provider 응답 이후에도 서버의 JSON Schema·record·semantic validation을 통과해야 한다.

AI_PROVIDER=openai
OPENAI_API_KEY=
OPENAI_API_BASE_URL=https://api.openai.com
OPENAI_API_MODEL=gpt-5.6-luna
OPENAI_API_TIMEOUT=60s
OPENAI_API_MAX_TOKENS=4096
OPENAI_API_REASONING_EFFORT=medium

운영 compose.prod.yml은 AI_PROVIDER, OPENAI_API_KEY, OPENAI_API_MODEL을 필수로 전달한다. 값이 누락되면 배포 설정 검증 또는 애플리케이션 기동이 실패하며, 의도적으로 AI_PROVIDER=none을 선택한 환경에서는 기존 AI 결과 조회와 비AI 기능만 유지하고 신규·재시도 AI 실행을 503 AI008로 거부한다.

로컬에서 외부 호출 없이 애플리케이션을 확인하려면 .env의 AI_PROVIDER=none을 사용한다. 기본 단위· 계약 테스트는 API key나 네트워크를 요구하지 않으며, 실제 OpenAI smoke는 key와 별도 opt-in을 모두 설정한 경우에만 실행된다.

OpenAI 연결과 opt-in synthetic smoke 절차는 docs/engineering/ai/openai-gpt-5-6-luna.md를 참고한다.

패키지 구조

기능 단위의 도메인형 패키지 구조를 사용하며, 여러 도메인이 공유하는 코드는 global에서 관리합니다.

com.wevo.backend
├── global
│   ├── config
│   ├── security
│   ├── exception
│   └── response
├── auth
├── user
├── project
├── section
├── opinion
├── ai
├── review
└── export

로컬 실행

로컬 데이터베이스 스키마는 Flyway가 생성하고 Hibernate는 엔티티 매핑 일치 여부만 검증합니다. 최초 실행은 .env.example을 .env로 복사해 값을 채운 뒤 진행합니다.

docker compose up -d
.\gradlew.bat bootRun --args='--spring.profiles.active=local'

Flyway V1 도입 전에 ddl-auto=update로 만든 기존 로컬 DB가 있다면 필요한 데이터를 백업한 뒤 볼륨을 한 번 재생성해야 합니다. 자세한 절차와 이유는 src/main/resources/db/migration/README.md를 참고합니다.

API 공통 규칙

• Base URL: /api
• 인증 방식: Bearer JWT
• Content-Type: application/json
• 모든 응답은 ApiResponse<T> 형식으로 통일
• 테이블과 컬럼은 snake_case, Enum은 문자열로 저장

BE 역할

담당자	담당 도메인
한호석	인증·팀·프로젝트 기반
이윤호	의견 수집·실시간 협업
이종원	AI 퍼실리테이터
조은솔	검토·확정·결과물
신진용	인프라·공통·DevOps

협업 규칙

• dev 브랜치에서 작업 브랜치를 생성하고 Pull Request로 병합합니다.
• 브랜치명은 타입/이슈번호-기능명 형식을 사용합니다.
• 커밋 메시지는 타입: 설명 (#이슈번호) 형식을 사용합니다.
• Pull Request는 두 명 이상의 승인을 받은 뒤 Merge commit 방식으로 병합합니다.

운영 배포

AWS 운영 환경의 수동 배포, 상태 확인, 복구 및 롤백 절차는 DEPLOYMENT.md를 참고합니다.

관련 링크

• Wevo Notion
• Team Wevo GitHub
• Wevo Frontend