06 Local Development

로컬 개발 가이드

문서 상태

현재 저장소는 Spring Boot 초기 골격 단계입니다. 이 페이지는 현재 가능한 실행 방법과 #3 개발 기반 완료 후의 M3 목표 개발환경을 구분합니다.

현재 저장소 실행

준비물

• Git
• Java 17
• 인터넷 연결: 첫 Gradle 의존성 다운로드에 필요

내려받기

git clone https://github.com/fowoco/server.git
cd server

테스트

현재 gradlew 실행 권한이 없으므로 #3이 완료되기 전에는 다음처럼 실행합니다.

bash gradlew test

#3 완료 후 표준 명령은 다음과 같습니다.

./gradlew clean test

서버 실행

bash gradlew bootRun

현재 local 프로필은 인메모리 H2를 사용합니다.

curl http://localhost:8080/health

예상 응답:

OK

M3 목표 개발환경

#3과 #9 완료 후에는 다음 흐름을 표준으로 사용합니다.

1. .env.example을 참고해 개인 환경변수를 설정합니다.
2. Docker Compose로 PostgreSQL을 실행합니다.
3. Flyway가 빈 DB에 migration을 적용합니다.
4. local Provider를 Fake 또는 LM Studio로 선택합니다.
5. ./gradlew bootRun으로 Backend를 실행합니다.
6. Swagger와 Health/Readiness를 확인합니다.

예정 명령 예시:

docker compose up -d postgres
./gradlew bootRun
./gradlew test

실제 Compose 서비스명과 환경변수는 구현 PR의 README를 기준으로 갱신합니다.

AI Provider 선택

Provider	사용 환경	주의
fake	단위·통합 테스트	외부 네트워크 없이 결정적 결과
lmstudio	개발 실험	최종 데모에 사용하지 않음
external	staging·demo	API Key를 환경변수/Secret으로 관리

설정 개념 예시:

fowoco:
  ai:
    provider: fake
    agent-version: task-agent-v1
    prompt-version: task-analysis-v1
    context-pack-version: context-v0.2
    workflow-catalog-version: workflow-v1

실제 Provider 이름과 모델명은 #8 구현에서 확정합니다.

테스트 층

테스트	목적	외부 의존성
단위 테스트	상태 전이·검증 규칙	없음
Repository 테스트	JPA 쿼리·사업장 격리	Testcontainers PostgreSQL
API 통합 테스트	인증·권한·HTTP 계약	Fake AI + PostgreSQL
Provider 계약 테스트	외부 LLM JSON 계약	별도 수동/Smoke 환경
E2E	대표 사용자 흐름	배포 환경

일반 PR의 CI는 외부 유료 LLM을 호출하지 않습니다.

브랜치와 PR

git switch main
git pull --ff-only
git switch -c feat/3-foundation

권장 브랜치 이름:

feat/4-auth-multitenancy
feat/6-task-workflow
fix/7-expired-worker-link
docs/wiki-local-development

한 PR은 가능하면 한 Issue를 해결합니다. PR 본문에 Closes #번호를 넣고 해당 Issue의 완료 조건을 체크합니다.

Secret 주의

다음 파일과 값을 커밋하지 않습니다.

• .env
• LLM API Key
• JWT Secret
• DB 비밀번호
• Worker Link 토큰
• 실제 근로자 개인정보가 든 Seed·로그·스크린샷

실수로 커밋했다면 파일만 지우고 끝내지 말고 즉시 Key를 폐기·재발급하고 팀에 알립니다.

자주 생기는 문제

./gradlew: permission denied

#3 완료 전에는 bash gradlew ...을 사용합니다. 근본 해결은 Git 실행 비트 반영입니다.

Java 버전 오류

java -version

Java 17이 선택됐는지 확인합니다.

DB 연결 실패

• PostgreSQL 컨테이너 상태
• DATABASE_URL 또는 host/port
• 사용자와 DB 이름
• Flyway migration 로그
• prod/local 프로필 혼용 여부

AI 요청 실패

• 현재 Provider 설정
• Base URL과 모델명
• Timeout과 Rate Limit
• API Key 존재 여부만 확인하고 값은 출력하지 않기
• AiInvocation의 request_id와 오류 유형

관련 이슈

• #3 개발 기반
• #8 AI Adapter
• #9 데모 배포
• #10 E2E