-
Notifications
You must be signed in to change notification settings - Fork 0
06 Local Development
#3 개발 기반은 PR #22로 완료됐습니다. 현재 main에서 Gradle Wrapper 실행 권한, Spring Security, Swagger, Flyway, 공통 오류, request_id, profile, H2/PostgreSQL test, CI를 사용할 수 있습니다.
기능 API는 아직 GET /health 하나뿐입니다. 아래 “현재 사용 가능”과 “후속 Issue에서 추가”를 구분해 주세요.
- Git
- JDK 17
- 첫 Gradle dependency download를 위한 internet
git clone https://github.com/fowoco/server.git
cd server
./gradlew clean test
./gradlew bootRun새 terminal에서 확인합니다.
curl http://localhost:8080/health정상 응답은 OK입니다.
- Swagger UI:
http://localhost:8080/swagger-ui.html - OpenAPI JSON:
http://localhost:8080/v3/api-docs - H2 Console(local 전용):
http://localhost:8080/h2-console
기본 profile은 local이며 memory H2를 사용합니다. 서버를 다시 실행하면 local data가 초기화되고 Flyway migration이 다시 적용됩니다. local server는 H2 Console 보호를 위해 기본적으로 127.0.0.1에 bind합니다.
먼저 local PostgreSQL에 fowoco database를 준비합니다. Docker Compose는 #9에서 표준화할 예정이므로 현재는 팀의 local PostgreSQL 방법을 사용합니다.
export DB_URL=jdbc:postgresql://localhost:5432/fowoco
export DB_USERNAME=postgres
export DB_PASSWORD='로컬 전용 값'
export SPRING_PROFILES_ACTIVE=dev
./gradlew bootRun.env.example은 필요한 변수 이름을 보여주는 문서이며 Spring Boot가 자동으로 읽지 않습니다. shell 또는 IDE run configuration에 값을 등록합니다.
| Profile | DB | 용도 | 주의 |
|---|---|---|---|
local |
memory H2 + Flyway | 빠른 개발·Swagger | PostgreSQL 전용 동작을 보장하지 않음 |
test |
test별 H2 | 빠른 자동 test | domain 통합은 PostgreSQL test도 필요 |
dev |
PostgreSQL | local 통합 개발 | DB 환경변수 필요 |
prod |
PostgreSQL | 배포 | Swagger/H2 Console 비활성, CORS 값 필수 |
JPA는 모든 profile에서 ddl-auto: validate입니다. schema 변경은 Entity 자동 생성이 아니라 src/main/resources/db/migration의 Flyway SQL로 관리합니다.
-
/health, Swagger/OpenAPI, local H2 Console만 공개합니다. - 그 외 endpoint는 JWT가 아직 없어 기본적으로 차단됩니다.
- #4에서 Access/Refresh Token, Role,
company_idContext를 연결합니다. - session 없는 Authorization header 기반 REST를 전제로 현재 CSRF를 비활성화했습니다.
- cookie 인증을 추가하면 CSRF 결정을 반드시 다시 검토합니다.
Client 주소가 기본 http://localhost:3000, http://localhost:5173과 다르면 CORS_ALLOWED_ORIGINS에 쉼표로 등록합니다. prod에서는 이 값이 없으면 시작하지 않게 유지합니다.
AI Provider 선택은 아직 구현되지 않았습니다. #8과 #24가 완료된 뒤 다음 원칙으로 구성합니다.
| Provider | 환경 | 원칙 |
|---|---|---|
| Fake | unit/integration test | 외부 network 없이 결정적 결과 |
| LM Studio | local experiment | 최종 demo 의존성 금지 |
| External | staging/demo | API key를 Secret으로 관리 |
Fake는 test fixture이지 실제 장애 fallback이 아닙니다. 장애를 성공으로 위장하지 않습니다.
| Test | 목적 | 의존성 |
|---|---|---|
| Unit | 상태 전이·검증·fingerprint·error mapping | 없음 |
| Repository | JPA·tenant query·unique/optimistic lock | Testcontainers PostgreSQL |
| API integration | 인증·권한·HTTP·idempotency | Fake AI + PostgreSQL |
| Provider contract | HTTP·Structured Output·timeout | 별도 smoke 환경 |
| Recovery | process restart·event replay·duplicate delivery | PostgreSQL |
| E2E | 대표 사용자·실패 흐름 | 배포 환경 |
일반 PR CI는 유료 외부 LLM을 호출하지 않습니다.
작업 시작:
git switch main
git pull --ff-only
git switch -c feat/23-architecture-adr권장 branch 예시:
feat/4-auth-multitenancy
feat/24-async-ai-run
fix/7-worker-link-expiry
docs/23-architecture-adr
- 한 PR은 가능하면 한 Issue를 해결합니다.
-
PR 제목은 팀 규칙대로 한국어로 작성하되
AI Run,Workflow,JWT, class/API 이름 같은 기술 식별자를 억지로 번역하지 않습니다. - Commit은 Conventional Commits 형식을 사용합니다. 모든 내용을 무조건 한글로 바꾸는 규칙은 없습니다.
feat(ai): persist async AI run lifecycle
fix(workflow): 승인 버전 불일치 전이 차단
test(event): restart recovery scenario 추가
docs(wiki): reliable execution contract 정리
PR 본문에는 변경 이유·검증·보안 영향·rollback과 Closes #번호를 적습니다.
commit하지 않는 것:
-
.env, LLM API key, JWT secret, DB password - Worker Link 원본 token과 Authorization header
- 실제 근로자 개인정보가 든 seed·log·screenshot
- Provider request/response 전문과 Prompt 원문
실수로 commit했다면 file만 지우지 말고 key/token을 즉시 폐기·rotation하고 팀에 알립니다.
현재 main에는 실행 권한이 반영돼 있습니다. 오래된 branch라면 git fetch origin 후 최신 main과 비교하세요. 임시로 bash gradlew에 의존해 권한 문제를 숨기지 않습니다.
java -versionJDK 17이 선택됐는지 확인합니다.
-
SPRING_PROFILES_ACTIVE와 DB URL - PostgreSQL process/container 상태
- 사용자·database 권한
- Flyway version 순서와 checksum
- Entity와 migration 불일치
flywayClean으로 공유 DB를 지우지 않습니다.
현재 미구현 API는 Security 기본 차단이 정상입니다. /health와 local Swagger가 접근 가능한지 먼저 확인하고 #4 구현 상태를 봅니다.
AI 기능이 아직 구현 전인지 #8/#24 상태를 먼저 확인합니다. 구현 후에는 Provider, timeout, circuit, request_id/trace_id, AI Run error_code를 확인하되 key 값은 출력하지 않습니다.