chore: develop 변경사항 main 릴리즈 배포

build.gradle

@@ -41,7 +41,6 @@ dependencies {
     implementation 'software.amazon.awssdk:s3'
     implementation 'com.drewnoakes:metadata-extractor:2.19.0'
     implementation 'com.fasterxml.jackson.core:jackson-databind'
-    implementation 'org.apache.pdfbox:pdfbox:3.0.3'
     runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.12.6'
     runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.12.6'
     compileOnly 'org.projectlombok:lombok'

deploy/.env.example

@@ -31,7 +31,12 @@ SPRING_MAIL_PROPERTIES_MAIL_SMTP_AUTH=true
 SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_ENABLE=true
 SPRING_MAIL_USERNAME=
 
+AI_SERVER_BASE_URL=http://ai:8000
+OPENAI_ENABLED=false
 OPENAI_API_KEY=
+OPENAI_MODEL=gpt-4.1-mini
+OPENAI_BASE_URL=https://api.openai.com/v1
+OPENAI_TIMEOUT_SECONDS=60
 
 AUTH_EMAIL_FROM_ADDRESS=
 AUTH_EMAIL_NOOP_ALLOWED=false

deploy/docker-compose.yml

@@ -97,9 +97,7 @@ services:
       CLOVA_OCR_SECRET_KEY: ${CLOVA_OCR_SECRET_KEY}
       PAPAGO_CLIENT_ID: ${PAPAGO_CLIENT_ID}
       PAPAGO_CLIENT_SECRET: ${PAPAGO_CLIENT_SECRET}
-      OPENAI_API_KEY: ${OPENAI_API_KEY}
-      OPENAI_MODEL: ${OPENAI_MODEL:-gpt-4.1-mini}
-      OPENAI_MAX_TOKENS: ${OPENAI_MAX_TOKENS:-2000}
+      AI_SERVER_BASE_URL: ${AI_SERVER_BASE_URL:-http://ai:8000}
     secrets:
       - source: spring_mail_password
         target: spring_mail_password
@@ -108,6 +106,8 @@ services:
         condition: service_healthy
       redis:
         condition: service_healthy
+      ai:
+        condition: service_healthy
     healthcheck:
       test: ["CMD-SHELL", "curl -fsS http://localhost:8080/actuator/health || exit 1"]
       interval: 30s
@@ -120,7 +120,11 @@ services:
     image: ${AI_IMAGE:-gachi-ai:latest}
     container_name: gachi-ai
     environment:
-      OPENAI_API_KEY: ${OPENAI_API_KEY}
+      OPENAI_ENABLED: ${OPENAI_ENABLED:-false}
+      OPENAI_API_KEY: ${OPENAI_API_KEY:-}
+      OPENAI_MODEL: ${OPENAI_MODEL:-gpt-4.1-mini}
+      OPENAI_BASE_URL: ${OPENAI_BASE_URL:-https://api.openai.com/v1}
+      OPENAI_TIMEOUT_SECONDS: ${OPENAI_TIMEOUT_SECONDS:-60}
     healthcheck:
       test: ["CMD-SHELL", "curl -fsS http://localhost:8000/ai/health || exit 1"]
       interval: 30s

deploy/nginx/nginx.conf

@@ -100,6 +100,36 @@ http {
       proxy_set_header X-Forwarded-Proto $scheme;
     }
 
+    location /ai/docs {
+      auth_basic "GACHI Swagger";
+      auth_basic_user_file /etc/nginx/secrets/swagger_htpasswd.txt;
+      proxy_pass http://ai_upstream;
+      proxy_set_header Host $host;
+      proxy_set_header X-Real-IP $remote_addr;
+      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+      proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    location = /ai/openapi.json {
+      auth_basic "GACHI Swagger";
+      auth_basic_user_file /etc/nginx/secrets/swagger_htpasswd.txt;
+      proxy_pass http://ai_upstream;
+      proxy_set_header Host $host;
+      proxy_set_header X-Real-IP $remote_addr;
+      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+      proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    location /ai/redoc {
+      auth_basic "GACHI Swagger";
+      auth_basic_user_file /etc/nginx/secrets/swagger_htpasswd.txt;
+      proxy_pass http://ai_upstream;
+      proxy_set_header Host $host;
+      proxy_set_header X-Real-IP $remote_addr;
+      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+      proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
     location /ai/ {
       proxy_pass http://ai_upstream;
       proxy_set_header Host $host;

deploy/nginx/nginx.https.template.conf

@@ -80,6 +80,36 @@ http {
       proxy_set_header X-Forwarded-Proto $scheme;
     }
 
+    location /ai/docs {
+      auth_basic "GACHI Swagger";
+      auth_basic_user_file /etc/nginx/secrets/swagger_htpasswd.txt;
+      proxy_pass http://ai_upstream;
+      proxy_set_header Host $host;
+      proxy_set_header X-Real-IP $remote_addr;
+      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+      proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    location = /ai/openapi.json {
+      auth_basic "GACHI Swagger";
+      auth_basic_user_file /etc/nginx/secrets/swagger_htpasswd.txt;
+      proxy_pass http://ai_upstream;
+      proxy_set_header Host $host;
+      proxy_set_header X-Real-IP $remote_addr;
+      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+      proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    location /ai/redoc {
+      auth_basic "GACHI Swagger";
+      auth_basic_user_file /etc/nginx/secrets/swagger_htpasswd.txt;
+      proxy_pass http://ai_upstream;
+      proxy_set_header Host $host;
+      proxy_set_header X-Real-IP $remote_addr;
+      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+      proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
     location /ai/ {
       proxy_pass http://ai_upstream;
       proxy_set_header Host $host;
@@ -93,4 +123,4 @@ http {
       add_header Content-Type text/plain;
     }
   }
-}
+}

docs/error-code.md

@@ -2,7 +2,7 @@
 
 상세 에러 코드는 아래 Google Sheets를 단일 원본으로 관리합니다.
 
-- Google Sheets: [Error Code Single Source](https://docs.google.com/spreadsheets/d/1sUG_JJsVl6a8nR6k8jO_b7UrIEZzuvQdPB6S2S6fqgo/edit?gid=2097363290#gid=2097363290)
+- Google Sheets: [Error Code Single Source](https://docs.google.com/spreadsheets/d/1sUG_JJsVl6a8nR6k8jO_b7UrIEZzuvQdPB6S2S6fqgo/edit?gid=1519705696#gid=1519705696)
 
 ## 운영 원칙
 

docs/newsletter-ai-analyze-integration.md

@@ -0,0 +1,28 @@
+# 가정통신문 AI 전체 분석 응답 저장 연동
+
+이 문서는 BE가 AI 서버의 가정통신문 전체 분석 응답을 저장 모델에 반영하는 구현 결정을 정리한다. 상세 API 명세는 노션을 기준으로 관리한다.
+
+## 결정 사항
+
+- BE는 가정통신문 파이프라인의 AI 분석 단계에서 `POST /ai/newsletters/analyze`를 호출한다.
+- AI 서버 응답의 top-level `title`, `summary`를 `newsletter.title`, `newsletter.summary`에 저장한다.
+- AI 서버 응답의 `items`는 기존 checklist 저장 흐름에 연결한다.
+- `dateCandidates` 요청 형식과 `items` 응답 형식은 기존 `extract-items` 계약을 유지한다.
+- `meta`는 운영 보조 정보로 받고, 현재 BE 저장 모델에는 직접 저장하지 않는다.
+- AI 서버 호출 실패 정책은 `docs/newsletter-ai-failure-policy.md`를 따른다.
+
+## 저장 정책
+
+- `title`: AI 응답 제목을 우선 저장한다. 빈 값이면 기존 BE fallback 제목을 사용한다.
+- `summary`: AI 응답 요약을 우선 저장한다. 빈 값이면 기존 BE fallback 요약을 사용한다.
+- `items`: `title`이 비어 있지 않은 항목만 checklist로 저장한다.
+- `datetime`: TODO 저장 시 `targetDate`, `targetDateLabel` 생성에 사용한다. 파싱 실패 시 날짜 없이 저장한다.
+- `dateStatus`: checklist 저장 모델에는 별도 컬럼이 없으므로 직접 저장하지 않는다. 단, `confirmed`이고 `datetime`이 파싱 가능한 항목은 calendar preview 생성 대상으로 사용한다.
+- `calendar preview`: AI 분석으로 저장된 checklist/TODO ID와 확정 날짜를 묶어 Redis preview에 저장한다. `ambiguous`, `missing`, 날짜 파싱 실패 항목은 사용자가 확인해야 하므로 preview에 자동 포함하지 않는다.
+
+## 호환 정책
+
+- AI 서버의 `extract-items` baseline API는 유지하지만, BE 파이프라인은 `analyze`를 우선 사용한다.
+- AI 서버가 `items`를 빈 배열로 반환해도 `title`, `summary`는 저장할 수 있다.
+- 확정 날짜가 없는 분석 결과는 기존 Redis preview를 비워, 재분석 후 오래된 일정 후보가 남지 않게 한다.
+- AI 서버 장애 시에는 OCR/번역/dateCandidates 스냅샷을 보존하고 newsletter 상태를 `FAILED`로 둔다.

docs/newsletter-ai-failure-policy.md

@@ -0,0 +1,43 @@
+# AI 서버 장애 시 가정통신문 처리 정책
+
+이 문서는 API 명세서가 아니라 BE가 장애 상황에서 어떤 상태와 데이터를 남길지 정한 운영 정책이다.
+상세 API 명세는 노션을 기준으로 관리한다.
+
+## 결정 사항
+
+- AI 서버 호출 실패 시 newsletter 상태는 `FAILED`로 둔다.
+- 별도 부분 성공 상태는 이번 범위에서 추가하지 않는다.
+- OCR, 정제 원문, 번역 결과, 날짜 후보는 가능한 범위까지 저장한다.
+- AI 분석 결과에서 파생되는 제목, 요약, checklist, calendar event는 생성하지 않는다.
+- 실패 원인 추적을 위해 `failureStage`, `failureReason`을 저장한다.
+- 상태 조회 응답은 `FAILED`일 때 `canRetry=true`와 실패 단계를 반환한다.
+- 사용자는 `POST /api/v1/newsletters/{newsletterId}/analysis/retry`로 같은 문서를 다시 분석할 수 있다.
+
+## 실패 시 저장 범위
+
+AI 서버 단계에서 실패하면 다음 데이터는 남긴다.
+
+- `status = FAILED`
+- `ocrText`
+- `originalText`
+- `translatedText`
+- `dateCandidates`
+- `failureStage = AI_SERVER`
+- `failureReason`
+
+다음 데이터는 비워 둔다.
+
+- `title`
+- `summary`
+- checklist
+- calendar event
+
+## 재시도 정책
+
+재시도는 `FAILED` 상태에서만 허용한다.
+
+재시도 요청이 들어오면 기존 checklist와 calendar event 파생 데이터를 삭제하고, newsletter 상태를 `PENDING`으로 되돌린 뒤 파이프라인을 다시 실행한다.
+
+자동 재시도 큐는 이번 범위에서 만들지 않는다. AI 서버 장애와 문서 입력 문제를 자동으로 구분하기 어렵고, 외부 API 비용과 장애 확산 위험이 있기 때문이다.
+
+추후 필요하면 `failureStage=AI_SERVER`인 건만 백오프 큐에 넣는 방식으로 확장한다.

src/main/java/com/gachi/be/domain/auth/dto/request/SignupRequest.java

@@ -17,4 +17,9 @@ public record SignupRequest(
     @NotBlank
         @Pattern(regexp = PhoneNumberValidation.REGEXP, message = PhoneNumberValidation.MESSAGE)
         String phoneNumber,
-    @NotNull Boolean consentAgreed) {}
+    @NotNull Boolean consentAgreed,
+    @NotNull(message = "languageCode는 필수입니다.")
+        @Pattern(
+            regexp = "^(KO|US|ZH|VI)$",
+            message = "지원하지 않는 언어 코드입니다. KO, US, ZH, VI 중 하나여야 합니다.")
+        String languageCode) {}

src/main/java/com/gachi/be/domain/auth/service/AuthenticatedUserResolver.java

@@ -1,7 +1,7 @@
 package com.gachi.be.domain.auth.service;
 
 import com.gachi.be.domain.user.entity.User;
-import com.gachi.be.domain.user.entity.UserStatus;
+import com.gachi.be.domain.user.entity.enums.UserStatus;
 import com.gachi.be.domain.user.repository.UserRepository;
 import com.gachi.be.global.code.ErrorCode;
 import com.gachi.be.global.exception.BusinessException;

src/main/java/com/gachi/be/domain/auth/service/impl/AuthServiceImpl.java

@@ -22,7 +22,7 @@
 import com.gachi.be.domain.auth.service.TokenHashService;
 import com.gachi.be.domain.auth.service.password.PasswordStrengthEvaluator;
 import com.gachi.be.domain.user.entity.User;
-import com.gachi.be.domain.user.entity.UserStatus;
+import com.gachi.be.domain.user.entity.enums.UserStatus;
 import com.gachi.be.domain.user.repository.UserRepository;
 import com.gachi.be.global.code.ErrorCode;
 import com.gachi.be.global.exception.AppException;
@@ -138,6 +138,7 @@ public SignupResponse signup(SignupRequest request) {
             .name(name)
             .phoneNumber(phoneNumber)
             .status(UserStatus.ACTIVE)
+            .languageCode(request.languageCode())
             .emailVerifiedAt(now)
             .consentAgreedAt(now)
             .consentVersion(authProperties.getConsentVersion())

src/main/java/com/gachi/be/domain/calendar/service/CalendarPreviewRedisService.java

@@ -13,9 +13,9 @@
 /**
  * 캘린더 일정 등록 플로우에서 사용하는 Redis 임시 데이터 관리 서비스.
  *
- * <p>흐름 요약: 1. 가정통신문 AI 분석 완료 → AI 파이프라인에서 Redis에 preview 데이터 저장 (추후 연결) 2. GET /calendar/preview →
- * Redis에서 읽어 팝업에 표시 3. PATCH /calendar/dates → Redis에서 날짜 수정 후 다시 저장 4. POST /calendar → Redis 데이터
- * 기반으로 calendar_events insert → Redis 키 삭제
+ * <p>흐름 요약: 1. 가정통신문 AI 분석 완료 → AI 파이프라인에서 Redis에 preview 데이터 저장 2. GET /calendar/preview → Redis에서
+ * 읽어 팝업에 표시 3. PATCH /calendar/dates → Redis에서 날짜 수정 후 다시 저장 4. POST /calendar → Redis 데이터 기반으로
+ * calendar_events insert → Redis 키 삭제
  *
  * <p>Redis 키 형식: newsletter:preview:{newsletterId} - TTL: 1시간 (사용자가 팝업을 열고 이탈해도 자동 만료)
  */

src/main/java/com/gachi/be/domain/newsletter/api/controller/NewsletterController.java

@@ -65,13 +65,10 @@ public ApiResponse<NewsletterUploadResponse> upload(
                       schema = @Schema(type = "string", format = "binary")))
           @RequestPart("file")
           MultipartFile file,
-      @Parameter(description = "연결할 자녀 ID. 미선택 시 생략") @RequestParam(required = false) Long childId,
-      @Parameter(description = "언어 코드 (KO/US/ZH/VI). 기본값 KO")
-          @RequestParam(defaultValue = "KO")
-          @Pattern(regexp = "KO|US|ZH|VI", message = "language는 KO/US/ZH/VI 중 하나여야 합니다.")
-          String language) {
+      @Parameter(description = "연결할 자녀 ID. 미선택 시 생략") @RequestParam(required = false)
+          Long childId) {
 
-    NewsletterUploadResponse response = newsletterService.upload(userId, file, childId, language);
+    NewsletterUploadResponse response = newsletterService.upload(userId, file, childId);
     return ApiResponse.success(SuccessCode.NEWSLETTER_UPLOAD_SUCCESS, response);
   }
 
@@ -92,6 +89,24 @@ public ApiResponse<NewsletterStatusResponse> getStatus(
     return ApiResponse.success(SuccessCode.NEWSLETTER_STATUS_SUCCESS, response);
   }
 
+  /** 실패한 가정통신문 분석 재시도 API */
+  @Operation(
+      summary = "가정통신문 분석 재시도",
+      description =
+          """
+      FAILED 상태의 가정통신문 분석을 다시 시작합니다.
+      AI 서버 장애로 실패한 경우 기존 OCR/번역 결과는 보존되어 있고, 재시도 시 파이프라인이 다시 실행됩니다.
+      """)
+  @PostMapping("/{newsletterId}/analysis/retry")
+  @ResponseStatus(HttpStatus.ACCEPTED)
+  public ApiResponse<NewsletterUploadResponse> retryAnalysis(
+      @AuthenticationPrincipal Long userId,
+      @Parameter(description = "가정통신문 ID", required = true) @PathVariable Long newsletterId) {
+
+    NewsletterUploadResponse response = newsletterService.retryAnalysis(userId, newsletterId);
+    return ApiResponse.success(SuccessCode.NEWSLETTER_RETRY_ACCEPTED, response);
+  }
+
   /** 번역 결과 조회 API. */
   @Operation(
       summary = "번역 결과 조회",

src/main/java/com/gachi/be/domain/newsletter/dto/response/NewsletterStatusResponse.java

@@ -1,6 +1,7 @@
 package com.gachi.be.domain.newsletter.dto.response;
 
 import com.fasterxml.jackson.annotation.JsonInclude;
+import com.gachi.be.domain.newsletter.entity.Newsletter;
 import com.gachi.be.domain.newsletter.entity.enums.NewsletterStatus;
 
 /**
@@ -10,19 +11,31 @@
  */
 @JsonInclude(JsonInclude.Include.NON_NULL) // null인 필드는 JSON 응답에서 제외
 public record NewsletterStatusResponse(
-    NewsletterStatus status, int progressPercent, String progressMessage, String errorMessage) {
+    NewsletterStatus status,
+    int progressPercent,
+    String progressMessage,
+    String errorMessage,
+    String failureStage,
+    boolean canRetry) {
 
   /**
    * 분석 상태에 따라 적절한 진행률과 에러메시지를 자동 계산하는 팩토리 메서드. TODO: 현재는 고정값으로 처리, 추후 AI 서버에서 단계별 진행률을 받아 세분화 예정
    */
-  public static NewsletterStatusResponse of(NewsletterStatus status) {
-    String safeErrorMessage = "분석 중 오류가 발생했어요. 잠시 후 다시 시도해 주세요.";
+  public static NewsletterStatusResponse of(Newsletter newsletter) {
+    NewsletterStatus status = newsletter.getStatus();
     return switch (status) {
-      case PENDING -> new NewsletterStatusResponse(status, 0, "문서를 준비하고 있어요", null);
-      case PROCESSING -> new NewsletterStatusResponse(status, 60, "텍스트를 인식하고 번역하고 있어요", null);
-      case COMPLETED -> new NewsletterStatusResponse(status, 100, "분석이 완료되었어요", null);
+      case PENDING -> new NewsletterStatusResponse(status, 0, "문서를 준비하고 있어요", null, null, false);
+      case PROCESSING ->
+          new NewsletterStatusResponse(status, 60, "텍스트를 인식하고 번역하고 있어요", null, null, false);
+      case COMPLETED -> new NewsletterStatusResponse(status, 100, "분석이 완료되었어요", null, null, false);
       case FAILED ->
-          new NewsletterStatusResponse(status, 0, null, "분석 중 오류가 발생했어요. 잠시 후 다시 시도해 주세요.");
+          new NewsletterStatusResponse(
+              status,
+              0,
+              null,
+              "분석 중 오류가 발생했어요. 다시 분석을 시도할 수 있어요.",
+              newsletter.getFailureStage(),
+              true);
     };
   }
 }