ah/backend

08_backend 입문 — Spring Boot / JPA 기초 primer (백엔드 교재 읽기 전 필독)

원본 코드: backend/src/main/java/com/DevBridge/devbridge/... (이 문서는 추측 없이 실제 프로젝트 코드만 인용합니다)
이 문서는 교재 표준 형식(엔진 교재의 01_backtest/vbt_engine.md)을 따릅니다.
용도: ① 백엔드 도메인 교재를 읽기 전 Spring/JPA 기초 다지기 → ② 한 줄씩 학습 → ③ 강의 자료.
작성 원칙: "아주 잘 가르치는 교수"처럼 — 비유·예시·"초보가 헷갈리는 포인트"를 곁들인다.

---

📌 이 파일 한눈에

이 primer는 "Java/Spring 백엔드라는 건물의 설계도" 입니다. 엔진 교재(Python/FastAPI)를 다 읽고 나서 백엔드(08_backend/*)로 넘어오면, 갑자기 @RestController, @Entity, @Transactional 같은 낯선 애너테이션(@로 시작하는 표식) 이 쏟아집니다. 이 문서는 그 표식들이 무슨 뜻인지, 그리고 HTTP 요청 하나가 어떻게 자바 메서드까지 흘러가 DB를 건드리고 다시 JSON으로 돌아오는지를 한 흐름으로 설명합니다.

핵심만 먼저:

개념	한 줄 요약	비유
Spring Boot	서버 앱을 "자동 조립"해주는 프레임워크 (톰캣 내장)	가구가 미리 조립돼 오는 이케아 풀세트
3계층	Controller(접수) → Service(처리) → Repository(DB)	은행 창구 → 직원 → 금고
DI(의존성 주입)	필요한 부품을 스프링이 알아서 꽂아줌	콘센트에 플러그 꽂기(전기는 한전이 줌)
JPA/Hibernate	자바 객체 ↔ DB 테이블 자동 변환	한국어↔영어 자동 통역기
이 프로젝트 특수성	Spring Security 끔 → 인가는 컨트롤러에서 AuthContext null 체크로 수동	자동문 대신, 직원이 직접 신분증 확인

비유: 엔진(Analytics)이 "숫자를 계산하는 연구소" 였다면, 백엔드(Spring)는 "은행 창구" 입니다. 누가(인증) 무엇을(요청) 요구했는지 확인하고, 금고(DB)에서 돈/데이터를 꺼내거나 넣고, 영수증(JSON)을 돌려줍니다.

---

🧠 사전 지식 (이거 모르면 막힘)

1) "애너테이션(Annotation)" = 코드에 붙이는 스티커 라벨

@RestController   // ← 이게 애너테이션
public class NotificationController { ... }

• @로 시작하는 한 줄짜리 표식. 실행되는 코드가 아니라, 스프링에게 주는 지시문입니다.
• @RestController는 "이 클래스는 HTTP 요청을 받는 접수처야"라고 스프링에게 알려주는 라벨.
• 비유: 택배 상자에 붙은 "취급주의", "냉장보관" 스티커. 상자 내용물(코드)은 그대로지만, 처리하는 쪽(스프링)이 라벨을 보고 다르게 다룹니다.

2) "빈(Bean)" = 스프링이 만들어서 보관 중인 부품 객체 하나

• 스프링은 앱이 켜질 때 @Component, @Service, @RestController, @Repository 라벨이 붙은 클래스들을 하나씩 만들어 창고(ApplicationContext)에 넣어둡니다. 이 창고 속 객체 하나하나가 "빈"입니다.
• 비유: 공장이 가동되면 필요한 기계(부품)를 미리 다 조립해 공장 한쪽에 세워둠. 필요할 때 가져다 씀(새로 안 만듦).

3) "HTTP 요청/응답" = 편지 한 통

요청:  GET /api/notifications        ← "내 알림 목록 줘"
응답:  200 OK  [ {...}, {...} ]       ← "여기 있어 (상태코드 + JSON 본문)"

• 메서드(GET=조회 / POST=생성 / PATCH=일부수정 / DELETE=삭제) + 경로(/api/notifications) + 가끔 본문(body, JSON).
• 응답에는 상태코드(200 성공, 401 인증필요, 404 없음, 500 서버오류)와 본문이 들어갑니다.

4) "JSON" = 프론트(React)와 백엔드가 주고받는 공통 문서 포맷

{ "id": 7, "title": "체결 완료", "isRead": false }

• 자바 객체 → JSON 변환은 스프링(Jackson 라이브러리)이 자동으로 합니다. 우리는 자바 객체만 반환하면 됩니다.

---

🗺 전체 흐름도 — 요청 하나의 일생

이 프로젝트의 알림(notification) 도메인을 예로, GET /api/notifications 요청 하나가 흐르는 경로:

[React 프론트]  GET /api/notifications  (+ HttpOnly JWT 쿠키)
       │
       ▼
[JwtAuthenticationFilter]  쿠키에서 JWT 꺼내 → request에 userId 도장 찍음  ★필터 단계
       │
       ▼
[NotificationController]  @GetMapping  ← "접수처"
       │   AuthContext.currentUserId() 로 신원 확인 (null이면 401)   ★수동 인가
       ▼
[StreamChatService]  @Transactional  ← "처리 직원" (비즈니스 규칙)
       │
       ▼
[NotificationRepository]  findByUser...()  ← "금고지기" (SQL 자동 생성)
       │
       ▼
[MySQL  NOTIFICATION 테이블]  ← 실제 데이터
       │  (조회된 Notification 엔티티들이 거꾸로 올라옴)
       ▼
[Controller]  엔티티 → NotificationResponse(DTO) 변환 → ResponseEntity.ok(...)
       │
       ▼
[스프링/Jackson]  DTO → JSON 자동 변환 → 200 OK 응답

이 한 장이 백엔드의 전부입니다. 아래에서 각 단계를 실제 코드로 풉니다.

---

📖 개념별 해설 (실제 코드 인용 + 비유)

A. Spring Boot 가 뭔가 — "자동 조립 + 내장 톰캣"

backend/build.gradle 의 맨 위:

// build.gradle:1-5
plugins {
    id 'java'
    id 'org.springframework.boot' version '4.0.4'
    id 'io.spring.dependency-management' version '1.1.7'
}

• Spring Boot 는 "스프링으로 서버를 만들 때 필요한 수백 가지 설정을 미리 해둔 풀세트"입니다. 핵심 마법 두 가지:
  1. 자동설정(Auto-configuration) — DB 드라이버를 의존성에 넣기만 하면, 스프링이 "아 MySQL 쓰는구나" 하고 연결을 알아서 구성. 우리가 XML로 일일이 설정하지 않습니다.
  2. 내장 톰캣(Embedded Tomcat) — 옛날엔 톰캣(웹서버)을 따로 설치하고 그 위에 앱을 얹었지만, Spring Boot 는 웹서버를 앱 안에 품고 있어 gradlew bootRun 한 줄이면 서버가 켜집니다.

build.gradle 의 의존성(dependencies) 블록이 "어떤 부품을 쓸지"의 목록입니다:

// build.gradle:27-34 (발췌)
implementation 'org.springframework.boot:spring-boot-starter-data-jpa'   // JPA(DB)
implementation 'org.springframework.boot:spring-boot-starter-webmvc'      // 웹(HTTP)
implementation 'io.jsonwebtoken:jjwt-api:0.12.6'                          // JWT
implementation 'org.flywaydb:flyway-core'                                 // DB 마이그레이션

• ...starter-* 는 "세트 메뉴" 입니다. starter-webmvc 하나면 HTTP 처리에 필요한 수십 개 라이브러리가 한 번에 딸려옵니다.

💡 초보 포인트: CLAUDE.md엔 "Java 21"이라 적혀 있지만 실제 build.gradle의 toolchain은 17(JavaLanguageVersion.of(17))입니다. 문서와 코드가 다를 땐 코드가 진실입니다 — 항상 실제 빌드 파일을 확인하세요.

---

B. 3계층 아키텍처 — Controller → Service → Repository

이 프로젝트는 도메인 드리븐 구조로, 각 도메인(notification, user, strategy...)이 자기만의 5개 폴더를 가집니다:

domain/notification/
├── controller/   ← 접수처 (HTTP 요청 받기)
├── service/      ← 처리실 (비즈니스 규칙)  ※알림은 chat 도메인의 StreamChatService가 겸함
├── entity/       ← DB 테이블의 자바 거울
├── repository/   ← 금고지기 (DB 읽고 쓰기)
└── dto/          ← 바깥세상과 주고받는 포장지

왜 3개로 쪼개나? 비유: 은행에서 "창구 직원이 직접 금고에 들어가 돈을 세고 영수증까지 인쇄"하면 혼란스럽고 위험합니다. 그래서 창구(Controller)는 접수만, 직원(Service)은 규칙 판단만, 금고지기(Repository)는 보관만 — 역할을 나눠 각자 한 가지만 잘하게 합니다. 한 곳이 고장 나도 다른 곳에 영향이 적고, 테스트·교체가 쉬워집니다.

1) Controller — "접수처"

// NotificationController.java:23-39
@RestController
@RequestMapping("/api/notifications")
@RequiredArgsConstructor
public class NotificationController {

    private final StreamChatService streamChatService;
    private final UserRepository userRepository;

    /** GET /api/notifications — 인증 사용자 본인 알림 전체, 최신순. */
    @GetMapping
    public ResponseEntity<?> getAll() {
        User user = currentUser();
        if (user == null) return unauthorized();
        List<NotificationResponse> list = streamChatService.getNotificationsForUser(user)
                .stream().map(NotificationResponse::from).toList();
        return ResponseEntity.ok(list);
    }

• @RestController — "이 클래스는 HTTP 접수처, 반환값은 JSON으로"
• @RequestMapping("/api/notifications") — 이 클래스의 모든 메서드 경로 앞에 공통으로 붙는 주소 접두사.
• 컨트롤러는 직접 일하지 않습니다. streamChatService.getNotificationsForUser(user)로 처리를 Service에게 위임하고, 결과를 DTO로 포장해 돌려줄 뿐입니다. (창구 직원이 금고에 직접 안 들어가는 것.)

2) Service — "처리실 (비즈니스 규칙)"

// StreamChatService.java:226-251 (발췌)
public List<Notification> getNotificationsForUser(User user) {
    return notificationRepository.findByUserOrderByCreatedAtDesc(user);
}

@Transactional
public void markNotificationRead(Long notificationId, User user) {
    notificationRepository.findById(notificationId).ifPresent(n -> {
        if (n.getUser().getId().equals(user.getId())) {   // ★소유권 재확인
            n.setRead(true);
            notificationRepository.save(n);
        }
    });
}

• Service는 "규칙" 이 사는 곳입니다. 위 markNotificationRead는 단순히 "읽음 처리"가 아니라, "이 알림이 정말 이 사용자 것인지 한 번 더 확인"(n.getUser().getId().equals(user.getId()))하는 보안 규칙을 품고 있습니다. 남의 알림이면 조용히 무시합니다.
• Repository(금고지기)를 호출해 실제 데이터를 가져오거나 저장합니다.

3) Repository — "금고지기 (DB)"

// NotificationRepository.java:12-22
public interface NotificationRepository extends JpaRepository<Notification, Long> {

    List<Notification> findByUserOrderByCreatedAtDesc(User user);

    List<Notification> findByUserAndIsReadFalseOrderByCreatedAtDesc(User user);

    long countByUserAndIsReadFalse(User user);

    @Modifying
    @Query("UPDATE Notification n SET n.isRead = true WHERE n.user = :user AND n.isRead = false")
    void markAllReadByUser(@Param("user") User user);
}

• 놀라운 점: 이건 interface(껍데기)일 뿐, 구현 코드(SQL)가 없습니다. 그런데도 동작합니다. (→ 아래 D절 "메서드 이름 쿼리"에서 설명.)
• extends JpaRepository<Notification, Long> — "Notification 엔티티를, ID 타입은 Long으로 다루는 금고지기" 라는 뜻. 이것만으로 save(), findById(), findAll(), delete() 같은 기본 CRUD가 공짜로 생깁니다.

💡 초보 포인트: 데이터는 위→아래로 요청이 내려가고, 결과는 아래→위로 올라옵니다. Controller는 Service만 알고, Service는 Repository만 알고, Repository만 DB를 압니다. 이 "한 방향 의존"이 깨지면(예: Repository가 Controller를 부르면) 구조가 무너집니다.

---

C. 의존성 주입(DI) · @RequiredArgsConstructor · 빈(Bean)

위 컨트롤러에서 streamChatService, userRepository는 어디서 만들어졌을까요? 우리는 new StreamChatService()를 어디에도 쓰지 않았습니다.

// NotificationController.java:25-29
@RequiredArgsConstructor
public class NotificationController {

    private final StreamChatService streamChatService;
    private final UserRepository userRepository;

• DI(Dependency Injection, 의존성 주입) = "내가 필요한 부품을 내가 new로 만들지 않고, 스프링이 만들어서 꽂아준다".

• @RequiredArgsConstructor(Lombok) — final 필드들을 받는 생성자를 자동으로 만들어줍니다. 즉 내부적으로는:

  public NotificationController(StreamChatService s, UserRepository u) {
      this.streamChatService = s; this.userRepository = u;
  }

  이 생성자를 스프링이 보고, 창고(ApplicationContext)에서 해당 타입의 빈을 찾아 인자로 넣어줍니다.

• 비유: 새 가전제품(컨트롤러)을 사면 전기를 직접 발전하지 않습니다. 콘센트(생성자)에 플러그를 꽂으면 한전(스프링)이 전기(빈)를 공급. 우리는 "전기가 필요하다"고 선언만 하면 됩니다.

왜 좋은가? 테스트할 때 진짜 Service 대신 가짜(Mock) Service를 꽂아 컨트롤러만 따로 시험할 수 있습니다. 부품을 갈아끼우기 쉬워집니다.

💡 초보 포인트: final + @RequiredArgsConstructor 조합이 이 프로젝트의 표준 DI 패턴입니다. 필드에 @Autowired를 직접 붙이는 옛날 방식보다 권장됩니다(불변·테스트 용이).

---

D. HTTP 요청이 자바 메서드로 매핑되는 법 (매핑 애너테이션 총정리)

스프링은 "어떤 URL + 메서드"가 들어오면 "어떤 자바 함수"를 부를지 애너테이션으로 연결합니다. 알림 컨트롤러에 다 들어 있습니다:

// NotificationController.java (발췌)
@GetMapping                                   // GET  /api/notifications
public ResponseEntity<?> getAll() { ... }

@GetMapping("/unread")                         // GET  /api/notifications/unread
public ResponseEntity<?> getUnread() { ... }

@PatchMapping("/{notificationId}/read")        // PATCH /api/notifications/3/read
public ResponseEntity<?> markOneRead(@PathVariable Long notificationId) { ... }

@PatchMapping("/read-all")                     // PATCH /api/notifications/read-all
public ResponseEntity<?> markAllRead() { ... }

애너테이션	HTTP 메서드	용도	비유
@GetMapping	GET	조회 (데이터 안 바꿈)	"잔액 조회해줘"
@PostMapping	POST	생성 (새로 만듦)	"새 계좌 만들어줘"
@PatchMapping	PATCH	일부 수정	"주소만 바꿔줘"
@DeleteMapping	DELETE	삭제	"계좌 닫아줘"
@RequestMapping("/api/...")	(클래스 레벨)	공통 경로 접두사	"이 창구는 3번 창구"

요청에서 값을 꺼내는 3가지 입구:

1. @PathVariable — URL 경로 안의 변수.

   // NotificationController.java:61-62
   @PatchMapping("/{notificationId}/read")
   public ResponseEntity<?> markOneRead(@PathVariable Long notificationId) {

   • /api/notifications/**3**/read 로 요청하면 notificationId = 3 이 됩니다. 경로의 {notificationId} 칸과 메서드 인자 이름이 짝지어집니다.

2. @RequestParam — ?key=value 쿼리 파라미터. (예: ?page=2) — 이 컨트롤러에선 의도적으로 안 씁니다. 아래 ⚠️ 특이점 절에서 "왜 ?userId=를 안 받는지" 설명합니다.

3. @RequestBody — POST/PATCH의 본문(JSON) 을 자바 객체로 변환.

   // (다른 도메인 예시 패턴) 로그인 요청 본문을 객체로 받기
   @PostMapping("/login")
   public ResponseEntity<?> login(@RequestBody LoginRequest req) { ... }

   • 프론트가 보낸 {"email":"...","password":"..."} JSON을 스프링이 LoginRequest 객체로 자동 변환해 꽂아줍니다.

💡 초보 포인트: GET은 본문(@RequestBody)을 거의 안 쓰고 경로/쿼리로 값을 받습니다. "데이터를 바꾸는(POST/PATCH/PUT)" 요청만 본문 JSON을 보냅니다.

---

E. ResponseEntity 와 상태코드

컨트롤러는 보통 그냥 객체를 반환해도 되지만, 상태코드까지 직접 정하고 싶을 때 ResponseEntity를 씁니다.

// NotificationController.java:33-38, 53-57, 65-66, 85-87
return ResponseEntity.ok(list);                                  // 200 OK + 본문
return ResponseEntity.ok(Map.of("unreadCount", count));          // 200 OK + JSON {unreadCount: 5}
return ResponseEntity.noContent().build();                       // 204 No Content (성공, 본문 없음)
return ResponseEntity.status(HttpStatus.UNAUTHORIZED)            // 401 + {error:"인증 필요"}
                     .body(Map.of("error", "인증 필요"));

코드	의미	이 프로젝트에서
200 OK	성공 + 데이터 있음	알림 목록 반환
204 No Content	성공 + 돌려줄 본문 없음	"읽음 처리" 후
401 Unauthorized	인증 필요(로그인 안 됨)	currentUser() == null 일 때
404 Not Found	자원 없음	존재하지 않는 ID
500 Internal Server Error	서버 터짐	잡히지 않은 예외

• Map.of("unreadCount", count) 같은 임시 자바 Map 도 Jackson이 JSON으로 변환해줍니다({"unreadCount": 5}). 별도 DTO 클래스를 만들 만큼 무겁지 않은 응답에 쓰는 흔한 손쉬운 패턴.

💡 초보 포인트: ResponseEntity<?>의 <?>는 "본문 타입이 경우마다 다르다(리스트일 수도, Map일 수도)"라서 와일드카드로 둔 것. 한 메서드가 성공 시 리스트, 실패 시 에러맵을 반환하니 자연스럽습니다.

---

F. JPA / Hibernate — 자바 객체 ↔ DB 테이블

JPA(Java Persistence API)는 "자바 객체와 DB 테이블을 자동으로 이어주는 규격"이고, Hibernate는 그 규격을 실제로 구현한 엔진입니다. 핵심 마법: SQL을 거의 안 쓰고도 DB를 다룹니다.

1) @Entity — "DB 테이블의 자바 거울"

// Notification.java:15-31 (발췌)
@Entity
@Table(name = "NOTIFICATION")
@Getter @Setter @NoArgsConstructor @AllArgsConstructor @Builder
@EntityListeners(AuditingEntityListener.class)
public class Notification {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "user_id", nullable = false)
    private User user;

• @Entity — "이 클래스는 DB 테이블 하나에 대응한다". 이 클래스의 객체 한 개 = 테이블의 행(row) 한 개.
• @Table(name = "NOTIFICATION") — 대응하는 테이블 이름.
• @Id — 이 필드가 기본키(PK), 행을 구분하는 고유 번호.
• @GeneratedValue(strategy = IDENTITY) — ID를 DB가 자동 증가(auto-increment) 로 매겨줌. 우리가 직접 안 넣음.
• @ManyToOne — 관계 매핑. "여러(Many) 알림이 한(One) 유저에 속한다". 자바에선 notification.getUser()로 객체를 바로 꺼낼 수 있고, DB에선 user_id 외래키(FK) 컬럼으로 저장됩니다.
• @JoinColumn(name = "user_id") — 그 FK 컬럼 이름.
• fetch = FetchType.LAZY — 지연 로딩. 알림을 읽을 때 연결된 User까지 즉시 다 불러오지 않고, getUser()를 실제로 호출하는 순간에만 DB에서 가져옴. (불필요한 조회를 줄여 성능↑.)

각 컬럼은 @Column으로 세부 설정합니다:

// Notification.java:37-55 (발췌)
@Column(nullable = false, length = 200)
private String title;                       // NOT NULL, VARCHAR(200)

@Column(nullable = false, columnDefinition = "TEXT")
private String message;                     // TEXT 타입

@Enumerated(EnumType.STRING)
@Column(name = "notification_type", nullable = false, length = 50)
private NotificationType notificationType;  // enum을 "문자열"로 저장 (숫자 X)

@Column(name = "is_read", nullable = false)
@Builder.Default
private boolean isRead = false;             // 기본값 false

@CreatedDate
@Column(name = "created_at", nullable = false, updatable = false)
private LocalDateTime createdAt;            // 생성 시각 자동 기록 (수정 불가)

• @Enumerated(EnumType.STRING) — NEW_MESSAGE 같은 enum을 DB에 문자열 그대로 저장. (EnumType.ORDINAL로 숫자 0,1,2 저장하면 enum 순서 바뀔 때 데이터가 깨지므로 STRING이 안전.)
• @CreatedDate + @EntityListeners(AuditingEntityListener.class) — 행이 처음 저장될 때 현재 시각을 자동 기입. updatable = false라 이후 수정 불가(생성 시각은 영원히 고정).

2) Repository 인터페이스가 SQL 없이 동작하는 법 — 메서드 이름 쿼리

다시 Repository를 봅시다:

// NotificationRepository.java:14-18
List<Notification> findByUserOrderByCreatedAtDesc(User user);
List<Notification> findByUserAndIsReadFalseOrderByCreatedAtDesc(User user);
long countByUserAndIsReadFalse(User user);

• 충격 포인트: 구현이 없는데 동작합니다. 스프링 데이터 JPA가 메서드 이름을 분석해 SQL을 자동 생성하기 때문입니다.
• 이름을 단어로 끊어 읽으면 그게 곧 쿼리입니다:
  • findBy User OrderBy CreatedAt Desc
    → SELECT * FROM notification WHERE user_id = ? ORDER BY created_at DESC
  • count By User And IsReadFalse
    → SELECT COUNT(*) FROM notification WHERE user_id = ? AND is_read = false
• 비유: 메뉴판에 "매운·곱빼기·계란추가 라면"이라고 적으면 주방장이 알아서 그렇게 만들어 줌. 우리는 이름만 정확히 짓고 레시피(SQL)는 안 씁니다.

이름으로 표현하기 복잡한 쿼리는 @Query로 직접 JPQL을 씁니다:

// NotificationRepository.java:20-22
@Modifying
@Query("UPDATE Notification n SET n.isRead = true WHERE n.user = :user AND n.isRead = false")
void markAllReadByUser(@Param("user") User user);

• @Query — 직접 작성한 쿼리. 단, 테이블이 아니라 Notification이라는 엔티티(자바 클래스)를 대상으로 하는 JPQL입니다(SQL과 비슷하지만 객체 기준).
• @Modifying — "이건 조회가 아니라 데이터를 바꾸는 쿼리"라고 알림(UPDATE/DELETE에 필수).
• :user / @Param("user") — 쿼리 속 자리표시자에 메서드 인자를 끼워넣음(SQL 인젝션 안전).

💡 초보 포인트: 오타가 무섭습니다. findByUesr(오타)라고 쓰면 스프링이 Uesr라는 필드를 못 찾아 앱 기동 시 에러로 알려줍니다(다행히 런타임 중이 아니라 시작할 때 터짐).

---

G. @Transactional — 트랜잭션 (모 아니면 도)

// StreamChatService.java:243-251
@Transactional
public void markNotificationRead(Long notificationId, User user) {
    notificationRepository.findById(notificationId).ifPresent(n -> {
        if (n.getUser().getId().equals(user.getId())) {
            n.setRead(true);
            notificationRepository.save(n);
        }
    });
}

• 트랜잭션(Transaction) = "여러 DB 작업을 하나로 묶어, 전부 성공하거나 전부 취소되게 하는 단위".
• @Transactional이 붙은 메서드는 시작할 때 작업을 열고, 정상 종료 시 커밋(확정), 도중에 예외가 터지면 롤백(전부 되돌림) 합니다.
• 비유: 계좌이체. "A에서 출금"과 "B에 입금" 둘 다 성공해야 하고, 중간에 멈추면 둘 다 없던 일로 해야 함. 출금만 되고 입금이 안 되면 돈이 증발하니까요.
• 숨은 편의 하나: @Transactional 안에서 엔티티의 setRead(true)처럼 값을 바꾸면, 트랜잭션이 끝날 때 Hibernate가 변경을 감지(dirty checking)해 자동으로 UPDATE를 날립니다. (위 코드의 save(n)은 명시적이지만, 트랜잭션 안에서는 생략해도 반영되는 경우가 많습니다.)

💡 초보 포인트: 보통 Controller가 아니라 Service에 @Transactional을 붙입니다. "한 번의 비즈니스 행동(=하나의 Service 메서드)" 단위로 트랜잭션을 잡는 게 자연스럽기 때문.

---

H. DTO ↔ 엔티티 분리, Lombok

1) 왜 엔티티를 그대로 프론트에 안 주고 DTO로 바꾸나?

// NotificationResponse.java (DTO 전체)
@Getter @Builder @NoArgsConstructor @AllArgsConstructor
public class NotificationResponse {
    private Long id;
    private String notificationType;   // enum → String 으로 변환됨
    private String title;
    private String message;
    private String relatedEntityType;
    private Long relatedEntityId;
    private boolean isRead;
    private LocalDateTime createdAt;

    public static NotificationResponse from(Notification n) {       // 엔티티 → DTO 변환기
        return NotificationResponse.builder()
                .id(n.getId())
                .notificationType(n.getNotificationType().name())   // enum.name() = 문자열
                .title(n.getTitle())
                .message(n.getMessage())
                .relatedEntityType(n.getRelatedEntityType())
                .relatedEntityId(n.getRelatedEntityId())
                .isRead(n.isRead())
                .createdAt(n.getCreatedAt())
                .build();
    }
}

• DTO(Data Transfer Object) = "바깥세상(프론트)과 주고받는 포장지". 엔티티(DB 거울)와 일부러 분리합니다.
• 왜 분리하나?
  1. 보안 — 엔티티 Notification은 @ManyToOne private User user(비밀번호 등 민감 정보 포함 가능)를 들고 있습니다. 그대로 JSON으로 내보내면 유저 내부 정보가 줄줄 새거나 무한 순환참조로 터집니다. DTO는 내보낼 필드만 골라 담습니다(위에 user가 없죠).
  2. 안정성 — DB 구조(엔티티)가 바뀌어도 API 응답(DTO) 모양은 그대로 유지 가능. 프론트가 안 깨집니다.
• 컨트롤러에서의 변환은 한 줄:

  // NotificationController.java:36-37
  streamChatService.getNotificationsForUser(user)
          .stream().map(NotificationResponse::from).toList();

  엔티티 리스트를 map(...from)으로 DTO 리스트로 갈아끼웁니다.

2) Lombok — 반복 코드 자동 생성기

엔티티/DTO 위에 붙은 @Getter, @Builder 등이 Lombok 애너테이션입니다. build.gradle:60,62에서 의존성으로 들어옵니다.

Lombok 라벨	자동으로 만들어주는 것
@Getter / @Setter	getTitle(), setRead(...) 같은 접근자 메서드
@Builder	NotificationResponse.builder().id(1).title("x").build() 빌더 패턴
@NoArgsConstructor	인자 없는 기본 생성자 (JPA가 요구)
@AllArgsConstructor	모든 필드를 받는 생성자
@RequiredArgsConstructor	final 필드만 받는 생성자 (← DI에 사용)
@Builder.Default	빌더 사용 시에도 필드 기본값(isRead=false) 유지

• 이 라벨들이 없으면 getter/setter/생성자를 수십 줄 손으로 써야 합니다. Lombok이 컴파일 시점에 자동 생성해 코드를 깔끔하게 유지합니다.

💡 초보 포인트: IDE에서 엔티티를 봐도 getTitle() 정의가 안 보일 수 있습니다 — Lombok이 컴파일할 때 만들기 때문. "분명 호출하는데 정의가 없네?" 싶으면 클래스 위 @Getter를 확인하세요.

---

I. application.properties — 프로파일(local / prod)

같은 코드를 로컬 개발과 운영(EC2) 에서 다르게 설정하려고 프로파일(profile) 을 씁니다.

# application.properties:6  (공통 기본값)
spring.profiles.default=local

# application.properties:20  (기본/공통 — 로컬 친화)
spring.jpa.hibernate.ddl-auto=update
spring.flyway.enabled=false

• 파일 3개가 계층으로 합쳐집니다:
  • application.properties — 공통 기본값 (모든 환경 공유).
  • application-local.properties — 로컬 개발용 덮어쓰기(실키·로컬 DB 비번 등, git 커밋 금지).
  • application-prod.properties — 운영용 덮어쓰기(HTTPS 쿠키, Flyway 켬 등).
• 실행 시 --spring.profiles.active=local 또는 =prod로 어느 덮어쓰기를 쓸지 고릅니다. 안 주면 spring.profiles.default=local이 적용됩니다.
• ${VAR:기본값} 문법 — 환경변수 우선, 없으면 기본값. 예:

  # application.properties:16-18
  spring.datasource.url=jdbc:mysql://${DB_HOST:localhost}:${DB_PORT:3306}/${DB_NAME:alphahelix_db}?...
  spring.datasource.password=${DB_PASSWORD}      ← 기본값 없음 → 반드시 환경/로컬 파일에서 주입

  application-local.properties:6-10이 바로 그 DB_HOST=localhost 등을 채워줍니다.

⚠️ 메모리 교훈: env 우선순위를 바꾸기 전, 같은 키가 다른 파일에서 다른 값으로 중복 정의돼 있는지 반드시 확인하세요(특히 app.crypto.key). application.properties엔 개발용 기본값이, application-local.properties:19엔 또 다른 값이 있어 어느 쪽이 이기는지 헷갈리면 KIS 복호화가 깨집니다.

---

J. Flyway 마이그레이션 — DB 스키마 버전 관리

DB 테이블 구조(스키마)를 코드처럼 버전 관리하는 도구가 Flyway입니다.

# application.properties:132-142 (발췌)
# 로컬(ddl-auto=update)은 비활성, 운영(ddl-auto=validate)은 활성화해서 스키마 버전 관리
spring.flyway.enabled=false
spring.flyway.locations=classpath:db/migration
spring.flyway.baseline-on-migrate=true
spring.flyway.baseline-version=16

• 마이그레이션 파일은 backend/src/main/resources/db/migration/에 V1__baseline.sql, V2__..., ... V18__refresh_tokens_table.sql 처럼 번호 순서대로 쌓입니다.
• Flyway는 DB에 flyway_schema_history 표를 만들어 "어느 V까지 적용했는지" 를 기록하고, 앱 기동 시 아직 안 돌린 V만 차례로 실행합니다. → 누구의 DB든 같은 최종 스키마가 보장됩니다.
• ddl-auto와의 역할 분담(중요):
  • 로컬: ddl-auto=update + flyway.enabled=false → 엔티티를 바꾸면 Hibernate가 편하게 테이블을 자동 수정(빠른 개발).
  • 운영: ddl-auto=validate + Flyway 켬 → Hibernate는 스키마를 절대 바꾸지 않고(검증만), 스키마 변경은 오직 Flyway SQL 파일로만 통제(안전·추적 가능).
• 비유: Flyway는 DB의 git입니다. "테이블에 컬럼 추가" 같은 변경을 번호 매긴 커밋(SQL 파일) 으로 남겨, 어느 서버든 똑같이 재현합니다.

💡 초보 포인트: 새 마이그레이션(V19__...)을 추가하면 application.properties:142의 baseline-version도 그에 맞춰 올려야 한다고 주석이 경고합니다. 번호는 건너뛰지 말고 연속으로.

---

⚠️ 이 프로젝트 특이점 (다른 도메인 교재의 대전제)

★★★ 특이점 1: Spring Security를 끄고, 인가를 컨트롤러에서 수동 처리한다

이게 이 백엔드에서 가장 중요하고 가장 헷갈리는 부분입니다. 다른 도메인 교재들은 전부 이 전제를 깔고 있으니 여기서 확실히 잡고 갑시다.

증거 1 — Security 프레임워크를 의존성에서 뺐다:

// build.gradle:28-30
// implementation 'org.springframework.boot:spring-boot-starter-security'   ← 주석 처리(=안 씀)
// 비밀번호 BCrypt 해싱만 사용 (전체 Security 프레임워크/auto-config 없이 PasswordEncoder 만)
implementation 'org.springframework.security:spring-security-crypto'

• 보통 스프링 앱은 spring-boot-starter-security가 모든 요청을 가로막고 로그인/권한을 자동 관리합니다. 이 프로젝트는 그 전체 프레임워크를 끄고, 비밀번호 해싱용 spring-security-crypto(BCrypt)만 떼어 씁니다.

그럼 인증/인가는 누가 하나? → 직접 만든 필터 + 컨트롤러 수동 체크.

증거 2 — JWT 필터는 "막지 않고, 도장만 찍는다":

// JwtAuthenticationFilter.java:28-32, 42-60 (발췌)
@Component
@Order(Ordered.HIGHEST_PRECEDENCE + 10)
public class JwtAuthenticationFilter extends OncePerRequestFilter {
    ...
    protected void doFilterInternal(HttpServletRequest request, ...) {
        String token = extractToken(request);          // 쿠키 또는 Bearer 헤더에서 JWT 추출
        if (token != null && !token.isBlank()) {
            try {
                var claims = jwtUtil.parse(token);
                Object uid = claims.get("uid");
                if (uid instanceof Number n) {
                    request.setAttribute(ATTR_USER_ID, n.longValue());   // ★ userId를 요청에 "도장"
                }
                ...
            } catch (Exception e) {
                // 토큰 파싱 실패: 익명 요청으로 통과   ← ★막지 않는다!
            }
        }
        chain.doFilter(request, response);              // 무조건 다음으로 통과
    }

• 이 필터는 요청을 거부하지 않습니다. JWT가 유효하면 request에 userId 도장을 찍고, 없거나 깨졌어도 그냥 통과시킵니다(익명으로). 즉 "문지기"가 아니라 "신원 스탬프 찍는 사람"입니다.
• @Order(...HIGHEST_PRECEDENCE + 10) — 이 필터가 다른 필터(AiRateLimitFilter, +20)보다 먼저 돌아야 userId 도장이 미리 찍힙니다.

증거 3 — 실제 "막는" 곳은 컨트롤러다 (수동 인가):

// NotificationController.java:78-87
/** JWT(AuthContext) 의 사용자 — 미인증/미존재면 null. 요청 파라미터 신원은 신뢰하지 않는다. */
private User currentUser() {
    Long uid = AuthContext.currentUserId();        // 필터가 찍은 도장을 꺼냄
    if (uid == null) return null;
    return userRepository.findById(uid).orElse(null);
}

private static ResponseEntity<?> unauthorized() {
    return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body(Map.of("error", "인증 필요"));
}

// NotificationController.java:33-35  (모든 보호 엔드포인트의 첫 두 줄 패턴)
User user = currentUser();
if (user == null) return unauthorized();           // ★ 여기서 직접 401을 낸다

• 이 두 줄(currentUser() → null이면 unauthorized())이 이 프로젝트의 "인가 게이트"입니다. Security 프레임워크가 자동으로 안 막아주므로, 모든 보호 엔드포인트가 자기 손으로 null 체크를 해야 합니다. 빠뜨리면 그 엔드포인트는 무방비로 뚫립니다.

증거 4 — 신원은 오직 JWT에서만 (IDOR 차단):

// AuthContext.java:27-34
public static Long currentUserId() {
    Long override = OVERRIDE_USER_ID.get();        // 스케줄러용 임시 주입(아래 설명)
    if (override != null) return override;
    HttpServletRequest req = currentRequest();
    if (req == null) return null;
    Object v = req.getAttribute(JwtAuthenticationFilter.ATTR_USER_ID);   // 필터가 찍은 도장
    return v instanceof Long ? (Long) v : null;
}

• AuthContext는 "지금 이 요청의 진짜 주인이 누구인지" 를 알려주는 헬퍼입니다. 신원을 JWT 도장에서만 읽습니다.
• 컨트롤러 클래스 주석(NotificationController.java:19-21)이 그 이유를 못 박습니다:

  M9 보안 수정: 이전에는 ?userId= 요청 파라미터를 그대로 신뢰해 인증된 누구나 타인의 알림을 조회/읽음처리할 수 있는 IDOR가 있었다. 이제 신원은 항상 JWT(AuthContext)에서만 가져오고, 요청 파라미터로 받지 않는다.

• 그래서 이 컨트롤러는 @RequestParam Long userId를 절대 쓰지 않습니다. 만약 클라이언트가 보낸 ?userId=42를 믿으면, 공격자가 남의 ID를 넣어 남의 데이터를 훔쳐볼(IDOR, Insecure Direct Object Reference) 수 있기 때문. 신원은 위조 불가능한 JWT 도장에서만 옵니다.

증거 5 — Service에서 한 번 더 소유권 확인 (이중 방어):

// StreamChatService.java:244-250
public void markNotificationRead(Long notificationId, User user) {
    notificationRepository.findById(notificationId).ifPresent(n -> {
        if (n.getUser().getId().equals(user.getId())) {   // ★ 이 알림이 정말 이 user 것인가?
            n.setRead(true);
            ...

• 컨트롤러에서 신원을 확인했어도, Service가 "이 알림 ID가 정말 그 유저 소유인지" 를 한 번 더 검사합니다. 남의 알림 ID(3)를 넣어도 조용히 무시됩니다.

정리 — 이 프로젝트의 인증/인가 4단 방어:

1) JwtAuthenticationFilter  : 쿠키/헤더의 JWT → request에 userId 도장 (막지 않음)
2) AuthContext.currentUserId(): 도장에서만 신원 읽기 (요청 파라미터 신뢰 안 함)
3) Controller               : currentUser()==null → 401 (수동 인가 게이트)
4) Service                  : 자원 소유권 재확인 (n.user == 현재 user)

🚨 강의/고도화 핵심: 다른 도메인 교재에서 if (user == null) return unauthorized(); 두 줄이 반복되는 걸 보게 됩니다. 그건 중복이 아니라 이 아키텍처의 필수 인가 코드입니다. Security를 안 쓰기로 한 대가로, 각 컨트롤러가 스스로 문지기가 됩니다.

특이점 2: AuthContext의 스케줄러용 "임시 신원 주입"

// AuthContext.java:15-25
private static final ThreadLocal<Long> OVERRIDE_USER_ID = new ThreadLocal<>();

public static void set(Long userId) {        // 예: DailySignalGenerator가 특정 유저 대신 실행
    if (userId != null) OVERRIDE_USER_ID.set(userId);
}
public static void clear() {                 // 반드시 finally에서 호출
    OVERRIDE_USER_ID.remove();
}

• HTTP 요청이 없는 백그라운드 잡(스케줄러) 에는 JWT 쿠키가 없습니다. 그래서 "이 작업은 유저 42번 것처럼 실행"하고 싶을 때 AuthContext.set(42L)로 임시 신원을 주입합니다.
• ThreadLocal — "현재 실행 스레드에만 보이는 변수". 반드시 finally에서 clear() 해야 스레드가 재사용될 때 남의 신원이 새지 않습니다(스레드풀 누수 주의).

특이점 3: 인증은 HttpOnly JWT 쿠키가 표준 (헤더는 레거시)

// JwtAuthenticationFilter.java:62-78 (발췌)
// 1순위: HttpOnly 쿠키 (DEVBRIDGE_TOKEN)
for (Cookie c : cookies) {
    if (AuthController.AUTH_COOKIE_NAME.equals(c.getName())) { ... return v.trim(); }
}
// 2순위: Authorization 헤더 (레거시 호환)
if (header != null && header.startsWith("Bearer ")) { return header.substring(7).trim(); }

• JWT는 HttpOnly 쿠키(JS가 못 읽음 → XSS 토큰 탈취 방지)로 전달되는 게 1순위, Authorization: Bearer 헤더는 옛 클라이언트 호환용 2순위입니다.

---

📚 용어 사전 (이 primer 한정)

용어	뜻
애너테이션(@...)	코드에 붙여 스프링/Lombok에 지시하는 스티커 라벨
빈(Bean)	스프링이 만들어 창고에 보관 중인 객체 하나
DI(의존성 주입)	필요한 빈을 스프링이 생성자로 꽂아주는 것
@RequiredArgsConstructor	final 필드 생성자를 Lombok이 자동 생성(→ DI 통로)
Controller	HTTP 요청 접수처(@RestController)
Service	비즈니스 규칙·트랜잭션이 사는 처리실
Repository	DB 읽기/쓰기 담당(JpaRepository 상속)
엔티티(@Entity)	DB 테이블 한 행에 대응하는 자바 객체
DTO	프론트와 주고받는 포장지 객체(엔티티와 분리)
@Id / @GeneratedValue	기본키 / 자동 증가
@ManyToOne / @JoinColumn	관계 매핑(여러→하나) / 외래키 컬럼
@Column	컬럼 세부 설정(이름·NOT NULL·길이·타입)
@Enumerated(STRING)	enum을 문자열로 DB 저장(순서 변경 안전)
메서드 이름 쿼리	findByUserOrderBy... 이름만으로 SQL 자동 생성
@Query / @Modifying	직접 작성 JPQL / 데이터 변경 쿼리 표시
@Transactional	여러 DB 작업을 "전부 성공 or 전부 취소"로 묶음
ResponseEntity	상태코드 + 본문을 직접 정해 반환하는 응답 객체
@PathVariable / @RequestParam / @RequestBody	URL 경로값 / 쿼리값 / 본문 JSON 추출
프로파일(profile)	local/prod 등 환경별 설정 묶음
${VAR:기본값}	환경변수 우선, 없으면 기본값
Flyway	번호 매긴 SQL로 DB 스키마를 버전 관리(=DB의 git)
ddl-auto	Hibernate의 스키마 처리 모드(local=update, prod=validate)
IDOR	남의 ID를 넣어 남의 자원에 접근하는 취약점(이 프로젝트가 JWT 신원으로 차단)
AuthContext	현재 요청의 신원(userId)을 JWT 도장에서 읽는 헬퍼
HttpOnly 쿠키	JS가 못 읽는 쿠키 → XSS 토큰 탈취 방지
Lombok	getter/builder/생성자를 컴파일 시 자동 생성하는 라이브러리

---

✅ 다음 단계

이 primer를 이해했다면 08_backend/의 각 도메인 교재로 넘어가세요. 어느 교재를 읽든 아래 패턴이 반복됩니다 — 이제 다 읽을 수 있습니다:

@RestController @RequiredArgsConstructor          // 접수처 + DI
public class XxxController {
    private final XxxService service;              // 주입받은 Service
    @GetMapping("/...")
    public ResponseEntity<?> handle(@PathVariable ...) {
        User user = currentUser();                 // JWT 신원
        if (user == null) return unauthorized();   // ★수동 인가 게이트 (이 프로젝트 시그니처)
        return ResponseEntity.ok(service.doSomething(user, ...));
    }
}
```# `domain/ai` — Alpha 워크스페이스·채팅·패치 (완전 라인별 해설)

> 원본 디렉터리: `backend/src/main/java/com/DevBridge/devbridge/domain/ai/`
> 다루는 파일:
> - 서비스 — `service/AlphaHelixService.java`(960줄) · `service/AlphaPatchService.java` · `service/ClaudeCodeAgentService.java`
> - 컨트롤러 — `controller/AlphaWorkspaceController.java` · `controller/AlphaPatchController.java` · `controller/AlphaAnalyticsController.java`
> - 엔티티 — `entity/AlphaWorkspace.java` · `entity/AlphaChatMessage.java` · `entity/AlphaDecisionLog.java` · `entity/AlphaWorkspaceChangeSet.java`
>
> 이 문서는 교재 표준 형식(README "3. 공통 형식")을 따릅니다. Spring 기초(`@Service`/`@RestController`/JPA/Lombok)는 알고 있다고 전제합니다.

---

## 📌 이 파트 한눈에

이 파트는 **"자연어로 말한 인생 목표를, 백테스트 가능한 전략 카드까지 안내하는 AI 매니저의 두뇌"** 입니다.

사용자가 채팅창에 *"5년 안에 월 300만원 현금흐름 만들고 싶어요"* 라고 입력하면 →
AI가 8가지 조건을 한 단계씩 물어 채우고(목표 수집) → 그 목표를 **deterministic 백테스트가 가능한 전략 후보 3개**로 정형화하고 → 백테스트·국면·신뢰도까지 한 번에 돌리고 → (선택) 코드를 직접 편집(Claude CLI)하고 → 모든 변경을 **유지/취소 가능한 패치 묶음**으로 관리합니다.

비유로 풀면:
- **AlphaHelixService** = 매니저의 **두뇌**. 손님 말을 듣고(채팅), 메모로 정리하고(목표 JSON), 메뉴를 짜고(전략 후보), 시식을 돌립니다(백테스트·트러스트).
- **AlphaPatchService** = 매니저의 **연필과 지우개**. 설정을 살짝 고치되 항상 "되돌리기"가 가능하게(ChangeSet).
- **ClaudeCodeAgentService** = 매니저가 부르는 **외부 코딩 전문가(Claude CLI)**. 격리된 방에 코드를 펼쳐 주고, 손과 발(Bash·네트워크)은 묶은 채 파일만 고치게 합니다.

| 클래스 | 한 줄 역할 | 비유 |
|---|---|---|
| `AlphaHelixService` | 채팅 목표수집 → 정형화 → 백테스트/국면/신뢰/브리핑/자동주문/auto-run 전부 | 매니저의 두뇌(전 과정 오케스트레이션) |
| `AlphaPatchService` | strategyConfig·goalProfile·code 를 **부분 패치**하고 PENDING/KEPT/UNDONE 로 추적 | 연필+되돌리기 |
| `ClaudeCodeAgentService` | 헤드리스 `claude -p` CLI 로 워크스페이스 코드 실편집 → diff → 패치 | 외부 코딩 전문가(격리실) |
| `AlphaWorkspaceController` | 워크스페이스 CRUD + 채팅 + 로그/주문 조회 + 코드 저장 | 두뇌로 가는 정문 접수처 |
| `AlphaAnalyticsController` | backtest/regime/trust/queue-orders/auto-run/briefing 트리거 | 분석 파이프라인 접수처 |
| `AlphaPatchController` | changesets apply/keep/undo/list | 패치 접수처 |
| `AlphaWorkspace`(엔티티) | 목표·전략·백테스트·국면·신뢰·리포트·코드 JSON 을 한 행에 보관 | 손님 한 명의 서류철 |
| `AlphaChatMessage` | 채팅 한 줄(user/model) | 대화 녹취 한 줄 |
| `AlphaDecisionLog` | 모든 의사결정 시간순 기록 | 매니저의 업무일지 |
| `AlphaWorkspaceChangeSet` | 패치 한 묶음 + before/after 스냅샷 | 수정 영수증(되돌리기 표) |

**누가 호출하나?** → 프론트엔드 `frontend/src/alpha/` 의 AlphaWorkspace 탭(Chat / Config / Report / Regime / Trust / Briefing / Log)이 `/api/alpha/...` 로 호출합니다. 세 컨트롤러가 입구이고, 실제 일은 전부 위 세 서비스가 합니다.

**Analytics 엔진과의 관계** → 이 파트는 **두뇌(조율자)** 이고, 실제 숫자 계산(백테스트·Trust·Regime)은 `01_backtest`~`04_robust` 의 Python 엔진이 합니다. `AnalyticsClient`(strategy 도메인)가 그 다리입니다. 즉 이 문서는 "**누가 언제 무엇을 시키는가**"를, 앞선 문서들은 "**그 계산이 어떻게 돌아가는가**"를 다룹니다.

---

## 🧠 사전 지식 (이거 모르면 막힘)

### 1) 워크스페이스 = "손님 한 명의 전략 서류철 한 권"
`AlphaWorkspace` 엔티티 한 행 = 전략 1개. Slack 채널처럼 **워크스페이스 안에 채팅·로그·전략·결과가 모두 종속**됩니다. 한 사용자가 여러 워크스페이스를 가질 수 있습니다(목표마다 하나씩).

### 2) 상태 머신 — `status` 필드
워크스페이스는 정해진 단계를 밟습니다. 컨트롤러가 허용하는 값은 정확히 5개:

DRAFT → GOAL_SET → FORMALIZED → TESTED → LIVE
(생성) (목표 8개 (전략후보 3개 (백테스트 (실운용 중)
확정) 생성) 완료)

- `DRAFT`: 막 생성됨. 채팅으로 목표를 채우는 중.
- `GOAL_SET`: 8가지 목표가 전부 사용자 발화로 확정됨(`processChat`이 자동 승격).
- `FORMALIZED`: `doFormalize`가 전략 후보 3개를 만듦.
- `TESTED`: `doBacktest`가 한 번 돌아감.
- `LIVE`: 실제 운용 중. **이 상태에서는 backtest/formalize 가 status 를 강등하지 않습니다**(코드의 `if (!"LIVE"...)` 가드).

> 💡 초보 포인트: 상태는 "현재 어느 단계까지 왔나"를 한 글자로 요약한 라벨일 뿐, 강제 흐름 제어는 거의 없습니다(다음 단계 API 는 보통 "전제 조건"만 체크). 그래서 LIVE 보호 가드가 중요합니다.

### 3) goalProfile JSON — "매니저가 받아 적은 목표 메모"
채팅으로 수집하는 8가지가 하나의 JSON 으로 굳어집니다:
```json
{
  "goal": "5년 안에 월 300만원 현금흐름",
  "horizon_years": 5,
  "initial_capital_krw": 5000000,
  "monthly_contribution_krw": 1000000,
  "risk_tolerance": "중립",
  "max_drawdown_target_pct": 25,
  "assets": ["QQQ","SCHD"],
  "initial_strategy_direction": "추세추종 + 변동성조절"
}

이 JSON 이 AlphaWorkspace.goalProfileJson 컬럼에 문자열로 저장됩니다. 8개 키가 전부 채워졌는지를 hasAllGoalKeys()가 검사합니다(아래 라인별 해설).

4) strategyConfig "엔벨로프(envelope)" — 후보 3개를 담는 봉투

doFormalize의 결과는 단일 전략이 아니라 후보 배열을 감싼 봉투입니다:

{
  "candidates": [ {"id":"cand-1", ...}, {"id":"cand-2", ...}, {"id":"cand-3", ...} ],
  "selectedId": "cand-1"
}

• candidates: 보수/중립/공격 톤의 전략 카드 3장.
• selectedId: 현재 선택된 카드 id. 백테스트·국면·신뢰는 이 선택 카드 하나만 대상으로 합니다(getActiveStrategy()가 골라냄).

5) 패치 도구 "heli-patch" 와 ChangeSet 3상태

AI(또는 코드 편집·Claude 에이전트)가 설정을 바꿀 때, 통째로 덮어쓰지 않고 부분 패치(ops) 를 보냅니다:

[ { "target": "strategy", "path": "parameters.ma_window", "value": 120 } ]

• target: 어느 묶음을 고칠지(strategy / backtest / regime / trustScore / goalProfile / code).
• path: 점 표기 경로(parameters.ma_window).
• value: 새 값.

이 패치 한 번이 ChangeSet 한 행으로 기록되며, 항상 3상태를 거칩니다:

PENDING (적용됐지만 미확정)
   ├─ keep → KEPT   (유지 확정, 더 이상 되돌리기 불가)
   └─ undo → UNDONE (before 스냅샷으로 롤백)

before/after 전체 스냅샷을 저장하므로 undo 가 정확히 복원합니다. 비유: 워드의 "변경 내용 추적" + Ctrl+Z.

6) Claude CLI 격리 — "전문가를 격리실에 들여보낸다"

코드 실편집은 외부 claude CLI 프로세스를 띄워서 합니다. 위험하므로 안전장치 4겹:

1. 기본 OFF (app.claude.cli.enabled=false),
2. 임시 격리 디렉터리 (워크스페이스 코드만 복사해서 펼침),
3. 허용툴 화이트리스트 (Read,Edit,Write,Glob,Grep 만, Bash/WebFetch/WebSearch 차단),
4. 타임아웃 + 예산 상한(--max-budget-usd 1).

전문가는 그 방 안의 파일만 읽고 고칠 수 있고, 명령 실행이나 인터넷은 막혀 있습니다.

---

🗺 요청 흐름도

(A) 목표수집 채팅 → 전략 후보

[프론트 Chat 탭]  POST /api/alpha/workspaces/{id}/chat  { text }
        │
        ▼
AlphaWorkspaceController.chat()  — JWT 로 uid 확인, ws 소유 확인
        │
        ▼
AlphaHelixService.processChat(ws, uid, userText)
        │
        ├─① user 메시지 저장 (AlphaChatMessage)
        ├─② 컨텍스트 조립:
        │     buildWorkspaceStateContext(ws)   ← 현재 목표/전략/백테스트 수치 요약(코드 아님)
        │     + 최근 12개 대화 ([user]/[model])
        ├─③ system 프롬프트(퍼스널 퀀트 매니저 + 8개 항목 + 절대규칙)
        ├─④ callAi(uid, system, ctx)  ──▶ AiGatewayService.oneShot(쿼터·로그)  ──▶ Gemini
        ├─⑤ model 답변 저장
        └─⑥ extractJsonBlock(reply) → hasAllGoalKeys?
              YES → goalProfileJson 저장, status DRAFT→GOAL_SET, 로그 GOAL_DEFINED
        │
        ▼
{ reply, goalProfileExtracted, autoRunReady }

  ── (사용자가 'Goal → Strategy' 버튼) ──▶ POST .../formalize 또는 /auto-run
        │
        ▼
doFormalize(ws, uid):  goalProfileJson → LLM → 후보 3개 추출 → envelope 저장 → status FORMALIZED

(B) 분석 파이프라인 (개별 또는 auto-run 일괄)

선택 전략(getActiveStrategy) ──┬─ doBacktest  → AnalyticsClient.backtest/infiniteBuying  → lastBacktestJson
                              ├─ doRegime    → AnalyticsClient.regime                    → lastRegimeJson
                              ├─ doTrust     → AnalyticsClient.trustScore                → lastTrustJson
                              ├─ doQueueOrders(infinite_buying만) → OrderProposal(PENDING) 생성
                              └─ doBriefing  → LLM 모닝 브리핑 + 출처 링크

doAutoRun = formalize → backtest → regime → trust → (ib면) queue-orders 를 순차 실행
            (각 단계 실패는 catch 해서 error 로 담고 계속) → lastReportJson 저장

(C) 패치 / Claude 코드 에이전트

[Config 카드 수정 / AI 제안 / Claude 편집]
        │
        ▼
POST /changesets  { title, ops:[{target,path,value}] }
        │
        ▼
AlphaPatchService.apply():
   before 스냅샷 보존(strategyConfig+goalProfile+codeJson) → setPath 로 부분 적용
   → ws 저장 → ChangeSet(PENDING) 저장 → 로그 PARAM_CHANGED
        │
   사용자 선택 ──┬─ keep → KEPT  (Claude 변경이고 repo 연동되면 GitHub 자동 커밋)
                └─ undo → before 스냅샷으로 롤백 → UNDONE

[Claude 에이전트]  POST /claude-agent/start { request }
        │
        ▼
ClaudeCodeAgentService.startAgent → 백그라운드 스레드
   materialize(codeJson → 임시 디렉터리 파일들)
   → runCli(claude -p, allowedTools=Read/Edit/Write/Glob/Grep, disallowed=Bash/Web)
   → stream-json 라인 → 진행 로그(잡 스토어, 프론트 폴링 /status?since=N)
   → finishApply: 편집 diff → ops(target=code) → AlphaPatchService.apply() → ChangeSet(PENDING)
   → 임시 디렉터리 삭제(finally)

---

📖 핵심 클래스 라인별 심화

Ⅰ. AlphaHelixService — 두뇌

A. 클래스 골격과 의존성 — AlphaHelixService.java:48-72

// L48-L72 (요약)
@Slf4j @Service @RequiredArgsConstructor @lombok.Getter
public class AlphaHelixService {
    public final AlphaWorkspaceRepository workspaceRepo;
    public final AlphaChatMessageRepository chatRepo;
    public final AlphaDecisionLogRepository logRepo;
    ...
    private final GeminiService gemini;     // fallback (anonymous)
    private final AiGatewayService gateway; // 쿼터 관리 통합 (Task 12)
    public  final AnalyticsClient analytics;
    public final ObjectMapper om = new ObjectMapper();

    @Autowired @Lazy
    private AlphaHelixService self;          // self-injection
    ...
    private static final String DEFAULT_MODEL = "gemini-2.5-flash";

• 무엇을 하나: 세 컨트롤러(AlphaWorkspaceController/AlphaAnalyticsController/그리고 AlphaPatchController 도 recordLog 재사용)가 공유하는 서비스. 리포지토리·LLM·Analytics 클라이언트·JSON 매퍼를 모두 한 곳에 모읍니다.
• 왜 필드가 public final 인가: @lombok.Getter 가 게터를 만들어주고, 컨트롤러가 svc.getWorkspaceRepo() 식으로 직접 접근합니다. (정석은 private 이지만 여기선 의도적으로 노출.)
• @Autowired @Lazy private AlphaHelixService self; — self-injection (중요): 자기 자신을 주입받는 트릭. doAutoRun 안에서 self.doFormalize(...), self.doBacktest(...) 처럼 자기 메서드를 프록시를 통해 부릅니다.
  • 왜? Spring 의 @Transactional 은 프록시 객체를 통해 호출될 때만 동작합니다. this.doBacktest() 로 부르면 프록시를 우회해 트랜잭션 경계가 새로 안 생깁니다. self.doBacktest() 는 프록시를 거치므로 각 단계가 제대로 트랜잭션을 갖습니다. @Lazy 는 "생성 시점 순환참조(자기 자신)"를 깨기 위한 장치.

💡 초보가 헷갈리는 포인트: "왜 내 메서드를 this. 가 아니라 self. 로 부르지?" → Spring AOP(트랜잭션 등)는 self-invocation 에 안 먹는다는 유명한 함정 때문입니다. auto-run 처럼 내부에서 트랜잭션 메서드를 여러 번 부를 때 꼭 필요합니다.

B. LLM 호출 단일 통로 callAi — AlphaHelixService.java:80-85

// L80-L85
public String callAi(Long uid, String systemInstruction, String userInput) {
    if (uid != null) {
        return gateway.oneShot(uid, DEFAULT_MODEL, systemInstruction, userInput, false);
    }
    return gemini.oneShot(systemInstruction, userInput);
}

• 무엇을 하나: 이 서비스의 모든 LLM 호출은 이 한 메서드를 통과합니다(채팅·정형화·브리핑 모두).
• 왜 이렇게 하나: 인증된 사용자는 AiGatewayService 를 거쳐 쿼터 차감·사용 로그가 남습니다(gateway/AiGatewayService.java:54). 미인증은 GeminiService 폴백. 단, 주석대로 *"AlphaHelix 엔드포인트는 항상 인증 필수이므로 uid==null 은 오지 않는다"* — 즉 폴백 경로는 사실상 안전망.
• 마지막 인자 false = wantJson=false: Gemini 응답에 responseMimeType:application/json 강제를 걸지 않습니다. 채팅·브리핑은 마크다운 평문이 필요하기 때문(JSON 강제하면 마크다운 본문이 깨짐). 정형화처럼 순수 JSON 이 필요할 때도 여기선 false 로 받고, 응답에서 JSON 블록만 따로 추출(extractFirstJsonArray)하는 전략을 씁니다.

C. 선택 전략 골라내기 getActiveStrategy — AlphaHelixService.java:139-152

// L139-L152
public JsonNode getActiveStrategy(JsonNode cfg) {
    if (cfg == null || cfg.isMissingNode() || cfg.isNull()) return cfg;
    if (cfg.has("candidates") && cfg.get("candidates").isArray()) {
        String selId = cfg.path("selectedId").asText(null);
        JsonNode arr = cfg.get("candidates");
        if (selId != null) {
            for (JsonNode c : arr) {
                if (selId.equals(c.path("id").asText())) return c;
            }
        }
        if (arr.size() > 0) return arr.get(0);
    }
    return cfg;
}

• 무엇을 하나: 봉투(envelope)에서 현재 선택된 전략 카드 한 장을 꺼냅니다. selectedId 와 일치하는 카드를 찾고, 없으면 첫 카드, 봉투 구조가 아니면 입력을 그대로 반환.
• 왜 중요: doBacktest/doRegime/doTrust/doQueueOrders 가 전부 이 함수로 시작합니다. "후보 3개 중 무엇을 분석하느냐"의 단일 진실 공급원입니다.
• 초보 포인트: cfg.path("x") 와 cfg.get("x") 차이 — path 는 없으면 "MissingNode"(예외 없이 안전), get 은 없으면 null. Jackson 에서 안전 탐색은 path 를 씁니다.

D. 8개 목표 키 검증 hasAllGoalKeys / 준비완료 isAutoRunReady — AlphaHelixService.java:154-173

// L154-L165
public boolean hasAllGoalKeys(String json) {
    try {
        JsonNode g = om.readTree(json);
        return g.hasNonNull("goal")
            && g.hasNonNull("horizon_years")
            && g.hasNonNull("monthly_contribution_krw")
            && g.hasNonNull("risk_tolerance")
            && g.hasNonNull("max_drawdown_target_pct")
            && g.path("assets").isArray() && g.path("assets").size() > 0
            && g.hasNonNull("initial_strategy_direction");
    } catch (Exception e) { return false; }
}

• 무엇을 하나: 채팅에서 추출한 JSON 이 목표로 인정할 만큼 충분한지 검사. hasNonNull = 키가 있고 값이 null 이 아님. assets 는 반드시 비어있지 않은 배열.
• 왜 이렇게 빡빡한가: 이 검사가 통과해야만 processChat 이 goalProfile 을 저장하고 status 를 GOAL_SET 으로 올립니다. 즉 "진짜 다 모였을 때만 다음 단계로" 의 관문. (참고: initial_capital_krw 는 여기 검사에 빠져 있습니다 — 시스템 프롬프트는 8개를 요구하지만 이 게이트는 7개 필수+assets 입니다. 미묘한 비대칭이니 강의 시 짚을 포인트.)

// L167-L173
public boolean isAutoRunReady(String goalProfileJson) {
    ...
    return g.path("assets").isArray() && g.path("assets").size() > 0
        && !g.path("initial_strategy_direction").asText("").isBlank();
}

• 더 느슨한 검사: auto-run(원클릭 전체실행) 버튼을 띄울지 결정. 최소한 관심자산 + 전략방향만 있으면 진행 가능으로 봅니다.

E. LLM 답변에서 JSON 끄집어내기 extractJsonBlock — AlphaHelixService.java:175-211

// L175-L211 (핵심 발췌)
public String extractJsonBlock(String text) {
    if (text == null) return null;
    int s = text.indexOf("```json");
    if (s < 0) s = text.indexOf("```");
    if (s >= 0) { /* 코드펜스 안 본문을 잘라 om.readTree 로 검증 후 반환 */ }
    int objStart = text.indexOf('{');
    if (objStart < 0) return null;
    int depth = 0; boolean inStr = false; char prev = 0;
    for (int i = objStart; i < text.length(); i++) {
        char c = text.charAt(i);
        if (inStr) { if (c == '"' && prev != '\\') inStr = false; }
        else {
            if (c == '"') inStr = true;
            else if (c == '{') depth++;
            else if (c == '}') { depth--; if (depth == 0) { /* 균형 잡힌 첫 객체 반환 */ } }
        }
        prev = c;
    }
    return null;
}

• 무엇을 하나: LLM 응답에서 유효한 JSON 객체 하나를 안전하게 추출. 2단계 전략:
  1. ```json ... ``` 코드펜스가 있으면 그 안의 본문을 꺼내 om.readTree 로 파싱 검증(파싱 실패하면 무시).
  2. 코드펜스가 없으면 중괄호 균형(brace matching) 으로 첫 완결 객체를 찾습니다.
• 왜 직접 파싱하나(중요한 교훈): LLM 은 JSON 앞뒤에 *"조건을 정리해 보겠습니다 ✨"* 같은 설명 텍스트를 붙입니다. om.readTree(reply) 를 통째로 하면 깨집니다. 그래서 문자열 안에서 JSON 영역만 도려내는 손수 파서가 필요합니다.
• inStr/prev 추적이 핵심: 문자열 리터럴 안의 {/} 와 이스케이프된 \" 를 중괄호로 오해하지 않도록, "지금 문자열 안인가"와 "직전 문자가 백슬래시였나"를 추적합니다.
• 형제 메서드: extractFirstJsonArray(L213, [...] 배열용 — 정형화 후보 추출), extractFirstJson(L240, 더 단순한 객체 추출). extractFirstJsonArray 는 문자열 추적까지 하지만 extractFirstJson 은 단순 depth 카운팅만 합니다(차이 주의).

⚠️ 강의 포인트: "LLM 출력 = 신뢰 못 할 문자열" 이라는 대전제. 정규식 한 줄로 끝낼 것 같지만, 중첩 객체·문자열 내 괄호 때문에 정규식은 깨집니다. 이 brace-matching 패턴이 정석입니다.

F. 티커 정규화 normalizeTicker — AlphaHelixService.java:262-271

// L262-L271
public static String normalizeTicker(String t) {
    if (t == null || t.isBlank()) return "SPY";
    String up = t.trim().toUpperCase();
    return switch (up) {
        case "BTC", "BITCOIN" -> "BTC-USD";
        case "ETH", "ETHEREUM" -> "ETH-USD";
        case "VIX" -> "^VIX";
        default -> up;
    };
}

• 사용자/LLM 이 "BTC", "비트코인" 등 자유롭게 적어도 Analytics 엔진(야후/바이낸스)이 아는 심볼로 변환. 빈 값이면 안전 기본값 SPY. Java 21 switch 표현식 사용.

G. ⭐ 목표수집 채팅 processChat — AlphaHelixService.java:279-400

이 파트의 심장입니다. 단계별로 봅니다.

G-1. user 저장 + 컨텍스트 조립 — L280-L294

// L280-L294
@Transactional
public Map<String, Object> processChat(AlphaWorkspace ws, Long uid, String userText) {
    Long id = ws.getId();
    chatRepo.save(AlphaChatMessage.builder().workspaceId(id).role("user").text(userText).build());

    var history = chatRepo.findByWorkspaceIdOrderByCreatedAtAsc(id);
    StringBuilder ctx = new StringBuilder();
    // 현재 워크스페이스 상태를 컨텍스트 맨 앞에 주입한다.
    ctx.append(buildWorkspaceStateContext(ws));
    int start = Math.max(0, history.size() - 12);
    for (int i = start; i < history.size(); i++) {
        var m = history.get(i);
        ctx.append("[").append(m.getRole()).append("] ").append(m.getText()).append("\n");
    }

• 무엇을 하나: ① 사용자의 새 메시지를 즉시 DB 저장 → ② 전체 히스토리를 읽되 최근 12개만 컨텍스트에 넣음(토큰 절약) → ③ 그 앞에 현재 워크스페이스 상태 요약을 붙임.
• 왜 상태 요약을 맨 앞에(핵심 설계): 이미 전략·백테스트가 있는 워크스페이스에서 *"이 전략 승률 좀 올려줘"* 라고 물으면, AI 가 "로드된 전략(코드)이 없다"는 헛소리를 하지 않도록, 현재 수치(MDD·Sharpe·승률 등)를 컨텍스트로 미리 주입합니다(buildWorkspaceStateContext, 아래 H 참조). 신규 워크스페이스는 빈 문자열이라 온보딩에 영향 없음.
• @Transactional: 이 메서드 전체가 한 트랜잭션. user 저장·model 저장·goalProfile 저장이 한 묶음으로 커밋됩니다.

G-2. 시스템 프롬프트 — L296-L374

// L296-L327 (발췌)
String system = """
    너는 Alpha-Helix의 퍼스널 퀀트 매니저다. 사용자의 '삶의 목표'를 듣고 투자 전략 설계 조건 8가지를 한 단계씩 수집한다.
    ...
    🔎 분석가 모드 (이미 전략/백테스트가 있는 경우 — 아래 목표수집보다 우선)
    ...
    ⚠️ 절대 규칙 (위반 금지)
    ① 사용자가 명시적으로 답하지 않은 항목은 절대 임의로 채우지 않는다.
    ② 8가지가 전부 사용자 발화로 확인되기 전까지는 절대 JSON을 출력하지 않는다.
    ...
    수집해야 할 8가지 항목
    1) goal ... 8) initial_strategy_direction ...
    """;

• 무엇을 하나: Java 21 텍스트 블록("""...""") 으로 긴 한국어 프롬프트를 박아넣음. 이 프롬프트가 AI 의 행동 전부를 규정합니다.
• 두 가지 모드 분기를 프롬프트로 처리:
  • 목표수집 모드: 신규 워크스페이스 → 8가지를 한 단계씩 질문.
  • 분석가 모드: 컨텍스트에 상태가 있으면 → 목표수집을 다시 시작하지 말고 주어진 수치로 진단/개선.
• 절대 규칙의 의도: ①②는 환각 방지. 사용자가 말 안 한 값을 AI 가 멋대로 지어내거나, 덜 모였는데 JSON 을 뱉어 다음 단계로 넘어가는 것을 막습니다. (그래서 hasAllGoalKeys 게이트와 짝을 이룸.)
• [BTN:라벨|액션] 토큰(L371): 프론트가 이 토큰을 실제 버튼으로 렌더링합니다(액션: next / ask_more / formalize). 즉 LLM 이 UI 버튼을 "주문"할 수 있는 약속된 마크업.
• 무한매수법 인식(L334-L338): "라오어", "40분할", "LOC", "평단매수" 등 키워드가 나오면 initial_strategy_direction="infinite_buying" 으로 분기하고 추가 파라미터(split_count 등)를 더 수집하게 지시.

G-3. LLM 호출 + 답변 저장 — L376-L383

// L376-L383
String reply;
try {
    reply = callAi(uid, system, ctx.toString());
} catch (Exception e) {
    log.error("AI chat fail", e);
    reply = "(AI 응답 실패: " + e.getMessage() + ")";
}
chatRepo.save(AlphaChatMessage.builder().workspaceId(id).role("model").text(reply).build());

• LLM 실패해도 예외를 삼키고 사용자에게 보이는 에러 메시지를 model 메시지로 저장 → 채팅이 끊기지 않습니다(graceful degradation).

G-4. goalProfile 추출·승격 — L385-L399

// L385-L399
String extracted = extractJsonBlock(reply);
if (extracted != null && hasAllGoalKeys(extracted)) {
    ws.setGoalProfileJson(extracted);
    if ("DRAFT".equals(ws.getStatus())) ws.setStatus("GOAL_SET");
    workspaceRepo.save(ws);
    recordLog(id, "AI", "GOAL_DEFINED", "Goal Profile 추출 완료", extracted);
} else {
    extracted = null;
}
Map<String, Object> resp = new LinkedHashMap<>();
resp.put("reply", reply);
resp.put("goalProfileExtracted", extracted != null);
resp.put("autoRunReady", extracted != null && isAutoRunReady(extracted));
return resp;

• 무엇을 하나: AI 답변에 완성된 목표 JSON 이 들어있으면(추출 + 8키 검사 통과) → 저장하고 DRAFT→GOAL_SET 승격(이미 다른 상태면 건드리지 않음) → 결정 로그 남김.
• 반환 3필드: reply(보여줄 답변), goalProfileExtracted(목표 확정됐나 — 프론트가 'Goal→Strategy' 버튼 활성화), autoRunReady(원클릭 전체실행 가능한가).

H. 워크스페이스 상태 컨텍스트 buildWorkspaceStateContext — AlphaHelixService.java:407-485

// L407-L424 (목표 프로필 부분)
private String buildWorkspaceStateContext(AlphaWorkspace ws) {
    StringBuilder sb = new StringBuilder();
    try {
        String gj = ws.getGoalProfileJson();
        if (gj != null && !gj.isBlank()) {
            JsonNode g = om.readTree(gj);
            java.util.List<String> p = new java.util.ArrayList<>();
            if (g.hasNonNull("goal")) p.add("목표=\"" + g.get("goal").asText() + "\"");
            ... (기간/초기금/월적립/성향/MDD목표/관심자산/전략방향) ...
            if (!p.isEmpty()) sb.append("• 목표 프로필: ").append(String.join(", ", p)).append("\n");
        }
    } catch (Exception ignore) { }
    ...

• 무엇을 하나: 워크스페이스의 현재 상태를 사람이 읽는 한 줄 요약들로 압축합니다. 목표 / 선택 전략+파라미터(앞 8개만) / 최근 백테스트 stats / Regime 라벨 / Trust Score 를 각각 한 줄로.
• 왜 stats 만(중요): 주석대로 *"백테스트는 stats 만 추려 넣는다(equity_curve 같은 대용량 배열은 제외)". 자산곡선 2500점을 컨텍스트에 넣으면 토큰 폭발 + 노이즈. 매니저가 알아야 할 건 "총수익 X%, MDD Y%" 같은 *요약 수치**뿐입니다.
• catch (Exception ignore) 의 의미: 각 블록이 독립적으로 try/catch — 한 JSON 이 깨져도 나머지 요약은 살아남게. 방어적 프로그래밍.

// L482-L485
    if (sb.length() == 0) return "";
    return "\n[현재 워크스페이스 상태 — 사용자가 \"지금 보고 있는/이 전략\"이라고 하면 아래를 가리킨다]\n"
            + sb + "\n";
}

• 상태가 하나도 없으면 빈 문자열: 신규 워크스페이스는 컨텍스트 오염 없이 순수 온보딩. 상태가 있으면 *"'이 전략'이라고 하면 아래를 가리킨다"* 라는 안내 헤더를 붙여 AI 의 지시대명사 해석을 돕습니다.

I. ⭐ 정형화 doFormalize — AlphaHelixService.java:493-581

// L494-L529 (시스템 프롬프트 발췌)
@Transactional
public Map<String, Object> doFormalize(AlphaWorkspace ws, Long uid) throws Exception {
    String system = """
        너는 사용자 목표(JSON)를 받아 **deterministic 백테스트가 가능한** 전략 config 후보 3개를 제시한다.
        각 후보는 아래 7개 템플릿 중 서로 다른 strategy_type을 고른 보수/중립/공격 톤으로 ...:
          - buy_hold / moving_average_timing / momentum_rotation / vix_risk_off
          - trend_volatility_control / dividend_tilt / infinite_buying
        ...
        반드시 코드블록 없이 **순수 JSON 배열만** 출력하라. 길이는 정확히 3.
        """;

• 무엇을 하나: goalProfile → 전략 후보 3개 JSON 배열 생성. 7개 템플릿 중 서로 다른 것을 보수/중립/공격 톤으로.
• deterministic 강조: 후보의 strategy_type 은 반드시 백테스트 엔진(01_backtest/vbt_engine.md 의 6전략 + 무한매수)으로 재현 가능한 것이어야 합니다. AI 가 "감으로 사고팔기" 같은 비결정 전략을 만들지 못하게.

// L531-L567 (파싱 + 폴백)
String result;
try { result = callAi(uid, system, ws.getGoalProfileJson()); }
catch (RuntimeException e) { throw new RuntimeException("정형화 실패: " + e.getMessage(), e); }
...
String arrayJson = extractFirstJsonArray(result);
List<Map<String, Object>> candidates = new ArrayList<>();
try {
    if (arrayJson != null) {
        JsonNode arr = om.readTree(arrayJson);
        for (int i = 0; i < arr.size() && i < 3; i++) {
            Map<String, Object> cand = om.convertValue(arr.get(i), Map.class);
            cand.put("id", "cand-" + (i + 1));
            candidates.add(cand);
        }
    }
    if (candidates.isEmpty()) {            // 배열 추출 실패 → 단일 객체라도 건진다
        String obj = extractFirstJson(result);
        if (obj != null) { Map<String,Object> cand = om.readValue(obj, Map.class); cand.put("id","cand-1"); candidates.add(cand); }
    }
} catch (Exception e) { log.error("formalize parse fail", e); }
if (candidates.isEmpty()) throw new RuntimeException("LLM 응답을 파싱하지 못했습니다: " + result);

• 방어적 파싱 2단계: ① 배열 추출 → 최대 3개에 id(cand-1..3) 부여. ② 배열이 없으면 단일 객체라도 건져 후보 1개로. 둘 다 실패하면 명시적 예외.
• om.convertValue vs om.readValue: 전자는 이미 JsonNode 인 것을 Map 으로 변환, 후자는 문자열을 파싱. 둘 다 결과는 Map<String,Object>.

// L569-L581 (봉투 저장)
Map<String, Object> envelope = new LinkedHashMap<>();
envelope.put("candidates", candidates);
envelope.put("selectedId", candidates.get(0).get("id"));   // 기본 선택 = 첫 후보
String envelopeJson = om.writeValueAsString(envelope);
ws.setStrategyConfigJson(envelopeJson);
if (!"LIVE".equals(ws.getStatus())) ws.setStatus("FORMALIZED"); // LIVE 운용 중이면 강등 금지
workspaceRepo.save(ws);
recordLog(ws.getId(), "AI", "STRATEGY_PROPOSED", "Strategy 후보 " + candidates.size() + "개 생성", envelopeJson);
return Map.of("strategyConfig", envelopeJson, "candidates", candidates);

• 봉투로 포장 → 첫 후보를 selectedId 로 → strategyConfigJson 저장 → status FORMALIZED(LIVE 보호). 사전지식 4번의 envelope 가 여기서 만들어집니다.

J. 백테스트 디스패치 doBacktest — AlphaHelixService.java:590-655

// L590-L596
@Transactional
public String doBacktest(AlphaWorkspace ws, String period, Map<String, Object> customParams) throws Exception {
    JsonNode cfg = getActiveStrategy(om.readTree(ws.getStrategyConfigJson()));
    String stype = cfg.path("strategy_type").asText("moving_average_timing");
    String pickedPeriod = (period != null && !period.isBlank()) ? period.trim() : "5y";
    if (customParams == null) customParams = Map.of();

• 무엇을 하나: 선택 전략 종류(stype)에 따라 두 갈래로 Analytics 엔진을 호출.
• 갈래 1 — infinite_buying(L596-L621): tickers 정규화 → split/take_profit/loc_offset/initial_capital 파라미터를 모아 analytics.infiniteBuying(...) 호출.
• 갈래 2 — 일반 6전략(L623-L654): strategy_type 을 Python 엔진 전략명으로 매핑(momentum_rotation→macd, 그 외→sma_cross). 사용자가 코드에서 편집한 customParams(sma_fast/slow, rsi_, macd_ 등)가 있으면 우선 적용, 없으면 parameters.ma_window 를 sma_slow 로 사용.

  // L648-L654
  JsonNode bt = analytics.backtest(ticker, pyStrategy, extra);
  ws.setLastBacktestJson(bt.toString());
  if (!"LIVE".equals(ws.getStatus())) ws.setStatus("TESTED"); // LIVE 운용 중이면 강등 금지
  workspaceRepo.save(ws);
  recordLog(ws.getId(), "SYSTEM", "BACKTEST_RUN", ticker + " / " + pyStrategy + " 백테스트 완료", null);
  return bt.toString();

• 결과를 lastBacktestJson 에 캐시 → status TESTED(LIVE 보호) → 결정 로그 → raw JSON 문자열 반환(컨트롤러가 그대로 프론트에 전달).

💡 매핑이 단순한 이유: 7개 전략 템플릿 이름(LLM 용)과 Python 엔진의 6전략 이름이 다릅니다. 여기서 moving_average_timing→sma_cross 처럼 번역합니다. 즉 LLM 어휘 ↔ 엔진 어휘 어댑터.

K. Regime / Trust / Queue-Orders / Briefing / Auto-Run (요약)

• doRegime(L660-L678): 선택 전략 첫 자산으로 analytics.regime(ticker, options). options 에 method=hmm 명시하면 HMM, 기본은 rule(빠름). → lastRegimeJson.
• doTrust(L683-L704): analytics.trustScore(ticker, pyStrategy, options) → lastTrustJson. 로그에 trust_score 정수 기록.
• doQueueOrders(L709-L792): infinite_buying 전용(다른 전략은 IllegalStateException). 워크스페이스에 BrokerAccount 가 없으면 사용자의 MOCK KIS 계정을 자동 사용(없으면 에러 — 실주문 안전장치). analytics.infiniteBuyingPlan(...) 의 각 plan 을 OrderProposal(status=PENDING, source=SIGNAL, expiresAt=now+24h) 로 저장. 수량 ≤ 0 은 스킵.
• doBriefing(L796-L822): 목표+전략+백테스트+트러스트를 LLM 에 넘겨 한국어 모닝 브리핑 생성. buildRegimeReferences(L828-L850)가 실재하는 출처 링크 ≥5개(FRED·VIX·TradingView 등) + 자산 키워드(BTC/TQQQ/KOSPI)에 따른 특화 출처를 붙임.
• doAutoRun(L867-L949): 원클릭 전체 파이프라인. self-injection 으로 self.doFormalize → self.doBacktest → self.doRegime → self.doTrust → (ib면) self.doQueueOrders 를 순차 실행.

  // L876-L887 (auto-run 1단계)
  if (ws.getStrategyConfigJson() == null) {
    try {
        self.doFormalize(ws, uid);
        ws = workspaceRepo.findById(wsId).orElse(ws); // reload after save
        steps.add("formalize");
    } catch (Exception e) { report.put("formalizeError", e.getMessage()); return saveReport(ws, report); }
  } else { steps.add("formalize:cached"); }

  • 각 단계 실패는 catch → report 에 error 로 담고 계속(formalize 만 실패 시 조기 반환 — 후속 단계의 전제이므로). 단계마다 workspaceRepo.findById 로 재로딩: 직전 self.doXxx 가 별도 트랜잭션에서 ws 를 저장했으므로 최신 상태를 다시 읽어옵니다.
  • 최종 결과는 lastReportJson 에 저장(saveReport, L951-L959) → 프론트 캐시.

---

Ⅱ. AlphaPatchService — 연필+되돌리기

A. 허용 target 과 한글 키 별칭 — AlphaPatchService.java:35-52

// L35-L52
private static final Set<String> ALLOWED_TARGETS = Set.of(
        "strategy", "backtest", "regime", "trustScore", "goalProfile", "code");

private static final Map<String, String> GOAL_KEY_ALIAS = Map.ofEntries(
        Map.entry("기간", "horizon_years"),
        Map.entry("초기투자금", "initial_capital_krw"),
        Map.entry("관심자산", "assets_of_interest"),
        Map.entry("전략방향", "strategy_direction"),
        ... );

• ALLOWED_TARGETS (보안 화이트리스트): 패치가 건드릴 수 있는 묶음을 6개로 제한. 그 외 target 은 거부(아래 apply). 임의 필드 조작 차단.
• GOAL_KEY_ALIAS: 구버전 모델이 기간/전략방향 같은 한글 키로 보내도 프론트 카드가 읽는 영문 키로 정규화. 점 경로의 첫 토큰만 치환.

B. ⭐ apply — 패치 적용 + before/after 스냅샷 — AlphaPatchService.java:54-135

// L54-L90 (적용 루프)
@Transactional
public AlphaWorkspaceChangeSet apply(AlphaWorkspace ws, String title, List<Map<String, Object>> ops) {
    if (ops == null || ops.isEmpty()) throw new IllegalArgumentException("ops 가 비어있습니다");
    String strategyBefore = ws.getStrategyConfigJson();
    String goalBefore     = ws.getGoalProfileJson();
    String codeBefore     = ws.getCodeJson();
    Map<String, Object> cfg  = readMap(strategyBefore);
    Map<String, Object> goal = readMap(goalBefore);
    Map<String, Object> code = readMap(codeBefore);

    for (Map<String, Object> op : ops) {
        String target = String.valueOf(op.getOrDefault("target", "strategy")).trim();
        String path   = op.get("path") == null ? "" : String.valueOf(op.get("path")).trim();
        Object value  = op.get("value");
        if (!ALLOWED_TARGETS.contains(target)) throw new IllegalArgumentException("허용되지 않은 target: " + target);
        if (path.isEmpty()) throw new IllegalArgumentException("path 가 비어있습니다");

        if ("goalProfile".equals(target)) {            // 한글 키 → 영문 키 정규화
            String[] gp = path.split("\\.", 2);
            String head = GOAL_KEY_ALIAS.getOrDefault(gp[0], gp[0]);
            String normalized = gp.length > 1 ? head + "." + gp[1] : head;
            setPath(goal, normalized, value);
        } else if ("code".equals(target)) {            // path=파일명, value=새 전체 파일
            code.put(path, value == null ? "" : String.valueOf(value));
        } else {                                        // strategy → path, 그 외 → target.path
            String fullPath = "strategy".equals(target) ? path : target + "." + path;
            setPath(cfg, fullPath, value);
        }
    }

• 무엇을 하나: ops 배열을 돌며 세 갈래로 적용 — goalProfile(별칭 정규화), code(파일 통째 교체), 나머지(strategyConfig 내부 경로).
• target 경로 규칙(클래스 주석 L18-L23): target=strategy → strategyConfig.{path}, target=backtest/regime/trustScore → strategyConfig.{target}.{path}. 즉 strategy 외 target 은 한 단계 더 깊이 들어갑니다.
• 부분 적용 헬퍼 setPath(L204-L217): 점 경로를 따라 중첩 Map 을 파고들며, 중간 노드가 없거나 Map 이 아니면 새로 만들어가며 마지막 키에 값을 넣음.

// L98-L135 (스냅샷 + ChangeSet 저장)
try {
    strategyAfter = om.writeValueAsString(cfg);
    goalAfter     = om.writeValueAsString(goal);
    codeAfter     = om.writeValueAsString(code);
    opsJson       = om.writeValueAsString(ops);
    Map<String, String> bs = new LinkedHashMap<>();   // before: 세 JSON 모두 보존
    bs.put("strategyConfig", strategyBefore);
    bs.put("goalProfile",    goalBefore);
    bs.put("codeJson",       codeBefore);
    beforeSnap = om.writeValueAsString(bs);
    Map<String, String> as = new LinkedHashMap<>();   // after: 세 JSON 모두
    as.put("strategyConfig", strategyAfter); ...
    afterSnap = om.writeValueAsString(as);
} catch (Exception e) { throw new RuntimeException("JSON 직렬화 실패: " + e.getMessage(), e); }

ws.setStrategyConfigJson(strategyAfter);
ws.setGoalProfileJson(goalAfter);
ws.setCodeJson(codeAfter);
workspaceRepo.save(ws);

AlphaWorkspaceChangeSet cs = changeSetRepo.save(AlphaWorkspaceChangeSet.builder()
        .workspaceId(ws.getId()).title(...).opsJson(opsJson)
        .beforeJson(beforeSnap).afterJson(afterSnap).status("PENDING").build());
helix.recordLog(ws.getId(), "AI", "PARAM_CHANGED", "Heli 패치 적용: " + cs.getTitle(), opsJson);
return cs;

• 핵심 설계 — before/after 에 세 JSON 전부 보존: strategyConfig 만 저장하면 goalProfile·code 패치는 undo 가 안 됩니다. 그래서 {strategyConfig, goalProfile, codeJson} 세 개를 통째로 스냅샷. 이게 undo 정확성의 비결.
• 항상 status="PENDING" 으로 시작.

C. keep / undo — AlphaPatchService.java:137-183

// L137-L146 (keep)
@Transactional
public AlphaWorkspaceChangeSet keep(AlphaWorkspace ws, Long csId) {
    AlphaWorkspaceChangeSet cs = changeSetRepo.findByIdAndWorkspaceId(csId, ws.getId())
            .orElseThrow(() -> new NoSuchElementException("changeset not found"));
    if (!"PENDING".equals(cs.getStatus())) return cs;      // 멱등: 이미 처리됐으면 그대로
    cs.setStatus("KEPT");
    helix.recordLog(ws.getId(), "USER", "PARAM_CHANGED", "변경 유지: " + cs.getTitle(), null);
    return changeSetRepo.save(cs);
}

• keep: PENDING → KEPT. 이미 PENDING 이 아니면 아무것도 안 함(멱등). KEPT 후에는 되돌리기 불가.

// L148-L183 (undo)
@Transactional
public AlphaWorkspaceChangeSet undo(AlphaWorkspace ws, Long csId) {
    AlphaWorkspaceChangeSet cs = ...;
    if (!"PENDING".equals(cs.getStatus()))
        throw new IllegalStateException("PENDING 상태에서만 실행취소 가능 (현재: " + cs.getStatus() + ")");
    String raw = cs.getBeforeJson();
    boolean restored = false;
    if (raw != null && !raw.isBlank()) {
        try {
            Map<String, Object> bs = om.readValue(raw, new TypeReference<LinkedHashMap<String, Object>>() {});
            if (bs.containsKey("strategyConfig") || bs.containsKey("goalProfile") || bs.containsKey("codeJson")) {
                ws.setStrategyConfigJson(...); ws.setGoalProfileJson(...);
                if (bs.containsKey("codeJson")) ws.setCodeJson(...);
                restored = true;
            }
        } catch (Exception ignore) { /* 구포맷으로 폴백 */ }
    }
    if (!restored) ws.setStrategyConfigJson(raw);   // 구포맷: before 가 strategyConfig 단독 문자열
    workspaceRepo.save(ws);
    cs.setStatus("UNDONE");
    helix.recordLog(ws.getId(), "USER", "USER_REVISION", "변경 실행취소: " + cs.getTitle(), null);
    return changeSetRepo.save(cs);
}

• undo: PENDING 일 때만 가능(KEPT/UNDONE 은 IllegalStateException → 컨트롤러가 409 Conflict). before 스냅샷을 그대로 복원.
• 신/구 포맷 양립(중요): 신규 포맷은 {strategyConfig, goalProfile, codeJson} 객체, 구포맷은 strategyConfig 문자열 단독. 객체 파싱이 실패하거나 키가 없으면 구포맷으로 폴백(raw 를 strategyConfig 로). 과거 데이터 호환 보장.

---

Ⅲ. ClaudeCodeAgentService — 외부 코딩 전문가(격리실)

A. 설정과 기본 OFF — ClaudeCodeAgentService.java:46-61

// L46-L61
@Value("${app.claude.cli.enabled:false}")  private boolean enabled;       // 기본 OFF
@Value("${app.claude.cli.path:claude}")     private String cliPath;
@Value("${app.claude.cli.timeout-sec:180}") private int timeoutSec;
@Value("${anthropic.api.key:}")             private String apiKey;

private static final Set<String> CODE_EXT = Set.of(
        "py", "js", "jsx", "ts", "tsx", "json", "txt", "md", "yaml", "yml", "csv", "ipynb", "java");
public boolean isEnabled() { return enabled; }

• enabled 기본 false: 운영 안전을 위해 명시적으로 켜야만(app.claude.cli.enabled=true) 동작. 컨트롤러도 !agent.isEnabled() 면 503 반환.
• CODE_EXT: 에이전트가 새로 만든 파일 중 코드 확장자만 변경으로 인정(쓰레기 파일 무시).

B. ⭐ 격리 디렉터리 materialize — ClaudeCodeAgentService.java:188-203

// L188-L203
private Materialized materialize(AlphaWorkspace ws) throws IOException {
    Map<String, Object> codeMap = readMap(ws.getCodeJson());
    if (codeMap.isEmpty()) codeMap.put("main", "");
    Path tmp = Files.createTempDirectory("alpha-claude-ws-" + ws.getId() + "-");
    Map<String, String> fileToKey = new LinkedHashMap<>();
    Map<String, String> original = new LinkedHashMap<>();
    for (Map.Entry<String, Object> e : codeMap.entrySet()) {
        String key = e.getKey();
        String content = e.getValue() == null ? "" : String.valueOf(e.getValue());
        String filename = key.contains(".") ? key : key + ".py";   // 확장자 없으면 .py
        Files.writeString(tmp.resolve(filename), content, StandardCharsets.UTF_8);
        fileToKey.put(filename, key);
        original.put(filename, content);
    }
    return new Materialized(tmp, fileToKey, original);
}

• 무엇을 하나: DB 의 codeJson({"main":"...", "risk_control":"..."})을 임시 디렉터리의 실제 파일들로 펼침. 확장자 없는 키는 .py 로 가정.
• 왜 격리 디렉터리: Claude CLI 는 작업 디렉터리(cwd)의 파일을 읽고 씁니다. 프로젝트 본체가 아니라 버려도 되는 임시 폴더에 워크스페이스 코드만 복사해 줌으로써 다른 파일 접근을 원천 차단.
• original 맵 보관: 나중에 편집 전/후 비교(diff) 에 사용.

C. ⭐⭐ CLI 커맨드 — 허용툴 화이트리스트 + Bash 차단 — ClaudeCodeAgentService.java:205-215

// L205-L215
private List<String> buildCommand(boolean streaming) {
    List<String> cmd = new ArrayList<>(List.of(resolveCli(), "-p",
            "--output-format", streaming ? "stream-json" : "json"));
    if (streaming) cmd.add("--verbose");
    cmd.addAll(List.of(
            "--allowedTools", "Read,Edit,Write,Glob,Grep",
            "--disallowedTools", "Bash,WebFetch,WebSearch",   // 보안: 임의 명령/네트워크 차단
            "--no-session-persistence",
            "--max-budget-usd", "1"));
    return cmd;
}

• 이 파일에서 가장 중요한 보안 라인:
  • --allowedTools Read,Edit,Write,Glob,Grep — 파일 읽기/편집/작성/검색만 허용.
  • --disallowedTools Bash,WebFetch,WebSearch — 임의 셸 명령 실행과 네트워크를 차단. 전문가의 손발을 묶고 펜만 쥐어주는 것.
  • --no-session-persistence — 세션 잔재 안 남김.
  • --max-budget-usd 1 — 토큰 폭주 비용 상한.
• -p(print/headless) + --output-format json|stream-json — 대화형이 아니라 헤드리스로 한 번 돌리고 결과를 JSON 으로.

⚠️ 강의 포인트: "AI 에게 코드 편집을 맡긴다"의 진짜 위험은 Bash 와 네트워크입니다(rm -rf, 데이터 유출). allowedTools/disallowedTools 화이트리스트가 그 위험을 봉합합니다. enabled 기본 OFF + 격리 디렉터리 + 예산 상한과 합쳐 4중 방어.

D. CLI 실행 — stdin 프롬프트 + 타임아웃 — ClaudeCodeAgentService.java:218-245

// L218-L245 (발췌)
private String[] runCli(Path cwd, String request, boolean streaming, Consumer<String> onLine) ... {
    String prompt = "이 디렉터리는 퀀트 트레이딩 전략 코드입니다. 코드를 직접 편집해 다음 요청을 수행하세요.\n요청: " + request;
    ProcessBuilder pb = new ProcessBuilder(buildCommand(streaming));
    pb.directory(cwd.toFile());
    if (apiKey != null && !apiKey.isBlank()) pb.environment().put("ANTHROPIC_API_KEY", apiKey);
    Process proc = pb.start();
    ...
    Thread tOut = pump(proc.getInputStream(), out, onLine);  // stdout 라인별 콜백
    Thread tErr = pump(proc.getErrorStream(), err, null);
    tOut.start(); tErr.start();
    try (OutputStream stdin = proc.getOutputStream()) {       // 프롬프트는 stdin 으로
        stdin.write(prompt.getBytes(StandardCharsets.UTF_8)); stdin.flush();
    }
    boolean finished = proc.waitFor(timeoutSec, TimeUnit.SECONDS);
    if (!finished) { proc.destroyForcibly(); throw new RuntimeException("Claude Code CLI 타임아웃 ..."); }
    ...
    return new String[]{out.toString(), err.toString()};
}

• 프롬프트를 stdin 으로 보내는 이유(클래스 주석 L36): *"프롬프트는 stdin(Windows .cmd 인용 회피)"*. 커맨드라인 인자로 넘기면 Windows .cmd 의 따옴표·특수문자 이스케이프 지옥에 빠집니다. stdin 으로 주면 안전.
• stdout/stderr 를 별도 스레드로 pump(L311-L323): 출력 버퍼가 가득 차 프로세스가 멈추는 데드락 방지 정석. stdout 은 onLine 콜백으로 스트리밍.
• 타임아웃 시 destroyForcibly: 매달린 프로세스를 강제 종료.
• resolveCli()(L292-L300): Windows 에서 claude → claude.cmd 로 자동 보정.

E. ⭐ 편집 결과 → diff → 패치 finishApply — ClaudeCodeAgentService.java:248-283

// L248-L283 (발췌)
private AgentResult finishApply(AlphaWorkspace ws, String request, Materialized m, String narration, long t0) ... {
    List<Map<String, Object>> ops = new ArrayList<>();
    ...
    try (Stream<Path> walk = Files.list(m.tmp)) {
        for (Path p : walk.filter(Files::isRegularFile).sorted().toList()) {
            String fn = p.getFileName().toString();
            if (fn.startsWith(".")) continue;
            boolean wasOriginal = m.original.containsKey(fn);
            String ext = ...;
            if (!wasOriginal && !CODE_EXT.contains(ext)) continue;   // 새 파일은 코드 확장자만
            String content = Files.readString(p, StandardCharsets.UTF_8);
            String orig = m.original.get(fn);
            if (orig == null || !orig.equals(content)) {              // 변경된 것만
                String key = m.fileToKey.getOrDefault(fn, ...);
                Map<String,Object> op = new LinkedHashMap<>();
                op.put("target", "code"); op.put("path", key); op.put("value", content);
                ops.add(op);
                changes.add(new FileChange(key, fn, orig == null ? "" : orig, content));
            }
        }
    }
    AlphaWorkspaceChangeSet cs = null;
    if (!ops.isEmpty()) cs = patchService.apply(ws, "Claude Code: " + shortReq, ops);
    ...
    return new AgentResult(cs, narration ..., changedFiles, changes, elapsed);
}

• 무엇을 하나: Claude 가 편집을 마친 임시 디렉터리를 훑어 원본과 다른 파일만 골라 target=code 패치 ops 로 만들고, AlphaPatchService.apply() 로 ChangeSet(PENDING) 생성.
• 두 서비스의 연결(설계 정점): Claude 에이전트는 직접 DB 를 안 건드립니다. 편집 결과를 패치 ops 로 변환해 AlphaPatchService 에 위임 → 모든 변경이 동일한 PENDING/KEEP/UNDO 흐름을 탑니다. 즉 AI 코드 편집도 사람 편집과 똑같이 되돌릴 수 있습니다.
• FileChange(path, filename, before, after) 레코드 → 프론트 Monaco 에디터 diff 뷰에 사용.
• title "Claude Code: ...": 이 접두사로 AlphaPatchController.keep 에서 *"Claude 변경이면 GitHub 자동 커밋"*(L72)을 판별합니다.

F. 스트리밍 잡 스토어 — ClaudeCodeAgentService.java:100-169, 367-406

// L100-L107
public String startAgent(AlphaWorkspace ws, String request) {
    guard(request);
    ClaudeJob job = createJob();
    Thread t = new Thread(() -> runStreamingJob(job, ws, request), "claude-agent-" + job.id);
    t.setDaemon(true); t.start();
    return job.id;        // 즉시 jobId 반환 → 프론트는 /status?since=N 폴링
}

• 무엇을 하나: 긴 작업(수십 초~수 분)을 백그라운드 데몬 스레드로 돌리고 jobId 만 즉시 반환. 프론트는 /claude-agent/status/{jobId}?since=N 으로 증분 로그를 폴링.
• streamLineToJob(L145-L169): claude 의 stream-json 한 줄(이벤트)을 사람이 읽는 진행 로그로 변환. assistant 이벤트의 tool_use(📖 읽기/✏️ 편집/📝 작성/🔍 검색)와 text(💬), thinking(💭)만 노출하고 result 이벤트의 최종 narration 을 잡음.
• toolUseMessage(L171-L182): Read→"📖 파일명 읽기" 식 이모지 매핑. 사용자가 에이전트의 행동을 실시간으로 보게.
• ClaudeJob(L367-L406): volatile 상태(running/done/error) + 동기화된 로그 리스트(최대 1000) + snapshot(since) 로 커서 이후만 잘라 반환. 잡은 최대 64개 보관(createJob 이 끝난 잡부터 정리).
• 임시 디렉터리는 항상 finally 에서 삭제(deleteRecursive, L334-L340) — 자원 누수 방지.

---

Ⅳ. 컨트롤러 3종 (입구)

세 컨트롤러는 모두 같은 패턴을 따릅니다 — ① JWT 로 uid 추출 → ② 워크스페이스 소유 확인 → ③ 서비스 위임 → ④ 결과/에러 매핑.

A. AlphaWorkspaceController — CRUD + 채팅 — controller/AlphaWorkspaceController.java

// L42-L49 (목록)
@GetMapping("/workspaces")
public ResponseEntity<?> list() {
    Long uid = AuthContext.currentUserId();
    if (uid == null) return unauth();
    return ResponseEntity.ok(svc.getWorkspaceRepo()
            .findByUserIdOrderByUpdatedAtDesc(uid)
            .stream().map(svc::toSummary).toList());
}

• AuthContext.currentUserId() (보안 핵심): 신원은 오직 JWT 에서 옵니다. 클라이언트가 보낸 userId 를 믿지 않습니다(IDOR 방지). 모든 핸들러 첫 줄이 이 패턴.
• 소유권 검증 findByIdAndUserId(id, uid): 워크스페이스 조회는 항상 "id 그리고 내 uid" 로. 남의 워크스페이스 id 를 넣어도 못 봅니다.
• 채팅(L221-L232): processChat 위임. 빈 텍스트는 400. 빈 히스토리면 친절한 온보딩 인사를 먼저 저장(L199-L217).
• 코드 저장(L258-L273): PATCH /code 로 codeJson 통째 저장(DeveloperLab 직접 편집).

B. AlphaAnalyticsController — 파이프라인 — controller/AlphaAnalyticsController.java

// L34-L62 (backtest 발췌)
@PostMapping("/workspaces/{id}/backtest")
public ResponseEntity<?> backtest(@PathVariable Long id,
        @RequestParam(value="period", required=false) String period,
        @RequestBody(required=false) Map<String,Object> body) {
    ...
    if (ws.getStrategyConfigJson() == null)
        return ResponseEntity.status(HttpStatus.UNPROCESSABLE_ENTITY)
                .body(Map.of("error", "먼저 /formalize로 전략을 정형화하세요"));
    try {
        ... String json = svc.doBacktest(ws, periodFinal, customParams);
        return ResponseEntity.ok().contentType(MediaType.APPLICATION_JSON).body(json);
    } catch (Exception e) {
        return ResponseEntity.status(HttpStatus.BAD_GATEWAY).body(Map.of("error", ...));
    }
}

• 전제조건 게이트: 전략이 없으면 422(먼저 /formalize). auto-run 은 goalProfile 없으면 422(먼저 채팅으로 목표 정의).
• 에러 → HTTP 상태 매핑(중요): Analytics 엔진 호출 실패는 502 Bad Gateway(우리 잘못이 아니라 하위 서비스 문제), 전제조건 위반은 422, 서버 내부 오류는 500. 의미 있는 상태코드로 프론트가 분기.
• raw JSON 그대로 반환: doBacktest 가 Python 엔진 JSON 문자열을 그대로 돌려주고, 컨트롤러는 contentType(APPLICATION_JSON) 으로 통과시킴(다시 파싱 안 함 — 오버헤드·왜곡 방지). (메모: 이는 Boot4 Jackson3 JsonNode 빈 버그를 피하는 패턴과도 통합니다.)

C. AlphaPatchController — 패치 — controller/AlphaPatchController.java

// L61-L79 (keep + GitHub 커밋)
@PostMapping("/workspaces/{id}/changesets/{csId}/keep")
public ResponseEntity<?> keep(@PathVariable Long id, @PathVariable Long csId) {
    ...
    AlphaWorkspaceChangeSet cs = patch.keep(ws, csId);
    Map<String, Object> dto = toDto(cs, ws);
    if (cs.getTitle() != null && cs.getTitle().startsWith("Claude Code:") && ws.getGithubRepoFullName() != null) {
        dto.put("gitCommit", gitSync.commitChangeSet(ws, cs, uid));   // A3: Co-Authored-By Claude
    }
    return ResponseEntity.ok(dto);
}

• apply(L37-L59): ops 검증 실패는 IllegalArgumentException→400, 그 외는 500.
• keep 시 조건부 GitHub 커밋: ChangeSet title 이 "Claude Code:" 로 시작하고 워크스페이스에 repo 가 연동돼 있으면 ClaudeGitSyncService.commitChangeSet 으로 자동 커밋. AI 편집을 유지 확정하면 실제 Git 히스토리에 남깁니다.
• undo(L81-95): IllegalStateException(PENDING 아님)→409 Conflict.

---

Ⅴ. 엔티티 4종 (서류철)

엔티티	테이블	핵심 컬럼	메모
AlphaWorkspace	alpha_workspace	goalProfileJson(TEXT) · strategyConfigJson(LONGTEXT) · lastBacktestJson/lastRegimeJson/lastReportJson(LONGTEXT) · lastTrustJson(TEXT) · codeJson(LONGTEXT) · status · brokerAccountId · githubRepoFullName/githubBranch	한 행이 손님 한 명의 전략 전체. JSON 을 문자열 컬럼에 통째로(스키마리스 유연성)
AlphaChatMessage	alpha_chat_message	workspaceId · role(user/model) · text(TEXT)	(workspace_id, created_at) 인덱스로 시간순 조회 빠르게
AlphaDecisionLog	alpha_decision_log	actor(USER/AI/SYSTEM) · eventType(GOAL_DEFINED/STRATEGY_PROPOSED/PARAM_CHANGED/BACKTEST_RUN/...) · summary · payloadJson	업무일지. recordLog 가 채움
AlphaWorkspaceChangeSet	alpha_workspace_changeset	opsJson · beforeJson · afterJson · status(PENDING/KEPT/UNDONE)	되돌리기 영수증. before/after 전체 스냅샷

// AlphaWorkspace.java:38-63 (JSON 컬럼들)
@Lob @Column(columnDefinition = "TEXT")      private String goalProfileJson;
@Lob @Column(columnDefinition = "LONGTEXT")  private String strategyConfigJson;
@Lob @Column(columnDefinition = "LONGTEXT")  private String lastBacktestJson;
@Lob @Column(columnDefinition = "TEXT")      private String lastTrustJson;
@Lob @Column(name="last_regime_json", columnDefinition="LONGTEXT") private String lastRegimeJson;
@Lob @Column(name="last_report_json", columnDefinition="LONGTEXT") private String lastReportJson;
@Lob @Column(name="code_json", columnDefinition="LONGTEXT")        private String codeJson;

• 왜 JSON 문자열로(설계 철학): 목표/전략/백테스트 결과는 구조가 자주 바뀌고 중첩이 깊습니다. 매번 컬럼·테이블을 쪼개면 마이그레이션 지옥. JSON 을 통째 문자열로 두면 스키마 변경 없이 진화 가능(Document-in-RDB 패턴). 대신 DB 레벨 쿼리(WHERE goal=...)는 못 합니다 — 이 도메인은 그게 필요 없습니다(항상 워크스페이스 단위로 통째 로드).
• TEXT vs LONGTEXT: 백테스트 결과·전략·코드처럼 클 수 있는 건 LONGTEXT(최대 4GB), 짧은 건 TEXT(64KB).

---

⚠️ 함정·보안 주의 (코드에 박힌 교훈 모음)

1. Claude CLI = Bash/네트워크 차단(최우선) — --allowedTools Read,Edit,Write,Glob,Grep + --disallowedTools Bash,WebFetch,WebSearch. 여기에 기본 OFF(enabled=false) + 임시 격리 디렉터리 + --max-budget-usd 1 + 타임아웃 4중 방어. 하나라도 풀면 "AI 에게 셸을 쥐어주는" 위험.
2. 패치 JSON 파싱 복구 — LLM 응답은 설명+JSON 이 섞입니다. extractJsonBlock/extractFirstJsonArray 의 brace-matching + 문자열/이스케이프 추적으로 JSON 만 도려냅니다. 통째 readTree 는 깨짐. 정형화는 배열 실패 시 단일 객체로, 그래도 안 되면 명시적 예외.
3. 워크스페이스 인지 컨텍스트 = 최근 수정사항 — buildWorkspaceStateContext 가 현재 목표/전략/백테스트 수치를 컨텍스트 앞에 주입해야 AI 가 *"이 전략 승률 올려줘"* 에 답합니다. stats 만(equity_curve 제외) 넣어 토큰 폭발 방지. 빈 워크스페이스는 빈 문자열(온보딩 보호).
4. self-injection 트랜잭션 — auto-run 은 반드시 self.doXxx(프록시 경유)로 호출해야 @Transactional 이 단계별로 작동. this. 면 트랜잭션이 안 걸림. 각 단계 후 workspaceRepo.findById 재로딩.
5. before/after 세 JSON 전부 스냅샷 — strategyConfig 만 저장하면 goalProfile·code 패치 undo 불가. {strategyConfig, goalProfile, codeJson} 통째 보존 + 구포맷 폴백.
6. undo 는 PENDING 에서만 — KEPT/UNDONE 은 409. keep 은 멱등(이미 처리됐으면 무동작).
7. LIVE 상태 강등 금지 — backtest/formalize 가 if (!"LIVE"...) 가드로 운용 중 워크스페이스의 status 를 덮지 않음.
8. 신원은 JWT 에서만 + 소유권 검증 — AuthContext.currentUserId() + findByIdAndUserId. 클라이언트 userId 불신(IDOR 방지).
9. 자동주문은 MOCK 우선 — doQueueOrders 는 infinite_buying 전용 + BrokerAccount 없으면 MOCK KIS 계정 자동 사용(없으면 에러). OrderProposal 은 PENDING + 24h 만료. 실주문은 별도 승인 단계(05 보안 설계의 MOCK→REAL 게이트).
10. 에러 → 상태코드 의미 부여 — Analytics 실패 502, 전제조건 422, 충돌 409, 인증 401. 프론트가 정확히 분기.

---

🚀 고도화 아이디어 (강의·개선 버전용)

• 목표 게이트 정합성: hasAllGoalKeys 가 initial_capital_krw 를 검사 안 함(프롬프트는 8개 요구). 게이트를 프롬프트와 일치시키거나, 프롬프트의 "8개" 표현을 게이트와 맞추기 — 요구사항 단일 진실 강의 예제로 최적.
• JSON 추출 라이브러리화: extractJsonBlock/extractFirstJson/extractFirstJsonArray 3개의 중복·미묘한 차이(문자열 추적 유무)를 한 유틸로 통합 + 단위 테스트(중첩/이스케이프/배열/잘린 응답).
• 스트리밍을 SSE/WebSocket 으로: 지금은 /status?since=N 폴링. Server-Sent Events 로 바꾸면 지연·요청수 감소.
• ChangeSet 충돌 관리: 동시에 두 PENDING 패치가 같은 path 를 건드리면? 낙관적 락(version) 또는 path 단위 잠금 도입.
• 패치 미리보기(dry-run): apply 전에 after 스냅샷만 계산해 프론트에 보여주고 사용자가 확정 시 저장 — 진짜 "변경 추적" UX.
• Claude 에이전트 동시성 상한: 사용자/서버당 동시 잡 수 제한(현재 MAX_JOBS=64 는 보관 한도일 뿐 동시 실행 제한 아님) + 큐잉.
• 무한매수 외 전략 자동주문: doQueueOrders 를 sma_cross/macd 등 latest_signal 기반으로 확장(엔진의 latest_signal 활용).
• 브리핑 출처 자동 검증: buildRegimeReferences 의 URL 헬스체크 캐시(깨진 링크 자동 제외).
• goalProfile 스키마 검증: JSON Schema 로 타입·범위(horizon_years>0, MDD 0~100)를 강제해 LLM 환각 수치 차단.

---

📚 용어 사전 (이 파트 한정)

용어	뜻
워크스페이스(AlphaWorkspace)	전략 1개 = 서류철 1권. 채팅·로그·전략·결과가 종속
status 머신	DRAFT→GOAL_SET→FORMALIZED→TESTED→LIVE 5단계 라벨
goalProfile	채팅으로 모은 8가지 목표 JSON
strategyConfig envelope	{candidates:[...3개], selectedId} 후보 봉투
getActiveStrategy	봉투에서 selectedId 카드 1장 꺼내기
formalize(정형화)	목표 → deterministic 백테스트 가능한 전략 후보 3개
heli-patch / ops	{target,path,value} 부분 패치 명령
ChangeSet	패치 한 묶음 + before/after 스냅샷. PENDING/KEPT/UNDONE
PENDING/KEPT/UNDONE	적용됨(미확정)/유지확정/롤백완료
setPath	점 경로(a.b.c)를 따라 중첩 Map 에 값 주입
callAi	모든 LLM 호출의 단일 통로(인증=Gateway 쿼터, 미인증=Gemini 폴백)
buildWorkspaceStateContext	현재 상태 요약(stats만)을 컨텍스트에 주입 → 분석가 모드
extractJsonBlock	LLM 답변에서 brace-matching 으로 JSON 도려내기
self-injection	@Lazy self 로 자기 트랜잭션 메서드를 프록시 경유 호출
doAutoRun	formalize→backtest→regime→trust→(ib)queue 원클릭 파이프라인
materialize	codeJson → 임시 격리 디렉터리의 실제 파일들
allowedTools/disallowedTools	Claude CLI 도구 화이트/블랙리스트(Read/Edit/Write/Glob/Grep 허용, Bash/Web 차단)
stream-json	claude -p 의 라인별 이벤트 출력 포맷(진행 로그용)
잡 스토어(ClaudeJob)	비동기 에이전트 진행/로그/결과 보관소. /status?since=N 폴링
FileChange	편집 전/후(before/after) — 프론트 Monaco diff
AuthContext.currentUserId()	JWT 에서만 신원 취득(IDOR 방지)
findByIdAndUserId	소유권까지 검증하는 조회
recordLog / AlphaDecisionLog	모든 의사결정 시간순 기록(업무일지)
OrderProposal(PENDING)	자동 큐잉된 주문 제안(24h 만료, 별도 승인 필요)

domain/ai — 멀티 LLM · 게이트웨이 · 쿼터 (완전 라인별 해설)

원본 폴더: backend/src/main/java/com/DevBridge/devbridge/domain/ai/
전제: Spring 기초는 [08_backend/00_spring_primer.md] 를 먼저 읽었다고 가정합니다(@Service·@RestController·DI·@Value 등은 여기서 다시 풀어 설명하지 않습니다).
이 문서는 교재 표준 형식([01_backtest/vbt_engine.md])을 따릅니다.

---

📌 이 파트 한눈에

이 파트는 "여러 AI 모델(Gemini·Claude·GPT·Perplexity)을 하나의 창구로 묶어 쓰고, 누가 얼마나 썼는지 관리하는 콜센터" 입니다.

비유로 풀면 이렇습니다. 회사에 외국어 상담사가 4명 있다고 합시다 — 영어 담당(GPT), 한국어 담당(Gemini), 법률 전문(Claude), 최신뉴스 검색 담당(Perplexity). 고객(프론트엔드)이 질문을 던지면:

1. 접수 데스크(Controller) 가 전화를 받고
2. 관리실(AiGatewayService) 이 "이 고객이 이번 달 상담 시간을 다 썼나?"(쿼터)를 확인한 뒤
3. 적합한 상담사(Provider) 에게 연결하고
4. 통화가 끝나면 통화 기록부(AiUsageLog) 에 몇 분 썼는지 적습니다.

⚠️ 가장 먼저 알아야 할 핵심: 이 도메인에는 AI 프로바이더 묶음이 두 벌(두 개의 평행 세계) 존재합니다. 처음 보면 반드시 헷갈리니 표로 못박고 시작합니다.

구분	service/gateway/ 묶음	service/llm/ 묶음
공통 인터페이스	AiProvider	LlmProvider
조율자	AiGatewayService (쿼터·로그)	LlmRouter (폴백 체인)
진입 컨트롤러	AiController (/api/ai/**)	LlmController (/api/llm/**)
쿼터/사용로그	있음 (AiUsageLog·AiModelCatalog)	없음
폴백(키 없으면 다른 모델로)	없음 (못 쓰면 거부)	있음 (defaultProvider())
토큰 사용량 추적	있음 (Result.tokensIn/Out)	없음
용도	로그인 사용자 메인 채팅 + 한도 청구 근거	우측 도크 "Quick Ask" 자유 채팅

두 묶음은 같은 4개 외부 API(Gemini·Anthropic·OpenAI·Perplexity)를 호출하지만, 목적이 달라 코드가 분리돼 있습니다. 이 문서는 주로 쿼터·로그가 있는 gateway 묶음을 깊게 파고, llm 묶음의 폴백 체인을 그 다음으로 다룹니다.

핵심 클래스 역할표

클래스	위치	한 줄 역할	비유
AiGatewayService	service/gateway/	쿼터 확인 → 프로바이더 라우팅 → 사용량 로깅	콜센터 관리실(시간 체크·연결·기록)
AiProvider (interface)	service/gateway/	4개 프로바이더의 공통 규격 (chat/oneShot/isAvailable)	상담사 직무 표준서
GeminiProvider	service/gateway/	기존 GeminiService를 AiProvider로 감싸는 어댑터	베테랑 직원을 표준 양식에 맞춰 등록
AnthropicProvider/OpenAiProvider/PerplexityProvider	service/gateway/	각 외부 API 직접 HTTP 호출 + 토큰 사용량 파싱	각 언어 상담사
GeminiService	service/	Gemini REST API 실제 호출(429 폴백·재시도 포함)	가장 바쁜 한국어 상담사 본체
AiModelCatalog (entity)	entity/	쓸 수 있는 모델 목록 + Free/Pro 월 한도	상담 메뉴판(요금표)
AiUsageLog (entity)	entity/	호출 1건당 토큰·성공여부 기록	통화 기록부
LlmRouter	service/llm/	providerId로 라우팅 + 키 없으면 폴백	자유 상담용 교환원
AiRateLimitFilter	global/config/	시간당 횟수 제한(20회/시간)	콜센터 입구 회전문(과밀 차단)

---

🧠 사전 지식 (이거 모르면 막힘)

1) LLM 프로바이더(provider)란?

• LLM(Large Language Model, 대형 언어 모델) = "글을 이해하고 글을 생성하는 AI". ChatGPT가 대표적.
• 프로바이더 = 그 LLM을 인터넷 너머에서 빌려주는 회사. 우리는 4곳을 씁니다:
  • Gemini(Google) — 기본·범용·빠름
  • Anthropic Claude — 복잡 추론·코드·전략 정형화
  • OpenAI GPT — 범용 멀티모달
  • Perplexity Sonar — 웹검색 기반(출처를 붙여줌)
• 각 회사 API는 HTTP로 JSON을 주고받는 방식이 미묘하게 다릅니다. 그래서 "공통 규격(인터페이스)"으로 감싸 한 줄로 호출할 수 있게 만듭니다.

2) 인터페이스 + 구현체 묶음 주입 (이 파트의 설계 핵심)

• Java interface = "이런 메서드를 가져야 한다"는 계약서. AiProvider가 그것.
• GeminiProvider, AnthropicProvider 등은 그 계약을 구현(implements) 한 실제 일꾼.
• Spring의 마법: 생성자에 List<AiProvider> providers 라고 적으면, 그 인터페이스를 구현한 모든 @Component를 자동으로 리스트에 담아 넣어줍니다. (콜센터 관리실이 "AiProvider 자격증 가진 직원 전원 명단"을 자동으로 받는 셈.)
• 그래서 새 프로바이더를 추가하려면 → AiProvider 구현 클래스 하나 만들고 @Component 붙이면 끝. 관리실 코드는 안 건드림.

3) 쿼터(quota) vs 레이트리밋(rate limit) — 둘은 다릅니다!

초보가 가장 헷갈리는 지점입니다. 이 시스템은 2층 방어선을 씁니다.

	쿼터(Quota)	레이트리밋(Rate Limit)
단위	토큰 수(글자량)	요청 횟수
기간	한 달	1시간
누가	AiGatewayService (DB로 누적 합산)	AiRateLimitFilter (메모리 버킷)
비유	월 데이터 요금제 GB 한도	1분에 문자 N개 발송 제한(스팸 방지)
초과 시	IllegalStateException("한도 초과")	HTTP 429 즉시 응답

• 쿼터는 "이번 달 너무 많이 썼나(비용)"를 막고, 레이트리밋은 "짧은 시간에 폭주(서버 과부하·악용)"를 막습니다. 둘 다 통과해야 실제 AI 호출이 일어납니다.

4) 토큰(token)이란?

• AI는 글을 "토큰"이라는 조각 단위로 셉니다. 대략 영어 4자 ≈ 1토큰, 한글은 더 잘게.
• 입력 토큰(tokensIn, 내가 보낸 질문)과 출력 토큰(tokensOut, AI가 답한 글) 둘 다 비용에 포함됩니다.
• 외부 API는 보통 응답 JSON의 usage 필드에 정확한 토큰 수를 담아줍니다. 단, Gemini 어댑터는 그걸 안 쓰고 글자수로 추정합니다(뒤에서 설명).

5) 폴백 체인(fallback chain)이란?

• "1순위가 안 되면 2순위, 그것도 안 되면 3순위"로 자동 전환하는 사다리.
• 여기엔 두 종류의 폴백이 있어 헷갈리기 쉽습니다:
  • 프로바이더 폴백 (LlmRouter): "Gemini 키가 없으면 → OpenAI로" 처럼 회사를 바꿈.
  • 모델 폴백 (GeminiService 내부): "gemini-2.5-flash가 429(한도초과)면 → gemini-2.0-flash로" 처럼 같은 회사 안에서 모델만 바꿈.

6) @Value("${키:기본값}") — 환경변수 주입

• @Value("${anthropic.api.key:}") 는 "설정에서 anthropic.api.key를 읽되, 없으면 빈 문자열(: 뒤가 기본값)" 이라는 뜻.
• 그래서 API 키를 안 넣어도 앱은 죽지 않고, available()이 false가 되어 그 프로바이더만 비활성화됩니다. (Gemini만은 예외 — 뒤 함정 참고.)

---

🗺 요청 흐름도

[프론트엔드] POST /api/ai/chat  (JWT 쿠키 포함)
        │
        ▼
┌─────────────────────────────────────────────┐
│  AiRateLimitFilter  (※ /api/alpha/** 경로만)   │  ← 횟수 제한(20회/시간)
│  ※ /api/ai/chat 은 이 필터 대상 아님(아래 함정) │
└─────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────┐
│  AiController.chat()                          │  접수 데스크
│  - AuthContext.currentUserId() 로 신원 확인    │
│  - 비로그인 → GeminiService 직접 (게이트 우회)  │
│  - 로그인  → AiGatewayService.chat()           │
└─────────────────────────────────────────────┘
        │ (로그인 사용자)
        ▼
┌─────────────────────────────────────────────┐
│  AiGatewayService.chat(userId, modelId, req)  │  관리실
│  ① ensureUsable() — 모델 존재? 활성? 쿼터 OK?  │ ──거부──▶ IllegalStateException
│  ② providerFor()  — modelId의 provider 매칭    │
│  ③ provider.chat() 호출                        │
│  ④ recordUsage()  — 성공/실패 모두 로그 저장    │
└─────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────┐
│  GeminiProvider / AnthropicProvider / ...     │  상담사(어댑터)
│  → 실제 외부 API HTTP POST (JSON)              │
│  → 응답 텍스트 + 토큰 사용량(Result) 반환       │
└─────────────────────────────────────────────┘
        │
        ▼
   DB: AI_USAGE_LOG  (이번 달 누적 토큰 ← 다음 쿼터 계산에 사용)


[별개 경로]  POST /api/llm/chat (자유 채팅)
        │
        ▼
   LlmController → LlmRouter.get(providerId)
        │            └─ 키 없으면 defaultProvider() 로 폴백
        ▼
   LlmProvider.oneShot()  → 외부 API (쿼터/로그 없음)

---

📖 핵심 클래스 라인별 심화

A. AiProvider 인터페이스 — 모든 상담사의 표준서 (service/gateway/AiProvider.java)

// AiProvider.java:9-25
public interface AiProvider {
    String providerKey();                 // "GEMINI" / "ANTHROPIC" / "OPENAI" / "PERPLEXITY"
    boolean isAvailable();                // API 키 보유 여부 (없으면 게이트웨이가 거부)
    Result chat(String modelId, AiChatRequest request);                              // 멀티턴 채팅
    Result oneShot(String modelId, String systemInstruction, String userPrompt, boolean wantJson); // 단발
    record Result(String text, long tokensIn, long tokensOut) {}  // 결과 + 토큰
}

• 이 4개 메서드가 "AI 상담사라면 반드시 할 수 있어야 하는 일" 입니다. 4개 구현체가 각자 다른 방식으로 이 계약을 지킵니다.
• providerKey() — 자기가 누구인지 대문자 키로 알려줌. AiGatewayService가 모델의 provider와 이 키를 문자열 비교해 짝을 찾습니다(아래 providerForOpt).
• isAvailable() — "지금 일할 수 있냐"(API 키가 있냐). 키 없는 상담사는 명단에는 있되 회색 처리됩니다.
• Result 는 record(불변 데이터 묶음). 응답 글(text) + 입력 토큰 + 출력 토큰 3개를 한 봉투에 담아 반환. 이 토큰 숫자가 곧 쿼터 차감량입니다.

💡 초보 포인트: chat은 대화 히스토리 전체(여러 턴)를 받고, oneShot은 시스템 지시 + 질문 한 개만 받는 단발성. 채팅창은 chat, "이 텍스트에서 JSON 뽑아줘" 같은 일회성 작업은 oneShot.

---

B. AiGatewayService — 관리실 (이 파트의 알맹이) (service/gateway/AiGatewayService.java)

B-1. 의존성 주입: 프로바이더 "전원 명단" 받기 — L32-L37

// AiGatewayService.java:32-37
public class AiGatewayService {
    private final AiModelCatalogRepository catalogRepo;   // 모델 메뉴판 조회
    private final AiUsageLogRepository usageRepo;         // 사용량 기록/합산
    private final SubscriptionService subscriptionService;// 이 유저가 Free냐 Pro냐
    private final List<AiProvider> providers;             // ★ AiProvider 구현 전원

• 마지막 줄이 사전지식 2번의 마법입니다. List<AiProvider> 라고만 적으면 Spring이 GeminiProvider, AnthropicProvider, OpenAiProvider, PerplexityProvider 4개를 모두 담아 주입합니다.
• 관리실은 "직원이 몇 명인지·누구인지" 하드코딩하지 않습니다. 새 직원(프로바이더)이 와도 이 코드는 그대로.

B-2. chat() — 한 번의 호출 전체 흐름 — L40-L52

// AiGatewayService.java:40-52
public String chat(Long userId, String modelId, AiChatRequest request) {
    AiModelCatalog model = ensureUsable(userId, modelId);   // ① 쿼터·존재 검증
    AiProvider provider = providerFor(model);               // ② 담당 상담사 찾기
    AiProvider.Result result;
    try {
        result = provider.chat(model.getModelId(), request);// ③ 실제 호출
        recordUsage(userId, modelId, result.tokensIn(), result.tokensOut(), true, null); // ④ 성공 로그
        return result.text();
    } catch (RuntimeException e) {
        recordUsage(userId, modelId, 0, 0, false, e.getMessage());  // ④' 실패도 로그
        throw e;
    }
}

• 4단계 파이프라인이 한눈에 보입니다: 검증 → 라우팅 → 호출 → 기록.
• 핵심 설계: 성공이든 실패든 반드시 recordUsage를 호출합니다(try에서 성공, catch에서 실패). 실패는 토큰 0으로 기록하되 에러 메시지를 남겨 "왜 실패했나" 추적이 됩니다.
• 실패 시 throw e로 에러를 다시 던집니다 — 로그만 남기고 삼키지 않음. 그래야 컨트롤러가 사용자에게 에러를 알려줄 수 있습니다.

💡 초보 포인트: oneShot()(L54-66)도 구조가 완전히 같습니다 — 검증→라우팅→호출→로그. chat 대신 provider.oneShot을 부르는 것만 다릅니다. 이런 반복 구조를 "템플릿" 이라 부르며, 익혀두면 코드가 빠르게 읽힙니다.

B-3. ensureUsable() — 쿼터 가드 (가장 중요한 검증) — L105-L123

// AiGatewayService.java:105-123
private AiModelCatalog ensureUsable(Long userId, String modelId) {
    AiModelCatalog model = catalogRepo.findById(modelId)
            .filter(AiModelCatalog::isEnabled)              // 비활성 모델이면 빈 Optional
            .orElseThrow(() -> new IllegalArgumentException("알 수 없거나 비활성화된 모델: " + modelId));

    Subscription.Tier tier = subscriptionService.currentTier(userId);   // FREE or PRO
    long quota = (tier == Subscription.Tier.PRO) ? model.getProQuota() : model.getFreeQuota();
    if (quota == 0) {
        throw new IllegalStateException("이 모델은 Pro 전용입니다. (" + model.getDisplayName() + ")");
    }
    if (quota != -1) {                                       // -1 = 무제한이면 검사 스킵
        LocalDateTime monthStart = LocalDateTime.now().withDayOfMonth(1).withHour(0).withMinute(0).withSecond(0);
        long used = usageRepo.sumTokensByUserAndModelSince(userId, modelId, monthStart);
        if (used >= quota) {
            throw new IllegalStateException("이번 달 사용 한도(" + quota + " 토큰)를 초과했습니다.");
        }
    }
    return model;
}

이 메서드가 쿼터 시스템의 심장입니다. 한 줄씩 풀어봅니다.

1. 모델 존재·활성 검증: 메뉴판(catalogRepo)에서 modelId를 찾고, .filter(isEnabled)로 "꺼진 모델"을 걸러냅니다. 없으면 IllegalArgumentException.
2. 티어 확인: subscriptionService.currentTier(userId)로 이 사용자가 무료(FREE)인지 유료(PRO)인지 판정. (결제 도메인과 연결되는 지점.)
3. 한도 선택: Pro면 proQuota, 아니면 freeQuota. 한도는 숫자 3종 의미가 있습니다:
   • 0 → Pro 전용(Free는 못 씀) → 즉시 거부
   • -1 → 무제한 → 사용량 검사 자체를 건너뜀
   • 그 외 양수 → 월 토큰 한도
4. 이번 달 누적 합산: monthStart(이번 달 1일 00:00)부터 지금까지 이 유저가 이 모델로 쓴 토큰 합(sumTokensByUserAndModelSince). used >= quota면 거부.

⚠️ 초보가 놓치는 포인트: withDayOfMonth(1).withHour(0)... 은 "이번 달 1일 자정"을 만드는 것. withMinute·withSecond는 0으로 맞추지만 나노초(withNano)는 안 건드립니다 — 합산 쿼리가 >= since라 1일 0시 0분 0초 이후를 다 포함하므로 실무상 문제는 없지만, 정밀하게는 .withNano(0)까지 넣는 게 깔끔합니다(고도화 항목).

B-4. 쿼터 합산 쿼리 — AiUsageLogRepository.java:13-20

// AiUsageLogRepository.java:13-20
@Query("""
    SELECT COALESCE(SUM(u.tokensIn + u.tokensOut), 0)
    FROM AiUsageLog u
    WHERE u.userId = :uid AND u.modelId = :model AND u.createdAt >= :since AND u.success = true
""")
long sumTokensByUserAndModelSince(@Param("uid") Long uid, @Param("model") String modelId, @Param("since") LocalDateTime since);

• tokensIn + tokensOut을 함께 합산 — 입력·출력 모두 비용이므로.
• COALESCE(..., 0) — 호출 기록이 하나도 없으면 SUM이 null을 주는데, 이걸 0으로 바꿔줍니다(NPE 방지). 신규 유저는 0으로 시작.
• u.success = true — 실패한 호출은 쿼터에서 빼지 않습니다. API 에러로 답을 못 받았으면 토큰을 안 깎는 게 공정. (실패 로그는 남되 합산에는 불포함.)
• 이 쿼리가 AiUsageLog 엔티티의 복합 인덱스 ix_aiusage_user_model_time (user_id, model_id, created_at) 을 그대로 탑니다 — 그래서 사용량이 쌓여도 빠릅니다.

B-5. providerForOpt() — 모델 → 상담사 매칭 — L130-L133

// AiGatewayService.java:130-133
private java.util.Optional<AiProvider> providerForOpt(AiModelCatalog model) {
    String key = model.getProvider().name();                         // 예: "ANTHROPIC"
    return providers.stream().filter(p -> p.providerKey().equals(key)).findFirst();
}

• 모델 메뉴판의 provider(enum) 이름과, 주입된 4개 프로바이더의 providerKey()를 문자열로 비교해 짝을 찾습니다.
• 예: 사용자가 claude-sonnet-4 모델을 고르면 → 그 모델의 provider는 ANTHROPIC → providerKey()=="ANTHROPIC"인 AnthropicProvider로 연결.
• Optional로 감싼 이유: 짝이 없을 수도 있어서. providerFor()(L125-128)는 짝이 없으면 예외를, listModelsFor는 "사용불가(회색)"로 표시.

B-6. listModelsFor() — UI 모델 선택기 데이터 — L70-L95

// AiGatewayService.java:74-94 (요약)
return catalogRepo.findByEnabledTrueOrderBySortOrderAsc().stream().map(m -> {
    long quota = (tier == Subscription.Tier.PRO) ? m.getProQuota() : m.getFreeQuota();
    long used = usageRepo.sumTokensByUserAndModelSince(userId, m.getModelId(), monthStart);
    boolean providerOk = providerForOpt(m).map(AiProvider::isAvailable).orElse(false);
    boolean unlocked = quota != 0 || tier == Subscription.Tier.PRO;
    boolean usable = providerOk && unlocked && (quota == -1 || used < quota);
    long remaining = (quota == -1) ? Long.MAX_VALUE : Math.max(0, quota - used);
    return Map.<String, Object>of( "modelId", ..., "quota", quota, "used", used,
        "remaining", remaining == Long.MAX_VALUE ? -1 : remaining,
        "usable", usable, "lockReason", lockReason(...) );
}).toList();

• 프론트의 모델 드롭다운에 뿌릴 데이터를 모델마다 한 줄씩 만듭니다.
• usable 3조건 AND: ① 프로바이더 키가 있고(providerOk) ② 잠금 해제됐고(unlocked, Pro전용 아님) ③ 한도 안 넘었다. 셋 다 참이어야 선택 가능.
• remaining이 무제한(-1 표시)일 땐 내부적으로 Long.MAX_VALUE를 쓰다가 응답 직전 -1로 변환 — 프론트는 -1을 "무제한"으로 해석.
• lockReason(L97-102)은 못 쓰는 이유를 사람 말로 돌려줍니다: "API 키 미설정" / "Pro 전용" / "이번 달 한도 초과". 사용자가 왜 회색인지 알 수 있게.

💡 listModelsFor에는 @Transactional(readOnly = true)(L69)가 붙어 있습니다. 읽기 전용 트랜잭션 — 여러 번의 DB 조회를 한 트랜잭션으로 묶어 일관성을 보장하고, 쓰기가 없음을 명시해 약간의 최적화도 얻습니다.

B-7. recordUsage() — 통화 기록부 작성 — L135-L148

// AiGatewayService.java:135-148
private void recordUsage(Long userId, String modelId, long tIn, long tOut, boolean ok, String err) {
    try {
        usageRepo.save(AiUsageLog.builder()
                .userId(userId).modelId(modelId)
                .tokensIn(tIn).tokensOut(tOut)
                .success(ok)
                .errorMessage(err == null ? null : err.substring(0, Math.min(err.length(), 500)))
                .build());
    } catch (Exception e) {
        log.warn("AiUsageLog 저장 실패 (무시): {}", e.getMessage());
    }
}

• errorMessage를 최대 500자로 자릅니다(substring(0, min(len, 500))). 엔티티의 length=500 컬럼을 넘지 않게. (긴 스택트레이스가 와도 DB 저장 실패 안 함.)
• 로그 저장 실패는 통째로 삼킵니다(catch에서 log.warn만). "기록부 작성이 실패해도 사용자 응답은 이미 나갔으니 무너지면 안 된다"는 판단. 로깅은 부수 작업이라 본 흐름을 막지 않습니다.

---

C. GeminiProvider 어댑터 — 베테랑을 표준 양식에 끼우기 (service/gateway/GeminiProvider.java)

이 클래스는 다른 3개 프로바이더와 결이 다릅니다. 직접 HTTP를 치지 않고, 기존 GeminiService를 감싸기(어댑터 패턴) 만 합니다.

// GeminiProvider.java:22-36
@Override
public Result chat(String modelId, AiChatRequest request) {
    String text = geminiService.chat(request);          // ← 실제 일은 GeminiService가 함
    long tIn = estimateTokens(buildPromptText(request)); // ← 토큰은 "추정"
    long tOut = estimateTokens(text);
    return new Result(text, tIn, tOut);
}

// GeminiProvider.java:49-53
/** 영문 ~4자=1토큰, 한글 ~1.5자=1토큰. 보수적으로 chars/3 사용. */
static long estimateTokens(String s) {
    if (s == null || s.isEmpty()) return 0;
    return Math.max(1, s.length() / 3);
}

• ⚠️ 핵심 차이: Anthropic/OpenAI/Perplexity는 응답 JSON의 usage 필드에서 정확한 토큰 수를 읽지만, GeminiProvider는 글자수 ÷ 3으로 추정합니다(estimateTokens). 주석에도 "정확한 사용량은 Gemini usageMetadata 파싱 필요"라고 명시 — 즉 알려진 부정확성입니다.
• chars/3을 쓰는 이유: 한글은 1.5자/토큰, 영어는 4자/토큰이라 섞이면 평균이 애매한데, 3으로 나누면 약간 과대추정(보수적)이 됩니다. 쿼터를 약간 빡빡하게 잡아 "초과 미허용" 쪽으로 안전.
• modelId 파라미터를 받지만 안 씁니다 — geminiService.chat이 내부 기본 모델을 쓰기 때문(현재 구조의 한계). 고도화 항목.

💡 어댑터 패턴이란: "기존에 잘 돌던 클래스(GeminiService)를, 새 표준 인터페이스(AiProvider)에 맞게 변환기를 씌워 재사용"하는 기법. 콘센트 모양이 달라도 돼지코 어댑터로 꽂는 것과 같습니다.

---

D. GeminiService — 실제 Gemini API 호출 본체 (service/GeminiService.java)

이게 진짜로 인터넷 너머 Google에 HTTP를 치는 곳입니다. 가장 정교한 에러 처리가 들어있습니다.

D-1. 모델 레벨 폴백 — L181-L205

// GeminiService.java:181-205 (요약)
private Map<String, Object> generateContent(Map<String, Object> body) {
    try {
        return postGenerateContent(model, body, true);          // 1순위: 기본 모델
    } catch (HttpClientErrorException.TooManyRequests primary429) {
        if (fallbackModel == null || fallbackModel.isBlank() || fallbackModel.equals(model)) {
            throw new RuntimeException(buildQuotaMessage(...), primary429); // 폴백 없으면 친절한 메시지
        }
        log.warn("Gemini 429 on primary model {}. Falling back to {}.", model, fallbackModel);
        return postGenerateContent(fallbackModel, body, false); // 2순위: 폴백 모델
    } catch (HttpClientErrorException e) {
        if (e.getStatusCode().value() == 403 && fallbackModel 존재) {
            return postGenerateContent(fallbackModel, body, false);  // 403도 폴백
        }
        throw e;
    }
}

• 429(Too Many Requests, 한도초과) 와 403(Forbidden, 접근불가) 둘 다 → 폴백 모델로 한 번 더 시도.
• 이것이 사전지식 5번의 "같은 회사 안에서 모델만 바꾸는 폴백"(gemini-2.5-flash → 폴백). LlmRouter의 "회사 자체를 바꾸는 폴백"과 다릅니다.

D-2. 429 본문 파싱 — L227-L251

// GeminiService.java:227-247 (요약)
private Quota429Info parse429Info(HttpClientErrorException e) {
    String body = e.getResponseBodyAsString();
    boolean isFreeTier = body.contains("free_tier") || body.contains("FreeTier");
    boolean isDailyQuota = body.contains("PerDay") || body.contains("GenerateRequestsPerDay");
    long retryDelayMs = 5_000L;
    int rdIdx = body.indexOf("\"retryDelay\"");
    if (rdIdx >= 0) { /* "retryDelay":"52.98s" 형식에서 52.98 추출 → ms */ }
    return new Quota429Info(isFreeTier, isDailyQuota, retryDelayMs);
}

• Google이 보낸 429 응답 본문에서 "무료 티어인가 / 일간 한도인가 / 몇 초 기다리라는가" 를 추출.
• 흥미로운 점: JSON 파서(Jackson)를 안 쓰고 문자열 검색(contains/indexOf)으로 처리합니다. 주석에 "Jackson 의존 없이 처리"라고 명시. (메모리의 Spring Boot 4 Jackson JsonNode 버그 회피와 같은 맥락 — 단순 추출엔 문자열 검색이 더 안전.)
• 추출 결과로 메시지를 다르게 만듭니다(buildQuotaMessage, L208-221): 일간 무료 한도 소진이면 "결제 활성화하라", RPM 초과면 "N초 후 재시도".

D-3. RPM 재시도 with 백오프 — L254-L294

// GeminiService.java:271-290 (요약)
} catch (HttpClientErrorException.TooManyRequests e) {
    Quota429Info info = parse429Info(e);
    if (info.isFreeTier() && info.isDailyQuota()) {
        throw e;   // 일간 한도는 기다려도 무의미 → 즉시 던짐 → 상위에서 모델 폴백
    }
    if (attempt >= maxAttempts) throw e;
    long waitMs = Math.min(info.retryDelayMs(), 60_000L);  // API가 알려준 만큼, 최대 60초
    sleepMs(waitMs);   // 기다렸다가 1회 재시도
}

• 두 종류의 429를 구분합니다:
  • 일간 무료 한도 소진(isDailyQuota) → 기다려도 안 풀림 → 즉시 던져서 상위가 모델 폴백하게.
  • RPM(분당 요청) 초과 → API가 알려준 retryDelay만큼 기다렸다 1회 재시도(최대 60초 캡).
• sleepMs(L296-303)는 Thread.sleep 중 인터럽트가 오면 플래그를 복원(Thread.currentThread().interrupt())하고 예외를 던집니다 — 올바른 인터럽트 처리 관례.

⚠️ 함정: postGenerateContent은 응답을 Map.class로 받습니다(L270). 이건 메모리의 Spring Boot 4 Jackson JsonNode 버그를 피하려는 선택 — JsonNode로 받으면 Boot4(Jackson3 기본)에서 bean 속성 변환이 깨지므로 Map/String으로 받습니다. (gateway의 다른 프로바이더들은 String으로 받아 직접 ObjectMapper로 파싱.)

---

E. LlmRouter — 폴백 체인의 본진 (service/llm/LlmRouter.java)

이제 두 번째 평행 세계입니다. 쿼터·로그가 없는 대신 프로바이더 폴백이 핵심.

// LlmRouter.java:11-36
public class LlmRouter {
    private final Map<String, LlmProvider> providers;
    private final List<LlmProvider> ordered;

    public LlmRouter(List<LlmProvider> providers) {
        this.ordered = providers;                                          // Bean 주입 순서 보존
        this.providers = providers.stream().collect(Collectors.toMap(LlmProvider::id, p -> p)); // id→provider 맵
    }

    public LlmProvider get(String id) {
        if (id == null || id.isBlank()) return defaultProvider();
        LlmProvider p = providers.get(id);
        if (p == null || !p.available()) return defaultProvider();         // ★ 없거나 키 없으면 폴백
        return p;
    }

    public LlmProvider defaultProvider() {
        return ordered.stream()
            .filter(LlmProvider::available)                                 // 키 있는 첫 프로바이더
            .findFirst()
            .orElseThrow(() -> new IllegalStateException("사용 가능한 LLM 프로바이더가 없습니다. ..."));
    }
}

• 두 가지 자료구조를 동시에 보관:
  • ordered (List) — 주입 순서 그대로(UI 표시 순서·폴백 우선순위). Spring은 보통 @Component 발견 순/알파벳 순으로 주입.
  • providers (Map) — id("gemini"/"anthropic"/...)로 O(1) 빠른 조회.
• 폴백 로직은 get()에 응축돼 있습니다: 요청한 provider가 없거나(p == null) 키가 없으면(!p.available()) → defaultProvider()로 자동 대체.
• defaultProvider() = ordered에서 available()이 참인 첫 번째. CLAUDE.md의 "Gemini → OpenAI → Anthropic → Perplexity 폴백 체인"이 바로 이 순서대로 사다리를 타는 것(주입 순서에 의존).

⚠️ 주의: 이 폴백은 "호출 전 가용성 검사" 기반입니다. 즉 "키가 설정돼 있나"만 보고 고릅니다. 고른 프로바이더가 호출 중에 실패하면(예: 일시적 5xx) 다른 프로바이더로 자동 재시도하지는 않습니다 — oneShot의 예외가 그대로 컨트롤러로 올라갑니다. (고도화: 런타임 실패 시 다음 프로바이더로 재시도.)

E-1. 두 LLM 묶음의 프로바이더는 어떻게 다른가?

service/llm/의 프로바이더(AnthropicProvider 등)는 gateway 버전과 별개 클래스입니다. 차이를 표로:

	service/gateway/*Provider	service/llm/*Provider
인터페이스	AiProvider	LlmProvider
모델 목록 노출	없음(카탈로그 DB가 담당)	models() 메서드로 하드코딩 노출
토큰 사용량	usage에서 정확히 파싱	파싱 안 함(반환 안 함)
멀티턴 chat	있음	없음(oneShot만)
기본 모델	카탈로그의 modelId 사용	메서드 내 하드코딩(claude-sonnet-4-5 등)

• 예를 들어 service/llm/AnthropicProvider(L38-44)는 모델 목록을 코드에 직접 적어 /api/llm/providers로 노출합니다 — 우측 도크 모델 선택기용.
• service/gateway/AnthropicProvider(L97-98)는 응답에서 usage.input_tokens/output_tokens를 읽어 정확한 쿼터 차감을 합니다.

---

F. 엔티티 — 메뉴판과 기록부 (entity/)

F-1. AiModelCatalog — 모델 메뉴판(요금표)

// AiModelCatalog.java:39-53 (핵심 필드)
@Column(name = "free_quota", nullable = false) private long freeQuota;  // 0이면 Free 사용 불가
@Column(name = "pro_quota", nullable = false)  private long proQuota;   // -1이면 무제한
@Column(name = "sort_order", nullable = false) private int sortOrder;   // UI 정렬
@Column(nullable = false)                      private boolean enabled; // 비활성 토글

• @Id가 modelId(문자열) 입니다(L22-24) — 숫자 자동증가가 아니라 "gemini-2.5-flash" 같은 모델명 자체가 기본키. 그래서 catalogRepo.findById("claude-sonnet-4")가 가능.
• freeQuota=0 / proQuota=-1 의 매직 넘버 규약(0=금지, -1=무제한)이 AiGatewayService 곳곳의 if (quota == 0)·if (quota != -1) 분기와 짝을 이룹니다. 이 약속을 모르면 게이트웨이 코드가 안 읽힙니다.

F-2. AiUsageLog — 호출 기록부

// AiUsageLog.java:13-16 (인덱스)
@Table(name = "AI_USAGE_LOG", indexes = {
        @Index(name = "ix_aiusage_user_time", columnList = "user_id, created_at"),
        @Index(name = "ix_aiusage_user_model_time", columnList = "user_id, model_id, created_at")
})

// AiUsageLog.java:53-56
@PrePersist
void onCreate() {
    if (createdAt == null) createdAt = LocalDateTime.now();
}

• 복합 인덱스 2개: 쿼터 합산 쿼리(user_id + model_id + created_at)와 사용자별 시간순 조회를 빠르게. 인덱스를 미리 깔아둔 게 "이 테이블은 자주 합산·조회된다"는 설계 의도를 드러냅니다.
• @PrePersist: 저장 직전 createdAt을 자동으로 현재 시각으로. 주석 클래스 설명대로 "월간 한도 계산 + Pro 결제 청구 근거"가 이 테이블의 존재 이유.

---

G. 컨트롤러 — 접수 데스크 (controller/)

G-1. AiController — 메인 채팅 (controller/AiController.java)

// AiController.java:27-38 (핵심)
public ResponseEntity<AiChatResponse> chat(@RequestBody AiChatRequest request) {
    Long uid = AuthContext.currentUserId();
    String reply;
    if (uid == null) {
        reply = geminiService.chat(request);                          // 비로그인 → 게이트 우회
    } else {
        String model = (request.getModel() 비었으면) DEFAULT_MODEL : request.getModel();
        reply = gateway.chat(uid, model, request);                    // 로그인 → 게이트웨이
    }
    return ResponseEntity.ok(AiChatResponse.builder().reply(reply).build());
}

• 분기 핵심: 신원(AuthContext.currentUserId())이 null(비로그인)이면 GeminiService 직접 호출 — 쿼터/로그를 건너뜁니다. 로그인 상태에서만 게이트웨이(쿼터·로그)를 탑니다.
• ⚠️ 이 우회는 의도이자 위험입니다. 비로그인 경로는 쿼터가 없어 무제한 Gemini 호출이 가능 — 인증을 강제하지 않으면 비용 폭탄이 될 수 있습니다(함정 섹션 참고).
• 에러를 3종으로 구분(L39-50)해 적절한 HTTP 상태로: HttpClientErrorException→500, IllegalState/Argument(쿼터·잘못된 모델)→400, 기타→500. 사용자에게 원인을 알려주는 친절 설계.

G-2. LlmController — 자유 채팅 (controller/LlmController.java)

// LlmController.java:44-61 (요약)
public ResponseEntity<?> chat(@RequestBody Map<String, Object> body) {
    String provider = (String) body.get("provider");
    String model    = (String) body.get("model");
    String reply = router.oneShot(provider, model, system, prompt);   // 라우터 폴백 경유
    LlmProvider used = router.get(provider);                          // 실제 쓰인 프로바이더
    return ResponseEntity.ok(Map.of("reply", reply, "provider", used.id(), ...));
}

• 응답에 "실제로 어떤 프로바이더가 쓰였는지"(used.id())를 담아 돌려줍니다 — 폴백으로 다른 프로바이더가 선택됐을 수 있으니, 사용자가 "내가 고른 게 아니라 폴백됐구나"를 알 수 있게.
• @RequestBody Map<String, Object> 로 느슨하게 받습니다(전용 DTO 없이). 자유 채팅이라 필드가 유동적이기 때문.

---

H. AiRateLimitFilter (M10) — 입구 회전문 (global/config/AiRateLimitFilter.java)

H-1. M10에서 고쳐진 신원 해석 버그 — L73-L86

// AiRateLimitFilter.java:80-86
// 신원은 request attribute 에서 직접 읽는다. AuthContext.currentUserId() 는 RequestContextHolder 에 의존하는데
// 서블릿 필터 단계에서는 (DispatcherServlet 진입 전이라) 아직 채워지지 않아 항상 null → 레이트리밋이 전원 무력화되던 버그.
Object uidAttr = request.getAttribute(JwtAuthenticationFilter.ATTR_USER_ID);
Long userId = (uidAttr instanceof Long l) ? l : null;
if (userId == null) {
    chain.doFilter(request, response);   // 미인증은 통과(컨트롤러가 401 처리)
    return;
}

• ⚠️ 이것이 M10 수정의 핵심입니다. 원래는 AuthContext.currentUserId()로 신원을 얻으려 했는데, 서블릿 필터는 DispatcherServlet보다 먼저 실행되어 RequestContextHolder가 아직 비어 있어 항상 null이었습니다. → 모든 사용자가 userId==null로 분류돼 레이트리밋이 통째로 무력화되던 버그.
• 수정: JwtAuthenticationFilter가 먼저 채워둔 request attribute(ATTR_USER_ID = "auth.userId")를 직접 읽습니다. 두 필터의 실행 순서(@Order)가 이 수정의 전제:
  • JwtAuthenticationFilter = @Order(HIGHEST_PRECEDENCE + 10) (먼저, attribute 채움)
  • AiRateLimitFilter = @Order(HIGHEST_PRECEDENCE + 20) (나중, attribute 읽음)
• (JwtAuthenticationFilter.java:34,49에서 setAttribute(ATTR_USER_ID, n.longValue())로 채우는 것을 확인.)

H-2. 버킷 알고리즘 — L88-L110

// AiRateLimitFilter.java:88-109
Bucket bucket = buckets.computeIfAbsent(userId, this::newBucket);   // 유저별 버킷
if (bucket.tryConsume(1)) {
    chain.doFilter(request, response);                              // 토큰 있으면 통과
} else {
    response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());       // 없으면 429
    response.getWriter().write("{\"error\":\"... 1시간에 " + capacity + "회 ...\"}");
}
// newBucket:
Bandwidth limit = Bandwidth.classic(capacity, Refill.greedy(refillTokens, Duration.ofMinutes(refillMinutes)));

• 토큰 버킷 알고리즘: 각 유저에게 양동이(Bucket)를 주고, 요청마다 토큰 1개 소비(tryConsume(1)). 비면 429. 양동이는 refillMinutes(60분)마다 refillTokens(20개)씩 다시 채워짐.
• 적용 범위가 좁다는 점 주의: shouldNotFilter(L62-71)를 보면 POST /api/alpha/workspaces/{id}/{chat|formalize|briefing|auto-run} 만 대상. /api/ai/chat·/api/llm/chat은 이 필터 대상이 아닙니다(함정 섹션 참고).
• 클래스 주석대로 인메모리(ConcurrentHashMap)라 단일 서버 가정 — 다중 인스턴스면 Redis 연동 필요(고도화).

---

⚠️ 함정·보안 주의

1. API 키는 절대 클라이언트로 나가면 안 됨.

   • 모든 키는 @Value("${...api.key}")로 서버 환경변수에서만 주입되고, HTTP 호출의 헤더(x-api-key/Authorization)나 URL 쿼리(?key=)에만 쓰입니다. 응답으로는 절대 반환하지 않습니다.
   • GeminiService 생성자 로그(L47-54)는 키 끝 4자리만(apiKeyTail) 찍습니다 — 전체 키를 로그에 남기지 않는 안전 관례.
   • ⚠️ 단, Gemini는 URL 쿼리스트링에 키를 붙입니다(...:generateContent?key=apiKey, L255). URL은 액세스 로그·프록시에 남을 수 있어 헤더 방식보다 노출 위험이 큽니다(Google API 규격상 불가피하나, 로그 마스킹 점검 필요).

2. M10 레이트리밋의 신원 해석 — 필터 순서에 생명이 달림.

   • 레이트리밋은 AuthContext가 아니라 request attribute(JwtAuthenticationFilter.ATTR_USER_ID)로 신원을 읽어야 합니다(H-1). @Order를 잘못 바꾸면 attribute가 비어 레이트리밋이 다시 전원 무력화됩니다. 필터 순서 변경 시 반드시 재검증.

3. /api/ai/chat·/api/llm/chat은 레이트리밋 밖.

   • AiRateLimitFilter는 /api/alpha/workspaces/**의 4개 엔드포인트만 막습니다. 메인 채팅(/api/ai/chat)과 자유채팅(/api/llm/chat)은 횟수 제한이 없습니다. /api/ai/chat은 그나마 게이트웨이 쿼터(월 토큰)가 막지만, /api/llm/chat은 쿼터도 레이트리밋도 없습니다 — 키만 있으면 무제한 호출 가능. 비용·악용 관점에서 가장 약한 고리.

4. 비로그인 경로의 게이트 우회.

   • AiController.chat은 uid == null이면 게이트웨이를 건너뛰고 GeminiService를 직접 부릅니다(G-1). 이 엔드포인트에 인증이 강제되지 않으면 익명 사용자가 쿼터 없이 Gemini를 무한 호출할 수 있습니다. SecurityConfig에서 /api/ai/**의 인증 요구 여부를 반드시 확인할 것.

5. Gemini 토큰은 추정값 — 쿼터·청구가 부정확.

   • GeminiProvider.estimateTokens는 글자수÷3 추정(C 섹션). 정확한 usageMetadata를 안 씁니다. Gemini 모델의 쿼터/청구는 다른 3사보다 부정확합니다. 보수적(과대)이라 사용자가 손해 볼 일은 드물지만, 정산 정확도가 필요하면 실제 메타데이터 파싱 필요.

6. 폴백 시 비용·일관성 주의.

   • 모델 폴백(GeminiService): 1순위 모델이 429/403이면 폴백 모델로 자동 전환 — 폴백 모델이 더 비싸거나 품질이 다를 수 있음. 사용자는 다른 모델로 답받은 걸 모를 수 있음.
   • 프로바이더 폴백(LlmRouter): 키 없는 provider 요청 시 조용히 default로 대체. 응답에 실제 provider를 담아주긴 하나(G-2), 프론트가 이를 표시하지 않으면 사용자는 "Claude에게 물었는데 Gemini가 답한" 상황을 모를 수 있음.
   • ⚠️ 단, 게이트웨이(gateway) 묶음은 프로바이더 간 폴백이 없습니다. 짝 프로바이더가 없거나 키 없으면 그냥 거부 — 쿼터 정확성을 위해 의도적으로 폴백을 뺀 설계.

7. 로그 저장 실패는 삼켜짐 — 쿼터 누락 가능성.

   • recordUsage는 DB 저장 실패를 log.warn만 하고 넘깁니다(B-7). 저장이 실패하면 그 호출의 토큰이 쿼터에 반영되지 않아 한도를 살짝 넘게 쓸 수 있음. 본 흐름 보호를 위한 트레이드오프.

8. 인메모리 레이트리밋 — 수평 확장 시 깨짐.

   • 버킷이 ConcurrentHashMap(JVM 메모리)에 있어, 서버를 2대로 늘리면 각 서버가 별도 카운트 → 실효 한도가 2배가 됩니다. 운영 다중화 시 Redis 기반으로 교체 필요(클래스 주석에도 명시).

---

🚀 고도화 아이디어

• 두 프로바이더 묶음 통합: gateway/와 llm/이 같은 4개 API를 중복 호출. LlmProvider를 AiProvider로 흡수하거나 어댑터로 묶어 단일 프로바이더 추상화로 정리하면 유지보수가 절반.
• Gemini 정확 토큰 집계: GeminiService가 응답의 usageMetadata.promptTokenCount/candidatesTokenCount를 파싱해 추정 대신 실값을 쓰도록 — 쿼터·청구 정확도 향상.
• 런타임 폴백 추가: LlmRouter가 "선택한 provider 호출이 5xx로 실패하면 다음 available provider로 재시도"하도록 try-catch 사다리 추가(현재는 사전 가용성만 검사).
• 레이트리밋을 게이트웨이 경로까지 확장: /api/ai/chat·/api/llm/chat도 필터 대상에 포함하거나, 티어별 한도(FREE 20·PRO 60)를 실제 구현(현재 PRO 분기는 "추후 확장" 주석만).
• Redis 기반 분산 레이트리밋: Bucket4j JCache + Redis로 다중 인스턴스에서도 정확한 한도.
• 비용 대시보드: AiUsageLog를 집계해 사용자/모델/월별 토큰·실패율 차트 — 이미 인덱스가 깔려 있어 쿼리만 추가하면 됨.
• 스트리밍 응답: 현재는 전체 응답을 한 번에 받음. SSE로 토큰 단위 스트리밍하면 체감 속도 개선(단, 토큰 집계 로직 재설계 필요).
• 모델 폴백 투명화: 응답에 "실제 사용 모델/프로바이더"와 "폴백 여부"를 표준 필드로 항상 포함해 프론트가 사용자에게 고지.
• ensureUsable 정밀화: monthStart에 .withNano(0)를 추가하고, 쿼터 검사와 실제 차감 사이의 레이스 컨디션(동시 요청이 한도를 약간 초과)을 비관적 락이나 원자적 카운터로 보완.

---

📚 용어 사전 (이 파트 한정)

용어	뜻
LLM 프로바이더	AI 모델을 빌려주는 회사/API (Gemini·Anthropic·OpenAI·Perplexity)
게이트웨이(Gateway)	여러 프로바이더를 묶어 쿼터·로그·라우팅을 일괄 관리하는 중앙 창구(AiGatewayService)
쿼터(Quota)	월간 토큰 사용 한도. 0=금지, -1=무제한, 양수=한도
레이트리밋(Rate Limit)	시간당 요청 횟수 제한(20회/시간). Bucket4j 토큰버킷
토큰(Token)	AI가 글을 세는 단위. 입력(tokensIn)+출력(tokensOut) 모두 비용
티어(Tier)	구독 등급 FREE/PRO. 같은 모델도 티어별 쿼터가 다름
프로바이더 폴백	키 없는 회사 대신 다른 회사로 대체(LlmRouter)
모델 폴백	같은 회사 안에서 모델만 바꿈(429/403 시, GeminiService)
어댑터 패턴	기존 클래스를 새 인터페이스에 맞게 변환기로 감쌈(GeminiProvider→GeminiService)
List<인터페이스> 주입	그 인터페이스를 구현한 모든 @Component를 Spring이 자동으로 리스트로 주입
@Value("${키:기본값}")	설정값 주입, 없으면 기본값(빈 문자열) — 키 없는 프로바이더가 앱을 죽이지 않게
토큰 버킷(Token Bucket)	양동이에 토큰을 주기적으로 채우고 요청마다 1개씩 빼는 레이트리밋 알고리즘
request attribute	한 HTTP 요청 동안 필터·컨트롤러가 공유하는 임시 저장소. M10에서 신원 전달에 사용
@Order (필터 순서)	서블릿 필터 실행 순서. 숫자 작을수록 먼저. JWT(+10) → RateLimit(+20)
@PrePersist	JPA 엔티티가 INSERT 되기 직전 자동 실행되는 훅(createdAt 자동 세팅)
429 / 403	HTTP 상태코드. 429=요청 너무 많음(한도), 403=접근 금지(권한/모델불가)
RPM / 일간 한도	RPM=분당 요청 수(기다리면 풀림), 일간 한도=하루 총량(기다려도 안 풀림)
Result (record)	응답 텍스트 + 입출력 토큰을 묶은 불변 데이터 객체

global/ — 앱 전체에 깔리는 공통 인프라 (보안·설정·필터·시드·유틸·터미널) 완전 해설

원본: backend/src/main/java/com/DevBridge/devbridge/global/ (15개 .java)
형식 표준: README "3. 공통 형식" + 모범 예시 01_backtest/vbt_engine.md.
Spring 기초(빈·DI·어노테이션)는 이 문서 안에서도 그때그때 짧게 다시 풀어 설명합니다. 완전 초보자 기준.

---

📌 이 영역 한눈에

domain/ 폴더들(user·strategy·ai·payment…)이 "각 부서" 라면, global/ 은 "건물 전체에 공통으로 깔린 인프라" 입니다. 어느 부서를 가든 똑같이 통과해야 하는 정문 검문소(보안), 전기·수도 배선(설정), 청소·초기 비품 세팅(시드 데이터) 같은 것들이죠.

비유로 보면:

손님(HTTP 요청)이 건물에 들어옴
        │
   ┌────▼─────────────────────────────────────────┐
   │  1층 정문 검문소 = security/                    │
   │   - 신분증(JWT 쿠키) 확인 → 누구인지 명찰 부착   │ JwtAuthenticationFilter
   │   - 금고 열쇠 암호화                            │ AesGcmCryptoService
   ├────▼─────────────────────────────────────────┤
   │  통행량 제한 게이트 = config/AiRateLimitFilter   │ 비싼 AI 방은 시간당 N명만
   ├────▼─────────────────────────────────────────┤
   │  각 부서(controller) 로 안내                     │
   └───────────────────────────────────────────────┘

건물을 처음 열 때(앱 기동):
   seed/  = 초기 비품·샘플 데이터를 미리 채워둠 (이미 있으면 건너뜀=멱등)
   config/ = CORS·비밀번호 해시기·Stream 채팅·Jackson 브릿지 같은 배선 설치
   util/  = 자주 쓰는 변환 도구(EnumMapper)
   terminal/ = (로컬 개발 전용) 웹에서 셸을 여는 콘센트

핵심 클래스 역할표

폴더	클래스	한 줄 역할	비유
security	JwtUtil	JWT 토큰 발행/검증 (HS256)	명찰을 만들고, 위조 명찰을 가려내는 기계
security	JwtAuthenticationFilter	모든 요청에서 토큰 꺼내 검증 → request.attribute 에 userId 부착	정문에서 신분증 확인 후 손목밴드 채움
security	AuthContext	컨트롤러/서비스에서 "지금 누구?" 를 꺼내는 헬퍼	손목밴드를 읽어주는 리더기
security	AesGcmCryptoService	민감 토큰(GitHub PAT 등)을 DB 저장 전 AES-GCM 암호화	귀중품 금고
config	AiRateLimitFilter	비싼 AI 엔드포인트 사용자당 시간당 20회 제한 (Bucket4j)	놀이기구 1시간 N회 손목티켓
config	PasswordConfig	BCrypt PasswordEncoder 빈 1개 제공	비밀번호 일방향 분쇄기
config	WebConfig	전역 CORS 규칙 + 업로드 파일 정적 서빙	외부 출입 허가 명단 + 자료실 공개 선반
config	StreamChatConfig	Stream Chat SDK 초기화(키/시크릿 주입)	외부 채팅 업체 계정 연결
config	Jackson2NodeBridgeConfig	Boot4(Jackson3) 환경에서 옛 Jackson2 JsonNode 직렬화 깨짐 수술	구형 플러그를 신형 콘센트에 꽂는 어댑터
seed	DataSeeder	기동 시 mock JSON → DB 적재 + 데이터 마이그레이션/정리 오케스트레이션	개관 전 매장 진열·재고 정리
seed	DataCleanupService	"완전한" 프로젝트/클라이언트 50개만 남기고 정리	불량 진열 상품 솎아내기
seed	AiModelCatalogSeeder	AI 모델 카탈로그(Gemini/Claude/GPT) 6종 시드	메뉴판 초기 등록
util	EnumMapper	JSON 소문자 문자열 → 백엔드 UPPERCASE enum 변환	외국어 메뉴를 우리 코드로 번역
terminal	TerminalWebSocketHandler	(로컬·loopback 전용) WS 로 셸 프로세스 stdin/stdout 중계	개발용 콘센트(외부엔 차단)
terminal	TerminalWebSocketConfig	app.terminal.enabled=true 일 때만 /ws/terminal 등록	콘센트 차단기 스위치

누가 이걸 쓰나? → 거의 모든 도메인. 예) user 의 로그인은 JwtUtil 로 토큰을 만들고, strategy 의 컨트롤러는 AuthContext.requireUserId() 로 "지금 로그인한 사람"을 알아냅니다. AI 채팅은 AiRateLimitFilter 를 통과해야만 LLM 을 호출합니다.

---

🧠 사전 지식 (이거 모르면 막힘)

1) 빈(Bean)·DI·@Component/@Configuration/@Bean

• 빈(Bean) = Spring 이 직접 만들어 보관하는 "재사용 객체". 우리가 new 하지 않고 Spring 이 만들어서 필요한 곳에 끼워줍니다(= 의존성 주입, DI).
• @Component / @Service 를 클래스에 붙이면 "이 클래스를 빈으로 등록해" 라는 뜻. (@Service 는 의미만 다른 @Component.)
• @Configuration 클래스 안의 @Bean 메서드는 "이 메서드 반환값을 빈으로 등록해". → PasswordConfig 가 이 방식.
• @RequiredArgsConstructor(Lombok) = final 필드를 받는 생성자를 자동 생성 → 생성자 DI 를 짧게.

2) 서블릿 필터(Servlet Filter) = "컨트롤러 도착 전에 모든 요청이 거치는 관문"

요청 → [필터1] → [필터2] → ... → DispatcherServlet → @Controller

• 필터는 요청을 가로채서 통과시키거나(chain.doFilter(...)) 막을 수 있습니다(응답 직접 작성).
• OncePerRequestFilter = "한 요청에 딱 한 번만 실행"을 보장하는 Spring 의 필터 베이스 클래스. (포워딩 등으로 중복 실행되는 걸 막아줌.)
• 핵심: 필터는 컨트롤러보다 먼저 돕니다. 그래서 인증·레이트리밋 같은 "공통 사전 검사"에 딱입니다.

3) 필터 순서 @Order — 숫자가 작을수록 먼저

• 필터가 여러 개면 어느 게 먼저 도는지가 중요합니다. @Order(낮은 수) 가 먼저.
• Ordered.HIGHEST_PRECEDENCE = 가장 높은 우선순위(아주 작은 음수). 거기에 +10, +20 을 더해 상대 순서를 만듭니다.
• 이 프로젝트:
  • JwtAuthenticationFilter = HIGHEST_PRECEDENCE + 10 → 먼저
  • AiRateLimitFilter = HIGHEST_PRECEDENCE + 20 → 나중
  • 왜 이 순서가 목숨인지는 아래 "M10 함정"에서 다룹니다.

4) request attribute vs RequestContextHolder

• request attribute = 요청 객체에 임시로 붙이는 메모쪽지(request.setAttribute("키", 값) / getAttribute("키")). 그 요청이 끝나면 사라짐.
• RequestContextHolder = "지금 이 스레드가 처리 중인 요청"을 어디서나 꺼내게 해주는 Spring 의 전역 보관함. 단, DispatcherServlet 이 채워줍니다. → 필터 단계(디스패처 진입 전)에선 아직 비어 있을 수 있음. (이게 M10 버그의 뿌리.)

5) CORS = "브라우저가 다른 출처(origin) 호출을 막는 규칙"

• 프론트(http://localhost:5173)가 백엔드(http://localhost:8080)를 부르면 출처가 다릅니다(포트 다름). 브라우저는 기본적으로 이걸 막습니다.
• 서버가 "이 출처는 허용한다(Access-Control-Allow-Origin)" 고 응답 헤더로 알려줘야 통과. WebConfig.addCorsMappings 가 그 허용 목록.
• allowCredentials(true) = 쿠키를 실어 보내는 걸 허용(우리는 JWT 를 쿠키로 보냄). 이때 allowedOrigins 에 * 를 쓰면 안 됨(브라우저가 거부). 그래서 명시적 출처 목록을 씁니다.

6) 시더(Seeder) 멱등(idempotent) = "여러 번 돌려도 결과가 같다"

• 앱은 켤 때마다 시더가 돕니다. 만약 매번 또 넣으면 데이터가 N배로 중복됩니다.
• 그래서 시더는 보통 if (repository.count() > 0) return; 으로 이미 있으면 건너뜀. 이게 멱등의 핵심 패턴.

7) @Profile("!prod") = "운영 환경이 아닐 때만 이 빈 활성화"

• 스프링 프로필(local/prod)에 따라 빈을 켜고 끕니다. !prod = "prod 가 아닐 때". → mock 시드는 운영 DB 를 더럽히면 안 되니 운영에선 끔.

8) AES-GCM·BCrypt — 두 종류의 "지키기"는 다르다

• 암호화(AES-GCM) = 잠갔다 다시 풀 수 있음(양방향). 외부 API 키처럼 "나중에 원본이 필요한" 비밀에 씀.
• 해싱(BCrypt) = 분쇄해서 되돌릴 수 없음(단방향). 비밀번호처럼 "맞는지 비교만 하면 되는" 비밀에 씀. (로그인 시 입력값을 같은 방식으로 분쇄해 저장본과 대조.)

---

🗺 요청 흐름도

                       HTTP 요청 (브라우저에서 옴, 쿠키 DEVBRIDGE_TOKEN 동봉)
                                    │
        ┌───────────────────────────▼────────────────────────────┐
        │ 서블릿 필터 체인 (컨트롤러 도착 전, @Order 순서대로)         │
        │                                                          │
        │  ① JwtAuthenticationFilter   @Order(HIGHEST + 10)         │
        │     - 쿠키 DEVBRIDGE_TOKEN (1순위) / Bearer 헤더(2순위) 추출 │
        │     - JwtUtil.parse() 로 검증                              │
        │     - 성공 → request.setAttribute("auth.userId", 12)       │ ◀── 명찰 부착
        │     - 실패/없음 → 그냥 통과 (익명, attribute 안 채움)        │
        │                  │                                        │
        │                  ▼                                        │
        │  ② AiRateLimitFilter        @Order(HIGHEST + 20)          │
        │     - shouldNotFilter(): POST + /chat·/formalize·…만 대상   │
        │     - request.getAttribute("auth.userId") 로 신원 직독 ★     │ ◀── ①이 채운 명찰을 읽음
        │     - 사용자별 Bucket 토큰 1개 소비 → 없으면 429 즉시 응답    │
        │                  │ (통과 시)                               │
        └──────────────────▼──────────────────────────────────────┘
                           ▼
                   DispatcherServlet  ← 여기서 RequestContextHolder 채워짐
                           ▼
                     @Controller / @Service
                           │
                  AuthContext.requireUserId()  ← RequestContextHolder→request attribute 읽음
                           ▼
                   비즈니스 로직 실행 → 응답
                           │
                   (analytics 프록시면) Jackson2NodeBridge 가 JsonNode 를 올바른 JSON 으로 직렬화

  ───────────────────────────────────────────────────────────────────────
  앱 기동(1회):  CommandLineRunner 들이 순서대로 실행
     AiModelCatalogSeeder(@Order 100) · DataSeeder(@Profile !prod)
        → seedXxx() 들 (count>0 이면 skip) → 마이그레이션 → DataCleanupService 정리

★ 표시 줄(request.getAttribute 직독)이 이 문서에서 가장 중요한 지점입니다. 왜 AuthContext 를 안 쓰고 attribute 를 직접 읽는가 → M10 함정에서 상세히.

---

📖 핵심 클래스 라인별 심화

A. JwtUtil — 명찰(토큰) 발급기/검증기 (security/JwtUtil.java)

키 준비 — JwtUtil.java:25-38

// L25-L38
public JwtUtil(
        @Value("${app.jwt.secret:dev-bridge-default-secret-key-change-in-production-please}") String secret,
        @Value("${app.jwt.ttl-hours:1}") long ttlHours
) {
    byte[] bytes = secret.getBytes(StandardCharsets.UTF_8);
    if (bytes.length < 32) {
        // 32바이트 미만이면 패딩 (개발 편의)
        byte[] padded = new byte[32];
        System.arraycopy(bytes, 0, padded, 0, bytes.length);
        bytes = padded;
    }
    this.key = Keys.hmacShaKeyFor(bytes);
    this.ttlMillis = ttlHours * 60 * 60 * 1000L;
}

• @Value("${app.jwt.secret:기본값}") — 설정파일/환경변수의 app.jwt.secret 값을 주입. : 뒤는 없을 때 쓸 기본값. (이 기본값은 개발용이며 운영에선 반드시 환경변수로 덮어써야 함 — 문자열에도 "change-in-production"이라 박혀 있음.)
• HS256(HMAC-SHA256) 은 대칭키 서명 → 키가 최소 32바이트여야 함. 그래서 짧으면 0으로 패딩해 길이를 맞춥니다. (편의 기능이지만, 진짜 짧은 비밀키는 보안상 약하니 운영에선 충분히 긴 비밀키를 줘야 함.)
• ttlMillis — 토큰 유효시간(밀리초). 기본 1시간(ttl-hours:1).

💡 초보 포인트: 대칭키(HS256) = 같은 비밀키로 서명도 하고 검증도 함. 그래서 이 비밀키가 새면 누구나 위조 토큰을 만들 수 있음 → JWT_SECRET 은 1급 비밀.

토큰 발행 issue() — JwtUtil.java:46-58

// L46-L58
public String issue(Long userId, String email, String userType) {
    Date now = new Date();
    return Jwts.builder()
            .subject(email)
            .claims(Map.of("uid", userId, "type", userType))
            .issuedAt(now)
            .expiration(new Date(now.getTime() + ttlMillis))
            .signWith(key)
            .compact();
}

• JWT 는 헤더.페이로드.서명 3토막의 문자열. 여기서 페이로드에 claims(주장) 를 담습니다:
  • subject(email) = 표준 필드 sub 에 이메일.
  • uid = users.id(PK) ← 이게 가장 중요. 나중에 필터/AuthContext 가 이 값으로 "누구"를 식별.
  • type = "FREE"/"STANDARD"/"PREMIUM" 같은 등급(주석엔 PARTNER/CLIENT/ADMIN 으로 적혀 있으나, 실제 값은 호출부가 정함).
• signWith(key) = 위 비밀키로 서명 → 내용을 바꾸면 서명이 깨져 위조가 탄로남.
• .compact() = 최종 문자열로 직렬화.

⚠️ 주의: JWT 의 페이로드는 암호화가 아니라 인코딩(Base64url)일 뿐입니다. 누구나 디코드해 내용을 볼 수 있어요. "위조 방지(서명)"는 되지만 "비밀 유지"는 안 됨 → 민감정보(비밀번호 등)를 claims 에 넣지 말 것.

검증 parse() / 추출 — JwtUtil.java:61-73

// L61-L73
public Claims parse(String token) {
    return Jwts.parser().verifyWith(key).build()
            .parseSignedClaims(token).getPayload();
}
public Long extractUserId(String token) {
    Object uid = parse(token).get("uid");
    if (uid instanceof Number n) return n.longValue();
    return null;
}

• verifyWith(key) → 서명·만료 검증. 위조거나 만료면 예외가 터집니다(그래서 호출부가 try/catch 로 감쌈).
• extractUserId — claims 의 uid 를 꺼냄. JWT 안 숫자는 보통 Integer/Long 으로 역직렬화되므로 Number 로 받아 longValue() 로 통일. (이 "Number 로 받아 longValue" 패턴이 필터·AuthContext 에서 반복됩니다.)

---

B. JwtAuthenticationFilter — 정문 검문소 (security/JwtAuthenticationFilter.java)

클래스 선언 + 필터 순서 — JwtAuthenticationFilter.java:28-37

// L28-L37
@Component
@Order(Ordered.HIGHEST_PRECEDENCE + 10)   // 반드시 AiRateLimitFilter(+20)보다 먼저 실행 — 그래야 요청 attribute(userId)가 채워진다
@RequiredArgsConstructor
@Slf4j
public class JwtAuthenticationFilter extends OncePerRequestFilter {
    public static final String ATTR_USER_ID = "auth.userId";
    public static final String ATTR_USER_TYPE = "auth.userType";
    private final JwtUtil jwtUtil;

• @Component → 빈 등록(Boot 가 자동으로 필터 체인에 끼워줌). extends OncePerRequestFilter → 요청당 1회.
• @Order(HIGHEST + 10) → 체인에서 먼저 실행 (사전지식 3번). 주석이 이유를 직접 명시: 뒤에 오는 레이트리밋이 attribute(userId)를 읽으려면 여기가 먼저 채워줘야 함.
• ATTR_USER_ID, ATTR_USER_TYPE = attribute 키 이름을 상수로 공개 → AuthContext·AiRateLimitFilter 가 같은 키를 공유(오타 방지).

핵심 로직 doFilterInternal() — JwtAuthenticationFilter.java:39-60

// L39-L60
protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) {
    String token = extractToken(request);
    if (token != null && !token.isBlank()) {
        try {
            var claims = jwtUtil.parse(token);
            Object uid = claims.get("uid");
            Object type = claims.get("type");
            if (uid instanceof Number n) request.setAttribute(ATTR_USER_ID, n.longValue());
            if (type != null)           request.setAttribute(ATTR_USER_TYPE, type.toString());
        } catch (Exception e) {
            // 토큰 파싱 실패: 익명 요청으로 통과
            log.debug("JWT parse failed: {}", e.getMessage());
        }
    }
    chain.doFilter(request, response);   // ← 성공이든 실패든 항상 다음으로 넘김
}

• 흐름: 토큰 추출 → 있으면 검증 → 성공하면 request 에 userId/userType 명찰을 붙임.
• 중요한 설계 결정: 검증 실패해도 요청을 막지 않습니다(chain.doFilter 항상 호출). "익명으로 통과"시키고, 인증이 꼭 필요한 컨트롤러가 알아서 attribute 를 확인(AuthContext.requireUserId() 가 없으면 401)하는 구조. → "필터는 명찰만 붙이고, 입장 거부는 각 방(컨트롤러)이 결정".
• n.longValue() — JWT 숫자(보통 Integer)를 Long 으로 통일해 저장. 이 타입 통일이 뒤에서 함정이 됨(AuthContext 의 instanceof Long 캐스팅과 짝).

토큰 추출 우선순위 extractToken() — JwtAuthenticationFilter.java:62-79

// L62-L79
private String extractToken(HttpServletRequest request) {
    // 1순위: HttpOnly 쿠키
    Cookie[] cookies = request.getCookies();
    if (cookies != null) {
        for (Cookie c : cookies) {
            if (AuthController.AUTH_COOKIE_NAME.equals(c.getName())) {   // "DEVBRIDGE_TOKEN"
                String v = c.getValue();
                if (v != null && !v.isBlank()) return v.trim();
            }
        }
    }
    // 2순위: Authorization 헤더 (레거시 호환)
    String header = request.getHeader("Authorization");
    if (header != null && header.startsWith("Bearer ")) return header.substring(7).trim();
    return null;
}

• 1순위 = HttpOnly 쿠키 DEVBRIDGE_TOKEN. JS 가 못 읽는 쿠키라 XSS 토큰 탈취 방지(CLAUDE.md 보안 설계와 일치).
• 2순위 = Authorization: Bearer <token> 헤더 — 옛 클라이언트/도구 호환용. substring(7) 은 "Bearer "(7글자) 뒤를 자름.
• 쿠키 이름은 AuthController.AUTH_COOKIE_NAME 상수를 그대로 참조 → 발급(로그인)과 검증이 같은 이름을 쓰도록 단일 출처화.

💡 쿠키 발급 쪽(AuthController.buildAuthCookie)은 httpOnly(true), secure(운영 true), sameSite("Lax"), path("/"), maxAge=ttl 로 만듭니다. 즉 HttpOnly+Secure(prod)+SameSite=Lax 가 실제 코드로 확인됩니다.

---

C. AuthContext — "지금 누구?" 리더기 (⚠️ 필터에선 쓰면 안 되는 함정) (security/AuthContext.java)

클래스 + 오버라이드 슬롯 — AuthContext.java:11-25

// L11-L25
public final class AuthContext {
    private AuthContext() {}   // 인스턴스화 금지(정적 유틸)
    /** 백그라운드 잡(스케줄러 등) HTTP 컨텍스트 부재 시 임시 사용자 주입용 */
    private static final ThreadLocal<Long> OVERRIDE_USER_ID = new ThreadLocal<>();
    public static void set(Long userId) { if (userId != null) OVERRIDE_USER_ID.set(userId); }
    public static void clear() { OVERRIDE_USER_ID.remove(); }

• final 클래스 + private 생성자 = "인스턴스 만들지 말고 정적 메서드만 써라". (유틸 클래스 관용.)
• ThreadLocal<Long> OVERRIDE_USER_ID — 스레드 전용 변수. HTTP 요청이 아닌 곳(스케줄러·배치 잡)에는 "현재 사용자"라는 개념이 없으니, 그때 set(userId) 로 이 스레드에서만 임시 신원을 심습니다.
• 반드시 finally { clear() } 로 지워야 함(주석 강조). 안 지우면 스레드풀에서 그 스레드가 다음 요청에 엉뚱한 신원을 물고 갈 수 있음(스레드 재사용 누수).

현재 사용자 조회 currentUserId() — AuthContext.java:27-34

// L27-L34
public static Long currentUserId() {
    Long override = OVERRIDE_USER_ID.get();
    if (override != null) return override;                 // ① 스케줄러가 심은 값 우선
    HttpServletRequest req = currentRequest();             // ② 없으면 현재 HTTP 요청에서
    if (req == null) return null;
    Object v = req.getAttribute(JwtAuthenticationFilter.ATTR_USER_ID);
    return v instanceof Long ? (Long) v : null;            // ③ 필터가 붙인 명찰 읽기
}

• 우선순위: ① override(스케줄러) → ② HTTP 요청 attribute. 둘 다 없으면 null(익명).
• JwtAuthenticationFilter.ATTR_USER_ID 상수를 공유 → 필터가 setAttribute 한 값을 여기서 getAttribute.
• v instanceof Long — 필터가 n.longValue() 로 Long 을 넣었기에 캐스팅이 맞음. (만약 어디선가 Integer 로 넣으면 여기서 null 이 되는 함정이 잠재.)

request 획득 currentRequest() — AuthContext.java:43-55 (★함정의 진원지)

// L43-L55
public static Long requireUserId() {
    Long id = currentUserId();
    if (id == null) throw new RuntimeException("인증이 필요합니다.");
    return id;
}
private static HttpServletRequest currentRequest() {
    var attrs = RequestContextHolder.getRequestAttributes();
    if (attrs instanceof ServletRequestAttributes sra) return sra.getRequest();
    return null;
}

• requireUserId() = "로그인 필수" 메서드. 없으면 예외 → 컨트롤러가 401 비슷하게 처리. 컨트롤러에서 "현재 사용자"를 꺼내는 표준 진입점.
• currentRequest() 가 RequestContextHolder 에 의존하는 게 핵심. 이건 DispatcherServlet 이 채워주는 전역 보관함입니다(사전지식 4번).
• 따라서 AuthContext.currentUserId() 는 컨트롤러/서비스(디스패처 이후) 에서는 잘 동작하지만, 서블릿 필터 안(디스패처 이전) 에서는 RequestContextHolder 가 비어 있어 항상 null 을 돌려줍니다. → 바로 이게 다음에 나오는 M10 버그의 원인. 그래서 AiRateLimitFilter 는 AuthContext 를 안 쓰고 request.getAttribute 를 직접 읽습니다.

---

D. AiRateLimitFilter — 비싼 방 통행 제한 (M10 필터순서 교훈) (config/AiRateLimitFilter.java)

선언 + 순서 — AiRateLimitFilter.java:37-52

// L37-L52
@Slf4j @Component
@Order(Ordered.HIGHEST_PRECEDENCE + 20)   // JwtAuthenticationFilter(+10) 다음에 실행 — 그래야 request attribute(userId)가 채워진 상태
public class AiRateLimitFilter extends OncePerRequestFilter {
    @Value("${app.ratelimit.ai-chat.capacity:20}")      private int capacity;       // 버킷 용량(최대 토큰)
    @Value("${app.ratelimit.ai-chat.refill-tokens:20}") private int refillTokens;   // 채워지는 토큰 수
    @Value("${app.ratelimit.ai-chat.refill-minutes:60}")private int refillMinutes;  // 채우는 주기(분)
    /** userId → Bucket */
    private final Map<Long, Bucket> buckets = new ConcurrentHashMap<>();

• @Order(HIGHEST + 20) → JWT 필터(+10) 다음. 이게 정확해야 작동함(이유는 doFilterInternal 에서).
• Bucket4j 토큰버킷: 사용자마다 Bucket(토큰 통). 요청 1번 = 토큰 1개 소비. 비면 거부. 시간이 지나면 다시 채워짐(refill).
• ConcurrentHashMap<Long, Bucket> — userId 별 버킷을 메모리에 보관(스레드 안전). 주석대로 운영 다중 인스턴스라면 Redis 권장(서버마다 메모리가 따로라 한도가 합쳐지지 않음).

적용 대상 필터링 shouldNotFilter() — AiRateLimitFilter.java:54-71

// L54-L71
private static final String[] RATE_LIMITED_SUFFIXES = { "/chat", "/formalize", "/briefing", "/auto-run" };

protected boolean shouldNotFilter(HttpServletRequest request) {
    if (!"POST".equalsIgnoreCase(request.getMethod())) return true;           // POST 아니면 제외
    String path = request.getRequestURI();
    if (!path.startsWith("/api/alpha/workspaces/")) return true;              // 워크스페이스 경로 아니면 제외
    for (String suffix : RATE_LIMITED_SUFFIXES) if (path.endsWith(suffix)) return false; // 4종만 대상
    return true;
}

• shouldNotFilter 가 true 면 이 필터를 건너뜀. 즉 "막을 대상"을 좁게 한정: POST + /api/alpha/workspaces/... + 끝이 /chat·/formalize·/briefing·/auto-run 인 요청만 레이트리밋.
• 왜 이 4개? → 전부 LLM/전체 파이프라인 호출(돈·쿼터 소모) 엔드포인트(클래스 주석에 매핑 명시). 조회성 GET 은 막을 이유가 없음.

핵심: 신원 직독 + 토큰 소비 doFilterInternal() — AiRateLimitFilter.java:73-102

// L73-L102 (요약 발췌)
protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) {
    // 신원은 request attribute 에서 직접 읽는다. AuthContext.currentUserId() 는 RequestContextHolder 에 의존하는데
    // 서블릿 필터 단계에서는 (DispatcherServlet 진입 전이라) 아직 채워지지 않아 항상 null → 레이트리밋이 전원 무력화되던 버그.
    // JwtAuthenticationFilter(@Order +10)가 먼저 실행돼 이 attribute 를 채워둔다(@Order +20).
    Object uidAttr = request.getAttribute(JwtAuthenticationFilter.ATTR_USER_ID);
    Long userId = (uidAttr instanceof Long l) ? l : null;
    if (userId == null) { chain.doFilter(request, response); return; }   // 미인증 → 통과(컨트롤러가 401)

    Bucket bucket = buckets.computeIfAbsent(userId, this::newBucket);
    if (bucket.tryConsume(1)) {
        chain.doFilter(request, response);                               // 토큰 있음 → 통과
    } else {
        long availableIn = bucket.getAvailableTokens();
        response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());        // 429
        response.setContentType(MediaType.APPLICATION_JSON_VALUE);
        response.getWriter().write("{\"error\":\"...1시간에 " + capacity + "회...\",\"remaining\":" + availableIn + "}");
    }
}

• 이 8줄짜리 주석이 M10 의 전부입니다. 핵심: AuthContext.currentUserId() 를 필터에서 호출하면 RequestContextHolder 가 아직 비어 항상 null → 모든 사용자가 null 로 묶여 레이트리밋이 사실상 무력화되던 버그. 해결책은 JWT 필터가 미리 채워둔 request.getAttribute(ATTR_USER_ID) 를 직접 읽는 것.
• 그래서 두 가지가 동시에 성립해야 함: ① 순서(JWT +10 이 RateLimit +20 보다 먼저) ② 직독(AuthContext 우회). 둘 중 하나만 틀려도 레이트리밋이 깨짐.
• computeIfAbsent(userId, this::newBucket) — 그 사용자의 버킷이 없으면 새로 만들고, 있으면 재사용. tryConsume(1) — 토큰 1개 차감 시도(성공/실패 boolean).
• 거부 시 429 Too Many Requests + 한국어 JSON 에러를 직접 기록(컨트롤러까지 안 가고 필터에서 응답 종결).

버킷 생성 newBucket() — AiRateLimitFilter.java:104-110

// L104-L110
private Bucket newBucket(Long userId) {
    Bandwidth limit = Bandwidth.classic(capacity, Refill.greedy(refillTokens, Duration.ofMinutes(refillMinutes)));
    return Bucket.builder().addLimit(limit).build();
}

• Bandwidth.classic(20, greedy(20, 60분)) = "용량 20, 60분에 20개를 점진(greedy) 보충". 즉 시간당 20회. greedy 는 60분을 통째로 기다리지 않고 비율대로 조금씩 채움.

⚠️ 미인증(userId==null)일 때 통과시키는 게 의아할 수 있는데(레이트리밋 우회처럼 보임), 대상 컨트롤러들이 어차피 인증을 요구해 401 로 막히고, LLM 실제 호출은 인증 통과 후에만 일어나므로 비용 누수는 없습니다(주석 근거).

---

E. PasswordConfig — BCrypt 분쇄기 (config/PasswordConfig.java)

// L15-L22
@Configuration
public class PasswordConfig {
    @Bean
    public PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); }
}

• 딱 한 가지: PasswordEncoder 빈(BCrypt) 1개를 앱 전역에 공급. user 도메인의 회원가입/로그인이 passwordEncoder.encode(...) / .matches(...) 로 사용.
• 중요(클래스 주석): 이 프로젝트는 Spring Security 프레임워크 전체를 의도적으로 끔(build.gradle 의 spring-boot-starter-security 가 주석 처리, spring-security-crypto 만 의존). 즉 SecurityFilterChain·자동 인증 흐름이 없고, 인증/인가는 위의 JwtAuthenticationFilter + AuthContext 가 수동으로 담당. BCrypt 알고리즘만 빌려 쓰는 구조입니다.

💡 BCrypt 는 같은 비밀번호라도 매번 다른 salt 로 다른 해시를 냅니다. 그래서 저장본끼리 비교가 아니라 matches(원문, 저장해시) 로 검증해야 함.

---

F. AesGcmCryptoService — 귀중품 금고 (security/AesGcmCryptoService.java)

키 초기화 init() — AesGcmCryptoService.java:33-49

// L33-L49
@Value("${app.crypto.key:}")        private String configuredKey;
@Value("${app.jwt.secret:...32bytes}") private String jwtSecretFallback;
private SecretKey secretKey;
private final SecureRandom rng = new SecureRandom();

@PostConstruct
void init() throws Exception {
    String raw = (configuredKey != null && !configuredKey.isBlank()) ? configuredKey : jwtSecretFallback;
    byte[] keyBytes = MessageDigest.getInstance("SHA-256").digest(raw.getBytes());  // 무조건 32바이트로
    this.secretKey = new SecretKeySpec(keyBytes, "AES");
    log.info("AesGcmCryptoService initialized (key source: {})",
            (configuredKey != null && !configuredKey.isBlank()) ? "app.crypto.key" : "JWT secret fallback");
}

• @PostConstruct = 빈이 만들어진 직후 1회 실행(초기화 훅).
• 키 출처: app.crypto.key 우선, 비어 있으면 app.jwt.secret 으로 폴백. 어느 쪽이든 SHA-256 해시로 32바이트 고정 → AES-256 키. (원본 길이가 들쭉날쭉해도 항상 32바이트가 됨.)
• 시크릿 자체는 로깅하지 않고 "출처"만 INFO 로 남김(안전).

⚠️ 메모리 노트("Env priority changes need duplicate-key audit")와 직결: app.crypto.key 가 .env/application*.properties 에 서로 다른 값으로 중복 정의돼 있으면, 어떤 게 주입되느냐에 따라 복호화 키가 달라져 기존 암호문을 못 푸는 사고가 납니다. 이 클래스의 폴백 로직 때문에 더더욱 "키 일관성"이 중요.

암호화 encrypt() — AesGcmCryptoService.java:51-63

// L51-L63
public byte[] encrypt(String plaintext) {
    if (plaintext == null) return null;
    byte[] iv = new byte[IV_LENGTH];           // IV_LENGTH = 12
    rng.nextBytes(iv);                          // 매번 랜덤 IV
    Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
    cipher.init(Cipher.ENCRYPT_MODE, secretKey, new GCMParameterSpec(128, iv));  // 128 = tag bits
    byte[] ct = cipher.doFinal(plaintext.getBytes());
    return ByteBuffer.allocate(iv.length + ct.length).put(iv).put(ct).array();   // [12B IV][암호문+태그]
}

• AES-GCM = 암호화 + 무결성 태그(변조 감지)를 동시에 제공하는 모드. NoPadding 은 GCM 이 패딩이 필요 없어서.
• IV(초기화 벡터)는 매번 랜덤 12바이트. 같은 평문도 매번 다른 암호문이 되게 함(패턴 노출 방지). 재사용 금지가 GCM 의 철칙 → SecureRandom 으로 매번 새로.
• 저장 형식이 클래스 주석대로 [12B IV][암호문+태그] 한 덩어리. 복호화 때 앞 12바이트를 떼어 IV 로 씀.

복호화 decrypt() + Base64 헬퍼 — AesGcmCryptoService.java:65-89

// L65-L89 (요약)
public String decrypt(byte[] payload) {
    if (payload == null || payload.length < IV_LENGTH + 1) return null;
    ByteBuffer bb = ByteBuffer.wrap(payload);
    byte[] iv = new byte[IV_LENGTH]; bb.get(iv);          // 앞 12B = IV
    byte[] ct = new byte[bb.remaining()]; bb.get(ct);     // 나머지 = 암호문+태그
    Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
    cipher.init(Cipher.DECRYPT_MODE, secretKey, new GCMParameterSpec(128, iv));
    return new String(cipher.doFinal(ct));                // 태그 불일치 시 예외(변조 탐지)
}
public String encryptToBase64(String s) { ... }   // byte[] → Base64 문자열 (DB 컬럼/JSON 저장용)
public String decryptFromBase64(String b64) { ... }

• 복호화는 정확히 역순: IV 분리 → 복호화. 암호문이 한 비트라도 변조되면 GCM 태그 검증 실패로 예외 → 위변조를 자동 차단.
• encryptToBase64/decryptFromBase64 — 바이트를 그대로 DB/JSON 에 넣기 불편하니 Base64 텍스트로 변환하는 편의 래퍼. KIS 키·GitHub PAT 등을 문자열 컬럼에 저장할 때 사용.

---

G. WebConfig — CORS + 업로드 파일 서빙 (config/WebConfig.java)

허용 출처 해석 — WebConfig.java:28-39

// L28-L39
@Value("${app.cors.allowed-origins:http://localhost:5173,http://127.0.0.1:5173}")
private String allowedOriginsCsv;

private String[] resolveOrigins() {
    if (allowedOriginsCsv == null || allowedOriginsCsv.isBlank())
        return new String[]{"http://localhost:5173", "http://127.0.0.1:5173"};
    return java.util.Arrays.stream(allowedOriginsCsv.split(","))
            .map(String::trim).filter(s -> !s.isEmpty()).toArray(String[]::new);
}

• 콤마로 구분된 출처 목록을 환경변수(CORS_ALLOWED_ORIGINS)로 받아 배열로 분해. 비면 로컬 dev 주소로 폴백.
• 운영에선 실제 프론트 도메인을 넣어야 함. (CLAUDE.md 환경변수표에도 등장.)

CORS 매핑 — WebConfig.java:42-56

// L42-L56
public void addCorsMappings(CorsRegistry registry) {
    String[] origins = resolveOrigins();
    registry.addMapping("/api/**")
            .allowedOrigins(origins)
            .allowedMethods("GET","POST","PUT","PATCH","DELETE","OPTIONS")
            .allowedHeaders("*")
            .allowCredentials(true)    // ★ 쿠키 동봉 허용
            .maxAge(3600);
    registry.addMapping(publicBase + "/**")   // "/files/**" — 업로드 다운로드
            .allowedOrigins(origins).allowedMethods("GET","HEAD","OPTIONS").maxAge(3600);
}

• /api/** 에 CORS 허용. allowCredentials(true) + 명시적 allowedOrigins 조합이 핵심: 쿠키 인증(JWT 쿠키)을 쓰니 자격증명을 허용하되, 그러면 * 를 못 쓰므로 출처를 정확히 나열해야 함(사전지식 5번).
• maxAge(3600) — 프리플라이트(OPTIONS) 결과를 1시간 캐시 → 매 요청마다 사전검사 안 함(성능).

정적 리소스 핸들러 — WebConfig.java:59-65

// L59-L65
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    Path root = Paths.get(uploadDir).toAbsolutePath().normalize();
    String location = root.toUri().toString();    // file:/.../uploads/
    registry.addResourceHandler(publicBase + "/**")   // /files/**
            .addResourceLocations(location).setCachePeriod(3600);
}

• 업로드 폴더(app.upload.dir, 기본 uploads)를 /files/** URL 로 정적 서빙. 프론트가 <a href="/files/..."> 로 첨부파일을 직접 받음.
• .normalize() + 절대경로화 — 경로 정규화로 ../ 같은 트래버설 혼선을 줄임.

---

H. Jackson2NodeBridgeConfig — Boot4 직렬화 수술 (config/Jackson2NodeBridgeConfig.java)

// L33-L53 (요약)
@Bean
JacksonModule jackson2NodeBridgeModule() {
    SimpleModule module = new SimpleModule("Jackson2NodeBridge");
    module.addSerializer(com.fasterxml.jackson.databind.JsonNode.class, new Jackson2NodeSerializer());
    return module;
}
private static final class Jackson2NodeSerializer extends ValueSerializer<com.fasterxml.jackson.databind.JsonNode> {
    public void serialize(com.fasterxml.jackson.databind.JsonNode value, JsonGenerator gen, SerializationContext ctxt) {
        if (value == null || value.isNull()) gen.writeNull();
        else gen.writeRawValue(value.toString());   // 옛 JsonNode 의 원본 JSON 텍스트를 그대로 출력
    }
}

• 문제(메모리 "Spring Boot 4 Jackson JsonNode 버그"와 직결): Boot 4 의 기본 매퍼는 Jackson 3(tools.jackson)인데, 앱 곳곳(AnalyticsClient·브로커·LLM)이 Jackson 2(com.fasterxml.jackson)의 JsonNode 를 만들어 컨트롤러가 그대로 반환. Jackson 3 은 그걸 트리로 못 알아보고 getter 들(isArray·nodeType…)을 직렬화 → {"array":false,"nodeType":"OBJECT",...} 같은 쓰레기 JSON 이 나감. analytics 프록시 엔드포인트 전체가 영향.
• 해결: 기본 Jackson 3 매퍼는 건드리지 않고(DTO·날짜 직렬화 회귀 위험 0), Jackson 2 JsonNode 타입만 만났을 때 그 노드의 toString()(항상 유효한 JSON 텍스트)을 writeRawValue 로 원본 그대로 출력하는 직렬화기를 다리처럼 등록. 외과적 수정.
• Boot 4 가 컨텍스트의 모든 JacksonModule 빈을 기본 매퍼에 자동 등록하므로, 이 빈 하나 선언만으로 전역 적용. (앱이 Jackson3 로 완전 이행하면 이 브릿지는 제거 가능.)

💡 초보 포인트: "Jackson 이 2개"라는 게 함정의 본질. 패키지가 com.fasterxml.jackson(2) vs tools.jackson(3) 로 다릅니다. 같은 이름 JsonNode 라도 다른 타입이라 서로 못 알아봅니다.

---

I. StreamChatConfig — 외부 채팅 SDK 연결 (config/StreamChatConfig.java)

// L37-L53 (요약)
@PostConstruct
public void init() {
    boolean haveKey = apiKey != null && !apiKey.isBlank();
    boolean haveSecret = apiSecret != null && !apiSecret.isBlank();
    if (haveKey && System.getProperty("STREAM_KEY") == null)    System.setProperty("STREAM_KEY", apiKey);
    if (haveSecret && System.getProperty("STREAM_SECRET") == null) System.setProperty("STREAM_SECRET", apiSecret);
    log.info("[StreamChatConfig] keyPresent={}, secretPresent={}", haveKey, haveSecret);  // 존재 여부만(시크릿 노출 X)
    if (!haveKey || !haveSecret) log.warn("Stream Chat 키/시크릿이 비어있습니다. 채팅 기능이 동작하지 않을 수 있어요.");
}

• Stream Chat Java SDK 는 시스템 프로퍼티 STREAM_KEY/STREAM_SECRET 를 읽어 자체 초기화 → 그래서 System.setProperty 가 필수.
• 안전장치 3개: ① 외부에서 이미 주입돼 있으면 덮어쓰지 않음(== null 일 때만 set) ② 빈 값이면 아예 set 안 함(빈 값으로 초기화돼 런타임 401 나는 것 방지) ③ 시크릿은 로깅 금지, boolean 존재여부만.

---

J. DataSeeder — 개관 준비 오케스트레이터 (seed/DataSeeder.java)

선언 + 비-트랜잭션 결정 — DataSeeder.java:50-84

// L50-L84 (발췌)
@Slf4j @Component @Profile("!prod") @RequiredArgsConstructor
public class DataSeeder implements CommandLineRunner {
    ...repository 다수...
    private final ObjectMapper objectMapper = new ObjectMapper();
    private final Map<Long, Long> userIdMap = new HashMap<>();   // JSON id → 실제 DB PK
    ...
    @Override
    // 의도적으로 @Transactional 제거 — 거대한 outer 트랜잭션 안에서 일부 SQL 이 실패하면
    // rollback-only 마킹돼 마지막 commit 이 실패한다. 각 seedXxx()/cleanupXxx()/bootstrap*() 는
    // 내부에서 자체 트랜잭션을 관리하거나 REQUIRES_NEW 로 독립 커밋한다.
    public void run(String... args) throws Exception { ... }

• implements CommandLineRunner → 앱 기동 완료 직후 run() 1회 실행. (기동 시 데이터 준비에 표준.)
• @Profile("!prod") → 운영에선 비활성(mock 데이터로 운영 DB 오염 방지). AiModelCatalogSeeder 는 prod/local 둘 다였던 것과 대비.
• @Transactional 을 일부러 안 붙임(주석 핵심): 거대한 단일 트랜잭션이면 중간 한 SQL 실패가 전체를 rollback-only 로 만들어 최종 commit 까지 날림. 그래서 각 단계가 자기 트랜잭션을 따로 가짐(특히 cleanup 은 REQUIRES_NEW 로 독립 커밋).
• userIdMap/skillIdMap/... — JSON 의 원본 id → 실제 저장된 PK 매핑표. JSON 끼리의 FK 참조를 실제 DB PK 로 이어주는 다리(아래 seed 메서드들이 채우고 읽음).

실행 순서 run() — DataSeeder.java:84-153

// L84-L153 (구조 발췌)
log.info("===== DataSeeder 시작 =====");
seedSkillMaster(); seedProjectFieldMaster(); seedUsers();
seedClientProfile(); seedClientProfileStats(); seedClientPreferredSkill();
seedProjects(); seedProjectApplications(); seedProjectTags(); seedProjectSkillMapping(); seedChatRooms();
contractModuleSeeder.backfillAll();        // 7개 계약 모듈 백필
migrateBudgetManToWon();                    // 만원→원 단위 마이그레이션
backfillModulesFromContractTerms();         // AI 협의내용 → 모듈 반영
milestoneSeedingService.bootstrapAll();     // 마일스톤 자동 시드
// 1회성 정리(독립 트랜잭션으로 직접 호출):
pr = dataCleanupService.cleanupProjects();
cr = dataCleanupService.cleanupClients();
op = dataCleanupService.cleanupOrphans();

• 순서가 곧 의존성: skill_master/field_master → users → client_profile(user FK) → stats/skill(client FK) → projects(user FK) → application/tag/mapping(project FK) → chat. 부모를 먼저 만들어야 자식 FK 가 연결됨.
• 후반부는 시드가 아니라 데이터 보정 작업들(마이그레이션·백필·정리). 전부 try/catch + log.warn 으로 감싸 하나가 실패해도 나머지는 진행.
• ⚠️ Spring AOP self-invocation 함정(주석 명시): DataCleanupService.cleanupAll() 내부에서 cleanupProjects() 를 부르면 프록시를 거치지 않아 REQUIRES_NEW 가 무시됨. 그래서 DataSeeder 가 외부에서 각 cleanup 메서드를 직접 호출 → 진짜 독립 트랜잭션을 보장. (AOP 어노테이션은 "빈 외부 호출"에만 적용되는 한계.)

멱등 + id 매핑 패턴 seedSkillMaster() — DataSeeder.java:258-284

// L258-L284 (요약)
private void seedSkillMaster() throws Exception {
    if (skillMasterRepository.count() > 0) {     // ★ 멱등: 이미 있으면
        // 기존 데이터에 대해 JSON 을 다시 읽어 "원본 id → 실제 PK" 매핑만 복원하고 return
        JsonNode arr = readJson("seed/erd/skill_master.json");
        for (JsonNode n : arr) {
            Long jsonId = n.get("id").asLong();
            String name = n.get("name").asText();
            skillMasterRepository.findByName(name).ifPresent(s -> skillIdMap.put(jsonId, s.getId()));
        }
        return;
    }
    // 비어 있으면 실제 insert + 매핑 채움
    JsonNode arr = readJson("seed/erd/skill_master.json");
    for (JsonNode n : arr) {
        Long jsonId = n.get("id").asLong();
        SkillMaster saved = skillMasterRepository.save(SkillMaster.builder().name(n.get("name").asText()).build());
        skillIdMap.put(jsonId, saved.getId());
    }
}

• 모든 seedXxx 가 공유하는 2단 패턴: ① count() > 0 이면 재삽입 없이 매핑만 복원하고 return(멱등) ② 비어 있으면 삽입하며 매핑 채움.
• 왜 매핑 복원이 필요한가: 같은 기동 사이클에서 뒤따르는 seed(예: client_preferred_skill)가 skillIdMap 을 참조하기 때문. 이미 DB 에 있어도 이번 기동의 메모리 맵은 비어 있으니 다시 채워줘야 FK 연결이 됨.

JSON 읽기 + 안전 추출 헬퍼 — DataSeeder.java:622-664

// L622-L664 (발췌)
private JsonNode readJson(String classpathLocation) throws Exception {
    try (InputStream is = new ClassPathResource(classpathLocation).getInputStream()) {
        return objectMapper.readTree(is);     // classpath:seed/erd/*.json
    }
}
private static String text(JsonNode n, String f)  { JsonNode v=n.get(f); return (v==null||v.isNull())?null:v.asText(); }
private static Integer intOrNull(JsonNode n, String f) { ... }   // 없으면 null
private static Boolean boolOrNull(JsonNode n, String f){ ... }
private static String jsonString(JsonNode n, String f){ JsonNode v=n.get(f); return (v==null||v.isNull())?null:v.toString(); }
private static LocalDate parseDate(String s) { try { return LocalDate.parse(s); } catch(Exception e){ return null; } }

• 시드 JSON 은 classpath:seed/erd/*.json(build.gradle 가 복사). objectMapper.readTree 로 트리 파싱.
• 헬퍼들은 필드가 없거나 null 이어도 안 터지게 방어적으로 추출(null/기본값 반환). 시드 JSON 이 들쭉날쭉해도 견디게 하는 장치.
• EnumMapper.xxx(text(n, "...")) 조합으로 소문자 문자열 → enum 변환(아래 EnumMapper 참고).

💡 초보 포인트: 시더는 "한 번 잘 돌면 끝"이 아니라 매 기동마다 돕니다. 그래서 멱등성과 "이미 있으면 매핑만 복원" 패턴이 핵심. 새 시드 메서드를 추가할 땐 반드시 이 2단 패턴을 따르세요.

---

K. DataCleanupService — "완전한 데이터 50개만" 정리 (seed/DataCleanupService.java)

독립 트랜잭션 + 점수화 정리 cleanupProjects() — DataCleanupService.java:110-156

// L110-L156 (요약)
@Transactional(propagation = Propagation.REQUIRES_NEW)   // ★ 독립 커밋
public int cleanupProjects() {
    List<Project> all = projectRepository.findAll();
    if (all.size() <= KEEP_PROJECTS) { return 0; }       // 멱등: 이미 50 이하면 skip
    // 모든 프로젝트 점수화 → 내림차순 정렬 → 상위 50 유지, 나머지 삭제
    List<Project> ranked = all.stream().map(p -> Map.entry(p, scoreProject(...))).sorted(내림차순)...
    List<Project> toRemove = ranked.stream().skip(KEEP_PROJECTS).toList();
    // FK 의존 데이터 먼저 삭제(escrow→milestone→module→attachment→meeting→tag→skill→application)
    for (...) { ...deleteAll... }
    projectRepository.deleteAll(toRemove);
}

• REQUIRES_NEW → DataSeeder 가 직접 호출할 때 독립 트랜잭션으로 커밋(앞서 본 self-invocation 회피와 짝).
• 멱등 핵심: all.size() <= 50 이면 즉시 return 0. 한 번 50으로 줄면 재기동해도 추가 삭제 없음.
• 점수화 정리: 모든 프로젝트에 scoreProject 점수를 매겨 상위 50개만 남김. FK 자식들을 역순으로 먼저 삭제해야 부모 삭제 시 제약 위반이 안 남.

완전성 점수 scoreProject() — DataCleanupService.java:158-179

// L158-L179 (요약)
private long scoreProject(Project p, List<ProjectModule> mods, long milestoneCount) {
    if (p.getTitle()==null||p.getTitle().isBlank()) return Long.MIN_VALUE;   // 결격 → 최하위
    if (p.getBudgetAmount()==null||p.getBudgetAmount()<=0) return Long.MIN_VALUE;
    if (mods.size() < 7) return Long.MIN_VALUE;          // 7개 모듈 미만 결격
    if (milestoneCount < 1) return Long.MIN_VALUE;
    long score = milestoneCount*100 + mods.size()*50;
    for (ProjectModule m : mods) { score += (data 길이)/50; if ("협의완료".equals(m.getStatus())) score += 30; }
    if (desc 길이>30) score += 50; if (serviceField!=null) score += 20;
    if (status==IN_PROGRESS) score += 200; if (status==COMPLETED) score += 150;
    return score;
}

• 결격 조건(제목·예산·7모듈·마일스톤 중 하나라도 부실) 이면 Long.MIN_VALUE → 정렬 시 맨 뒤 → 우선 삭제 대상.
• 통과한 것끼리는 데이터 풍부도(모듈 데이터 길이·협의완료·설명·진행상태) 로 가점 → "진짜 쓸만한" 프로젝트가 살아남도록.
• cleanupClients()(L181-205)도 같은 철학: scoreClient 로 bio/industry/강점/예산 충실도를 점수화해 상위 50명 유지.

orphan 정리 cleanupOrphans() — DataCleanupService.java:78-103

// L78-L103 (요약)
@Transactional(propagation = Propagation.REQUIRES_NEW)
public int cleanupOrphans() {
    // 부모 projects 가 사라졌는데 남은 자식 행 일괄 삭제 (native SQL)
    em.createNativeQuery("DELETE FROM project_modules    WHERE project_id NOT IN (SELECT id FROM projects)").executeUpdate();
    em.createNativeQuery("DELETE FROM project_milestones WHERE project_id NOT IN (SELECT id FROM projects)").executeUpdate();
    em.createNativeQuery("DELETE FROM project_escrows    WHERE project_id NOT IN (SELECT id FROM projects)").executeUpdate();
}

• 고아(orphan) 행 = 부모가 삭제됐는데 살아남은 자식. native SQL NOT IN (SELECT id FROM projects) 로 일괄 청소. 매 기동 실행해도 안전(없으면 0건 삭제 = 멱등).

---

L. AiModelCatalogSeeder — AI 메뉴판 등록 (seed/AiModelCatalogSeeder.java)

// L22-L57 (요약)
@Component @Order(100)
public class AiModelCatalogSeeder implements CommandLineRunner {
    public void run(String... args) {
        // 정책 변경: 과거 시드된 Perplexity 모델은 제거
        repo.findByEnabledTrueOrderBySortOrderAsc().stream()
            .filter(m -> m.getProvider() == Provider.PERPLEXITY).forEach(repo::delete);
        if (repo.count() > 0) return;     // 멱등
        List<AiModelCatalog> seed = List.of(
            model("gemini-2.5-flash", ..., GEMINI,    200_000L, -1L,      10),   // 무료한도 20만토큰, pro 무제한(-1)
            model("gemini-2.5-pro",   ..., GEMINI,    0L,       500_000L, 20),
            model("claude-sonnet-4",  ..., ANTHROPIC, 0L,       300_000L, 30),
            model("claude-opus-4",    ..., ANTHROPIC, 0L,       100_000L, 40),
            model("gpt-4o-mini",      ..., OPENAI,    100_000L, -1L,      50),
            model("gpt-4o",           ..., OPENAI,    0L,       300_000L, 60));
        repo.saveAll(seed);
    }
}

• @Order(100) → 여러 CommandLineRunner 중 실행 순서 지정(작을수록 먼저; DataSeeder 와 독립적으로 동작).
• prod/local 모두 적용(@Profile 없음) — 모델 카탈로그는 운영에도 필요하니까. (DataSeeder 의 @Profile("!prod") 와 대비.)
• 멱등 패턴은 동일(count() > 0 이면 return). 단, 그 전에 정책 변경분(Perplexity) 정리를 먼저 수행 → "메뉴판 갱신".
• freeQuota/proQuota 의 -1L 은 무제한을 의미하는 센티넬 값. (Gemini flash·GPT-4o mini 의 무료/Pro 한도가 -1.)

---

M. EnumMapper — 번역기 (util/EnumMapper.java)

// L11-L33, L180-L189 (발췌)
public final class EnumMapper {
    private EnumMapper() {}
    public static User.UserType userType(String s) {
        if (s == null) return null;
        return switch (s.toLowerCase()) {
            case "client","user","free" -> User.UserType.FREE;
            case "partner","pro","standard" -> User.UserType.STANDARD;
            case "premium" -> User.UserType.PREMIUM;
            default -> null;
        };
    }
    public static Project.ProjectStatus projectStatus(String s) {
        if (s == null) return Project.ProjectStatus.RECRUITING;     // ← null 기본값 있음
        return switch (s.toLowerCase()) {
            case "recruiting" -> ProjectStatus.RECRUITING;
            case "in_progress" -> ProjectStatus.IN_PROGRESS;
            ...
            default -> ProjectStatus.RECRUITING;                    // ← 모르는 값도 기본값
        };
    }
}

• 역할: ERD v2 의 소문자 JSON enum 문자열 → 백엔드 UPPERCASE enum(정합표: docs/ERD_v2_enum_alignment.md). DataSeeder 가 시드 JSON 을 엔티티로 바꿀 때 사용.
• switch 표현식 화살표(->) 문법(Java 14+): break 불필요, 값을 바로 반환. s.toLowerCase() 로 대소문자 무시.
• 별칭 흡수가 똑똑함: 예) client/user/free 가 모두 FREE 로, partner/pro/standard 가 STANDARD 로. 옛 ERD 용어와 새 등급제를 동시에 수용.
• 두 가지 정책이 메서드마다 다름: ① 일부는 모르면 null(예: userType, gender) ② 일부는 안전한 기본값(예: projectStatus→RECRUITING, clientType→INDIVIDUAL, visibility→PUBLIC). → "이 필드는 비어도 되나/안 되나"에 따른 선택.

---

N. TerminalWebSocketHandler + Config — 로컬 전용 셸 콘센트 (terminal/)

등록 게이트 — TerminalWebSocketConfig.java:15-24

// L15-L24
@Configuration @EnableWebSocket
@ConditionalOnProperty(name = "app.terminal.enabled", havingValue = "true")   // ★ 이 설정 자체가 옵트인
public class TerminalWebSocketConfig implements WebSocketConfigurer {
    public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
        registry.addHandler(new TerminalWebSocketHandler(), "/ws/terminal").setAllowedOriginPatterns("*");
    }
}

• @ConditionalOnProperty(...havingValue="true") → app.terminal.enabled=true 일 때만 이 빈/엔드포인트가 존재. 운영 기본은 OFF → /ws/terminal 자체가 안 생김.

연결 시 loopback 검문 — TerminalWebSocketHandler.java:34-64

// L34-L64 (요약)
public void afterConnectionEstablished(WebSocketSession session) throws Exception {
    if (!isLoopback(session)) {                            // ★ 127.0.0.1 / ::1 만 허용
        session.close(CloseStatus.POLICY_VIOLATION.withReason("local only")); return;
    }
    String shell = shellFor(session);                     // ?shell=powershell|cmd|bash|sql
    ProcessBuilder pb = new ProcessBuilder(shellCmd(shell));
    pb.redirectErrorStream(true);                         // stderr 를 stdout 으로 합침
    pb.directory(new File(System.getProperty("user.dir")));
    Process p = pb.start();
    procs.put(session.getId(), p);
    // 출력 펌프 스레드 + 종료 감시 스레드(둘 다 daemon)
}

• 2중 안전장치: ① 설정 OFF 기본(Config) ② loopback 접속만 허용(핸들러). 외부 IP 면 즉시 POLICY_VIOLATION 으로 끊음 → 웹에서 임의 셸 실행(RCE) 차단.
• 세션마다 셸 프로세스 1개(procs 맵에 보관). redirectErrorStream(true) 로 에러도 같은 스트림에 → 클라이언트 한 화면에 표시.
• ?shell= 쿼리로 powershell/cmd/bash/sql 선택(shellCmd 가 OS별 실행 인자 매핑). 파이프 기반이라 완전한 PTY 가 아님 → vim 같은 풀스크린 TUI 는 제한, lean/git/python 명령엔 충분(클래스 주석).

stdin 중계 / 정리 — TerminalWebSocketHandler.java:66-102

// L66-L102 (요약)
protected void handleTextMessage(WebSocketSession session, TextMessage message) {
    Process p = procs.get(session.getId());
    if (p == null || !p.isAlive()) return;
    p.getOutputStream().write(message.getPayload().getBytes(UTF_8)); flush();   // WS 입력 → 프로세스 stdin
}
public void afterConnectionClosed(WebSocketSession session, CloseStatus status) {
    Process p = procs.remove(session.getId());
    if (p != null) p.destroyForcibly();        // ★ 세션 끊기면 프로세스 강제 종료(좀비 방지)
}
private void pumpOutput(...) { while(read) sendSafe(session, ...); }            // 프로세스 stdout → WS

• 양방향: WS 텍스트 → 프로세스 stdin(handleTextMessage), 프로세스 stdout → WS(pumpOutput 스레드).
• 세션 종료 시 destroyForcibly() 로 셸 프로세스를 반드시 죽임 → 좀비 프로세스 누수 방지. sendSafe 는 synchronized(session) 로 동시 전송 충돌을 막음.

⚠️ 이건 개발 편의 도구입니다. 운영에서 절대 켜지 마세요(설정 OFF 유지). 켜더라도 loopback 검문이 1차 방어선.

---

⚠️ 함정·보안 주의 (코드에 박힌 교훈 모음)

1. M10 — 필터 안에서 AuthContext 쓰면 항상 null (가장 중요)

   • AuthContext.currentUserId() 는 RequestContextHolder 의존인데, 이건 DispatcherServlet 이후에야 채워짐. 서블릿 필터(디스패처 이전) 에선 비어 있어 항상 null.
   • 결과(과거 버그): 모든 사용자가 null 로 묶여 레이트리밋이 전원 무력화.
   • 정답 2종 세트: ① AiRateLimitFilter 는 request.getAttribute(ATTR_USER_ID) 직독 ② 필터 순서(JWT @Order(+10) 가 RateLimit @Order(+20) 보다 먼저 실행돼 attribute 를 미리 채움). 둘 중 하나만 어긋나도 깨짐.

2. Spring Security 프레임워크 자체가 OFF

   • build.gradle 에서 spring-boot-starter-security 는 주석 처리, spring-security-crypto(BCrypt)만 의존. → SecurityFilterChain·자동 인증/인가가 없음.
   • 인증은 전부 수동(JwtAuthenticationFilter+AuthContext). 그래서 "필터가 막지 않고 통과시키고, 컨트롤러가 requireUserId() 로 거부"하는 패턴이 유일한 방어선 → 컨트롤러에서 신원 체크를 빠뜨리면 곧 인가 누락. (최근 커밋 "NotificationController IDOR 차단"이 바로 이 계열 사고.)

3. 필터 순서 의존성은 주석으로만 강제됨

   • @Order(+10)/@Order(+20) 숫자 관계가 깨지면 조용히 오작동. 새 필터 추가 시 이 상대 순서를 반드시 고려. 숫자는 "절대값"이 아니라 "상대 순서"라는 점에 유의.

4. 시더 멱등성 — count()>0 가드는 필수

   • 시더는 매 기동 실행. if (count()>0) return; 빠뜨리면 매번 중복 삽입. 새 seedXxx 추가 시 반드시 ① 멱등 가드 ② "이미 있으면 매핑만 복원" 2단 패턴.
   • DataCleanupService 도 size() <= 50 가드로 멱등(재기동 시 추가 삭제 없음).

5. app.crypto.key 중복/폴백 사고 (메모리 노트와 직결)

   • AesGcmCryptoService 는 app.crypto.key 없으면 app.jwt.secret 으로 폴백 → 둘이 다르거나, .env/application*.properties 에 같은 키가 다른 값으로 중복되면, 복호화 키가 바뀌어 기존 암호문을 못 푸는 사고. 환경변수 우선순위 변경 전 중복 키 감사 필수.

6. AOP self-invocation — REQUIRES_NEW 무시

   • DataCleanupService.cleanupAll() 내부에서 cleanupProjects() 를 부르면 프록시를 안 거쳐 트랜잭션 어노테이션이 무시됨. → DataSeeder 가 외부에서 직접 각 메서드를 호출해 진짜 독립 트랜잭션을 만든 것.

7. JWT 페이로드는 비밀이 아님

   • 서명으로 위조는 막지만 내용은 누구나 디코드 가능(Base64). claims 에 민감정보 넣지 말 것. uid/type 정도만.

8. CORS + 쿠키 조합 주의

   • allowCredentials(true) 면 allowedOrigins("*") 금지(브라우저 거부). 반드시 명시적 출처 목록. 운영에 실제 도메인 넣는 걸 잊으면 프론트가 막힘.

9. 터미널은 운영에서 켜지 말 것

   • app.terminal.enabled 기본 OFF + loopback 검문. 켜는 순간 RCE 위험이 생기므로 로컬 개발에서만.

10. Jackson 2/3 혼재

    • Boot4=Jackson3. 옛 com.fasterxml.jackson.JsonNode 를 컨트롤러가 반환하면 직렬화가 깨짐. Jackson2NodeBridgeConfig 가 외과적으로 메움. 새 코드는 가급적 Jackson3 또는 DTO 사용.

---

🚀 고도화 아이디어 (강의·개선 버전용)

• 레이트리밋 Redis 전환: AiRateLimitFilter 의 인메모리 ConcurrentHashMap 은 다중 인스턴스에서 한도가 안 합쳐짐. Bucket4j + Redis(JCache)로 옮기면 클러스터 전역 한도. 등급별 한도(FREE 20 / PRO 60)도 사용자 type 으로 분기 가능(현재 자리만 있고 미구현).
• 진짜 Spring Security 도입 검토: 수동 필터 방식은 가볍지만 인가(authorization) 를 컨트롤러마다 손으로 체크해야 해 IDOR/누락 위험. @PreAuthorize 같은 선언적 인가로 옮기면 실수 감소. (단, 회귀 비용 큼 — 점진 도입.)
• AES 키 회전(rotation): 현재 단일 키. 암호문에 키 버전 태그를 붙여 두면 키 교체 시 옛 데이터도 점진 재암호화 가능. KMS/Vault 연동으로 키를 코드/환경변수 밖으로.
• 시더를 Flyway/별도 import 로 분리: 마이그레이션·백필 로직(migrateBudgetManToWon·backfillModules…)이 시더에 섞여 비대. 1회성 마이그레이션은 Flyway repeatable/versioned 로, 데모 시드는 시더로 역할 분리하면 가독성·재현성↑.
• CleanupService 정책 외부화: KEEP_PROJECTS=50 등 매직넘버와 점수 가중치를 설정으로 빼면 환경별 튜닝 용이. 점수 함수에 단위 테스트 추가(결격 조건 회귀 방지).
• 터미널을 PTY 로: 현재 파이프라 풀스크린 TUI 제한. pty4j 등으로 진짜 PTY 를 붙이면 vim/htop 까지. (보안 게이트는 더 강화 필요.)
• EnumMapper 역방향 + 테스트: enum→문자열 역변환과, "모든 enum 값이 매핑되는지" 검증 테스트를 추가하면 ERD 정합 깨짐을 컴파일/테스트 단계에서 포착.

---

📚 용어 사전 (이 영역 한정)

용어	뜻
빈(Bean)	Spring 이 만들어 보관·주입하는 재사용 객체 (@Component/@Bean)
DI(의존성 주입)	객체를 직접 new 하지 않고 Spring 이 끼워주는 것 (@RequiredArgsConstructor)
서블릿 필터	컨트롤러 도착 전 모든 요청이 거치는 관문. OncePerRequestFilter = 요청당 1회
@Order	필터/러너 실행 순서. 숫자 작을수록 먼저. HIGHEST_PRECEDENCE + N 으로 상대 순서
request attribute	요청 객체에 붙이는 임시 메모(set/getAttribute). 요청 끝나면 소멸
RequestContextHolder	"현재 스레드의 요청"을 어디서나 꺼내는 전역 보관함. DispatcherServlet 이 채움(필터 단계엔 빔)
JWT	헤더.페이로드.서명 토큰. 서명으로 위조 방지, 내용은 공개(암호화 아님)
HS256	HMAC-SHA256 대칭키 서명. 같은 비밀키로 서명·검증
claims	JWT 페이로드의 주장값(여기선 uid, type, sub)
CORS	브라우저의 교차 출처 호출 통제 규칙. allowCredentials+명시 출처가 쿠키 인증의 짝
프리플라이트	본요청 전 브라우저가 보내는 OPTIONS 사전 확인. maxAge 로 캐시
Bucket4j / 토큰버킷	요청=토큰1소비, 시간경과로 보충하는 레이트리밋 알고리즘
BCrypt	단방향 비밀번호 해시(매번 다른 salt). matches로 검증
AES-GCM	암호화+무결성 태그를 동시 제공하는 양방향 암호. IV 매번 랜덤 12B 필수
IV(초기화 벡터)	같은 평문도 매번 다른 암호문이 되게 하는 랜덤값. 재사용 금지
멱등(idempotent)	여러 번 실행해도 결과가 같음. 시더의 count()>0 → skip 패턴
CommandLineRunner	앱 기동 완료 직후 run() 1회 실행하는 인터페이스(시더에 사용)
@Profile("!prod")	운영이 아닐 때만 빈 활성화(mock 시드 격리)
@PostConstruct	빈 생성 직후 1회 실행되는 초기화 훅
REQUIRES_NEW	호출 시 항상 새 독립 트랜잭션 시작(별도 커밋/롤백)
AOP self-invocation	같은 빈 내부 메서드 호출은 프록시를 안 거쳐 @Transactional이 무시되는 한계
orphan(고아) 행	부모가 삭제됐는데 남은 자식 FK 행
loopback	127.0.0.1 / ::1(자기 자신). 터미널이 이 주소만 허용해 RCE 차단
PTY vs 파이프	PTY=완전한 가상 터미널(풀스크린 TUI 가능), 파이프=단순 입출력 스트림(제한적)

domain/notification — 알림·이메일 도메인 (완전 라인별 해설)

원본 디렉터리: backend/src/main/java/com/DevBridge/devbridge/domain/notification/ (5개 파일)

• controller/NotificationController.java (88줄)
• service/EmailAlertService.java (98줄)
• entity/Notification.java (71줄)
• repository/NotificationRepository.java (23줄)
• dto/NotificationResponse.java (37줄)

이 문서는 교재 표준 형식(README "3. 공통 형식")을 따릅니다. Spring 기본 개념(@RestController·@Service·JPA·Lombok 등)은 08_backend/00_spring_primer.md 를 먼저 읽었다고 가정합니다.

---

📌 이 도메인 한눈에

이 도메인은 사용자에게 소식을 전하는 "알림 우편함 + 이메일 발송실" 두 가지를 담당합니다.

비유	실제	담당
앱 안의 우편함 (종 모양 아이콘에 빨간 배지)	화면에 쌓이는 인앱 알림 — 읽음/안읽음 표시	Notification 엔티티 + NotificationController + NotificationRepository
이메일 발송실	오늘의 매매 신호를 모아 한 통의 이메일로 발송	EmailAlertService

핵심은 이 도메인이 두 개의 거의 독립된 기능이라는 점입니다. 하나는 "DB에 쌓아두고 화면에서 읽는 인앱 알림", 다른 하나는 "이메일로 밀어내는 다이제스트"입니다. 둘은 서로 호출하지 않습니다.

클래스	한 줄 역할	비유
Notification (entity)	DB의 NOTIFICATION 테이블 한 줄 = 알림 하나(제목·내용·읽음여부·연결대상)	우편함에 꽂힌 편지 한 통
NotificationRepository	그 편지들을 사용자별·읽음여부별로 꺼내는 JPA 인터페이스	우편함을 뒤지는 사서
NotificationResponse (dto)	엔티티를 프론트에 줄 안전한 JSON 형태로 바꾼 것	편지를 봉투에 담아 외부로 내보냄
NotificationController	/api/notifications REST 입구. 신원은 JWT에서만 확인(M9 보안)	우편함 창구 직원
EmailAlertService	미발송 시그널을 사용자별로 묶어 비동기 이메일 발송	이메일 발송실

⚠️ 중요한 사실 하나: NotificationController 가 실제 작업을 시키는 서비스는 이 도메인 안에 없습니다. 컨트롤러는 domain/chat 패키지의 StreamChatService 를 호출합니다(자세한 이유는 라인별 해설 참고). 즉 인앱 알림의 "비즈니스 로직"은 chat 도메인에 얹혀 있고, 이 도메인에는 엔티티·레포지토리·DTO·컨트롤러만 있습니다.

누가 호출하나?

• 인앱 알림: 프론트엔드(예정 — 아래 M5 함정 참고)가 /api/notifications 를 호출.
• 이메일: 백엔드 스케줄러(일일 시그널 생성 후 dispatchPending(오늘날짜) 호출)가 트리거.

---

🧠 사전 지식 (이거 모르면 막힘)

1) "알림 엔티티" = DB 테이블의 한 줄을 자바 객체로

Notification 객체 1개 = NOTIFICATION 테이블의 1행입니다. JPA(Hibernate)가 자바 객체 ↔ DB 행을 자동 변환해 줍니다. 예:

id │ user_id │ notification_type │ title          │ is_read │ created_at
 1 │   42    │ NEW_MESSAGE       │ 새 메시지 도착   │ false   │ 2026-06-01 09:00

이 한 줄이 자바에서는 Notification 객체가 되고, 프론트로 나갈 땐 NotificationResponse(JSON)가 됩니다.

2) "읽음 상태(is_read)" = 안 읽음/읽음 토글

• 새 알림은 is_read = false(안 읽음)로 태어납니다. 종 아이콘 옆 빨간 숫자 배지가 곧 "안 읽음 개수"입니다.
• 사용자가 알림을 보면 is_read = true 로 바뀝니다. 한 건씩(/{id}/read) 또는 전체(/read-all) 처리 가능.
• "안 읽음 개수"를 빠르게 세려고 countByUserAndIsReadFalse 같은 전용 쿼리를 둡니다(전부 가져와 세지 않음 → 가볍고 빠름).

3) Gmail SMTP = 자바가 메일 서버를 통해 메일을 쏘는 길

• JavaMailSender 는 Spring이 주는 "메일 발송기"입니다. 뒤에서 Gmail의 SMTP 서버에 접속해 메일을 보냅니다.
• 접속에 필요한 계정·비밀번호는 설정값(spring.mail.username, spring.mail.password)에서 옵니다. Gmail은 일반 비밀번호가 아니라 "앱 비밀번호" 를 써야 합니다(CLAUDE.md의 MAIL_PASSWORD).
• SimpleMailMessage = 가장 단순한 형태의 메일(받는사람·제목·평문 본문). HTML이 아니라 줄바꿈만 있는 텍스트입니다.

4) 비동기(@Async) 발송 = "보내고 기다리지 않기"

• 이메일 발송은 외부 서버(Gmail)와 통신하므로 느릴 수 있습니다(수백 ms~수 초).
• @Async 를 붙이면 이 메서드는 별도 스레드에서 돌고, 호출한 쪽(예: 시그널 스케줄러)은 바로 다음 일을 합니다. → 스케줄러가 메일 발송을 기다리며 멈추지(block) 않습니다.
• 비유: 편지를 우체통에 넣고 곧장 가던 길을 갑니다. 우체부가 배달을 끝낼 때까지 우체통 앞에서 서 있지 않습니다.

5) IDOR(Insecure Direct Object Reference) — M9가 막은 그것

• "내 알림"을 가져오는 API가 ?userId=42 처럼 요청 파라미터로 받은 ID를 그대로 믿으면, 공격자가 ?userId=43 으로 바꿔 남의 알림을 훔쳐볼 수 있습니다. 이것이 IDOR.
• 해결: 신원을 절대 요청에서 받지 않고, 위조 불가능한 JWT(로그인 토큰)에서만 꺼냅니다. 이 도메인의 M9 보안 수정이 정확히 이것입니다.

---

🗺 요청 흐름도

(A) 인앱 알림 조회·읽음 — REST 흐름

프론트엔드(브라우저)
   │  GET /api/notifications   (JWT 쿠키 자동 첨부)
   ▼
JwtAuthenticationFilter  ─── 쿠키의 JWT 검증 → 요청에 user_id 속성 부착
   │
   ▼
NotificationController.getAll()
   │  ① currentUser() → AuthContext.currentUserId()  ← JWT에서만 신원 취득 (M9)
   │       │ uid 없으면 401 Unauthorized
   │       ▼
   │  ② userRepository.findById(uid) → User
   │       ▼
   │  ③ streamChatService.getNotificationsForUser(user)   ← chat 도메인 서비스
   │       │
   │       ▼
   │     NotificationRepository.findByUserOrderByCreatedAtDesc(user)
   │       │  (DB: 내 알림만, 최신순)
   │       ▼
   │     List<Notification>
   │       ▼
   │  ④ .map(NotificationResponse::from)   ← 엔티티 → 안전한 JSON DTO
   ▼
ResponseEntity.ok(List<NotificationResponse>)  → 프론트 JSON

(B) 이메일 다이제스트 — 스케줄러 흐름

일일 시그널 스케줄러 (장 마감 후)
   │  EmailAlertService.dispatchPending(오늘날짜)
   ▼
DailySignalRepository.findByAsOfDateAndDeliveredAtIsNull(오늘)   ← 아직 안 보낸 시그널
   │
   ▼
사용자별 그룹핑  (groupingBy: s.getStrategy().getUser())
   │   user42 → [signalA, signalB]
   │   user43 → [signalC]
   ▼
각 사용자마다  sendDigest(user, signals)   @Async (별도 스레드)
   │  ① 이메일 주소·발신주소 없으면 skip
   │  ② 제목·본문 조립 (buildBody)
   │  ③ JavaMailSender.send(SimpleMailMessage)  → Gmail SMTP
   │  ④ 성공 시 각 signal.deliveredAt = now → saveAll  (중복발송 방지)
   ▼
   (실패해도 catch로 삼켜 로그만 — 스케줄러는 계속 진행)

두 흐름이 만나지 않는다는 점을 다시 강조합니다. (A)는 Notification 테이블을 읽고, (B)는 DAILY_SIGNAL 테이블을 읽어 메일을 쏩니다. 이메일 발송은 인앱 Notification 행을 만들지 않습니다.

---

📖 라인별 해설

1) entity/Notification.java — 알림 한 통의 설계도

먼저 엔티티부터 봅니다. 모든 알림 데이터의 "모양"이 여기서 정의되기 때문입니다.

클래스 선언과 어노테이션 — Notification.java:11-23

// L11-L23
/**
 * In-app system notifications.
 * Covers both chat events (NEW_MESSAGE) and non-chat events (milestones, contracts, etc.).
 */
@Entity
@Table(name = "NOTIFICATION")
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@Builder
@EntityListeners(AuditingEntityListener.class)
public class Notification {

• 무엇을 하나: 이 클래스를 DB 테이블 NOTIFICATION 과 연결합니다.
• @Entity + @Table(name="NOTIFICATION") — "이 자바 클래스 1개 = DB 테이블 1개, 객체 1개 = 행 1개".
• @Getter/@Setter (Lombok) — 필드마다 getId()/setId() 같은 메서드를 컴파일 때 자동 생성. 코드에는 안 보이지만 존재합니다.
• @NoArgsConstructor(빈 생성자) + @AllArgsConstructor(모든 필드 생성자) + @Builder(빌더 패턴) — 객체를 여러 방식으로 만들 수 있게. JPA는 빈 생성자를 필수로 요구합니다.
• @EntityListeners(AuditingEntityListener.class) — 아래 @CreatedDate 가 작동하도록 "감시자"를 붙임. 저장 시 생성시각을 자동 기록.
• 초보 헷갈림 포인트: 클래스명은 Notification, 테이블명은 대문자 NOTIFICATION. 둘이 달라도 @Table(name=...) 이 다리를 놓아줍니다. 주석의 "chat 이벤트와 비-chat 이벤트(마일스톤·계약 등)를 모두 다룬다"는 설명은 이 엔티티가 원래 더 큰 협업/계약 시스템에서 가져온 흔적입니다(아래 enum 참고).

기본키(PK) — Notification.java:25-27

// L25-L27
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;

• @Id — 이 필드가 기본키(각 행의 고유 번호).
• @GeneratedValue(strategy = IDENTITY) — 번호를 DB가 auto_increment 로 자동 부여. 새 알림을 저장하면 DB가 1, 2, 3… 을 매깁니다. 우리가 직접 id를 정하지 않습니다.

알림 주인(사용자) — Notification.java:29-31

// L29-L31
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "user_id", nullable = false)
private User user;

• @ManyToOne — 여러(Many) 알림이 한(One) 사용자에 속함. 한 명이 알림을 여러 개 가질 수 있으니까요.
• @JoinColumn(name="user_id", nullable=false) — DB에는 user_id 라는 외래키 컬럼으로 저장. nullable=false = 주인 없는 알림은 금지.
• fetch = FetchType.LAZY — "필요할 때만" User를 DB에서 가져옴(지연 로딩). 알림 목록만 볼 땐 User 정보를 굳이 안 읽어 성능에 유리. (반대 EAGER는 항상 같이 읽음.)
• 왜 중요한가: 이 user 필드가 곧 "이 알림은 누구 것인가"의 근거입니다. M9 IDOR 방어, 소유권 재확인(아래 markNotificationRead)이 모두 이 필드를 비교합니다.

알림 종류(enum) — Notification.java:33-35 + 57-70

// L33-L35
@Enumerated(EnumType.STRING)
@Column(name = "notification_type", nullable = false, length = 50)
private NotificationType notificationType;

// L57-L70
public enum NotificationType {
    NEW_MESSAGE,
    APPLICATION_ACCEPTED,
    APPLICATION_REJECTED,
    MILESTONE_SUBMITTED,
    MILESTONE_APPROVED,
    MILESTONE_REVISION_REQUESTED,
    CONTRACT_ITEM_PROPOSED,
    CONTRACT_ITEM_AGREED,
    PROJECT_COMPLETED,
    REVIEW_RECEIVED,
    DEPOSIT_RECEIVED,
    PROJECT_UPDATED
}

• @Enumerated(EnumType.STRING) — enum을 DB에 문자열로 저장("NEW_MESSAGE"). EnumType.ORDINAL(0,1,2 숫자)을 쓰면 enum 순서를 바꿀 때 기존 데이터가 어긋나므로, STRING 이 안전한 관습입니다.
• @Column(... length=50) — 컬럼 길이 50자 제한.
• 솔직한 관찰(환각 아님, 실제 코드 기반): enum 값 12개 대부분(MILESTONE_*, CONTRACT_*, PROJECT_*, DEPOSIT_RECEIVED 등)은 퀀트 투자가 아니라 프리랜서/협업 프로젝트 도메인 용어입니다. 이는 이 코드베이스가 다른 프로젝트(DevBridge — 협업/계약 플랫폼)에서 유래해, 알림 엔티티를 그대로 가져온 흔적입니다. 현재 Alpha-Helix에서 실제로 만들어지는 알림이 이 중 어떤 값을 쓰는지는 이 도메인 코드만으로는 알 수 없습니다(생성 측 코드는 다른 도메인). 학습 시 "이 enum은 범용 알림 카탈로그이며, 투자 도메인이 전부 사용하는 건 아니다"로 이해하세요.

제목·본문 — Notification.java:37-41

// L37-L41
@Column(nullable = false, length = 200)
private String title;

@Column(nullable = false, columnDefinition = "TEXT")
private String message;

• title — 알림 제목. length=200 → DB의 VARCHAR(200). 비어 있을 수 없음(nullable=false).
• message — 알림 본문. columnDefinition="TEXT" → 길이 제한이 큰 TEXT 타입(긴 문장 가능). VARCHAR 가 아니라 TEXT 를 쓴 이유는 본문이 길 수 있어서입니다.

연결 대상(클릭하면 어디로?) — Notification.java:43-47

// L43-L47
@Column(name = "related_entity_type", length = 50)
private String relatedEntityType;

@Column(name = "related_entity_id")
private Long relatedEntityId;

• 이 두 필드는 "이 알림이 가리키는 대상" 을 느슨하게 가리킵니다. 예: relatedEntityType="STRATEGY", relatedEntityId=7 → "전략 7번에 관한 알림".
• nullable 표기가 없어 null 허용(둘 다 선택사항). 단순 시스템 공지처럼 연결 대상이 없을 수도 있으니까요.
• 왜 FK가 아니라 type+id 두 컬럼인가: 알림이 전략·계약·프로젝트 등 여러 종류의 대상을 가리킬 수 있어, 특정 테이블 하나에 외래키를 걸 수 없습니다. 그래서 "타입 문자열 + id" 조합으로 다형적(polymorphic) 참조를 흉내냅니다. (DB 무결성 보장은 약해지지만 유연합니다.)

읽음 여부 — Notification.java:49-51

// L49-L51
@Column(name = "is_read", nullable = false)
@Builder.Default
private boolean isRead = false;

• isRead — 읽음(true)/안읽음(false). 새 알림은 false.
• @Builder.Default — 빌더로 만들 때도 기본값 false 가 적용되게 함. 이게 없으면 @Builder 가 boolean 기본값 false(자바 원시값 기본)로만 채워 헷갈릴 수 있어, 명시적 초기화의 의도를 보존하려는 표시입니다.
• 초보 헷갈림: 필드명은 isRead 인데 Lombok이 만드는 getter는 boolean 관습상 isRead()(앞의 is를 중복하지 않음)입니다. DTO 변환부에서 n.isRead() 로 호출되는 이유입니다.

생성 시각(자동 기록) — Notification.java:53-55

// L53-L55
@CreatedDate
@Column(name = "created_at", nullable = false, updatable = false)
private LocalDateTime createdAt;

• @CreatedDate — 행이 처음 저장될 때 현재 시각을 자동 기입(위 AuditingEntityListener 덕분). 우리가 직접 안 넣어도 됩니다.
• updatable = false — 한 번 기록되면 수정 불가(생성 시각은 바뀌면 안 되니까).
• 이 컬럼이 "최신순 정렬"(OrderByCreatedAtDesc)의 기준이 됩니다.

---

2) repository/NotificationRepository.java — 알림을 꺼내는 사서

// L12-L23
public interface NotificationRepository extends JpaRepository<Notification, Long> {

    List<Notification> findByUserOrderByCreatedAtDesc(User user);

    List<Notification> findByUserAndIsReadFalseOrderByCreatedAtDesc(User user);

    long countByUserAndIsReadFalse(User user);

    @Modifying
    @Query("UPDATE Notification n SET n.isRead = true WHERE n.user = :user AND n.isRead = false")
    void markAllReadByUser(@Param("user") User user);
}

• extends JpaRepository<Notification, Long> — 이것만 상속하면 save/findById/findAll/delete 등 기본 CRUD가 공짜로 생깁니다. 구현 클래스를 우리가 안 짭니다(Spring Data JPA가 런타임에 자동 생성).
• 쿼리 메서드(메서드 이름 = 쿼리): Spring Data JPA는 메서드 이름을 분석해 SQL을 자동으로 만듭니다.
  • findByUserOrderByCreatedAtDesc(user) → "이 user의 알림을 created_at 내림차순(최신 먼저)으로 전부" = /api/notifications 가 쓰는 쿼리.
  • findByUserAndIsReadFalseOrderByCreatedAtDesc(user) → "이 user의 안 읽은 알림만, 최신순" = /unread 가 쓰는 쿼리.
  • countByUserAndIsReadFalse(user) → "이 user의 안 읽은 알림 개수"(목록을 안 가져오고 숫자만) = /count(배지)가 쓰는 쿼리. 목록 전체를 받아 세는 것보다 훨씬 가볍습니다.
• 벌크 업데이트 markAllReadByUser:
  • @Query("UPDATE ...") — JPQL(엔티티 기준 쿼리)로 "이 user의 안 읽은 알림 전부를 isRead=true 로" 한 방에 갱신.
  • @Modifying — 이게 읽기(SELECT)가 아니라 변경(UPDATE) 임을 JPA에 알림. 없으면 실행 시 에러.
  • 왜 직접 쿼리인가: 알림이 100개여도 객체 100개를 메모리로 불러 하나씩 setRead(true) 하면 느립니다. UPDATE 한 문장이 한 번의 DB 왕복으로 끝나 효율적.
  • 초보 주의: @Modifying 벌크 쿼리는 영속성 컨텍스트(1차 캐시)를 우회합니다. 같은 트랜잭션에서 이미 로딩한 엔티티가 있으면 캐시와 DB가 불일치할 수 있습니다(이 코드 흐름에선 직후 응답을 끝내므로 문제 없음).

---

3) dto/NotificationResponse.java — 프론트로 내보낼 안전한 봉투

// L11-L23
@Getter
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class NotificationResponse {
    private Long id;
    private String notificationType;
    private String title;
    private String message;
    private String relatedEntityType;
    private Long relatedEntityId;
    private boolean isRead;
    private LocalDateTime createdAt;

• 왜 엔티티를 그대로 안 주고 DTO를 따로 두나 (DTO 패턴의 핵심 이유):
  1. 보안/캡슐화: 엔티티 Notification 에는 user(User 객체 전체)가 들어 있습니다. 이를 그대로 JSON 직렬화하면 사용자 비밀번호 해시·이메일 등 민감정보가 새어나갈 위험이 있습니다. DTO는 user를 통째로 빼고, 외부에 줘도 되는 필드만 골라 담습니다.
  2. 지연로딩 함정 회피: 엔티티의 LAZY 필드를 직렬화 시점에 건드리면 LazyInitializationException 이 날 수 있는데, DTO로 미리 평탄화하면 안전합니다.
  3. 타입 변환: enum NotificationType 을 String(notificationType)으로 바꿔 프론트가 다루기 쉽게.
• 필드 구성이 엔티티와 닮았지만 user 가 없다는 게 핵심 차이입니다.

엔티티 → DTO 변환 — NotificationResponse.java:25-36

// L25-L36
public static NotificationResponse from(Notification n) {
    return NotificationResponse.builder()
            .id(n.getId())
            .notificationType(n.getNotificationType().name())
            .title(n.getTitle())
            .message(n.getMessage())
            .relatedEntityType(n.getRelatedEntityType())
            .relatedEntityId(n.getRelatedEntityId())
            .isRead(n.isRead())
            .createdAt(n.getCreatedAt())
            .build();
}

• static ... from(Notification n) — 정적 팩토리 메서드. "엔티티를 넣으면 DTO를 만들어주는 변환기". 컨트롤러에서 NotificationResponse::from(메서드 참조)으로 깔끔히 호출됩니다.
• .notificationType(n.getNotificationType().name()) — enum을 .name() 으로 문자열화(NEW_MESSAGE → "NEW_MESSAGE").
• .isRead(n.isRead()) — boolean getter는 isRead()(앞서 설명한 Lombok 관습).
• 빠진 것에 주목: user 를 복사하지 않습니다. 그래서 응답 JSON에 사용자 민감정보가 절대 포함되지 않습니다.

---

4) controller/NotificationController.java — 창구 + M9 IDOR 방어

클래스 주석 = M9 보안의 핵심 — NotificationController.java:16-26

// L16-L26
/**
 * Notification endpoints.
 *
 * <p>M9 보안 수정: 이전에는 {@code ?userId=} 요청 파라미터를 그대로 신뢰해 인증된 누구나 타인의 알림을
 * 조회/읽음처리할 수 있는 IDOR 가 있었다. 이제 신원은 항상 JWT(AuthContext)에서만 가져오고,
 * 요청 파라미터로 받지 않는다. CORS 는 WebConfig 가 전역 처리.
 */
@RestController
@RequestMapping("/api/notifications")
@RequiredArgsConstructor
public class NotificationController {

• M9가 무엇을 고쳤나: 과거 코드는 GET /api/notifications?userId=42 처럼 URL의 userId 를 그대로 믿었습니다. 로그인만 했으면 누구나 ?userId=43 으로 바꿔 남의 알림을 조회/읽음처리할 수 있었습니다(전형적 IDOR).
• 고친 방식: 모든 엔드포인트에서 userId 파라미터를 완전히 제거하고, 신원은 오직 AuthContext.currentUserId()(= 위조 불가능한 JWT)에서만 가져옵니다. 클라이언트가 보낸 값은 신원으로 절대 쓰지 않습니다.
• @RestController — 반환값을 JSON 본문으로(뷰 렌더링 X).
• @RequestMapping("/api/notifications") — 이 컨트롤러의 모든 경로 앞에 붙는 공통 접두사.
• @RequiredArgsConstructor(Lombok) — final 필드를 받는 생성자 자동 생성 → 아래 두 의존성을 생성자 주입.

의존성 — NotificationController.java:28-29

// L28-L29
private final StreamChatService streamChatService;
private final UserRepository userRepository;

• 여기가 도메인 구조의 핵심 단서: 이 컨트롤러는 notification 도메인 안의 서비스가 아니라, domain/chat 의 StreamChatService 에 일을 위임합니다(import com.DevBridge.devbridge.domain.chat.service.StreamChatService).
• 왜? 인앱 알림은 원래 "새 채팅 메시지 도착(NEW_MESSAGE)" 같은 chat 이벤트와 함께 생성/관리되었습니다. 그래서 알림 CRUD 로직이 채팅 서비스에 함께 들어 있습니다(StreamChatService.getNotificationsForUser 등). 이 도메인은 데이터 모델(엔티티·레포·DTO)과 REST 입구(컨트롤러)만 소유하고, 로직은 chat 도메인에 얹혀 있는 구조입니다.
• userRepository 는 JWT에서 얻은 user_id로 실제 User 객체를 조회하는 데 씁니다.

GET 전체 목록 — NotificationController.java:31-39

// L31-L39
/** GET /api/notifications — 인증 사용자 본인 알림 전체, 최신순. */
@GetMapping
public ResponseEntity<?> getAll() {
    User user = currentUser();
    if (user == null) return unauthorized();
    List<NotificationResponse> list = streamChatService.getNotificationsForUser(user)
            .stream().map(NotificationResponse::from).toList();
    return ResponseEntity.ok(list);
}

• 흐름: ① currentUser() 로 JWT 사용자 확보 → ② 없으면 401 → ③ streamChatService.getNotificationsForUser(user) 가 repo.findByUserOrderByCreatedAtDesc(user) 를 돌려 본인 알림만 조회 → ④ .map(NotificationResponse::from) 으로 엔티티를 DTO로 변환 → ⑤ 200 OK.
• IDOR이 불가능한 이유: 쿼리의 user 가 JWT에서 온 본인 객체이므로, 구조적으로 남의 알림이 끼어들 수 없습니다. URL을 어떻게 조작해도 신원에 영향을 못 줍니다.
• ResponseEntity<?> 의 ? — 정상이면 List<NotificationResponse>, 비정상이면 에러 Map 을 반환하므로 타입을 와일드카드로 둔 것.

GET 안 읽음 목록 — NotificationController.java:41-49

// L41-L49
/** GET /api/notifications/unread — 본인 미읽음 알림만. */
@GetMapping("/unread")
public ResponseEntity<?> getUnread() {
    User user = currentUser();
    if (user == null) return unauthorized();
    List<NotificationResponse> list = streamChatService.getUnreadNotificationsForUser(user)
            .stream().map(NotificationResponse::from).toList();
    return ResponseEntity.ok(list);
}

• getAll() 과 판박이지만 getUnreadNotificationsForUser 를 호출 → findByUserAndIsReadFalseOrderByCreatedAtDesc. 안 읽은 것만 돌려줍니다.

GET 안 읽음 개수(배지) — NotificationController.java:51-58

// L51-L58
/** GET /api/notifications/count — 본인 미읽음 개수(배지용). */
@GetMapping("/count")
public ResponseEntity<?> getUnreadCount() {
    User user = currentUser();
    if (user == null) return unauthorized();
    long count = streamChatService.countUnreadNotifications(user);
    return ResponseEntity.ok(Map.of("unreadCount", count));
}

• 목록이 아니라 숫자 하나(countByUserAndIsReadFalse)만 반환 → 종 아이콘 배지에 표시.
• Map.of("unreadCount", count) → JSON {"unreadCount": 3}. 미래 확장(다른 카운트 추가)을 위해 단일 숫자가 아니라 객체로 감쌌습니다.

PATCH 한 건 읽음 — NotificationController.java:60-67

// L60-L67
/** PATCH /api/notifications/{notificationId}/read — 본인 알림만 읽음 처리(서비스가 소유권 재확인). */
@PatchMapping("/{notificationId}/read")
public ResponseEntity<?> markOneRead(@PathVariable Long notificationId) {
    User user = currentUser();
    if (user == null) return unauthorized();
    streamChatService.markNotificationRead(notificationId, user);
    return ResponseEntity.noContent().build();
}

• @PatchMapping("/{notificationId}/read") — PATCH(부분 수정) 의미상 알맞은 메서드. @PathVariable Long notificationId 로 URL의 {notificationId} 를 받음.
• 이중 방어(매우 중요): 여기서 notificationId 는 URL에서 옵니다. 공격자가 남의 알림 id를 넣을 수 있습니다. 그래서 streamChatService.markNotificationRead(notificationId, user) 안에서 소유권을 다시 확인합니다(아래 코드).

  // StreamChatService.markNotificationRead (참조: chat 도메인)
  notificationRepository.findById(notificationId).ifPresent(n -> {
      if (n.getUser().getId().equals(user.getId())) {  // ← 본인 알림인지 재확인
          n.setRead(true);
          notificationRepository.save(n);
      }
  });

  • 즉 신원은 JWT에서(컨트롤러), 대상 소유권은 서비스에서 한 번 더 검증하는 2단 방어입니다. id가 남의 것이면 조용히 무시(아무 변경 없음).
• ResponseEntity.noContent().build() → 204 No Content(성공했지만 돌려줄 본문 없음). 읽음 처리 성공 신호로 적절.
• 초보 주의: 남의 id를 넣어도 204가 나올 수 있습니다(소유권 불일치 시 조용히 무시). "204=내 알림이 읽힘"이 아니라 "요청을 정상 접수, 권한 있는 것만 반영"으로 이해해야 합니다. 존재 여부를 응답으로 구분하지 않는 것도 정보 노출을 줄이는 방어입니다.

PATCH 전체 읽음 — NotificationController.java:69-76

// L69-L76
/** PATCH /api/notifications/read-all — 본인 알림 전체 읽음 처리. */
@PatchMapping("/read-all")
public ResponseEntity<?> markAllRead() {
    User user = currentUser();
    if (user == null) return unauthorized();
    streamChatService.markAllNotificationsRead(user);
    return ResponseEntity.noContent().build();
}

• markAllNotificationsRead(user) → 레포의 벌크 UPDATE(markAllReadByUser)로 본인 알림 전부를 한 번에 읽음 처리. user가 JWT 본인이라 남의 알림은 손대지 못합니다.

신원 헬퍼 = M9의 심장 — NotificationController.java:78-87

// L78-L87
/** JWT(AuthContext) 의 사용자 — 미인증/미존재면 null. 요청 파라미터 신원은 신뢰하지 않는다. */
private User currentUser() {
    Long uid = AuthContext.currentUserId();
    if (uid == null) return null;
    return userRepository.findById(uid).orElse(null);
}

private static ResponseEntity<?> unauthorized() {
    return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body(Map.of("error", "인증 필요"));
}

• AuthContext.currentUserId() — 현재 요청의 JWT에서 user_id를 꺼냅니다. (AuthContext 는 JwtAuthenticationFilter 가 검증 후 요청 속성에 심어둔 user_id를 ThreadLocal/요청에서 읽는 경량 헬퍼.) 클라이언트가 보낸 어떤 파라미터도 여기 끼어들 수 없습니다 — 이것이 IDOR 방어의 본질.
• uid == null → 미인증(또는 토큰 없음) → null 반환 → 각 엔드포인트가 401.
• findById(uid).orElse(null) — 토큰의 user_id에 해당하는 실제 User가 DB에 없으면(삭제됨 등) null → 역시 401.
• unauthorized() → 401 + {"error":"인증 필요"}.
• 모든 엔드포인트가 동일한 첫 두 줄(currentUser() → null이면 unauthorized())로 시작한다는 점이 일관된 보안 게이트입니다.

---

5) service/EmailAlertService.java — 이메일 다이제스트 발송실

이 클래스는 위 인앱 알림과 별개로, 오늘의 매매 시그널을 이메일로 모아 보냅니다.

클래스 선언과 의존성 — EmailAlertService.java:19-32

// L19-L32
/**
 * 사용자별로 미발송 시그널들을 묶어서 한 통의 이메일로 보냄.
 * 비동기로 처리해서 스케줄러를 막지 않음.
 */
@Service
@RequiredArgsConstructor
@Slf4j
public class EmailAlertService {

    private final JavaMailSender mailSender;
    private final DailySignalRepository signalRepo;

    @Value("${spring.mail.username:}")
    private String fromAddress;

• @Service — 비즈니스 로직 컴포넌트.
• @Slf4j(Lombok) — log 변수를 자동 생성(로깅용).
• JavaMailSender mailSender — Spring이 주입하는 메일 발송기(SMTP 설정은 application*.properties 의 spring.mail.*).
• DailySignalRepository signalRepo — DAILY_SIGNAL 테이블 접근. 인앱 Notification 이 아니라 시그널 테이블을 읽는다는 점에 주목.
• @Value("${spring.mail.username:}") — 설정값 spring.mail.username 을 fromAddress 에 주입. 콜론 뒤가 비어 있음(:}) = 설정이 없으면 빈 문자열이 기본값. (없을 때 앱이 죽지 않고, 아래에서 "발신주소 없음 → skip"으로 안전 처리하려는 의도.)

다이제스트 발송 — EmailAlertService.java:34-67

// L34-L46
@Async
@Transactional
public void sendDigest(User user, List<DailySignal> signals) {
    if (user == null || signals == null || signals.isEmpty()) return;
    String to = user.getEmail();
    if (to == null || to.isBlank()) {
        log.warn("[Email] user {} has no email — skip", user.getId());
        return;
    }
    if (fromAddress == null || fromAddress.isBlank()) {
        log.warn("[Email] spring.mail.username not set — skip send for {}", to);
        return;
    }

• @Async — 별도 스레드에서 실행(사전지식 4번). 호출한 스케줄러는 즉시 다음 사용자로 넘어갑니다.
• @Transactional — 이 메서드 안의 DB 작업(아래 saveAll)을 하나의 트랜잭션으로 묶음. (단, @Async 와 함께 쓰면 트랜잭션이 새 스레드에서 시작됨에 유의.)
• 가드(방어) 3종:
  1. user/signals 가 비면 조용히 종료(보낼 게 없음).
  2. 받는 사람 이메일이 없으면 경고 로그 + skip(메일 보낼 곳이 없음).
  3. 발신 주소(fromAddress)가 비어 있으면 skip — SMTP 미설정 환경(로컬 등)에서 메일을 시도조차 안 해 에러를 피함. CLAUDE.md "ANALYTICS 미설정 시 폴백"과 같은 "설정 없으면 우아하게 건너뛰기" 철학.

// L48-L67
    String subject = "[Alpha-Helix] " + signals.get(0).getAsOfDate() + " 오늘의 매매 신호 ("
            + signals.size() + "건)";
    String body = buildBody(user, signals);

    try {
        SimpleMailMessage msg = new SimpleMailMessage();
        msg.setFrom(fromAddress);
        msg.setTo(to);
        msg.setSubject(subject);
        msg.setText(body);
        mailSender.send(msg);

        LocalDateTime now = LocalDateTime.now();
        signals.forEach(s -> s.setDeliveredAt(now));
        signalRepo.saveAll(signals);
        log.info("[Email] sent digest to {} ({} signals)", to, signals.size());
    } catch (Exception e) {
        log.error("[Email] send failed to {}: {}", to, e.getMessage());
    }
}

• 제목: [Alpha-Helix] 2026-06-01 오늘의 매매 신호 (3건) 처럼 날짜·건수를 담음. signals.get(0).getAsOfDate() = 첫 시그널의 기준일(같은 배치라 모두 같은 날).
• 본문: buildBody(...) 로 조립(아래).
• 발송: SimpleMailMessage 에 발신/수신/제목/본문을 채워 mailSender.send(msg). setText(body) 이므로 평문(HTML 아님).
• 발송 성공 후 핵심 — 중복 발송 방지:
  • signals.forEach(s -> s.setDeliveredAt(now)) + signalRepo.saveAll(signals) 로 각 시그널의 deliveredAt 에 발송 시각을 도장 찍음.
  • 다음 번에 dispatchPending 이 "아직 deliveredAt 이 null인 것"만 찾으므로, 이미 보낸 시그널은 다시 안 보냅니다(멱등성). 이메일을 "두 번 보내는" 사고를 막는 장치.
• 에러 처리: try/catch 로 메일 실패를 삼키고 error 로그만 남깁니다. 왜? 한 사용자에게 메일이 실패해도(주소 오류·SMTP 일시장애 등) 다른 사용자 발송이나 스케줄러 전체가 멈추면 안 되기 때문. 단, catch 되면 deliveredAt 도 안 찍히므로 다음 배치에서 재시도됩니다(자연스러운 재시도 효과).

본문 조립 — EmailAlertService.java:69-87

// L69-L87
private String buildBody(User user, List<DailySignal> signals) {
    StringBuilder sb = new StringBuilder();
    sb.append("안녕하세요 ").append(user.getUsername()).append("님,\n\n");
    sb.append("오늘의 Alpha-Helix 매매 시그널입니다.\n");
    sb.append("─────────────────────────────────────\n\n");
    for (var s : signals) {
        sb.append("[").append(s.getSignal()).append("] ").append(s.getStrategy().getCode())
                .append(" — ").append(s.getStrategy().getTicker()).append("\n");
        sb.append("· 제목: ").append(safe(s.getTitle())).append("\n");
        sb.append("· 분석: ").append(safe(s.getSummary())).append("\n");
        sb.append("· 액션: ").append(safe(s.getAction())).append("\n\n");
    }
    sb.append("─────────────────────────────────────\n");
    sb.append("※ 본 메일은 자동 발송된 분석 정보이며 투자 권유가 아닙니다.\n");
    sb.append("Alpha-Helix · DevBridge\n");
    return sb.toString();
}

private String safe(String v) { return v == null ? "" : v; }

• StringBuilder 로 평문 메일을 조립. \n 줄바꿈으로 단락을 나눕니다(HTML 태그 없음).
• 각 시그널 한 블록: [BUY] 전략코드 — 티커 헤더 + 제목/분석/액션 3줄. (s.getSignal() 은 BUY/HOLD/WATCH/PAUSE enum, s.getStrategy().getCode()/getTicker() 는 전략 메타.)
• 끝에 면책 문구(투자 권유가 아닙니다) — 금융 정보 발송 시 법적 안전장치이자 좋은 관행.
• safe(v) — null이면 빈 문자열로. 왜? 만약 · 분석: null 처럼 문자 그대로 "null"이 메일에 찍히면 보기 흉합니다. null 필드를 깔끔히 비웁니다.
• 초보 주의(잠재 NPE): user.getUsername(), s.getStrategy().getCode() 등은 null 방어가 없습니다. 만약 전략이 LAZY인데 트랜잭션 밖이라면 로딩 문제가 날 수 있으나, 이 메서드는 @Transactional sendDigest 안에서 호출되므로 보통 안전합니다.

미발송 일괄 발송 진입점 — EmailAlertService.java:89-97

// L89-L97
/** 미발송 시그널을 user별로 묶어서 일괄 발송. */
@Transactional
public int dispatchPending(java.time.LocalDate asOfDate) {
    var pending = signalRepo.findByAsOfDateAndDeliveredAtIsNull(asOfDate);
    if (pending.isEmpty()) return 0;
    var byUser = pending.stream().collect(Collectors.groupingBy(s -> s.getStrategy().getUser()));
    byUser.forEach(this::sendDigest);
    return pending.size();
}

• 이 메서드가 이메일 흐름의 시작점(스케줄러가 "오늘 날짜"로 호출).
• findByAsOfDateAndDeliveredAtIsNull(asOfDate) — 그 날짜의 시그널 중 아직 안 보낸 것(deliveredAt IS NULL)만 조회. 위에서 발송 성공 시 도장을 찍기 때문에 이 필터가 중복발송을 막습니다.
• Collectors.groupingBy(s -> s.getStrategy().getUser()) — 시그널을 사용자별로 묶음. {user42: [s1,s2], user43: [s3]} 형태.
• byUser.forEach(this::sendDigest) — 사용자마다 sendDigest(user, signals) 호출. sendDigest 는 @Async 라 각각 별도 스레드에서 병렬 발송됩니다.
• return pending.size() — 처리 대상 시그널 수를 반환(스케줄러가 로깅/모니터링에 사용).
• 초보 헷갈림(@Async 트랜잭션 경계): dispatchPending 의 @Transactional 과 sendDigest 의 @Async @Transactional 은 다른 트랜잭션/스레드입니다. dispatchPending 이 끝나도 sendDigest 들은 백그라운드에서 계속 발송 중일 수 있습니다. 즉 반환된 숫자는 "발송 시도 대상 수"이지 "발송 성공 수"가 아닙니다.

---

⚠️ 함정·보안 주의

1. M9 — IDOR 차단(핵심 보안)

   • 과거: ?userId= 파라미터를 신뢰 → 로그인만 하면 누구나 타인의 알림 조회/읽음처리 가능(IDOR).
   • 현재: 신원은 오직 JWT(AuthContext.currentUserId()) 에서만. 요청 파라미터의 신원은 절대 신뢰하지 않음. (NotificationController.java:78-83)
   • 이중 방어: 읽음 처리는 대상 id가 URL에서 오므로, 서비스(markNotificationRead)에서 n.getUser().getId().equals(user.getId()) 로 소유권을 한 번 더 확인. 남의 id면 조용히 무시(204지만 변경 없음).
   • 학습 포인트: "신원=서버가 신뢰하는 출처(JWT)에서, 대상 소유권=DB 비교로 재확인" 2단 패턴.

2. M5 — 프론트엔드가 백엔드 알림과 미연동(현황)

   • 백엔드 /api/notifications API는 완비되어 있으나, 프론트엔드는 아직 이 API를 호출하지 않습니다.
   • 실제 코드 증거: frontend/src/store/useNotificationStore.js 의 buildInitial()(L4-L50)이 하드코딩된 더미 알림 7건("전략 정형화 완료", "Trust Score 상승" 등)을 만들고, Zustand persist 로 localStorage(alpha-notifications)에 저장합니다. markRead/markAllRead/remove/clearAll 모두 로컬 상태만 바꾸며 백엔드를 호출하지 않습니다(L52-L74).
   • 결과: 화면의 알림은 브라우저 안에서만 사는 가짜 데이터입니다. 서버 DB의 Notification 과 무관하고, 다른 기기/브라우저와 동기화되지 않으며, localStorage를 비우면 사라집니다.
   • 즉 백엔드와 프론트가 끊겨 있는(wire 안 된) 상태가 M5의 현황입니다. (고도화 아이디어에서 연결 방안 제시.)

3. SMTP 미설정 시 동작 — "조용한 skip" vs "헬스 DOWN"

   • EmailAlertService 는 spring.mail.username(발신주소)이 비면 메일을 시도하지 않고 skip + 경고 로그합니다(EmailAlertService.java:43-46). 즉 이메일 미설정만으로 발송 로직이 죽지는 않습니다(우아한 폴백).
   • 그러나 Spring Boot의 MailHealthIndicator(actuator)는 별개입니다. spring.mail.host 등 메일 설정이 잡혀 있는데 SMTP 서버에 연결할 수 없으면 /actuator/health 가 mail 컴포넌트를 DOWN 으로 보고, 전체 상태가 DOWN 으로 떨어질 수 있습니다. (헬스체크가 "UP"이 아니게 되어 배포/모니터링에서 오탐을 일으킴.)
   • 정리: 발송 로직은 skip으로 견디지만, actuator 헬스는 SMTP 연결 실패에 민감합니다. 로컬/CI에서 메일 설정을 어중간하게(host는 있고 접속은 안 되게) 두면 헬스가 DOWN 날 수 있으니, 안 쓸 거면 mail health를 제외(management.health.mail.enabled=false)하거나 설정을 완전히 비우는 게 안전합니다.

4. 중복 발송 — deliveredAt 멱등 장치 의존

   • 중복 메일 방지는 오직 deliveredAt 도장 + findBy...DeliveredAtIsNull 필터에 달려 있습니다. 발송은 성공했는데 saveAll 직전 예외가 나면(드물지만) 도장이 안 찍혀 다음 배치에서 재발송될 수 있습니다. "정확히 한 번"이 아니라 "최소 한 번(at-least-once)" 보장에 가깝습니다.

5. @Async + @Transactional 경계 혼동

   • dispatchPending 이 반환해도 sendDigest 들은 백그라운드 진행 중일 수 있습니다. 반환값은 "성공 수"가 아닌 "대상 수". 또한 @Async 메서드는 같은 클래스 내부 호출이면 프록시를 안 타 비동기가 안 걸립니다 — 여기서는 dispatchPending 이 this::sendDigest 를 호출하므로(자기 클래스 메서드 참조) 자기-호출(self-invocation) 입니다. 같은 빈 내부 호출은 Spring AOP 프록시를 우회할 수 있어, 실제로 비동기로 분리되지 않을 가능성이 있습니다(설정/프록시 방식에 따라). 동작을 비동기로 보장하려면 발송 루프를 별도 빈으로 분리하는 게 안전합니다. (학습 시 꼭 짚을 함정.)

6. enum과 실제 사용의 괴리

   • NotificationType 12개 중 다수는 협업/계약(DevBridge) 도메인 용어입니다. 알림 "생성" 코드는 이 도메인 밖에 있어, 어떤 타입이 실제로 쓰이는지는 이 5파일만으로 단정할 수 없습니다. 환각 방지를 위해 "범용 카탈로그"로만 이해하세요.

---

🚀 고도화 아이디어

1. M5 연동 — 프론트를 진짜 API에 연결 (가장 시급)

   • useNotificationStore.js 의 buildInitial() 더미 제거 → 앱 진입/주기적 폴링으로 GET /api/notifications, 배지엔 GET /api/notifications/count 호출.
   • markRead(id) → PATCH /api/notifications/{id}/read, markAllRead() → PATCH /api/notifications/read-all 로 교체(낙관적 업데이트 + 실패 롤백).
   • 주의: 백엔드 DTO 필드명(notificationType/message/createdAt/isRead)과 프론트 더미 필드명(type/body/time/read)이 다릅니다. 매핑 어댑터를 두거나 한쪽 스키마로 통일해야 합니다.

2. 실시간 푸시(폴링 → 이벤트)

   • 지금은 조회형(pull). SSE(Server-Sent Events)나 WebSocket으로 새 알림을 실시간 푸시하면 배지가 즉시 갱신됩니다. chat 도메인이 이미 Stream을 쓰므로 그 채널 재사용 가능.

3. 알림 생성 표준화(이벤트 기반)

   • 현재 알림 생성 로직이 chat 서비스에 얹혀 있음. Spring ApplicationEvent(예: SignalCreatedEvent, OrderFilledEvent)를 발행하고, @EventListener 가 Notification 을 만들도록 분리하면 도메인 결합도가 낮아집니다. → "시그널 생성 시 인앱 알림 + 이메일" 두 채널을 한 이벤트로 fan-out.

4. 이메일 고도화

   • SimpleMailMessage(평문) → MimeMessage + Thymeleaf HTML 템플릿으로 가독성·브랜딩 향상.
   • 발송 실패 시 재시도 큐/백오프, 발송 이력 테이블(감사 로그), 사용자별 수신 거부(opt-out) 설정.

5. @Async 자기-호출 함정 해소

   • 발송 루프를 별도 빈(EmailDispatcher)으로 빼서 비동기가 확실히 걸리게. 동시에 스레드풀(TaskExecutor) 크기를 설정해 대량 사용자 발송을 제어.

6. 읽음 동기화 정합성

   • 벌크 @Modifying 업데이트 후 응답에 갱신된 unreadCount를 함께 반환해 프론트가 한 번 더 조회하지 않게(왕복 절감).

---

📚 용어 사전 (이 도메인 한정)

용어	뜻
인앱 알림(in-app notification)	DB NOTIFICATION 에 쌓이고 화면 우편함에 표시되는 알림. 읽음/안읽음 상태를 가짐
다이제스트(digest) 이메일	여러 시그널을 한 통으로 묶어 보내는 요약 메일
IDOR	Insecure Direct Object Reference. 요청 파라미터의 객체 id/신원을 검증 없이 믿어 타인 자원에 접근하게 되는 취약점
AuthContext	JWT에서 현재 사용자 id를 꺼내는 경량 헬퍼(global/security). Spring Security 미사용 구현
JWT	로그인 시 발급되는 위조 불가능한 서명 토큰. 신원의 신뢰 출처
@Async	메서드를 별도 스레드에서 실행(비동기). 호출자가 결과를 기다리지 않음
@Transactional	메서드 내 DB 작업을 하나의 트랜잭션으로 묶음(전부 성공 or 전부 롤백)
JavaMailSender / SimpleMailMessage	Spring의 메일 발송기 / 평문 메일 메시지(받는이·제목·본문)
SMTP	메일을 보내는 표준 프로토콜. Gmail은 앱 비밀번호로 인증
쿼리 메서드	Spring Data JPA가 메서드 이름(findByUser...)을 해석해 SQL을 자동 생성
@Modifying 벌크 쿼리	UPDATE/DELETE JPQL. 한 문장으로 다수 행을 변경(영속성 컨텍스트 우회)
DTO(Data Transfer Object)	엔티티의 민감/내부 필드를 가리고 외부 응답용으로 추린 객체(NotificationResponse)
정적 팩토리 from()	엔티티를 받아 DTO를 만들어 주는 static 변환 메서드
deliveredAt	DailySignal 의 이메일 발송 시각. null이면 미발송 → 중복발송 방지 키
멱등성(idempotency)	같은 작업을 여러 번 해도 결과가 한 번과 같음. 여기선 "이미 보낸 메일 재발송 안 함"
@CreatedDate / Auditing	행 생성 시각 자동 기록(AuditingEntityListener)
LAZY 로딩	연관 객체(User 등)를 실제 필요할 때만 DB에서 가져오기
M5 / M9	이 프로젝트의 보안/품질 수정 항목 번호. M9=IDOR 차단(완료), M5=프론트-백엔드 알림 미연동(현황)

domain/payment — 결제·구독·암호화·원장 (완전 라인별 해설)

원본: backend/src/main/java/com/DevBridge/devbridge/domain/payment/ 전체
형식: 이 교재의 표준(README "3. 공통 형식" + 모범 예시 01_backtest/vbt_engine.md)을 따릅니다.
전제: Spring 기초(@Service·@RestController·DI·@Transactional)는 08_backend/00_spring_primer.md 에서 다룹니다. 여기서는 결제 도메인 고유 개념에 집중합니다.

---

📌 이 도메인 한눈에

이 패키지는 백엔드의 "돈을 다루는 창구 + 비밀을 보관하는 금고" 입니다. 두 가지 일을 합니다.

1. 결제 창구 — 사용자가 토스(Toss)로 구독료를 내면, 그 결제가 진짜인지 토스 서버에 물어보고(confirm), 결제 상태가 바뀌면(취소·환불) 토스가 보내는 알림(웹훅)을 받습니다. 그리고 등록한 카드 목록과 거래 내역(가계부/원장)을 관리합니다.
2. 금고(암호화) — KIS·Binance 같은 외부 증권사 API 비밀키를 DB에 저장하기 전에 AES-256-GCM 으로 암호화합니다. DB가 통째로 유출돼도 키 없이는 못 읽습니다.

비유: 이 도메인은 은행 지점입니다. TossPaymentsService 는 창구 직원(본점=토스에 "이 결제 진짜 맞아요?"라고 전화), TossWebhookController 는 본점에서 오는 팩스 수신기(취소·환불 통지가 비동기로 들어옴), CryptoService 는 금고(고객 비밀번호를 잠가서 보관), LedgerController 는 통장 거래내역 출력기, PaymentMethodService 는 등록된 카드 관리대장입니다.

핵심 클래스 역할표

클래스	레이어	한 줄 역할	비유
TossPaymentsService	service	토스 /v1/payments/confirm 호출 → 결제 확정	본점에 결제 진위 확인 전화
CryptoService	service	AES-256-GCM 암복호화 (KIS/Binance 키 보호)	금고 (잠그기/열기)
PaymentMethodService	service	카드 등록·삭제·기본카드 설정 (마스킹 저장)	카드 관리대장
TossWebhookController	controller	토스가 푸시하는 상태변경 수신(HMAC 검증)	본점 팩스 수신기
LedgerController	controller	에스크로 이벤트 → 가계부(수입/지출) 목록	통장 거래내역
PaymentMethodController	controller	카드 CRUD REST 엔드포인트	창구 접수대
PaymentMethod	entity	카드(브랜드·last4·만료) — 전체번호/CVC 저장 안 함	마스킹된 카드 사본
AesGcmCryptoService	global/security	(연관) GitHub PAT 등 다른 토큰용 별도 AES-GCM	다른 금고 (키 파생 방식 다름)
SubscriptionController	(strategy 도메인)	결제 confirm + Pro 활성화 + M8 멱등성	구독 발급 창구 (이 문서와 링크)

⚠️ 헷갈림 주의: 결제 confirm 의 진짜 진입점은 payment 가 아니라 strategy 도메인의 SubscriptionController 입니다. 그 컨트롤러가 payment 의 TossPaymentsService.confirm() 을 빌려 씁니다. 그래서 이 문서는 "결제를 누가 시작하나"를 설명할 때 그 클래스를 링크로 인용합니다(아래 §F).

---

🧠 사전 지식 (이거 모르면 막힘)

1) Toss Payments v1 — "결제창은 프론트, 확정은 서버"

토스 결제는 2단계입니다. 초보가 가장 많이 오해하는 부분.

• 1단계 (프론트): 사용자가 토스 SDK 결제창에서 카드정보를 넣고 "결제하기"를 누름 → 토스가 paymentKey, orderId, amount 3종 세트를 만들어 우리 프론트의 successUrl 로 돌려보냄. 이 시점엔 아직 돈이 안 빠짐. "결제 예약" 상태일 뿐.
• 2단계 (서버 confirm): 우리 백엔드가 그 3종 세트를 받아, 서버의 시크릿 키로 토스 /v1/payments/confirm 을 호출. 이때 비로소 실제 청구가 확정됨.

왜 굳이 서버가 한 번 더 확인하나? → 악성 사용자가 프론트 JS 를 조작해 "9,900원짜리를 100원으로" 바꿔도, 서버가 amount 를 다시 검증(VALID_PLANS)하고 토스에 그대로 보내므로 위변조가 막힙니다. 금액 검증의 최종 책임은 항상 서버.

2) 웹훅(Webhook) — "본점이 우리한테 거는 전화"

confirm 은 우리가 토스에게 거는 호출(동기, 즉시 응답). 반면 웹훅은 토스가 우리에게 거는 호출(비동기)입니다.

• 언제? 결제 확정 이후에 상태가 바뀔 때 — 사용자가 환불받음, 가상계좌 입금이 뒤늦게 완료됨, 부분취소 등. 이건 우리가 모르는 사이 일어나므로 토스가 푸시로 알려줍니다.
• 비유: confirm = 내가 본점에 전화(내가 끊을 때까지 대답 기다림). 웹훅 = 본점이 나중에 나한테 거는 전화(언제 올지 모름, 받을 준비만 해둠).

3) AES-256-GCM 대칭암호화 — "같은 열쇠로 잠그고 여는 금고 + 봉인스티커"

• 대칭(symmetric): 잠글 때와 열 때 같은 키를 씀(APP_CRYPTO_KEY). 공개키/개인키 한 쌍을 쓰는 비대칭(RSA 등)과 다름.
• AES-256: 256비트(=32바이트) 키를 쓰는 표준 암호. 키가 정확히 32바이트여야 함.
• GCM: 단순 암호화에 더해 인증 태그(GCM tag, 16바이트) 를 같이 만듦. 누가 암호문을 한 글자라도 바꾸면 복호화 시 태그가 안 맞아 즉시 위변조 탐지. (비유: 봉투에 봉인 스티커. 뜯으면 티 남.)
• IV / nonce(12바이트): "초기화 벡터". 매번 랜덤으로 새로 만드는 소금 같은 값. 같은 평문을 두 번 암호화해도 IV 가 다르면 암호문이 완전히 달라짐 → 패턴 분석 방지. 비밀이 아니어서 암호문 앞에 붙여 같이 저장해도 안전.
• 우리 저장 포맷: Base64( IV(12) ‖ ciphertext ‖ GCM_TAG(16) ) — 세 조각을 한 줄로 이어 한 문자열로 보관(마이그레이션이 단순해짐).

4) 멱등성(Idempotency) — "버튼 두 번 눌러도 결제는 한 번"

같은 요청을 여러 번 보내도 결과가 한 번 한 것과 같아야 한다는 성질. 결제에서 필수입니다.

• 왜? 사용자가 successUrl 에서 새로고침하거나, 네트워크가 끊겨 프론트가 재시도하거나, 더블클릭하면 confirm 이 2번 날아올 수 있음. 그대로 두면 구독이 2번 활성화되거나 토스에 2번 confirm 해 에러가 남.
• 해결(M8): toss_payment_key 를 DB 유니크 키로 걸고, 이미 처리된 키면 토스 재호출 없이 기존 구독을 그대로 돌려줌. (코드는 §F·DB 마이그레이션 V17.)

5) 원장(Ledger) — "거래내역 통장"

여러 상태 변화(에스크로 입금·환불·정산)를 시간순 거래 목록으로 뽑아 보여주는 것. 회계의 "장부"에서 온 말. 우리는 ProjectEscrow(에스크로) 이벤트를 수입(income)/지출(expense)으로 분류해 가계부처럼 보여줍니다.

6) PCI 정책 — "카드 전체번호·CVC 는 절대 저장 금지"

카드정보를 직접 보관하면 PCI-DSS 라는 무거운 보안 규제를 받습니다. 그래서 우리는 카드번호 뒤 4자리(last4)·브랜드·소유자명·만료월만 저장하고, 전체 번호와 CVC 는 형식 검증만 하고 버립니다(PaymentMethod 주석에 명시).

---

🗺 요청 흐름도

(A) 구독 결제 — 동기 confirm 흐름

[프론트 React]
  사용자가 토스 SDK 결제창에서 카드 입력 → "결제"
        │  토스가 paymentKey · orderId · amount 발급
        ▼
  successUrl 로 리다이렉트 (아직 청구 안 됨)
        │  POST /api/subscription/confirm  { paymentKey, orderId, amount }
        ▼
┌─────────────────────────────────────────────────────────┐
│ SubscriptionController.confirm()   (strategy 도메인)       │
│  1. JWT 로 본인 확인 (AuthContext.currentUserId)           │
│  2. amount ∈ VALID_PLANS ?  (9900/19900 위변조 방지)       │
│  3. paymentKey 비었나?                                     │
│  4. ⭐ findByPaymentKey() — 이미 처리됐으면 멱등 반환 (M8)   │
└─────────────────────────────────────────────────────────┘
        │  (신규 결제일 때만)
        ▼
┌─────────────────────────────────────────────────────────┐
│ TossPaymentsService.confirm()      (payment 도메인 ★)      │
│  POST https://api.tosspayments.com/v1/payments/confirm    │
│  Authorization: Basic base64(secretKey + ":")             │
│  body: { paymentKey, orderId, amount }                    │
└─────────────────────────────────────────────────────────┘
        │  토스 응답 JSON  { status:"DONE", method:"카드", ... }
        ▼
  status == "DONE" ? → SubscriptionService.activatePro() → Pro 등급 활성화
        │  (DB 유니크 충돌 시 DataIntegrityViolation → 멱등 재사용)
        ▼
  { tier:"STANDARD", status, expiresAt } 를 프론트에 응답

(B) 상태변경 — 비동기 웹훅 흐름 (취소·환불·가상계좌 입금)

[토스 서버]  결제 취소/환불/입금완료 발생
        │  POST /api/payments/toss/webhook
        │  헤더 X-Toss-Signature  +  raw JSON body
        ▼
┌─────────────────────────────────────────────────────────┐
│ TossWebhookController.webhook()                           │
│  1. webhookSecret 있으면 → HMAC-SHA256 서명 검증           │
│       (rawBody 를 secret 으로 해시 == X-Toss-Signature ?)  │
│  2. eventType / data.paymentKey / data.status 파싱        │
│  3. escrowRepository.findByPaymentTxId(paymentKey)        │
│  4. status 에 따라 에스크로 상태 전이                       │
│       CANCELED/PARTIAL_CANCELED → REFUNDED               │
│       DONE(가상계좌 입금) → markDepositedFromExternal      │
└─────────────────────────────────────────────────────────┘
        │  항상 200 { ok:true } (토스에 "잘 받았다" 신호)

(C) 자격증명 금고 — CryptoService 사용처

[BrokerAccountController]  사용자가 KIS appsecret / Binance secret 등록
        │  crypto.encrypt(appsecret)
        ▼
  CryptoService.encrypt()  → Base64(IV‖CT‖TAG)
        ▼
  BrokerAccount.appSecretEnc 컬럼에 암호문 저장 (평문 절대 금지)
        │  ... 실주문 시 ...
        ▼
  CryptoService.decrypt(appSecretEnc) → 평문 복원 → KIS 호출

---

📖 핵심 클래스 라인별 심화

A. TossPaymentsService.confirm() — 결제 확정 호출

원본: domain/payment/service/TossPaymentsService.java

A-1. 클래스 선언과 주입 — TossPaymentsService.java:25-37

// L25-L37
@Slf4j
@Service
@RequiredArgsConstructor
public class TossPaymentsService {

    @Value("${tosspayments.secret-key}")
    private String secretKey;

    @Value("${tosspayments.api-base}")
    private String apiBase;

    private final RestTemplate restTemplate = new RestTemplate();
    private final ObjectMapper om = new ObjectMapper();

• @Service — 스프링이 이 클래스를 빈(bean)으로 만들어 다른 곳에 주입할 수 있게 함.
• @Value("${tosspayments.secret-key}") — application*.properties(또는 환경변수 TOSS_SECRET_KEY)에서 시크릿 키를 읽어 secretKey 필드에 넣음. 이 키는 절대 프론트에 노출되면 안 됩니다(서버 전용). 클라이언트 키(test_ck_...)와 시크릿 키(test_sk_...)는 반드시 같은 토스 계정의 키쌍이어야 함(CLAUDE.md 주의사항).
• apiBase — https://api.tosspayments.com 같은 베이스 URL. 환경별로 바꿀 수 있게 외부화.
• RestTemplate — 스프링의 HTTP 클라이언트(우리가 토스에게 거는 전화기). ObjectMapper — JSON 문자열 ↔ 자바 객체 변환기.

💡 초보 포인트: @Value 의 ${...} 안에 : 가 없으면(예: 여기) 키가 없으면 부팅 실패입니다. 토스 키는 반드시 설정돼야 한다는 뜻.

A-2. confirm 본체 — Basic 인증 헤더 만들기 — TossPaymentsService.java:43-58

// L43-L58
public JsonNode confirm(String paymentKey, String orderId, long amount) {
    String url = apiBase + "/v1/payments/confirm";

    // Basic Auth: secretKey + ":" base64
    String basic = Base64.getEncoder().encodeToString(
            (secretKey + ":").getBytes(StandardCharsets.UTF_8));

    HttpHeaders headers = new HttpHeaders();
    headers.setContentType(MediaType.APPLICATION_JSON);
    headers.set("Authorization", "Basic " + basic);

    Map<String, Object> body = Map.of(
            "paymentKey", paymentKey,
            "orderId", orderId,
            "amount", amount
    );

• 토스 인증 방식 = HTTP Basic Auth. 규칙: "시크릿키:" (콜론 뒤 비밀번호는 비움)을 Base64 로 인코딩해 Authorization: Basic <인코딩값> 헤더에 넣음.
  • 왜 secretKey + ":" 인가? Basic Auth 는 원래 아이디:비밀번호 형식인데, 토스는 시크릿키를 아이디 자리에 넣고 비밀번호는 비움. 그래서 콜론 뒤가 비어 있음.
• body 3종 세트 = 프론트가 받은 그대로의 paymentKey, orderId, amount. 토스는 이 셋이 자기가 발급한 것과 일치하는지(특히 amount) 대조해 위변조를 잡습니다.

A-3. 호출 + 성공 처리 — TossPaymentsService.java:60-66

// L60-L66
    HttpEntity<Map<String, Object>> entity = new HttpEntity<>(body, headers);
    try {
        ResponseEntity<String> res = restTemplate.exchange(url, HttpMethod.POST, entity, String.class);
        JsonNode json = om.readTree(res.getBody());
        log.info("[Toss] confirm OK orderId={} status={} method={}",
                orderId, json.path("status").asText(), json.path("method").asText());
        return json;

• restTemplate.exchange(...) — 실제 POST 전송. 응답 타입을 String.class 로 받는 점이 핵심: JSON 을 문자열로 받은 뒤 om.readTree() 로 직접 트리(JsonNode)로 파싱합니다.
  • 왜 자동 매핑(JsonNode.class) 안 쓰나? → 메모리의 "Spring Boot 4 Jackson JsonNode 버그"(Boot4 기본이 Jackson3 라 JsonNode 자동 역직렬화가 깨짐). String 으로 받아 우리 ObjectMapper(Jackson2)로 파싱하는 우회 패턴입니다.
• 성공 시 토스 응답 JSON 을 그대로 반환. 호출자(SubscriptionController)가 json.path("status") 가 "DONE" 인지 확인.
• json.path("status") — .path() 는 키가 없어도 예외 대신 "빈 노드"를 돌려줘 NPE 안전.

A-4. 실패 처리 — 토스 에러 메시지 추출 — TossPaymentsService.java:67-82

// L67-L82
    } catch (HttpStatusCodeException e) {
        String msg = "토스 결제 승인 실패";
        try {
            JsonNode err = om.readTree(e.getResponseBodyAsString());
            msg = err.path("message").asText(msg);
            log.warn("[Toss] confirm fail orderId={} code={} message={}", orderId,
                    err.path("code").asText(), msg);
        } catch (Exception ignore) {
            log.warn("[Toss] confirm fail orderId={} body={}", orderId, e.getResponseBodyAsString());
        }
        throw new RuntimeException(msg);
    } catch (Exception e) {
        log.warn("[Toss] confirm error orderId={}: {}", orderId, e.getMessage());
        throw new RuntimeException("결제 승인 중 오류가 발생했습니다: " + e.getMessage());
    }
}

• HttpStatusCodeException — 토스가 4xx/5xx 를 돌려준 경우(예: 이미 처리된 결제, 금액 불일치). 에러 바디에서 토스가 준 한글 메시지(message)를 꺼내 그대로 사용자에게 전달 → 친절한 에러.
• 두 단계 catch: 토스가 준 구조화된 에러(HttpStatusCodeException) vs 그 외 모든 오류(네트워크 끊김 등). 어느 쪽이든 RuntimeException 으로 통일해 위로 던짐 → 컨트롤러가 badRequest 로 변환.

⚠️ 함정: RuntimeException 한 종류로 뭉뚱그리면, 호출 측(SubscriptionController)에서 "토스 거절"과 "네트워크 장애"를 구분 못 합니다. 고도화 시 커스텀 예외로 분리하면 재시도 정책을 다르게 줄 수 있습니다(§고도화).

---

B. CryptoService.encrypt() / decrypt() — AES-GCM 금고

원본: domain/payment/service/CryptoService.java

B-1. 키 로딩 + 검증 (생성자) — CryptoService.java:44-61

// L44-L61
public CryptoService(@Value("${app.crypto.key}") String base64Key) {
    String trimmed = base64Key == null ? "" : base64Key.trim();
    byte[] keyBytes;
    try {
        keyBytes = Base64.getDecoder().decode(trimmed);
    } catch (IllegalArgumentException e) {
        throw new IllegalStateException("app.crypto.key는 Base64로 인코딩된 32바이트여야 합니다.", e);
    }
    if (keyBytes.length != 32) {
        throw new IllegalStateException("app.crypto.key는 정확히 32바이트(=AES-256)이어야 합니다. 현재: " + keyBytes.length + "바이트");
    }
    this.secretKey = new SecretKeySpec(keyBytes, ALG);
    this.devKey = trimmed.startsWith("dev-only")
            || "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=".equals(trimmed);
    ...

• @Value("${app.crypto.key}") — 콜론 없는 플레이스홀더 → 기본값이 없음. 즉 APP_CRYPTO_KEY(또는 app.crypto.key)가 설정 안 되면 앱이 부팅하다 죽습니다(CLAUDE.md 의 핵심 주의). 이건 의도된 안전장치: "암호화 키 없이 민감정보 다루지 마라."
• 키는 Base64 로 인코딩된 32바이트여야 함. 디코딩 실패하거나 길이가 32 가 아니면 명확한 한글 메시지로 IllegalStateException → 부팅 중단. (32바이트 = AES-256 의 요구 키 길이.)
• devKey 판정: 키가 dev-only 로 시작하거나 알려진 개발용 기본 Base64(AAECAwQF...)면 "개발용 키"로 표시 → 운영에서 실수로 쓰면 경고하려는 용도.

💡 초보 포인트: 생성자에서 키를 검증하는 이유 → 잘못된 키로 운영하다 나중에 복호화가 깨지느니, 시작할 때 빨리 죽는 게 낫다("fail fast"). 암호화는 한 번 잘못되면 데이터를 영영 못 읽을 수 있어 더욱 중요.

B-2. 시작 로그 — 키 지문(fingerprint)만 노출 — CryptoService.java:63-82

// L63-L71
@PostConstruct
void warn() {
    // 시작 시점에 어떤 키가 active 인지 fingerprint 로 식별 (값 자체는 노출 안 함)
    log.info("[CryptoService] app.crypto.key loaded — b64len={} b64tail=...{}  sha256[0..8]={} dev={}",
            keyB64Len, keyB64Tail, keyFingerprint, devKey);
    if (devKey) {
        log.warn("⚠️  app.crypto.key가 개발용 기본값입니다. 운영 배포 전 반드시 APP_CRYPTO_KEY 환경변수로 교체하세요.");
    }
}

• @PostConstruct — 빈이 만들어진 직후 1회 실행. 시작 로그에 어떤 키가 활성인지 식별 정보를 남김.
• 핵심 보안 설계: 키 값 자체는 로그에 안 찍습니다. 대신 SHA-256 해시의 앞 4바이트(keyFingerprint)·길이·꼬리 4글자만 찍음. 이러면 "지금 서버 A 와 B 가 같은 키를 쓰나?"를 지문 비교로 확인하면서도 키 자체는 유출 안 됨.
• 이게 왜 중요? → 메모리 "Env priority changes need duplicate-key audit": app.crypto.key 가 여러 파일에 다른 값으로 중복되면, 암호화한 키로 복호화가 안 되는 대참사가 납니다. 이 지문 로그가 그걸 잡는 진단 도구.

B-3. encrypt — IV 랜덤 생성 + 조립 — CryptoService.java:85-100

// L85-L100
public String encrypt(String plain) {
    if (plain == null) return null;
    try {
        byte[] iv = new byte[IV_LEN];           // IV_LEN = 12
        rng.nextBytes(iv);                       // 매번 새 랜덤 nonce
        Cipher c = Cipher.getInstance(TRANSFORM);// "AES/GCM/NoPadding"
        c.init(Cipher.ENCRYPT_MODE, secretKey, new GCMParameterSpec(TAG_BITS, iv)); // TAG_BITS = 128
        byte[] ct = c.doFinal(plain.getBytes(StandardCharsets.UTF_8));
        byte[] out = new byte[iv.length + ct.length];
        System.arraycopy(iv, 0, out, 0, iv.length);
        System.arraycopy(ct, 0, out, iv.length, ct.length);
        return Base64.getEncoder().encodeToString(out);
    } catch (Exception e) {
        throw new RuntimeException("encrypt failed", e);
    }
}

• rng.nextBytes(iv) — 매 암호화마다 새 12바이트 IV(nonce)를 랜덤 생성. GCM 의 황금률: "같은 키로 같은 IV 를 재사용하면 안 된다"(재사용하면 보안이 무너짐). SecureRandom 이라 예측 불가.
• GCMParameterSpec(128, iv) — 인증 태그를 128비트(16바이트)로. GCM 은 암호화 후 이 태그를 ct 끝에 자동으로 붙여 줍니다. 즉 c.doFinal() 결과 ct = 실제암호문 + 16바이트 태그.
• 조립: out = IV(12) + ct(암호문+태그). 이걸 Base64 한 문자열로 → DB 한 컬럼에 저장.
  • IV 를 암호문 앞에 같이 저장하는 게 맞나? → 네. IV 는 비밀이 아니며(랜덤이기만 하면 됨), 복호화하려면 반드시 같은 IV 가 필요하므로 함께 보관하는 게 표준입니다.

encrypt 결과 바이트 레이아웃:
┌──────────┬───────────────────────┬──────────────┐
│ IV (12B) │  ciphertext (가변)     │ GCM tag(16B) │   ← 전체를 Base64
└──────────┴───────────────────────┴──────────────┘
   └ 랜덤 nonce        └ 진짜 암호문         └ 봉인 스티커

B-4. decrypt — 분해 + 태그 검증 — CryptoService.java:103-118

// L103-L118
public String decrypt(String encoded) {
    if (encoded == null) return null;
    try {
        byte[] all = Base64.getDecoder().decode(encoded);
        if (all.length < IV_LEN + 16) throw new IllegalArgumentException("ciphertext too short");
        byte[] iv = new byte[IV_LEN];
        System.arraycopy(all, 0, iv, 0, IV_LEN);
        byte[] ct = new byte[all.length - IV_LEN];
        System.arraycopy(all, IV_LEN, ct, 0, ct.length);
        Cipher c = Cipher.getInstance(TRANSFORM);
        c.init(Cipher.DECRYPT_MODE, secretKey, new GCMParameterSpec(TAG_BITS, iv));
        return new String(c.doFinal(ct), StandardCharsets.UTF_8);
    } catch (Exception e) {
        throw new RuntimeException("decrypt failed (key mismatch or tampered ciphertext)", e);
    }
}

• 암호화의 정확한 역순: Base64 풀고 → 앞 12바이트를 IV 로, 나머지를 ct(암호문+태그)로 쪼갬.
• if (all.length < IV_LEN + 16) — 최소 길이(IV 12 + 태그 16 = 28바이트) 미만이면 깨진 데이터 → 즉시 거부.
• c.doFinal(ct) — 여기서 GCM 이 태그를 자동 검증. 암호문이 1비트라도 변조됐거나 키가 다르면 AEADBadTagException 이 터짐 → catch 로 잡아 "key mismatch or tampered ciphertext" 메시지로 던짐.
  • 즉 이 한 줄이 위변조 탐지 + 키 불일치 탐지를 동시에 합니다. 에러 메시지가 두 원인을 같이 적은 이유.

B-5. mask — 화면 노출용 마스킹 — CryptoService.java:121-124

// L121-L124
public static String mask(String v) {
    if (v == null || v.length() <= 8) return "********";
    return v.substring(0, 4) + "*".repeat(Math.max(4, v.length() - 8)) + v.substring(v.length() - 4);
}

• 복호화한 키를 화면에 "확인용"으로 보여줄 때, 앞 4 + 뒤 4만 남기고 가운데는 *. 8자 이하면 통째로 가림. (저장이 아니라 표시 용도.)

💡 CryptoService vs AesGcmCryptoService 차이(둘 다 AES-GCM):
| | CryptoService(payment) | AesGcmCryptoService(global/security) |
|---|---|---|
| 키 출처 | app.crypto.key (Base64 32B, 기본값 없음) | app.crypto.key → 없으면 JWT_SECRET 의 SHA-256 fallback |
| 키 검증 | 정확히 32B 아니면 부팅 실패 | 어떤 문자열이든 SHA-256 으로 32B 파생 |
| 반환형 | String(Base64) | byte[] + *Base64 변형 |
| 주 용도 | KIS·Binance 시크릿 | GitHub PAT 등 |
같은 평문을 둘로 암호화한 결과는 호환되지 않습니다(키 파생 방식이 다름). 어느 서비스로 암호화했는지 일관성 유지가 중요.

---

C. TossWebhookController — 비동기 상태변경 수신

원본: domain/payment/controller/TossWebhookController.java

C-1. 엔드포인트 + 서명 검증 게이트 — TossWebhookController.java:45-55

// L45-L55
@PostMapping("/webhook")
@Transactional
public ResponseEntity<?> webhook(@RequestHeader(value = "X-Toss-Signature", required = false) String signature,
                                 @RequestBody String rawBody) {
    // 보안키가 비어있으면 검증 skip (개발 단계). 운영에서는 필수.
    if (webhookSecret != null && !webhookSecret.isBlank()) {
        if (signature == null || !verifyHmac(rawBody, signature)) {
            log.warn("[TossWebhook] 서명 검증 실패");
            return ResponseEntity.status(401).body(Map.of("message", "invalid signature"));
        }
    }

• @RequestBody String rawBody — JSON 을 객체가 아니라 원시 문자열로 받는 게 핵심. 서명은 토스가 보낸 바이트 그대로에 대해 계산했으므로, 우리도 파싱하기 전 원본으로 HMAC 을 계산해야 일치합니다. (객체로 받아 다시 직렬화하면 공백·키순서가 달라져 서명이 깨짐.)
• X-Toss-Signature 헤더 — 토스가 본문을 자기 비밀키로 HMAC 한 값. required=false 라 헤더가 없어도 메서드에는 들어옴(아래서 직접 검사).
• 검증 게이트: webhookSecret 이 설정돼 있을 때만 검증. 비어 있으면(개발) skip. ⚠️ 운영에서 tosspayments.webhook-secret 를 안 넣으면 아무나 위조 웹훅을 보내 환불 상태를 조작할 수 있음 → 운영 필수(§함정).

C-2. 본문 파싱 + 에스크로 매칭 — TossWebhookController.java:57-77

// L57-L77
    try {
        JsonNode body = om.readTree(rawBody);
        String eventType = body.path("eventType").asText("");
        JsonNode data    = body.path("data");
        String paymentKey = data.path("paymentKey").asText("");
        String status     = data.path("status").asText("");

        log.info("[TossWebhook] eventType={} status={} paymentKey={}", eventType, status, paymentKey);

        if (paymentKey.isBlank()) return ResponseEntity.ok(Map.of("ok", true));

        // payment_tx_id 컬럼에 paymentKey 가 저장돼있음 → 단건 조회.
        escrowRepository.findByPaymentTxId(paymentKey)
                .ifPresent(e -> applyStatus(e, status));

        return ResponseEntity.ok(Map.of("ok", true));
    } catch (Exception ex) {
        log.warn("[TossWebhook] 처리 오류: {}", ex.getMessage());
        return ResponseEntity.status(500).body(Map.of("message", ex.getMessage()));
    }
}

• 토스 웹훅 페이로드 구조: { eventType, data:{ paymentKey, status, ... } }. data.paymentKey 로 우리 DB 의 어떤 에스크로인지 찾음(payment_tx_id 컬럼에 paymentKey 가 저장돼 있음).
• findByPaymentTxId(...).ifPresent(...) — 매칭되는 에스크로가 있을 때만 상태 갱신. 없으면 조용히 무시(우리와 무관한 결제일 수 있음).
• 항상 200 ok:true 반환(매칭 안 돼도). 웹훅은 "받았다"는 신호를 빨리 줘야 토스가 재전송을 멈춥니다. 단, 처리 중 예외는 500 으로 → 토스가 나중에 재시도.

C-3. 상태 전이 로직 — TossWebhookController.java:79-98

// L79-L98
private void applyStatus(ProjectEscrow e, String tossStatus) {
    switch (tossStatus) {
        case "CANCELED", "PARTIAL_CANCELED" -> {
            if (e.getStatus() != ProjectEscrow.EscrowStatus.REFUNDED) {
                e.setStatus(ProjectEscrow.EscrowStatus.REFUNDED);
                e.setRefundedAt(LocalDateTime.now());
                escrowRepository.save(e);
                log.info("[TossWebhook] 에스크로 {} → REFUNDED", e.getId());
            }
        }
        case "DONE" -> {
            if (e.getStatus() == ProjectEscrow.EscrowStatus.PENDING) {
                // 가상계좌 입금 완료 등 — 에스크로 전이 + 마일스톤 IN_PROGRESS + 파트너 알림 일괄 처리.
                dashboardService.markDepositedFromExternal(e.getId());
                log.info("[TossWebhook] 에스크로 {} → DEPOSITED (webhook 보강)", e.getId());
            }
        }
        default -> { /* WAITING_FOR_DEPOSIT 등은 무시 */ }
    }
}

• 취소/부분취소 → REFUNDED, 단 if (status != REFUNDED) 가드로 이미 환불됐으면 또 안 함 → 웹훅이 중복 도착해도 안전(멱등). refundedAt 타임스탬프 기록.
• DONE(가상계좌 입금 완료) → DEPOSITED, 단 PENDING 상태일 때만. 입금은 confirm 시점이 아니라 나중에 일어날 수 있어 웹훅으로 보강하는 것. 단순 상태변경이 아니라 markDepositedFromExternal() 로 마일스톤 진행 + 파트너 알림까지 일괄 처리.
• default — 그 외 상태(WAITING_FOR_DEPOSIT 등)는 무시. 모든 분기에 가드(if)가 있어 같은 웹훅을 여러 번 받아도 결과가 같음(웹훅 멱등의 모범).

---

D. PaymentMethodService — 카드 등록(마스킹) 핵심

원본: domain/payment/service/PaymentMethodService.java

D-1. 카드번호 검증 + CVC 폐기 — PaymentMethodService.java:38-50

// L38-L50
String rawNumber = req.getNumber() == null ? "" : req.getNumber().replaceAll("[\\s-]", "");
if (!rawNumber.matches("\\d{13,19}")) {
    throw new IllegalArgumentException("카드 번호 형식이 올바르지 않습니다.");
}
if (!luhnCheck(rawNumber)) {
    // Mock 환경: Luhn 실패해도 통과시키되 로그만 남김
    // throw new IllegalArgumentException("유효하지 않은 카드 번호입니다.");
}

String cvc = req.getCvc() == null ? "" : req.getCvc().trim();
if (!cvc.matches("\\d{3,4}")) {
    throw new IllegalArgumentException("CVC 형식이 올바르지 않습니다.");
}

• 공백·하이픈 제거 후 13~19자리 숫자인지 검사. luhnCheck(아래)는 Mock 환경에서 통과시키되 코드는 남겨둠(주석 처리). → 테스트 카드도 등록되게 한 의도.
• CVC 는 형식(3~4자리)만 검사하고 변수에서 그대로 버려집니다. 어디에도 저장 안 함 → PCI 원칙 준수.

D-2. 마스킹 저장 — PaymentMethodService.java:77-92

// L77-L92
PaymentMethod pm = PaymentMethod.builder()
        .user(user)
        .brand(detectBrand(rawNumber))
        .last4(rawNumber.substring(rawNumber.length() - 4))
        .holderName(holder)
        .expMonth(m)
        .expYear(y)
        .isDefault(makeDefault)
        .nickname(req.getNickname() == null ? null : req.getNickname().trim())
        .build();

PaymentMethod saved = paymentMethodRepository.save(pm);
if (makeDefault) {
    paymentMethodRepository.clearOtherDefaults(user, saved.getId());
}

• DB 에 들어가는 건 brand + last4(뒤 4자리) + 소유자 + 만료뿐. 전체 카드번호 rawNumber 는 메서드가 끝나면 사라짐.
• 기본 카드 단일성 보장: 새 카드를 default 로 만들면 clearOtherDefaults(user, savedId) 로 나머지 카드의 isDefault 를 일괄 false(레포지토리의 @Modifying UPDATE). "기본 카드는 항상 1개"라는 불변식을 코드로 강제.
• detectBrand — 카드번호 앞자리로 브랜드 판정(4→VISA, 51-55/2221-2720→MASTERCARD, 34/37→AMEX, 35→JCB, 6→DISCOVER, 그 외 LOCAL). 표준 BIN 규칙.

D-3. 본인 소유 강제 — PaymentMethodService.java:126-133

// L126-L133
@Transactional(readOnly = true)
public PaymentMethod requireOwned(Long userId, Long pmId) {
    User user = userRepository.findById(userId)
            .orElseThrow(() -> new IllegalArgumentException("사용자를 찾을 수 없습니다."));
    return paymentMethodRepository.findByIdAndUser(pmId, user)
            .orElseThrow(() -> new IllegalArgumentException("결제 수단을 찾을 수 없습니다."));
}

• findByIdAndUser(pmId, user) — id 만으로 찾지 않고 "id AND 소유자"로 조회. 남의 카드 id 를 넣어도 내 것이 아니면 못 찾음 → IDOR(다른 사용자 리소스 무단 접근) 방지. 삭제·기본설정 등 모든 변경 경로가 이 패턴을 씁니다.

---

E. 컨트롤러·엔티티 요약 (REST 표면)

• PaymentMethodController (/api/payment-methods): GET(목록)·POST(등록)·PATCH /{id}/default(기본설정)·DELETE /{id}. 매 메서드 첫 줄이 AuthContext.currentUserId() → null 이면 401. 신원을 항상 JWT 에서만 취득(요청 body 의 userId 같은 건 신뢰 안 함 — 최근 커밋의 IDOR 차단 패턴과 동일).
• LedgerController (/api/ledger/me): 내 에스크로 이벤트를 가계부로. payer 의 DEPOSITED→지출·REFUNDED→환불수입, payee 의 RELEASED→정산수입. 카드/계좌 미등록이면 linked:false + 빈 목록(프론트가 안내 띄우게). 응답을 LinkedHashMap 으로 만들어 키 순서 보존.
• PaymentMethod(entity): @Table(name="PAYMENT_METHODS"), last4 length=4, brand는 @Enumerated(STRING). 클래스 주석에 "PCI 정책상 카드 전체번호·CVC 절대 저장 안 함" 명시. @CreatedDate·@UpdateTimestamp 로 감사 시각 자동 기록.

---

F. (링크) 결제 confirm 의 진짜 시작점 — SubscriptionController

위치: domain/strategy/controller/SubscriptionController.java (이 문서의 payment 도메인이 아님 — 링크로만 연결). TossPaymentsService 를 주입받아 사용.

핵심은 M8 멱등성 2중 방어 — SubscriptionController.java:79-104:

// L79-L84  ① 선조회 멱등 (가장 흔한 경로: 새로고침/더블클릭)
Subscription already = subscriptionService.findByPaymentKey(paymentKey);
if (already != null) {
    log.info("[Subscription] 멱등 confirm — 이미 처리된 결제 ...");
    return ResponseEntity.ok(idempotentBody(already, true));
}

// L98-L104  ② DB 유니크 충돌 멱등 (동시 confirm 경합)
} catch (org.springframework.dao.DataIntegrityViolationException dup) {
    Subscription existing = subscriptionService.findByPaymentKey(paymentKey);
    if (existing != null) {
        return ResponseEntity.ok(idempotentBody(existing, true));
    }
    ...
}

• 방어 1 (선조회): confirm 전에 findByPaymentKey(= findByTossPaymentKey)로 이미 처리된 결제인지 확인 → 있으면 토스 재호출 없이 기존 구독 반환. 새로고침·재시도·더블클릭의 99%를 여기서 막음.
• 방어 2 (DB 유니크): 두 요청이 동시에 선조회를 통과해버린 경합(race)에서는, subscription.toss_payment_key 에 걸린 DB 유니크 제약(uq_subscription_toss_payment_key, 마이그레이션 V17__subscription_payment_idempotency.sql)이 두 번째 INSERT 를 막아 DataIntegrityViolationException 발생 → 먼저 성공한 구독을 재사용. 애플리케이션 검사 + DB 제약의 2중 그물.
• 추가로 VALID_PLANS(9900/19900) 로 금액 위변조를 컨트롤러에서 한 번 더 검증(SubscriptionController.java:29-32, 71-74).

---

⚠️ 함정·보안 주의

1. APP_CRYPTO_KEY 기본값 없음 → 미설정 시 부팅 실패. CryptoService 생성자가 @Value("${app.crypto.key}")(콜론 없음)이라 키가 없으면 앱이 시작 못 함. 로컬에서도 반드시 Base64 32바이트 키를 설정. 이건 버그가 아니라 의도된 fail-fast 안전장치.

2. app.crypto.key 중복정의 = 복호화 대참사. 메모리 "Env priority changes need duplicate-key audit" 핵심: 같은 키가 .env/application*.properties 에 다른 값으로 중복되면, A 값으로 암호화한 KIS 시크릿을 B 값으로 복호화 시도 → AEADBadTagException("key mismatch") → 영영 못 읽음. 우선순위 변경 전 반드시 중복 감사. 시작 로그의 sha256[0..8] 지문으로 서버 간 키 일치 확인 가능.

3. 결제 멱등성(M8)은 2중이어야 한다. 애플리케이션 선조회(findByPaymentKey)만으로는 동시 요청 경합을 못 막음. DB 유니크 키(uq_subscription_toss_payment_key)가 최종 방어선. 둘 중 하나만 있으면 더블 결제 위험.

4. 클라이언트 키 ↔ 시크릿 키 쌍 일치. 프론트의 test_ck_... 와 서버의 test_sk_... 는 같은 토스 계정이어야 함. 다른 계정 키를 섞으면 confirm 이 토스에서 거부됨(CLAUDE.md 주의).

5. 웹훅 서명 검증은 운영 필수. tosspayments.webhook-secret 이 비면 TossWebhookController 가 검증을 skip 함 → 운영에서 비워두면 누구나 위조 웹훅으로 에스크로를 REFUNDED 로 조작 가능. 반드시 운영에서 시크릿 주입. 또한 서명 검증은 파싱 전 raw body로 해야 일치(객체로 받으면 깨짐).

6. 금액 검증의 최종 책임은 서버. 프론트가 보낸 amount 를 그대로 믿지 말고 VALID_PLANS 로 화이트리스트 검증 후 토스에 전달. 토스도 발급 금액과 대조하지만, 우리 측 1차 방어가 우선.

7. 시크릿 키·복호화 평문을 로그에 찍지 말 것. CryptoService 가 키를 지문(해시 앞 4바이트)으로만 로깅하는 이유. confirm 로그도 status/method 만 남기고 카드정보는 안 남김.

8. CVC·전체 카드번호 저장 금지(PCI). PaymentMethodService 는 형식만 검사하고 last4 만 보관. 새 필드를 추가할 때 실수로 전체번호를 저장하지 않도록 주의.

9. Jackson3(Boot4) JsonNode 함정. TossPaymentsService 가 응답을 String 으로 받아 우리 ObjectMapper 로 파싱하는 건 메모리 "Spring Boot 4 Jackson JsonNode 버그" 우회. JsonNode.class 로 직접 받으면 깨질 수 있음.

---

🚀 고도화 아이디어

• 결제 예외 세분화: 지금은 모두 RuntimeException. TossDeclinedException(토스 거절·재시도 무의미) vs TossUnavailableException(네트워크·일시장애·재시도 가치)로 나눠 confirm 에 Resilience4j Retry/CircuitBreaker 적용(전략 도메인 AnalyticsClient 패턴 재사용).
• 웹훅 멱등 테이블: 현재는 상태 가드(if)로 멱등을 보장하지만, 토스 eventId 를 유니크로 가진 webhook_event 테이블에 먼저 INSERT 해 "이미 처리한 이벤트면 skip"하면 더 견고. 결제 confirm 의 M8 과 같은 철학.
• 키 회전(rotation): AES 키 교체 시 기존 암호문을 못 읽는 문제 → 암호문에 키 버전 prefix(v2:)를 붙이고 CryptoService 가 버전별 키를 들고 복호화 → 무중단 키 회전.
• 타이밍 안전 비교: verifyHmac 의 equalsIgnoreCase 는 이론상 타이밍 공격 표면. MessageDigest.isEqual 같은 상수시간 비교로 교체.
• 원장 성능: LedgerController 가 payer/payee 에스크로를 전부 로드 후 메모리 정렬. 거래가 많아지면 페이지네이션 + DB 정렬/필터로 이전.
• 결제 멱등 응답 표준화: confirm 성공/멱등 응답의 키(tier/status/expiresAt/idempotent)를 DTO 클래스로 통일해 프론트 계약을 명확히.
• CryptoService 통합: CryptoService 와 AesGcmCryptoService 가 둘 다 AES-GCM 인데 키 파생·반환형이 달라 혼동 위험. 하나로 통합하거나 역할 경계를 문서/네이밍으로 명확히.

---

📚 용어 사전 (이 도메인 한정)

용어	뜻
paymentKey	토스가 결제건마다 발급하는 고유 식별자. confirm·웹훅·멱등 키의 기준
orderId	우리(가맹점)가 만드는 주문 번호. 토스 confirm 에 함께 전달
confirm	서버가 토스 /v1/payments/confirm 호출 → 실제 청구 확정(동기)
웹훅(Webhook)	토스가 우리 서버로 보내는 상태변경 푸시(비동기). X-Toss-Signature 로 검증
Basic Auth	base64(secretKey + ":") 를 Authorization: Basic 헤더에 — 토스 인증 방식
AES-256-GCM	32바이트 키 대칭암호 + 인증 태그(위변조 탐지)
IV / nonce	매 암호화마다 새로 만드는 12바이트 랜덤값. 같은 키+같은 IV 재사용 금지
GCM tag	16바이트 인증 태그. 복호화 시 안 맞으면 변조/키불일치로 거부
HMAC-SHA256	비밀키 기반 메시지 인증. 웹훅 서명(raw body 해시) 검증에 사용
멱등성(Idempotency)	같은 요청을 여러 번 해도 결과가 한 번과 동일. M8 = paymentKey 유니크
원장(Ledger)	거래내역 장부. 에스크로 이벤트를 수입/지출로 분류한 목록
에스크로(Escrow)	제3자 보관. 결제금을 중간 보관했다가 조건 충족 시 정산(payer↔payee)
PCI-DSS	카드정보 보호 규제. 우리는 last4 만 저장해 적용 범위를 최소화
last4	카드번호 뒤 4자리. 식별용으로만 저장(전체번호·CVC 는 저장 안 함)
Luhn 검사	카드번호 체크섬 검증. Mock 환경에선 통과시킴
IDOR	남의 리소스 id 로 무단 접근. findByIdAndUser 로 차단
fail-fast	잘못된 설정이면 시작 시점에 즉시 죽기(키 검증). 늦게 터지는 것보다 안전

domain/strategy — 백테스트·전략·시그널·구독 (완전 라인별 해설)

원본: backend/src/main/java/com/DevBridge/devbridge/domain/strategy/
이 문서는 표준 형식(01_backtest/vbt_engine.md)을 따릅니다.
Spring 기초(@Service·@RestController·DI·@Transactional)는 08_backend/00_spring_primer.md 를 전제로 합니다(아직 미작성이라면, 각 절의 "초보 포인트"가 그 빈틈을 메웁니다).
다루는 파일: service/BacktestService · service/AnalyticsClient · service/DailySignalGenerator · service/SubscriptionService · service/MarketDataService · controller/StrategyController · controller/SubscriptionController · controller/AnalyticsController · entity/{Strategy,Subscription,DailySignal,OrderProposal}

---

📌 이 파트 한눈에

이 파트는 백엔드(Spring)의 "전략 운영 본부" 입니다. 사용자가 만든 투자 전략을 보관하고, 매일 자동으로 백테스트를 돌려 "오늘 뭘 사야 하나(시그널)"를 계산하고, 그 시그널을 주문 제안(OrderProposal) 으로 바꾸고, 유료 기능을 쓸 수 있는지(구독)를 확인합니다.

비유: 이 파트는 자산운용사의 백오피스입니다.

• 전략 보관실(Strategy 엔티티 + StrategyController) — 고객별 전략 카드를 캐비닛에 보관.
• 리서치팀(BacktestService, AnalyticsClient) — 과거 데이터로 "이 전략 얼마나 벌었나"를 계산. 단순 계산은 사내(Java)에서, 무거운 정밀 분석은 외부 연구소(Python:8001)에 위탁.
• 데일리 데스크(DailySignalGenerator) — 매일 밤 22:30 모든 전략을 재계산하고 "내일 행동 지침"을 메일로 발송 + 주문 제안서 작성.
• 회계·요금제팀(SubscriptionService) — 누가 유료 회원인지, 결제가 중복되지 않았는지 관리.

⭐ 가장 먼저 이해할 핵심 구조 — "백테스트가 두 군데서 돈다"

초보가 가장 헷갈리는 지점입니다. 이 코드베이스에는 백테스트 경로가 둘 있습니다.

경로	누가	어디서 계산	무엇을
경로 A (사내 Java 엔진)	BacktestService	백엔드 안(순수 Java for-loop)	무한매수법(LOC)·VR 밸류리밸런싱. DB에 캐시된 일봉을 직접 돌림. → Strategy/StrategyController/DailySignalGenerator 가 사용
경로 B (외부 Python 위탁)	AnalyticsClient	Analytics 사이드카(:8001, vectorbt)	sma_cross·rsi·macd 등 6전략 + XGBoost + Trust/Regime. → AnalyticsController 가 프론트에 노출

즉 BacktestService 는 Python을 호출하지 않습니다 — 무한매수/VR 알고리즘을 Java로 직접 구현했습니다(프론트의 lib/backtest.js 와 1:1 동일). 반면 AnalyticsClient 는 백엔드↔Python 다리로, vectorbt·XGBoost 같은 무거운 퀀트 로직을 :8001 의 main.py 엔드포인트에 위탁합니다.

핵심 클래스	한 줄 역할	비유
StrategyController	전략 CRUD + 사용자 격리 + 백테스트 수동 트리거	전략 카드 캐비닛 접수창구
BacktestService	사내 무한매수/VR 백테스트 엔진(Java) → trades·summary·state·signal 저장	리서치팀의 자체 계산기
MarketDataService	일봉 OHLC 수집(Stooq/Binance) + DB 캐시	가격 데이터 창고지기
AnalyticsClient	외부 Python:8001 호출(서킷브레이커+재시도)	외부 연구소 위탁 담당자
AnalyticsController	AnalyticsClient 를 프론트에 얇게 노출	위탁 결과 전달 데스크
DailySignalGenerator	매 평일 22:30 전체 재계산 → 메일 + OrderProposal	데일리 데스크 야간조
SubscriptionService	구독 등급 조회/활성화/만료(멱등 보장)	회계·요금제팀
SubscriptionController	Toss 결제 confirm + 금액 위변조 차단	결제 창구

---

🧠 사전 지식 (이거 모르면 막힘)

1) 서킷 브레이커(Circuit Breaker) = "전기 두꺼비집"

• 외부 서비스(Python:8001)가 죽었는데도 계속 호출하면, 매번 타임아웃까지 기다리느라 백엔드 전체가 느려집니다(장애 전파).
• 두꺼비집처럼 "최근 호출의 50%가 실패하면 회로를 OPEN(차단)" 해서, 한동안(여기선 30초) 아예 호출을 안 하고 즉시 실패시킵니다. → 빠른 실패(fast-fail)로 백엔드를 보호.
• 상태 3가지: CLOSED(정상, 통과) → OPEN(차단, 즉시 실패) → HALF_OPEN(시험삼아 몇 건만 통과시켜 회복됐나 확인).
• 이 프로젝트 설정(application.properties): 슬라이딩 윈도우 10건 중 실패율 50% → OPEN 30초 → HALF_OPEN에서 3건 시험.

2) 재시도(Retry) = "한 번 더 눌러보기"

• 네트워크는 가끔 일시적으로 끊깁니다(패킷 유실 등). 그럴 때 한 번 더 보내면 성공하는 경우가 많습니다.
• 이 프로젝트: 최대 3회, 2초 간격. 단, 4xx(잘못된 요청)는 재시도 안 함 — 파라미터가 틀린 요청은 100번 보내도 똑같이 틀리니까(낭비). 5xx·네트워크 오류만 재시도.

3) 사이드카(Sidecar) 호출 = "본체 옆에 붙은 전문 보조 프로세스"

• 무거운 수학(vectorbt·XGBoost)을 Java로 다시 짜면 비효율적이라, Python 전용 프로세스(:8001) 를 옆에 띄워 HTTP로 일을 시킵니다.
• 백엔드는 매 요청에 X-Internal-Token 헤더를 붙여 "나는 정식 백엔드다"를 증명합니다(외부인이 :8001 직접 호출 차단). → 엔진 쪽 해설은 06_api/main.md 의 require_internal_token 참고.

4) 구독 플랜 — DB는 단순, 표시는 금액으로

• 이 프로젝트의 미묘한 설계: DB의 Subscription.Tier enum 은 FREE / PRO 둘뿐입니다.
• 사용자에게 보이는 STANDARD(9,900원) / PREMIUM(19,900원) 구분은 DB에 따로 컬럼이 없고, 결제 금액(amountKrw)으로 런타임에 파생합니다(deriveTierDisplay: 19,900 이상이면 PREMIUM, 아니면 STANDARD).
• User.UserType 에는 FREE/STANDARD/PREMIUM 이 따로 있어, 결제 시 금액에 맞춰 갱신합니다. (CLAUDE.md의 "EXPERT(준비중)"는 아직 코드에 없음.)

5) 멱등성(Idempotency) = "여러 번 눌러도 결과는 한 번"

• 결제 성공 후 사용자가 새로고침하거나 더블클릭하면 confirm 요청이 2번 갈 수 있습니다. 그대로 두면 구독이 2개 생기고 이중 과금처럼 보입니다.
• "같은 결제키면 두 번째부터는 새로 만들지 않고 기존 것을 그대로 반환" → 이게 멱등성. 이 프로젝트는 3중 방어(애플리케이션 사전체크 + DB 유니크 제약 + 경합 예외 처리)로 보장합니다(아래 함정 절).

6) @Transactional = "전부 성공 아니면 전부 취소(트랜잭션)"

• 메서드에 붙이면 그 안의 DB 작업들이 하나의 묶음(원자적). 중간에 예외가 나면 앞서 한 저장도 롤백됩니다.
• readOnly = true 는 "읽기 전용"이라 DB에 약간의 최적화 힌트를 줍니다(쓰기 안 함 보장).

7) @Scheduled(cron=...) = "정해진 시각에 자동 실행되는 알람"

• cron = "0 30 22 * * MON-FRI" = 초 분 시 일 월 요일 → "월~금 매일 22시 30분 0초". zone="Asia/Seoul" 로 한국시간 기준.
• 서버가 떠 있기만 하면, 아무도 호출하지 않아도 스프링이 알아서 실행합니다.

8) AuthContext.currentUserId() = "지금 요청한 사람이 누구인지"

• JWT 필터가 토큰에서 사용자 ID를 꺼내 요청 스레드에 보관해 둔 것. 컨트롤러는 이걸 읽어 "이 전략이 정말 이 사람 것인가"를 검사합니다(소유권 격리).

---

🗺 요청 흐름도

흐름 ①: 사용자가 "백테스트 실행" 버튼 (경로 A — 사내 Java 엔진)

[프론트] POST /api/strategies/{id}/backtest  (JWT 쿠키)
        │
        ▼
StrategyController.runBacktest()
        │  ① AuthContext.currentUserId() 로 로그인 확인
        │  ② strategy.user.id == uid  소유권 검증 (남의 전략 차단)
        ▼
BacktestService.runFor(Strategy)
        │  ③ MarketDataService.getDaily(ticker, startDate)
        │        └─ DB에 일봉 있으면 그대로, 오래됐으면(2일↑) Stooq/Binance에서 받아 채움
        │  ④ method 분기:
        │        INFINITE_BUY     → runInfiniteBuy()   (LOC 분할매수 시뮬레이션)
        │        VALUE_REBALANCING→ runValueRebalancing() (V값 밴드 매매)
        │  ⑤ 결과를 DB에 4종 저장:
        │        StrategyTrade(source=BACKTEST) 재생성
        │        StrategyState (마지막 날 잔고) upsert
        │        StrategyBacktestSummary (CAGR/MDD/승률/TrustScore) upsert
        │        DailySignal (오늘 BUY/HOLD/WATCH/PAUSE) upsert
        ▼
[프론트] ← StrategyBacktestSummaryDto (성적표 카드)

흐름 ②: 프론트가 "정밀 분석(vectorbt/XGBoost)" 요청 (경로 B — Python 위탁)

[프론트] POST /api/analytics/backtest  (JWT)
        │
        ▼
AnalyticsController.backtest()
        ▼
AnalyticsClient.backtest(ticker, strategy, extra)
        │  call() → [Retry(3회)] → [CircuitBreaker]
        │             │
        │             ▼  HTTP POST  + 헤더 X-Internal-Token
        ▼
[Analytics :8001]  main.py  POST /backtest
        │  get_history → run_backtest(vectorbt) → compute_metrics(QuantStats)
        ▼
        JSON {stats, equity_curve, risk_metrics}  → JsonNode → 프론트 차트
        ⚠ 회로 OPEN이면: 즉시 "Analytics 일시 사용불가" 던지고 끝(폴백)

흐름 ③: 매일 밤 22:30 자동 데일리 잡

@Scheduled 22:30 KST  DailySignalGenerator.runDaily()
        │
        ├─ 1) marketDataService.scheduledRefresh()     시세 신선화
        ├─ 2) 활성 전략 전체 backtestService.runFor(s)  → DailySignal upsert
        ├─ 3) emailAlertService.dispatchPending(today)  미발송 시그널 메일
        ├─ 4) createProposalsFor(today)                 ★BUY 시그널 → OrderProposal
        │        └─ BUY인 전략마다:
        │             pickTradingAccount(거래가능 계정, REAL 우선)
        │             중복 체크(같은 sourceSignalId)
        │             OrderProposal(status=PENDING, expiresAt=+24h) 저장
        │             계정이 autoExecute=ON 이면 → ProposalExecutionService.execute()
        └─ 5) refreshAlphaWorkspaces()                  Alpha 워크스페이스 재실행

핵심 안전 원칙: 2~4단계가 자동이지만, OrderProposal은 항상 PENDING(대기) 으로 시작합니다. 사용자가 명시적으로 승인하지 않으면 실주문으로 가지 않습니다(autoExecute 계정은 예외 — 단 REAL 자동매매는 사전에 MOCK 졸업 게이트를 통과한 계정만).

---

📖 핵심 클래스 라인별 심화

A. BacktestService — 사내 백테스트 엔진 (Java)

이 클래스의 정체를 먼저 못박습니다. 파일 상단 주석:

// BacktestService.java:33-42
/**
 * 무한매수법(LOC) + VR 밸류 리밸런싱 백테스트 엔진.
 * Frontend lib/backtest.js의 알고리즘과 1:1 동일.
 * 결과:
 *  - StrategyTrade rows (source=BACKTEST) 재생성
 *  - StrategyBacktestSummary 1건 upsert
 *  - 마지막 날의 StrategyState 1건 upsert
 *  - 마지막 날의 DailySignal 1건 upsert
 */

• 이건 Python을 부르지 않습니다. 무한매수/VR 알고리즘을 순수 Java for-loop로 직접 돌립니다. (vectorbt 기반 6전략은 별개의 경로 B.)

A-1. 진입점 runFor — BacktestService.java:66-124

// BacktestService.java:66-75
@Transactional
public StrategyBacktestSummary runFor(Strategy s) {
    var ohlc = marketDataService.getDaily(s.getTicker(), s.getStartDate());
    if (ohlc.size() < 30) {
        log.warn("[Backtest] {} insufficient OHLC ({} rows)", s.getCode(), ohlc.size());
        return null;
    }
    Result r = s.getMethod() == Strategy.Method.INFINITE_BUY
            ? runInfiniteBuy(s, ohlc)
            : runValueRebalancing(s, ohlc);

• 무엇을 하나: ① 일봉을 가져오고 ② 30개 미만이면 포기(null) ③ 전략 method에 따라 두 엔진 중 하나를 호출.
• 왜 30개 컷: 30거래일도 안 되는 데이터로는 CAGR·MDD가 의미 없습니다(통계적 노이즈). 컨트롤러는 이 null을 받아 HTTP 422("insufficient market data") 로 변환합니다(StrategyController:320).
• 초보 포인트: ? : 는 삼항연산자 — "조건 ? 참일때값 : 거짓일때값". method == INFINITE_BUY 면 무한매수, 아니면 VR.

// BacktestService.java:77-94 (요약)
    // 1) trades 재생성 (백테스트 source만)
    tradeRepo.deleteByStrategyIdAndSource(s.getId(), StrategyTrade.Source.BACKTEST);
    tradeRepo.saveAll(r.trades);
    // 2) state upsert (마지막 날)
    var last = r.equityCurve.get(r.equityCurve.size() - 1);
    var stateOpt = stateRepo.findByStrategyIdAndAsOfDate(s.getId(), last.date);
    StrategyState st = stateOpt.orElseGet(() -> StrategyState.builder()
            .strategy(s).asOfDate(last.date).build());
    ... st.setCashUsd(...); st.setShares(...); ...
    stateRepo.save(st);

• 재생성 패턴: 백테스트를 다시 돌릴 때마다 기존 BACKTEST trades를 싹 지우고 새로 저장. 멱등하게 만드는 방법(여러 번 돌려도 trades가 누적되지 않음). ⚠️ source=BACKTEST 만 지웁니다 — 실제 체결(LIVE)·수동(MANUAL) trades는 건드리지 않음(실거래 기록 보존).
• upsert 패턴: findBy... 로 기존 행을 찾고, 없으면(orElseGet) 새로 빌드. 있으면 그 행의 필드만 갱신. → 전략×날짜당 state/summary/signal이 딱 1건만 유지(DailySignal의 uq_signal_strategy_date 유니크와 정합).

// BacktestService.java:104
    summary.setTrustScore(computeTrustScore(r.metrics));

• 여기 computeTrustScore는 사내 간이 점수입니다(아래 A-4). 경로 B의 Python Trust Score(/trust, Walk-Forward+Regime 기반)와는 다른 것임에 주의.

// BacktestService.java:110-121
    // 4) 오늘의 시그널 upsert
    if (r.signal != null) {
        var sigOpt = signalRepo.findByStrategyIdAndAsOfDate(s.getId(), last.date);
        DailySignal sig = sigOpt.orElseGet(() -> DailySignal.builder()
                .strategy(s).asOfDate(last.date).build());
        sig.setSignal(r.signal.signal);
        ... sig.setTitle/Summary/Action ...
        // 신규 시그널이면 deliveredAt은 null로 두고 알림 스케줄러가 발송
        signalRepo.save(sig);
    }

• 시그널이 메일로 가는 연결고리: 새 시그널은 deliveredAt=null. DailySignalGenerator가 22:30에 dispatchPending으로 null인 것만 골라 메일 발송 후 시각을 채웁니다(중복 발송 방지).

A-2. 무한매수 엔진 runInfiniteBuy — BacktestService.java:128-200

// BacktestService.java:128-136
private Result runInfiniteBuy(Strategy s, List<MarketOhlcDaily> ohlc) {
    Params p = parseParams(s.getParamsJson());
    boolean crypto = isCryptoTicker(s.getTicker()); // 크립토는 분수 수량
    double principalUsd = s.getPrincipalKrw() / USD_KRW;
    double dailyBudget = principalUsd / p.splits;
    double cash = principalUsd, shares = 0, totalCost = 0;

• 무엇을: 원금(KRW)을 USD로 환산(USD_KRW=1300 고정 — :48에 "실시간 환율 API로 교체" TODO)하고, splits(기본 40)로 나눠 하루 예산을 정합니다. 라오어식 무한매수법의 핵심 = "원금을 40등분해 매일 조금씩".
• 초보 포인트: parseParams는 Strategy.paramsJson(예: {"splits":40,"sellTargetPct":10,...})을 Jackson ObjectMapper로 읽어 Params 객체로 변환(아래 A-3).

// BacktestService.java:145-157  (매일: 1) 먼저 매도 체크)
    if (shares > 0 && avg > 0) {
        double sellPx = avg * (1 + p.sellTargetPct / 100.0);
        if (high >= sellPx) {        // 그날 고가가 목표가를 찍었으면 익절
            double proceeds = shares * sellPx;
            double pnl = proceeds - totalCost;
            ... trades.add(SELL_TARGET) ...
            cash += proceeds; shares = 0; totalCost = 0;  // 사이클 리셋
        }
    }

• 평단(avg) 대비 +sellTargetPct%(기본 10%)에 매도 지정가를 걸고, 그날 고가가 그 가격을 건드리면 전량 익절. 익절하면 보유 0으로 리셋 → 새 사이클 시작.

// BacktestService.java:169-190  (매일: 2) 매수 — LOC 두 종류)
    } else if (cash >= dailyBudget * 0.05) {
        double newAvg = shares > 0 ? totalCost / shares : close;
        double upperLOC = newAvg * (1 + p.locUpperPct / 100.0);
        if (close <= newAvg) {                         // 평단 이하 → 1회차 풀매수
            double qty = crypto ? dailyBudget / close : Math.floor(dailyBudget / close);
            ... kind = LOC_AVG ...
        } else if (close <= upperLOC) {                // 평단~상단 → 0.5회차
            double qty = crypto ? (dailyBudget/2.0)/close : Math.floor((dailyBudget/2.0)/close);
            ... kind = LOC_UPPER ...
        }
    }

• LOC(Limit On Close, 종가 지정가) 두 단계: 종가가 평단 이하면 하루치 풀매수, 평단~상단 사이면 절반 매수, 상단 위면 매수 안 함. "쌀수록 더 산다"는 분할매수 철학.
• ⚠️ 크립토 vs 주식: 주식은 Math.floor(정수 주식 수)지만, 고가 코인은 정수로 내림하면 0주가 되어버려 크립토는 분수 수량(dailyBudget/close)을 그대로 씁니다.

A-3. 파라미터 파싱 parseParams — BacktestService.java:377-396

// BacktestService.java:380-393 (발췌)
    try {
        JsonNode n = om.readTree(json);
        if (n.has("splits")) p.splits = n.get("splits").asInt(40);
        if (n.has("sellTargetPct")) p.sellTargetPct = n.get("sellTargetPct").asInt(10);
        ...
    } catch (Exception e) {
        log.warn("paramsJson parse failed: {}", e.getMessage());
    }
    return p;

• 방어적 파싱: 각 키가 있을 때만 덮어쓰고(if n.has), 파싱이 깨져도 예외를 삼켜 기본값 Params로 폴백. → 사용자가 paramsJson을 망가뜨려도 백테스트가 죽지 않습니다(안정성 > 엄격성).
• 초보 포인트: asInt(40)의 인자 40은 "값이 없거나 숫자가 아니면 40을 써라"는 기본값.

A-4. 사내 간이 Trust Score computeTrustScore — BacktestService.java:351-355

// BacktestService.java:351-355
private int computeTrustScore(Metrics m) {
    double mddAbs = Math.abs(m.mddPct);
    double raw = 70 - mddAbs * 0.7 + m.cagrPct * 0.4 + (m.winRate - 0.5) * 30;
    return Math.max(0, Math.min(100, (int) Math.round(raw)));
}

• 70점에서 출발해 낙폭(MDD)이 클수록 깎고, 수익(CAGR)·승률이 높을수록 더함. 0~100으로 클램프.
• ⚠️ 이건 경험적 공식입니다. 경로 B의 Python /trust(Walk-Forward + Regime + 파라미터 섭동으로 과적합까지 보는 정밀 채점)와는 깊이가 다릅니다. UI에 둘 다 "Trust Score"로 보일 수 있으니 출처를 구분하세요.

---

B. AnalyticsClient — Python 사이드카 호출 (서킷브레이커 + 재시도)

이 클래스가 백엔드(Java)↔Analytics 엔진(Python) 의 유일한 다리입니다. 호출 대상 엔드포인트는 06_api/main.md 에서 라인별로 해설됩니다.

B-1. 설정 주입 + CB/Retry 등록 — AnalyticsClient.java:38-61

// AnalyticsClient.java:38-61 (발췌)
@Value("${app.analytics.base-url}")          private String baseUrl;
@Value("${app.analytics.internal-token}")    private String token;
@Value("${app.analytics.timeout-sec:30}")    private int timeoutSec;
@Value("${app.analytics.heavy-timeout-sec:120}") private int heavyTimeoutSec;
...
@PostConstruct
void init() {
    circuitBreaker = cbRegistry.circuitBreaker("analytics");
    retry = retryRegistry.retry("analytics");
}

• baseUrl/token은 application.properties에서 주입:
  • app.analytics.base-url=${ANALYTICS_BASE_URL:http://localhost:8001} — 환경변수 미설정 시 기본 localhost:8001.
  • app.analytics.internal-token=${ANALYTICS_INTERNAL_TOKEN:dev-internal-token-change-me} — 기본값이 뻔하므로 prod 필수 변경(엔진 쪽 require_internal_token이 검사).
• @PostConstruct init() — 빈이 만들어진 직후, application.properties의 instances.analytics.* 설정(윈도우 10·실패율 50%·OPEN 30초·재시도 3회/2초)으로 등록된 CB·Retry를 이름("analytics")으로 꺼내옵니다.
• 일반 호출은 30초, 무거운 연산(Trust/Regime/Lean)은 120초 타임아웃으로 분리.

B-2. 실제 1회 호출 callOnce — 4xx/5xx 분기 — AnalyticsClient.java:80-118

// AnalyticsClient.java:85-107 (발췌)
HttpRequest.Builder b = HttpRequest.newBuilder()
        .uri(URI.create(baseUrl + path))
        .header("Content-Type", "application/json; charset=utf-8")
        .header("Accept", "application/json")
        .header("X-Internal-Token", token)            // ★ 사이드카 인증 헤더
        .timeout(Duration.ofSeconds(timeoutSeconds));
...
HttpResponse<String> resp = client().send(req, HttpResponse.BodyHandlers.ofString());
if (resp.statusCode() >= 400 && resp.statusCode() < 500) {
    // 4xx — 클라이언트 오류: 재시도 무의미, CB 카운트 제외
    throw new AnalyticsException.ClientError("analytics client error HTTP " + ...);
}
if (resp.statusCode() >= 500) {
    throw new AnalyticsException("analytics server error HTTP " + ...);
}
return om.readTree(resp.body());

• 핵심 설계 — 오류를 두 종류로 나눔:
  • 4xx → ClientError(별도 하위 예외): "내가 보낸 게 틀렸다". 재시도해도 똑같으니 재시도·CB 카운트에서 제외(application.properties의 ignore-exceptions에 등록).
  • 5xx → AnalyticsException: "서버가 잠깐 맛이 갔다". 재시도 대상.
• X-Internal-Token 헤더가 바로 사이드카 인증. 엔진의 require_internal_token과 짝.
• 초보 포인트: om.readTree(...)는 응답 JSON 문자열을 JsonNode(트리)로 파싱. 백엔드는 이 JsonNode를 그대로 프론트로 흘려보냅니다(아래 함정 절의 Jackson 이슈 주의).

B-3. CB+Retry 합성 + 폴백 call / executeDecorated — AnalyticsClient.java:121-150

// AnalyticsClient.java:121-127
private JsonNode call(String path, String method, Object body) {
    Supplier<JsonNode> decorated = CircuitBreaker.decorateSupplier(
            circuitBreaker,
            Retry.decorateSupplier(retry, () -> callOnce(path, method, body))
    );
    return executeDecorated(decorated, method, path);
}

• 데코레이터 합성 순서가 중요: callOnce를 Retry로 먼저 감싸고, 그걸 다시 CircuitBreaker로 감쌉니다. → 안쪽에서 3번 재시도가 모두 실패하면 그 "1번의 최종 실패"가 CB에 1건으로 집계됩니다.

// AnalyticsClient.java:138-150
private JsonNode executeDecorated(Supplier<JsonNode> decorated, String method, String path) {
    try {
        return decorated.get();
    } catch (AnalyticsException.ClientError e) {
        throw e; // 클라이언트 오류는 그대로 전파
    } catch (CallNotPermittedException e) {
        log.warn("analytics circuit OPEN — fast fail for {} {}", method, path);
        throw new AnalyticsException("Analytics 서비스가 일시적으로 사용 불가합니다. 잠시 후 다시 시도해주세요.");
    } catch (Exception e) {
        if (e instanceof AnalyticsException ae) throw ae;
        throw new AnalyticsException("analytics call failed: " + e.getMessage(), e);
    }
}

• CallNotPermittedException = "회로가 OPEN 상태라 호출 자체가 거부됨". 이때 백엔드는 타임아웃을 기다리지 않고 즉시 친절한 한국어 메시지로 실패 → 빠른 폴백. CLAUDE.md의 "ANALYTICS_BASE_URL 미설정 시 CB로 빠르게 폴백 — 시그널 없이 동작"이 바로 이 메커니즘.

B-4. heavy 호출은 재시도 없음 callHeavy — AnalyticsClient.java:130-136

// AnalyticsClient.java:130-136
private JsonNode callHeavy(String path, String method, Object body) {
    Supplier<JsonNode> decorated = CircuitBreaker.decorateSupplier(
            circuitBreaker, () -> callOnceHeavy(path, method, body));   // Retry 없음
    return executeDecorated(decorated, method, path);
}

• Trust/Regime/Lean처럼 연산이 수십 초~수 분 걸리는 호출은 재시도가 역효과(부하 폭증). 그래서 CB만 두르고 재시도는 뺍니다. 타임아웃도 120초로 길게.

B-5. health 체크는 CB 우회 — AnalyticsClient.java:152-160

// AnalyticsClient.java:153-159
public boolean isHealthy() {
    try {
        JsonNode n = callOnce("/health", "GET", null); // CB 우회
        return "ok".equals(n.path("status").asText());
    } catch (Exception e) { return false; }
}

• 의도적으로 call(CB 래핑)이 아니라 callOnce(생호출)를 씁니다. 회로가 OPEN이어도 "정말 살아났나?"를 직접 확인하기 위함. 죽었으면 조용히 false.

B-6. 엔드포인트별 메서드 ↔ 엔진 매핑

AnalyticsClient 메서드	호출	엔진(main.py) 핸들러	해설 문서
backtest(...) :163	call	POST /backtest	vbt_engine.md
todaySignals(...) :243	call	POST /signals/today	vbt_engine+xgb_signal
trainModel(...) :252	call	POST /models/train	xgb_signal.md
walkForward(...) :257	call	POST /robust/walk-forward	walkforward.md
regime(...) :287	callHeavy	POST /regime	regime.md
trustScore(...) :313	callHeavy	POST /trust	trust_score.md
infiniteBuying(...) :333	call	POST /backtest/infinite-buying	infinite_buying.md
leanBacktest(...) :172	callHeavy	POST /lean/backtest	07_lean/runner.md

• 주의: todaySignals//signals/today는 AnalyticsClient에는 존재하지만(경로 B), 실제 22:30 DailySignalGenerator는 이걸 호출하지 않고 사내 BacktestService(경로 A) 로 시그널을 만듭니다. /signals/today는 주로 AnalyticsController를 통해 프론트의 "Developer Studio"용으로 노출됩니다.
• ⚠️ regime은 옵션에서 키를 화이트리스트로 골라 넣습니다(AnalyticsClient:293) — Pydantic이 unknown 키를 거부하기 때문. trustScore도 동일(:319).

---

C. DailySignalGenerator — 일일 잡: 백테스트 → 시그널 → 제안

C-1. 스케줄 진입점 runDaily — DailySignalGenerator.java:53-99

// DailySignalGenerator.java:52-74 (발췌)
@Scheduled(cron = "0 30 22 * * MON-FRI", zone = "Asia/Seoul")
public void runDaily() {
    try { marketDataService.scheduledRefresh(); } catch (Exception e) { log.warn(...); }   // 1) 시세 신선화
    var actives = strategyRepo.findByActiveTrue();
    int ok = 0, fail = 0;
    for (var s : actives) {
        try { backtestService.runFor(s); ok++; }                                            // 2) 전체 백테스트
        catch (Exception e) { fail++; log.warn("[DailySignal] {} failed: {}", s.getCode(), e.getMessage()); }
    }

• 에러 격리: 각 전략을 개별 try/catch로 감싸 한 전략이 터져도 나머지는 계속(견고한 배치). 엔진 signals_today의 "한 종목 실패해도 다음 종목 계속" 패턴과 같은 철학.
• 왜 22:30: 주석(:28-29)에 "미국장 마감(KST 익일 새벽 6시)보다 앞서 발송 → 다음날 아침 사용자가 행동"이라고 명시.

// DailySignalGenerator.java:76-98 (발췌)
    int sent = emailAlertService.dispatchPending(LocalDate.now());        // 3) 미발송 메일 일괄
    int created = createProposalsFor(LocalDate.now());                    // 4) BUY → OrderProposal
    int refreshed = refreshAlphaWorkspaces();                            // 5) Alpha 워크스페이스 재실행

• 3·4·5단계도 각각 try/catch로 감싸 한 단계 실패가 다음 단계를 막지 않음.

C-2. ★ BUY 시그널 → OrderProposal createProposalsFor — DailySignalGenerator.java:128-201

// DailySignalGenerator.java:128-141 (발췌)
int createProposalsFor(LocalDate asOf) {
    var todays = signalRepo.findByAsOfDateFetchStrategyUser(asOf);   // strategy/user 즉시로딩
    for (DailySignal sig : todays) {
        if (sig.getSignal() != DailySignal.Signal.BUY) continue;      // BUY만 제안화
        var strategy = sig.getStrategy();
        Long userId = strategy.getUser().getId();
        boolean crypto = isCrypto(strategy.getTicker());
        BrokerAccount target = pickTradingAccount(userId, crypto);    // 거래가능 계정 선택
        if (target == null) continue;                                 // 없으면 스킵

• BUY일 때만 주문 제안을 만듭니다(HOLD/WATCH/PAUSE는 메일만).
• findByAsOfDateFetchStrategyUser — fetch join으로 strategy·user를 즉시 로딩. 주석(:129)대로 open-in-view=false 환경에서 트랜잭션 밖 lazy 접근(LazyInitializationException)을 방지하는 의도적 쿼리.

// DailySignalGenerator.java:143-155 (발췌)
    int qtyInt;  java.math.BigDecimal qtyDec = null;
    if (crypto) {
        double price = cryptoPrice(target, strategy.getTicker());
        if (price <= 0) { ...스킵... }
        double orderUsdt = cryptoOrderUsdt(strategy);
        qtyDec = BigDecimal.valueOf(orderUsdt / price).setScale(8, RoundingMode.DOWN);
        if (qtyDec.signum() <= 0) { ...스킵... }
        qtyInt = 1; // NOT NULL placeholder (실수량은 qtyDecimal)
    } else {
        qtyInt = parseFirstBuyShares(strategy.getParamsJson());
    }

• 수량 산정 — 자산군 분기: 주식은 정수 주식 수(firstBuyShares), 크립토는 명목가(USDT)÷현재가 → 분수(소수 8자리 내림). 크립토는 qtyInt=1을 placeholder로 채우고 실수량은 qtyDecimal에(엔티티가 qty NOT NULL이라).

// DailySignalGenerator.java:157-178 (발췌)
    // 중복 체크: 같은 sourceSignalId로 살아있는 제안이 있으면 skip
    boolean dup = proposalRepo.findByUserIdOrderByCreatedAtDesc(userId).stream()
            .anyMatch(p -> sig.getId().equals(p.getSourceSignalId())
                    && !"REJECTED".equals(p.getStatus())
                    && !"EXPIRED".equals(p.getStatus())
                    && !"EXEC_FAILED".equals(p.getStatus()));
    if (dup) continue;
    OrderProposal saved = proposalRepo.save(OrderProposal.builder()
            .userId(userId).brokerAccountId(target.getId())
            .ticker(strategy.getTicker()).side("BUY")
            .qty(qtyInt).qtyDecimal(qtyDec)
            .source("SIGNAL").sourceSignalId(sig.getId())
            .status("PENDING").expiresAt(LocalDateTime.now().plusHours(24))
            .build());

• 멱등 — 시그널당 제안 1건: 같은 sourceSignalId로 이미 살아있는(REJECTED/EXPIRED/EXEC_FAILED가 아닌) 제안이 있으면 새로 안 만듭니다. → 잡이 하루 여러 번 돌아도 중복 제안 방지.
• 항상 PENDING + 24시간 만료: 자동으로 실주문 안 됨. OrderProposalExpiryJob이 만료 처리. (엔티티 OrderProposal.java:12-23의 보안 원칙과 정합.)

// DailySignalGenerator.java:181-198 (발췌)
    if (Boolean.TRUE.equals(target.getAutoExecute())) {
        var res = exec.execute(saved, target, true);   // ProposalExecutionService
        if (!res.ok()) log.warn("[auto-exec] proposal {} 자동체결 보류: {}", saved.getId(), res.error());
        else log.info("[auto-exec] proposal {} 자동체결 접수 ...", ...);
    }

• 계정이 autoExecute=ON이면 사람 승인 없이 즉시 체결 시도. 단 주석(:182-183)대로 모든 안전 게이트(kill-switch·tradingEnabled·한도)는 ProposalExecutionService가 강제하고, REAL 계정의 autoExecute는 MOCK 졸업 게이트(2주+20회) 를 이미 통과한 상태만 켤 수 있습니다.

C-3. 거래 계정 선택 pickTradingAccount — DailySignalGenerator.java:204-213

// DailySignalGenerator.java:204-213
private BrokerAccount pickTradingAccount(Long userId, boolean crypto) {
    var want = crypto ? BrokerAccount.BrokerType.BINANCE : BrokerAccount.BrokerType.KIS;
    return brokerAccountRepo.findAllByUserIdOrderByEnvAsc(userId).stream()
            .filter(a -> Boolean.TRUE.equals(a.getTradingEnabled()))
            .filter(a -> a.getBrokerType() == want)
            .sorted((a, b) -> Boolean.compare(
                    b.getEnv() == BrokerAccount.Env.REAL, a.getEnv() == BrokerAccount.Env.REAL))
            .findFirst().orElse(null);
}

• 자산군→브로커 라우팅: 크립토는 Binance, 주식은 KIS. tradingEnabled=true인 계정만, REAL을 MOCK보다 우선(정렬). 적합 계정이 없으면 null(→ 제안 스킵).

---

D. SubscriptionService — 구독 등급·결제 멱등

⚠️ 이 파일의 일부 한글 주석은 인코딩이 깨져(mojibake) 보일 수 있습니다(예: ?ъ슜??). 코드 동작은 정상이며, 아래 해설은 실제 코드 로직 기준입니다.

D-1. 현재 등급 조회 currentTier — SubscriptionService.java:29-35

// SubscriptionService.java:29-35
@Transactional(readOnly = true)
public Subscription.Tier currentTier(Long userId) {
    return repo.findFirstByUserIdAndStatusOrderByExpiresAtDesc(userId, Subscription.Status.ACTIVE)
            .filter(s -> s.getExpiresAt() != null && s.getExpiresAt().isAfter(LocalDateTime.now()))
            .map(Subscription::getTier)
            .orElse(Subscription.Tier.FREE);
}

• 활성(ACTIVE)이고 아직 만료되지 않은 구독이 있으면 그 Tier(=PRO), 아니면 FREE. 만료 시각을 읽는 시점에 한 번 더 검사(만료 잡이 아직 안 돌았어도 실시간으로 정확).

D-2. 표시 등급 파생 deriveTierDisplay — SubscriptionService.java:52-57

// SubscriptionService.java:52-57
public static String deriveTierDisplay(Subscription sub) {
    if (sub == null) return "FREE";
    long amt = sub.getAmountKrw() != null ? sub.getAmountKrw() : 0L;
    if (amt >= 19900L) return "PREMIUM";
    return "STANDARD";
}

• 사전지식 4번의 핵심: DB Tier는 PRO 단일이지만, 결제 금액으로 STANDARD/PREMIUM을 런타임 파생. 19,900원 이상이면 PREMIUM.

D-3. ★ Pro 활성화 (멱등) activatePro — SubscriptionService.java:67-93

// SubscriptionService.java:67-93 (발췌)
@Transactional
public Subscription activatePro(Long userId, String paymentKey, String orderId, long amountKrw) {
    Subscription dup = findByPaymentKey(paymentKey);                       // M8 사전 멱등 체크
    if (dup != null) { log.info("Pro activate 멱등 처리 ..."); return dup; }
    LocalDateTime now = LocalDateTime.now();
    Subscription sub = Subscription.builder()
            .userId(userId).tier(Subscription.Tier.PRO).status(Subscription.Status.ACTIVE)
            .startedAt(now).expiresAt(now.plusDays(30))                    // 30일
            .tossPaymentKey(paymentKey).tossOrderId(orderId).amountKrw(amountKrw)
            .build();
    Subscription saved = repo.save(sub);
    userRepository.findById(userId).ifPresent(u -> {
        u.setUserType(amountKrw >= 19900L ? User.UserType.PREMIUM : User.UserType.STANDARD);  // User 등급 동기화
        userRepository.save(u);
    });
    return saved;
}

• 멱등 1차 방어: 같은 결제키로 이미 구독이 있으면 새로 INSERT하지 않고 기존 것 반환(이중 등급 부여 방지).
• 구독 기간 30일. 동시에 User.UserType도 금액에 맞춰 갱신(STANDARD/PREMIUM) — 구독과 사용자 등급을 함께 동기화.

D-4. 만료 일괄 처리 expireAllDue — SubscriptionService.java:96-109

// SubscriptionService.java:96-109
@Scheduled(cron = "0 0 * * * *")   // 매시 정각
@Transactional
public int expireAllDue() {
    var due = repo.findByStatusAndExpiresAtBefore(Subscription.Status.ACTIVE, LocalDateTime.now());
    for (var s : due) {
        s.setStatus(Subscription.Status.EXPIRED);
        userRepository.findById(s.getUserId()).ifPresent(u -> {
            u.setUserType(User.UserType.FREE); userRepository.save(u);   // FREE 강등
        });
    }
    return due.size();
}

• 매시 정각 만료된 활성 구독을 EXPIRED로 바꾸고 사용자를 FREE로 강등. (단 currentTier가 읽는 시점에도 만료를 검사하므로, 이 잡이 늦어도 사용자에게는 정확히 보임 — 이중 안전.)

---

E. SubscriptionController — 결제 confirm + 금액 위변조 차단

E-1. 허용 금액 화이트리스트 — SubscriptionController.java:29-32

// SubscriptionController.java:29-32
private static final java.util.Map<Long, String> VALID_PLANS = java.util.Map.of(
        9900L,  "STANDARD",
        19900L, "PREMIUM"
);

• 금액 위변조 방지의 핵심: 프론트가 보낸 금액이 이 Map에 없으면 거부. 사용자가 결제 금액을 1원으로 조작해 PREMIUM을 받는 공격을 차단.

E-2. ★ confirm — 3중 멱등 방어 — SubscriptionController.java:62-111

// SubscriptionController.java:67-84 (발췌)
String paymentKey = String.valueOf(body.get("paymentKey"));
long   amount     = ((Number) body.getOrDefault("amount", 0)).longValue();
if (!VALID_PLANS.containsKey(amount)) { ...badRequest("허용되지 않은 결제 금액")... }   // ① 금액 검증
if (paymentKey == null || paymentKey.isBlank() || "null".equals(paymentKey)) { ...badRequest... }
// M8 멱등성 ①: 이미 처리된 결제키면 Toss 재confirm 없이 기존 구독 반환
Subscription already = subscriptionService.findByPaymentKey(paymentKey);
if (already != null) { return ResponseEntity.ok(idempotentBody(already, true)); }

// SubscriptionController.java:86-106 (발췌)
try {
    JsonNode result = toss.confirm(paymentKey, orderId, amount);                  // ② Toss 서버 confirm
    if (!"DONE".equalsIgnoreCase(result.path("status").asText())) { ...badRequest... }
    Subscription sub = subscriptionService.activatePro(uid, paymentKey, orderId, amount);
    return ResponseEntity.ok(Map.of("tier", VALID_PLANS.get(amount), ...));
} catch (DataIntegrityViolationException dup) {
    // 동시 confirm 경합 — DB 유니크(uq_subscription_toss_payment_key)에 막힘 → 먼저 처리된 구독 재사용
    Subscription existing = subscriptionService.findByPaymentKey(paymentKey);
    if (existing != null) { return ResponseEntity.ok(idempotentBody(existing, true)); }
    ...
}

• 3중 멱등 방어(M8):
  1. 애플리케이션 사전체크(findByPaymentKey != null) — 흔한 더블클릭/새로고침.
  2. 서비스 레이어 재확인(activatePro 안의 dup 체크).
  3. DB 유니크 제약(uq_subscription_toss_payment_key) — 동시(race) 두 요청이 사전체크를 동시에 통과해도, 두 번째 INSERT가 DataIntegrityViolationException으로 막히고, catch에서 먼저 만들어진 구독을 재사용.
• → "사전체크는 흔한 경우를, DB 제약은 동시성 경합을 잡는다"는 견고한 멱등 설계. (엔티티 Subscription.java:14-17의 유니크 제약과 정합.)

---

F. StrategyController — 전략 CRUD + 소유권 격리

F-1. 소유권 격리 패턴 (모든 엔드포인트 공통) — 예: detail StrategyController.java:74-82

// StrategyController.java:74-82
@GetMapping("/{id}")
public ResponseEntity<?> detail(@PathVariable Long id) {
    Long uid = AuthContext.currentUserId();
    if (uid == null) return unauthorized();
    return strategyRepository.findById(id)
            .filter(s -> s.getUser().getId().equals(uid))     // ★ 소유권 검증
            .<ResponseEntity<?>>map(s -> ResponseEntity.ok(StrategyDto.from(s)))
            .orElse(ResponseEntity.notFound().build());
}

• IDOR 차단: id로 조회한 뒤 s.getUser().getId().equals(uid)로 "이 전략이 정말 내 것인가" 를 검사. 남의 전략이면 404(존재 자체를 숨김). 이 패턴이 detail/trades/states/signals/summary/update/delete/backtest 전부에 반복됩니다.

F-2. 생성 검증 create — StrategyController.java:157-186

// StrategyController.java:160-168 (발췌)
if (req.code() == null || req.code().isBlank()) return badRequest("code 필수");
if (req.ticker() == null || req.ticker().isBlank()) return badRequest("ticker 필수");
if (req.method() == null) return badRequest("method 필수");
if (req.principalKrw() == null || req.principalKrw() <= 0) return badRequest("principalKrw 양수 필수");
if (strategyRepository.existsByUserIdAndCode(uid, req.code())) {
    return ResponseEntity.status(HttpStatus.CONFLICT).body(Map.of("error", "이미 존재하는 code"));
}

• 필수값 + 사용자별 code 유니크(409 Conflict). principalKrw > 0을 강제해 "원금 분리" 규칙(엔티티 Strategy.java:57)을 입력 단에서 보장.

F-3. 수정 시 불변 필드 update — StrategyController.java:188-205

// StrategyController.java:203
    // ticker/code/method는 운영 중 변경 위험 → 변경 금지

• name/regime/goal/paramsJson/principal/startDate/benchmark/active만 수정 가능. ticker·code·method는 일부러 갱신 안 함 — 운영 중 종목·전략방식을 바꾸면 기존 trades/state와 불일치가 생기기 때문.

F-4. 백테스트 수동 트리거 runBacktest — StrategyController.java:312-328

// StrategyController.java:312-327 (발췌)
@PostMapping("/{id}/backtest")
public ResponseEntity<?> runBacktest(@PathVariable Long id) {
    ... 소유권 검증 ...
    try {
        var summary = backtestService.runFor(s);
        if (summary == null) return ResponseEntity.status(HttpStatus.UNPROCESSABLE_ENTITY)
                .body(Map.of("error", "insufficient market data"));      // 30개 미만 → 422
        return ResponseEntity.ok(StrategyBacktestSummaryDto.from(summary));
    } catch (Exception e) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(...);
    }
}

• BacktestService.runFor의 null(데이터 부족)을 422로, 예외를 500으로 변환. CLAUDE.md API 표의 POST /api/strategies/{id}/backtest가 이 메서드.

---

G. AnalyticsController — Python 브리지의 얇은 노출

// AnalyticsController.java:39-50 (발췌)
@PostMapping("/backtest")
public ResponseEntity<JsonNode> backtest(@RequestBody Map<String, Object> body) {
    String ticker = (String) body.get("ticker");
    if (ticker == null || ticker.isBlank()) return ResponseEntity.badRequest().build();
    String strategy = (String) body.getOrDefault("strategy", "sma_cross");
    Map<String, Object> extra = new HashMap<>(body);
    extra.remove("ticker"); extra.remove("strategy");
    return ResponseEntity.ok(analytics.backtest(ticker, strategy, extra));   // → 경로 B
}

• 얇은 위임(thin pass-through): 입력만 살짝 정리해 AnalyticsClient(경로 B)로 넘기고, 반환된 JsonNode를 그대로 프론트에. 계산은 전부 Python:8001에서.
• /api/analytics/**는 Spring Security가 JWT를 요구하고, 그 안에서 AnalyticsClient가 다시 X-Internal-Token으로 사이드카 인증 → 이중 인증 게이트.

---

⚠️ 함정·보안 주의

1. (M8) 결제 멱등성 — 3중 방어가 필요한 이유

• 사전체크(findByPaymentKey)만으로는 동시 요청을 못 막습니다(두 요청이 동시에 "없음"을 읽고 둘 다 INSERT). 그래서 DB 유니크 제약 uq_subscription_toss_payment_key 이 최종 방어선이고, 컨트롤러가 DataIntegrityViolationException을 잡아 멱등 응답으로 바꿉니다(SubscriptionController.java:98-104). 셋 중 하나라도 빠지면 이중 구독/과금 위험.

2. Jackson JsonNode 직렬화 (Spring Boot 4 = Jackson 3 기본)

• AnalyticsClient는 내부적으로 Jackson 2의 com.fasterxml.jackson.databind.JsonNode 로 응답을 파싱하고, AnalyticsController가 이 JsonNode를 그대로 반환합니다.
• ⚠️ 메모리 기록(project_springboot4_jackson_jsonnode_bug.md)대로 Spring Boot 4는 Jackson 3가 기본이라, 핸들러가 Jackson 2 JsonNode를 반환하면 모든 키가 빈 bean 속성으로 깨져 직렬화될 수 있습니다. analytics 응답이 프론트에서 {}처럼 비어 보이면 이 원인을 의심하세요(해결: 응답을 문자열/Map로 변환하거나 Jackson 3 JsonNode 사용).

3. ANALYTICS_BASE_URL 미설정 → CB 빠른 폴백

• 환경변수 미설정이면 base-url이 http://localhost:8001로 기본 동작합니다(application.properties:101). Python이 안 떠 있으면 ConnectException → 재시도 3회 실패 → 서킷 OPEN → 이후 30초간 즉시 실패. 백엔드는 안 죽지만 경로 B 기능(정밀 백테스트·Trust·Regime)이 비활성. 단 경로 A(무한매수/VR 백테스트·일일 시그널)는 Python과 무관하게 계속 동작합니다.

4. internal-token 기본값이 뻔함

• dev-internal-token-change-me가 기본값(application.properties:102). prod에서 ANALYTICS_INTERNAL_TOKEN을 안 바꾸면 누구나 :8001을 직접 호출 가능. prod 필수 변경.

5. USD_KRW = 1300.0 하드코딩

• BacktestService.java:48의 환율이 상수입니다(TODO: 실시간 API). 백테스트의 원금 환산·KRW 평가액이 실제 환율과 어긋날 수 있음. 시그널의 USDT 명목가 계산(DailySignalGenerator:226)도 1300 고정.

6. 사내 TrustScore vs Python TrustScore 혼동

• BacktestService.computeTrustScore(간이 경험식)와 /trust(Walk-Forward+Regime 정밀)는 다른 점수입니다. UI에서 둘 다 "Trust Score"로 보일 수 있으니 출처를 명확히.

7. OrderProposal은 항상 PENDING으로 시작

• 자동 시그널이 제안을 만들어도 승인 전 실주문 금지(엔티티 OrderProposal.java:18-22). autoExecute 계정만 예외이며, 그조차 kill-switch·졸업게이트 등 ProposalExecutionService의 게이트를 통과해야 함.

8. BacktestService의 와일드카드 import

• BacktestService.java:4-19가 거의 모든 도메인 엔티티/레포지토리를 *로 import합니다. 실제로 쓰는 건 strategy 도메인뿐 — 컴파일엔 무해하지만 가독성·결합도 측면의 정리 대상(고도화).

---

🚀 고도화 아이디어

• 실시간 환율: USD_KRW 상수를 환율 API(또는 캐시된 MarketDataService)로 교체 → 백테스트·시그널 명목가 정확도 향상. 한 줄 상수가 여러 계산에 퍼져 있어 좋은 리팩터 실습.
• 경로 A↔B 통합 시그널: 현재 일일 시그널은 사내 Java(경로 A)로만 생성. AnalyticsClient.todaySignals(XGBoost 확률+SHAP)를 합쳐 "규칙 시그널 + ML 확률"을 한 DailySignal에 담으면 설명력 강화. 엔진 /signals/today(main.md I절)가 이미 3엔진 합성을 지원.
• CB 폴백 캐시: 회로 OPEN 시 마지막 성공 응답을 캐시해 "오래된 값이라도" 보여주기(stale-while-revalidate). 지금은 즉시 실패만.
• 타이밍 안전 토큰 비교: 내부 토큰 비교를 MessageDigest.isEqual(상수시간)로 — 엔진 쪽 hmac.compare_digest 권장과 대칭.
• 구독 Tier 정규화: STANDARD/PREMIUM을 금액 파생이 아니라 DB enum/컬럼으로 승격하면 가격 변경 시 과거 구독 표시가 안정. CLAUDE.md의 EXPERT 플랜 확장도 수월.
• 백테스트 비동기화: backtest-all이 동기 루프라 전략이 많으면 응답 지연. 잡 큐(또는 @Async)로 분리하고 진행률을 폴링(Lean backtest/start+status 패턴 참고).
• StrategyBacktestSummary에 벤치마크 대비 알파: 현재 절대 성과만. benchmark 종목 대비 초과수익을 더하면 "그냥 지수보다 나은가?" 평가 가능(엔진 compute_metrics의 SPY 벤치마크 패턴 차용).

---

📚 용어 사전 (이 파트 한정)

용어	뜻
경로 A / 경로 B	A=사내 Java 백테스트(무한매수/VR, BacktestService), B=Python 위탁(vectorbt/XGBoost, AnalyticsClient)
사이드카(Sidecar)	본체 옆에 붙어 특정 작업을 전담하는 보조 프로세스(여기선 Analytics :8001)
서킷 브레이커(CircuitBreaker)	실패율이 임계치 넘으면 호출을 차단(OPEN)해 장애 전파를 막는 두꺼비집. CLOSED→OPEN→HALF_OPEN
Retry	일시적 실패에 한해 같은 호출을 N회 재시도(4xx는 제외)
CallNotPermittedException	회로가 OPEN이라 호출 자체가 거부됨 → 즉시 폴백
X-Internal-Token	백엔드가 사이드카에 "정식 백엔드"임을 증명하는 내부 인증 헤더
멱등성(Idempotency)	같은 요청을 여러 번 보내도 결과가 한 번과 동일(결제 중복 방지)
upsert	있으면 갱신, 없으면 삽입 — findBy…().orElseGet(build) 패턴
소유권 격리/IDOR	"이 리소스가 정말 내 것인가"를 검사해 남의 데이터 접근 차단
OrderProposal	시그널/수동에서 나온 주문 제안. PENDING으로 시작, 승인 전 실주문 금지
LOC (Limit On Close)	종가 기준 지정가 매수. 무한매수법의 핵심 주문 유형
VR (Value Rebalancing)	V값 밴드를 벗어나면 매수/매도해 목표 평가액으로 되돌리는 전략
Tier vs UserType	DB 구독은 FREE/PRO 단일, 표시(STANDARD/PREMIUM)는 결제 금액으로 파생
@Scheduled(cron)	정해진 시각에 자동 실행되는 잡(22:30 시그널, 매시 만료, 07:00 시세)
fetch join	lazy 연관을 쿼리에서 즉시 로딩해 트랜잭션 밖 LazyInitializationException 방지

strategy/service/broker — 브로커·주문 실행 (완전 라인별 해설)

원본: backend/src/main/java/com/DevBridge/devbridge/domain/strategy/
범위: service/broker/ (Broker·BrokerRouter·KIS/Binance 어댑터·ApiClient·ProposalExecutionService·OrderFillService·TradingControlService·PromotionGateService) + controller/ (BrokerAccount·BrokerOrder·OrderProposal) + entity/ (BrokerAccount·OrderProposal)
전제: Spring 기본 문법(@Service·@RestController·@Transactional·의존성 주입·JPA)은 00_spring_primer.md에서 다룹니다. 여기서는 도메인 로직에만 집중합니다.

---

📌 이 파트 한눈에

이 파트는 "여러 증권사에 주문을 넣는 단일 창구" 입니다. 우리 시스템은 두 군데에 진짜 돈을 보낼 수 있습니다 — KIS(한국투자증권, 미국주식) 와 Binance(바이낸스, 크립토 현물). 두 곳은 API 생김새가 완전히 다른데(한쪽은 KIS 게이트웨이 + TR-ID, 다른 쪽은 HMAC 서명 + 쿼리스트링), 이 파트는 그 차이를 하나의 Broker 계약으로 감싸서 윗단 코드가 "어느 증권사인지" 신경 쓰지 않게 만듭니다.

비유: 해외 송금 창구. 고객(주문 제안)은 "이 돈을 이 사람에게 보내줘"라고만 말합니다. 창구 직원(ProposalExecutionService)은 먼저 신분·한도·블랙리스트를 전부 확인하고(안전 게이트), 통과하면 환전소(BrokerRouter)에 넘깁니다. 환전소는 목적지가 미국이면 KIS 데스크로, 코인이면 Binance 데스크로 보냅니다. 각 데스크(어댑터)는 그 나라 양식으로 서류를 바꿔 실제로 송금합니다.

핵심 클래스 역할표:

클래스	한 줄 역할	비유
Broker (interface)	모든 증권사가 지켜야 할 공통 계약(주문/체결/잔고/시세 4개 메서드)	송금 표준 양식
BrokerRouter	brokerType(KIS/BINANCE)으로 알맞은 구현 선택	목적지별 데스크 안내
KisBrokerAdapter	Broker 계약 ↔ KisApiClient 변환 (정수화·rt_cd 해석)	미국 데스크
BinanceBrokerAdapter	Broker 계약 ↔ BinanceApiClient 변환 (필터 절삭·FUTURES 차단)	코인 데스크
KisApiClient	KIS OpenAPI 실제 호출(토큰·주문·잔고·시세). 수정 금지 원본	미국 송금망 단말
BinanceApiClient	Binance REST 실제 호출(HMAC 서명·주문·잔고). 수정 금지 원본	코인 송금망 단말
ProposalExecutionService	모든 주문이 반드시 지나는 단일 경로 + 안전 게이트 전부	창구 심사 데스크
OrderFillService	접수된 주문의 실제 체결 상태를 나중에 확인	송금 도착 확인
TradingControlService	전역 kill-switch(재시작 없이 전 주문 차단)	비상 정지 버튼
PromotionGateService	MOCK → REAL 승격 게이트(모의로 충분히 검증했나)	실거래 면허 시험

누가 이 파트를 호출하나? → ① 사용자가 화면에서 "승인" 버튼을 누르면 OrderProposalController.approve → ProposalExecutionService.execute. ② 사용자가 직접 주문 폼을 넣으면 BrokerOrderController.place. ③ 시그널 엔진(DailySignalGenerator)이 만든 자동 제안도 같은 ProposalExecutionService.execute로 모입니다. 즉 모든 길은 한 데스크로 모입니다.

---

🧠 사전 지식 (이거 모르면 막힘)

1) 브로커(Broker) = "주문을 받아 실제 시장에 넣어주는 증권사"

• 우리가 "SPY 1주 사줘"라고 해도, 진짜 주식시장에 주문을 넣는 건 증권사입니다. KIS·Binance가 그 증권사 역할.
• 각 브로커는 API 키(신분증)로 우리를 인증합니다. KIS는 appkey+appsecret, Binance는 apiKey+apiSecret.

2) OrderProposal(주문 제안) = "아직 실행 안 된 주문 초안"

• 시그널 엔진이나 사용자가 "이거 사면 어때?"라고 만든 초안입니다. 만든다고 바로 돈이 나가지 않습니다.
• 생명주기: PENDING(대기) → APPROVED(승인) → EXECUTED(접수됨) 또는 EXEC_FAILED(실패) / REJECTED(거절) / EXPIRED(만료).
• 핵심 보안 원칙: 시그널은 PENDING까지만 자동 생성, EXECUTED로 가려면 안전 게이트를 전부 통과해야 함.

3) MOCK vs REAL = "모의투자 vs 진짜 돈"

• MOCK = KIS 모의투자 / Binance 테스트넷. 가짜 돈, 연습용. 자유롭게 켜고 끔.
• REAL = KIS 실전 / Binance 메인넷. 진짜 돈이 나감. 그래서 켜기 전에 졸업 시험(승격 게이트)을 통과해야 함.
• 같은 env 이름이 두 브로커에서 의미가 다릅니다 — KIS는 도메인(URL)이 갈리고, Binance는 호스트가 갈림.

4) kill-switch(전역 거래 차단 스위치)

• "지금 당장 모든 주문을 막아라" 버튼. 운영 중 뭔가 잘못됐을 때 재시작 없이 모든 주문을 즉시 거부.
• 환경변수 TRADING_KILL_SWITCH=true가 기본값이고, TradingControlService가 런타임에 덮어쓸 수 있음.

5) 어댑터 패턴(Adapter Pattern)

• "모양이 다른 두 물건을 같은 콘센트에 꽂게 해주는 변환 플러그".
• KisApiClient/BinanceApiClient는 각자 생긴 대로 두고(원본 수정 금지), 그 위에 얇은 어댑터를 씌워 둘 다 Broker 인터페이스 모양으로 보이게 합니다. 윗단은 Broker만 알면 됩니다.

6) HMAC 서명 / 승인 TTL

• HMAC: 비밀키로 만든 "위조 불가 도장". Binance는 모든 사적 요청에 HMAC-SHA256(쿼리, secret) 서명을 붙여 "이 요청이 진짜 키 주인이 보냈음"을 증명합니다(secret 자체는 네트워크로 안 보냄).
• TTL(만료): OrderProposal은 보통 생성 +24시간 후 만료(expiresAt). OrderProposalExpiryJob이 5분마다 지난 것을 EXPIRED로 정리해, 오래된 초안이 실수로 실행되는 것을 막습니다.

---

🗺 요청 흐름도

 ① 자동 시그널                       ② 수동 승인                  ③ 직접 주문
 DailySignalGenerator          사용자 "승인" 클릭            사용자 주문 폼
      │ PENDING 생성                  │                           │
      ▼                              ▼                           ▼
  OrderProposal(PENDING) ──► OrderProposalController.approve   BrokerOrderController.place
                                     │                           │ (한도/검증 가드 직접 수행)
                                     ▼                           │
              ┌──────────────────────────────────────┐          │
              │   ProposalExecutionService.execute    │◄─ 단일 경로 ─┐ │
              │   ─ 안전 게이트 6중 ─                   │          │ │
              │   1. kill-switch                       │          │ │
              │   2. PENDING·만료 검증                  │          │ │  (place 는 자체 가드 후
              │   3. tradingEnabled 마스터 스위치       │          │ │   직접 BrokerRouter 호출)
              │   4. 1건당·일일 USD 한도                │          │ │
              │   5. KIS KRW 매수/매도 한도            │          │ │
              │   6. 손실 서킷브레이커                  │          │ │
              └──────────────────┬───────────────────┘          │ │
                                 │ 통과                          │ │
                                 ▼                               ▼ ▼
                         ┌───────────────┐
                         │  BrokerRouter │  brokerType 으로 분기
                         └───────┬───────┘
                       KIS │             │ BINANCE
                           ▼             ▼
                  KisBrokerAdapter   BinanceBrokerAdapter
                  · 수량 정수화        · LOT_SIZE/NOTIONAL 절삭
                  · 0원 지정가 방지     · FUTURES 차단
                  · rt_cd → 결과       · kill-switch 재확인
                           │             │
                           ▼             ▼
                   KisApiClient      BinanceApiClient
                   · 토큰 캐시(23h)    · HMAC-SHA256 서명
                   · 브라우저 UA       · X-MBX-APIKEY 헤더
                   · 거래소 폴백        · 429/418 백오프
                           │             │
                           ▼             ▼
                      🇺🇸 KIS 실주문    🪙 Binance 실주문
                           │             │
                           └──────┬──────┘
                                  ▼  status=EXECUTED, kisOrderNo 저장
                       (나중에 주기적으로)
                       OrderFillPollingJob → OrderFillService.pollFill
                                  │ broker.queryFill()
                                  ▼
                       fillStatus = FILLED/PARTIAL/OPEN/CANCELLED
                       + 잔고 스냅샷 동기화(lastBalanceJson)

핵심: ②와 ③은 다른 입구지만, ②는 반드시 ProposalExecutionService를 거치고 ③(place)은 같은 한도 정책 메서드를 재사용합니다. 두 경로의 정책이 어긋나지 않도록 일부러 코드를 공유합니다(뒤의 함정 섹션 참고).

---

📖 핵심 클래스 라인별 심화

A. Broker — 모든 증권사의 공통 계약 (Broker.java:20-61)

// Broker.java:20-24
public interface Broker {
    BrokerAccount.BrokerType type();
    enum Side { BUY, SELL }

• 무엇을 하나: "주문을 받는 증권사라면 반드시 이 메서드들을 구현하라"는 약속(인터페이스). type()은 자기가 KIS인지 BINANCE인지 알려줍니다 — BrokerRouter가 이걸로 등록합니다.
• 왜 이렇게 하나: 윗단 코드(ProposalExecutionService 등)가 if (KIS) ... else if (BINANCE) ... 분기를 곳곳에 두면 새 브로커 추가 때마다 지옥. 대신 "계약"만 알면 구현이 무엇이든 똑같이 다룹니다(다형성).

// Broker.java:26-44
record OrderResult(boolean ok, String orderNo, String code, String message) {
    public static OrderResult success(String orderNo, String code) { ... }
    public static OrderResult failure(String code, String message) { ... }
}
record FillResult(String fillStatus, BigDecimal filledQty, BigDecimal avgPrice, String error) { ... }

• 무엇을 하나: 주문 결과(OrderResult)와 체결 조회 결과(FillResult)를 정규화된 한 가지 모양으로 정의. KIS의 rt_cd든 Binance의 status든, 어댑터가 이 모양으로 번역해 돌려줍니다.
• 초보 포인트: record는 "값만 담는 불변 상자"를 짧게 만드는 자바 문법. success(...)/failure(...)는 정적 팩토리 — new OrderResult(true, ..., null) 대신 의미가 또렷한 OrderResult.success(...)로 만들게 해줍니다.

// Broker.java:46-60
OrderResult placeOrder(BrokerAccount account, String symbol, Side side, BigDecimal qty, BigDecimal limitPrice);
FillResult queryFill(BrokerAccount account, OrderProposal proposal);
Map<String, Object> getBalance(BrokerAccount account);
Map<String, Object> getQuote(BrokerAccount account, String symbol);

• 4개 메서드 = 증권사가 할 수 있는 일 전부: 주문 전송 / 체결 조회 / 잔고 / 현재가.
• 주석(Broker.java:46)의 핵심 한 줄: *"호출측이 모든 안전 게이트(kill-switch/한도/검증)를 먼저 통과시켜야 한다."* → 인터페이스 자체는 안전장치를 모름. 안전은 ProposalExecutionService의 책임. (어댑터에서 kill-switch를 한 번 더 보는 것은 이중 방어일 뿐.)
• limitPrice == null이면 시장가라는 약속(Broker.java:18)도 여기서 정의됩니다.

---

B. BrokerRouter — 단일 분기점 (BrokerRouter.java:16-34)

// BrokerRouter.java:18-23
private final Map<BrokerAccount.BrokerType, Broker> registry =
        new EnumMap<>(BrokerAccount.BrokerType.class);

public BrokerRouter(List<Broker> brokers) {
    for (Broker b : brokers) registry.put(b.type(), b);
}

• 무엇을 하나: 스프링이 등록된 모든 Broker 빈(KIS·Binance 어댑터)을 생성자에 리스트로 주입합니다. 라우터는 각자의 type()을 키로 EnumMap에 꽂아 "타입 → 구현" 색인을 만듭니다.
• 왜 이렇게 하나: 새 브로커(Broker 구현 + @Component)를 추가하면 이 클래스를 손대지 않아도 자동 등록됩니다. 확장에 열려 있고 수정에 닫힌 구조.

// BrokerRouter.java:25-33
public Broker forAccount(BrokerAccount account) {
    return forType(account == null ? null : account.getBrokerType());
}
public Broker forType(BrokerAccount.BrokerType type) {
    Broker b = registry.get(type == null ? BrokerAccount.BrokerType.KIS : type);
    if (b == null) throw new IllegalStateException("지원하지 않는 브로커: " + type);
    return b;
}

• 계정을 주면 그 계정의 brokerType에 맞는 구현을 돌려줍니다. null이면 KIS로 폴백 — 옛 데이터(brokerType 컬럼이 없던 시절)와의 하위호환.
• 모르는 타입이면 즉시 예외 → "조용히 엉뚱한 곳에 주문 넣기"보다 명확한 실패가 낫습니다.

---

C. ProposalExecutionService.execute — 안전 게이트의 심장 (ProposalExecutionService.java:54-139)

이 메서드가 이 파트에서 가장 중요합니다. 모든 주문(자동/수동)이 여기를 통과하므로, 안전 게이트가 한 곳에 모여 누락이 없습니다.

// ProposalExecutionService.java:54-59
@Transactional
public Result execute(OrderProposal p, BrokerAccount ba, boolean auto) {
    if (tradingControl.isKillSwitchOn()) {
        log.warn("[exec] kill-switch ON — 주문 거부 proposal={}", p.getId());
        return new Result(false, "전역 거래 차단(kill-switch) 활성화 — 모든 주문 거부", p);
    }

• 게이트 ①: kill-switch. 가장 먼저 본다. 켜져 있으면 그 무엇도 통과 못 함. auto 인자는 "자동 체결 여부" — 나중에 autoExecuted 플래그로 기록(승격 게이트 집계에 쓰임).

// ProposalExecutionService.java:60-71
if (!"PENDING".equals(p.getStatus())) {
    return new Result(false, "PENDING 상태가 아님 (현재=" + p.getStatus() + ")", p);
}
if (p.getExpiresAt() != null && p.getExpiresAt().isBefore(LocalDateTime.now())) {
    p.setStatus("EXPIRED");
    proposalRepo.save(p);
    return new Result(false, "이미 만료됨", p);
}
if (ba == null) return new Result(false, "BrokerAccount 없음", p);
if (!Boolean.TRUE.equals(ba.getTradingEnabled())) {
    return new Result(false, "BrokerAccount.tradingEnabled=false — 자동매매 마스터 스위치 OFF", p);
}

• 게이트 ②: 상태·만료. 이미 처리됐거나(EXECUTED/REJECTED) 만료된 제안은 재실행 불가. 만료를 발견하면 그 자리에서 EXPIRED로 굳혀 정합성 유지.
• 게이트 ③: 마스터 스위치. tradingEnabled=false면 끝. 사용자가 직접 끌 수 있는 "이 계좌의 매매 켜짐/꺼짐" 큰 스위치(BrokerAccount.java:108-111).
• 초보 포인트: Boolean.TRUE.equals(x)는 x가 null이어도 안전하게 false를 반환합니다. x == true(언박싱)는 null이면 NPE.

// ProposalExecutionService.java:73-89
Broker broker = brokerRouter.forAccount(ba);
BigDecimal qtyEff = effectiveQty(p);

// 1건당 한도 (시장가는 현재가로 추정 — 시장가 한도우회 방지)
double estUsd = estimateUsd(broker, ba, p, qtyEff);
if (ba.getMaxOrderUsd() != null && ba.getMaxOrderUsd() > 0 && estUsd > ba.getMaxOrderUsd()) {
    return new Result(false, "1건당 한도(USD " + ba.getMaxOrderUsd() + ") 초과: 예상 " + estUsd, p);
}
// 일일 누적 한도
if (ba.getDailyOrderUsd() != null && ba.getDailyOrderUsd() > 0) {
    BigDecimal todaySum = proposalRepo.sumExecutedUsdSince(p.getUserId(), LocalDate.now().atStartOfDay());
    double todayTotal = todaySum == null ? 0.0 : todaySum.doubleValue();
    if (todayTotal + estUsd > ba.getDailyOrderUsd()) {
        return new Result(false, "일일 누적 한도(USD " + ba.getDailyOrderUsd() + ") 초과: ...", p);
    }
}

• 게이트 ④: 금액 한도(USD). 한 건당(maxOrderUsd)과 하루 누적(dailyOrderUsd) 두 종류.
• 시장가 한도 우회 방지가 핵심: 시장가는 limitPrice가 없어 금액을 모릅니다. 그래서 estimateUsd(아래)가 현재가를 조회해 추정합니다 — 안 하면 "지정가는 막히는데 시장가로는 무제한"이 되는 구멍이 생깁니다.
• qtyEff(effectiveQty, ProposalExecutionService.java:142-145): 크립토 분수(qtyDecimal)가 있으면 우선, 없으면 정수 qty. KIS는 정수 주식, Binance는 0.0015 BTC 같은 분수라서.
• 일일 누적은 sumExecutedUsdSince로 오늘 자정 이후 EXECUTED 주문의 USD 합을 DB에서 계산(OrderProposalRepository.java:30-34: 수량 × limitPrice 우선, 없으면 fillAvgPrice).

// ProposalExecutionService.java:91-94
String krwViol = krwDailyLimitViolation(proposalRepo, ba, p.getSide(), p.getUserId(), estUsd);
if (krwViol != null) return new Result(false, krwViol, p);

• 게이트 ⑤: KIS KRW 매수/매도 한도. KIS 계정은 원화 한도(dailyBuyKrw/dailySellKrw)가 USD 한도보다 우선. krwDailyLimitViolation(ProposalExecutionService.java:153-169)이 public static인 이유: 수동 주문 경로(BrokerOrderController.place)가 같은 메서드를 재사용해 두 경로의 정책을 일치시키기 위함입니다. 주석(ProposalExecutionService.java:91-92)에 *"설정만 되고 두 주문 경로 어디서도 집행되지 않던 dead 한도였다"* — 과거에 한쪽 경로에서 빠져 우회됐던 버그를 고친 흔적.
• USD를 KRW로 바꿀 때 BrokerAccount.USD_KRW_APPROX = 1300.0(BrokerAccount.java:31) 근사 환율 사용.

// ProposalExecutionService.java:96-103
if ("BUY".equals(p.getSide()) && ba.getDailyLossLimitUsd() != null && ba.getDailyLossLimitUsd() > 0) {
    Double pnl = totalUnrealizedPnl(ba);
    if (pnl != null && pnl < -ba.getDailyLossLimitUsd()) {
        return new Result(false, "손실 한도 서킷브레이커: 미실현 손실 " + Math.round(-pnl)
                + " USD 가 한도(" + ba.getDailyLossLimitUsd() + " USD) 초과 — 신규 매수 차단", p);
    }
}

• 게이트 ⑥: 손실 서킷브레이커. 매수에만 적용. 마지막 잔고 스냅샷(lastBalanceJson)의 미실현 총손익(totalUnrealizedPnl, ProposalExecutionService.java:209-217 → total_market_value_usd 키)이 한도보다 더 큰 손실이면 추가 매수를 막아 물타기 폭주를 차단.

// ProposalExecutionService.java:105-130
p.setStatus("APPROVED");
p.setDecidedAt(LocalDateTime.now());
p.setAutoExecuted(auto);
proposalRepo.save(p);
try {
    Broker.Side side = "BUY".equals(p.getSide()) ? Broker.Side.BUY : Broker.Side.SELL;
    Broker.OrderResult res = broker.placeOrder(ba, p.getTicker(), side, qtyEff, p.getLimitPrice());
    if (!res.ok()) {
        p.setStatus("EXEC_FAILED");
        p.setExecError(...);
        proposalRepo.save(p);
        recordLog(...); recordAudit(..., "EXEC_FAILED", ...);
        return new Result(false, res.message(), p);
    }
    p.setStatus("EXECUTED");
    p.setExecutedAt(LocalDateTime.now());
    p.setKisOrderNo(res.orderNo());
    proposalRepo.save(p);
    recordLog(...); recordAudit(..., "EXECUTED", ...);
    return new Result(true, null, p);
}

• 모든 게이트 통과 후에야 APPROVED로 표시하고 실제로 broker.placeOrder 를 호출. 여기서부터 진짜 돈이 움직입니다.
• 성공이면 EXECUTED + 브로커 주문번호를 kisOrderNo에 저장(이름은 kis지만 Binance orderId도 여기 들어감). 실패면 EXEC_FAILED + 에러 기록.
• 감사 로그(recordAudit, ProposalExecutionService.java:189-206): 실제로 시장에 나간 모든 시도(성공/실패)를 OrderExecutionAudit에 불변 기록. best-effort(기록 실패가 주문을 막지 않음). 크립토 분수 수량은 정수 audit 필드로 표현 불가라 detail에 풀어 적습니다.

// ProposalExecutionService.java:171-186 (estimateUsd)
private double estimateUsd(Broker broker, BrokerAccount ba, OrderProposal p, BigDecimal qtyEff) {
    double price;
    if (p.getLimitPrice() != null) {
        price = p.getLimitPrice().doubleValue();
    } else {
        try {
            Map<String, Object> q = broker.getQuote(ba, p.getTicker());
            Object lp = q.get("last_price");
            price = lp instanceof Number n ? n.doubleValue() : Double.parseDouble(String.valueOf(lp));
        } catch (Exception e) { price = 0.0; }
    }
    return qtyEff.doubleValue() * price;
}

• 지정가면 그 값, 시장가면 현재가 조회로 추정(실패 시 0 — 기존 동작 유지). 위 게이트 ④/⑤가 시장가도 막을 수 있게 해주는 부분.

---

D. KisApiClient — KIS 실제 호출 (핵심만)

원본(671줄)은 수정 금지 클래스입니다. 서명·UA·env 분기 세 가지가 핵심.

env 분기: 도메인이 갈린다 (KisApiClient.java:47-114)

// KisApiClient.java:47-48, 112-114
private static final String MOCK_HOST = "https://openapivts.koreainvestment.com:29443";
private static final String REAL_HOST = "https://openapi.koreainvestment.com:9443";
private String host(BrokerAccount.Env env) {
    return env == BrokerAccount.Env.REAL ? REAL_HOST : MOCK_HOST;
}

• env=REAL이면 실전 도메인, MOCK이면 모의 도메인. 같은 코드가 계정의 env 하나로 모의/실전을 가릅니다. TR-ID도 같은 방식으로 갈림(예: 매수 실전 TTTT1002U / 모의 VTTT1002U, KisApiClient.java:484).

토큰 캐시 + 동시성 락 (KisApiClient.java:170-269)

// KisApiClient.java:170-178
public String getAccessToken(BrokerAccount b) {
    String key = cacheKey(b);                       // userId + ":" + env
    CachedToken cached = tokenCache.get(key);
    if (cached != null && cached.valid()) return cached.token;
    synchronized (tokenLockFor(key)) {
        CachedToken again = tokenCache.get(key);    // double-check
        if (again != null && again.valid()) return again.token;

• 왜 락이 필요: KIS는 토큰 발급을 1분 1회로 제한. 동시 요청이 몰리면 여러 번 발급을 시도하다 차단됩니다. synchronized + double-check로 한 번만 발급하고 나머지는 캐시를 씁니다. 토큰은 23시간 유효(CachedToken.valid()는 만료 5분 전부터 false로 보아 미리 갱신, KisApiClient.java:108-110).

UA(User-Agent) — 메모리에 박힌 교훈 (KisApiClient.java:198-226)

// KisApiClient.java:222-226
// 헤더: 공식 Python 샘플과 동일 + PowerShell 스타일 User-Agent.
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept", "text/plain");
conn.setRequestProperty("charset", "UTF-8");
conn.setRequestProperty("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 alpha-helix/1.0");

• 핵심 함정: Spring RestClient가 기본으로 붙이는 User-Agent: Java-http-client/...를 KIS 게이트웨이가 자동화 트래픽으로 보고 403 + EGW00002로 즉시 거부합니다(키/IP 검증 이전 단계). 그래서 토큰 발급은 RestClient가 아니라 JDK HttpURLConnection으로 내려가 브라우저 UA를 명시(KisApiClient.java:215-226). WebSocket 승인키 발급(getWsApprovalKey, KisApiClient.java:621-669)도 같은 이유로 동일 패턴.
• 추가 함정: KIS GW는 chunked 전송도 EGW00202로 거부. 그래서 본문을 byte[]로 직렬화해 Content-Length를 명시(jsonBytes, KisApiClient.java:146-152; 주문도 KisApiClient.java:515-517).

주문 + 거래소 폴백 (KisApiClient.java:476-550)

// KisApiClient.java:486-492
String primary = exchangeOf(ticker);
java.util.List<String> exchanges = new java.util.ArrayList<>();
exchanges.add(primary);
for (String alt : List.of("NASD", "NYSE", "AMEX")) {
    if (!exchanges.contains(alt)) exchanges.add(alt);
}

• KIS 미국주식 주문은 거래소 코드(NASD/NYSE/AMEX)를 정확히 보내야 합니다. 틀리면 EGW00202(GW 라우팅 오류). 티커별 알려진 매핑(EXCHANGE_BY_TICKER, KisApiClient.java:56-82; 예: 레버리지 ETF SOXL은 AMEX)으로 1차 시도하고, 실패하면 다른 거래소로 순차 폴백(KisApiClient.java:526-537).
• 주문 직전 kill-switch를 여기서도 한 번 더 확인(KisApiClient.java:479-481) — 이중 방어.
• rate-limit(EGW00201, 초당 거래건수 초과)은 withRateLimitRetry(KisApiClient.java:404-420)가 1.5초 후 1회 재시도.

---

E. BinanceApiClient — Binance 실제 호출 (핵심만)

env 분기 + 서명 (BinanceApiClient.java:45-71, 116-143)

// BinanceApiClient.java:63-71
private String spotHost(BrokerAccount b) {
    return b.getEnv() == BrokerAccount.Env.MOCK ? SPOT_TESTNET_HOST : SPOT_HOST;
}
private String futuresHost(BrokerAccount b) {
    return FUTURES_HOST;   // ⚠ MOCK 이어도 실거래 fapi 로 나간다
}

• 현물(SPOT): env=MOCK이면 테스트넷(testnet.binance.vision), REAL이면 메인넷(api.binance.com).
• 함정 주의: futuresHost는 MOCK이어도 실거래 fapi.binance.com을 반환합니다. 즉 선물은 테스트넷 분기가 없습니다 — 그래서 어댑터에서 FUTURES 주문을 통째로 차단합니다(아래 G 참고).

// BinanceApiClient.java:116-143
private String sign(String data, String secret) {
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    byte[] raw = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));
    return HexFormat.of().formatHex(raw);
}
private String signedQuery(Map<String, Object> params, String secret) {
    params.put("timestamp", System.currentTimeMillis());
    String qs = toQueryString(params);
    return qs + "&signature=" + sign(qs, secret);
}

• HMAC-SHA256 서명: 쿼리스트링 전체를 secret으로 도장 찍어 &signature=...를 붙입니다. secret은 절대 전송하지 않고 서명에만 씀(BinanceApiClient.java:34). API Key는 헤더 X-MBX-APIKEY로만 전달(BinanceApiClient.java:33).
• timestamp가 필수인 이유: Binance는 서버 시각과 차이가 크면 거부(-1021). 그래서 시스템 시계가 맞아야 함.

rate-limit 백오프 (BinanceApiClient.java:81-109)

// BinanceApiClient.java:86-104 (요약)
if ((sc == 429 || sc == 418) && attempts < 3) {
    ... Retry-After 헤더 존중, 점증 대기 후 재시도 ...
}

• HTTP 429(요청한도)/418(IP 자동밴 경고)을 받으면 Retry-After를 존중해 최대 3회 재시도. 무시하고 계속 때리면 IP가 최대 3일 밴되므로 모든 호출이 이 래퍼를 통과(BinanceApiClient.java:78-79).

거래소 필터 (BinanceApiClient.java:430-487)

// BinanceApiClient.java:470-487 (요약)
public record SymbolFilters(BigDecimal stepSize, BigDecimal tickSize, BigDecimal minQty, BigDecimal minNotional) {
    public BigDecimal truncateQty(BigDecimal qty) { ... stepSize 배수로 내림 ... }
    public BigDecimal truncatePrice(BigDecimal price) { ... tickSize 배수로 내림 ... }
}

• 크립토는 수량/가격이 거래소가 정한 stepSize/tickSize 배수여야 하고 명목가는 minNotional 이상이어야 합니다. 부동소수 반올림으로 거부당하지 않게 항상 BigDecimal로 내림 절삭(RoundingMode.DOWN). 심볼별로 캐시(filterCache).

---

F. KisBrokerAdapter — KIS를 Broker로 번역 (KisBrokerAdapter.java:31-92)

// KisBrokerAdapter.java:31-50
public OrderResult placeOrder(BrokerAccount b, String symbol, Side side, BigDecimal qty, BigDecimal limitPrice) {
    KisApiClient.Side ks = side == Side.BUY ? KisApiClient.Side.BUY : KisApiClient.Side.SELL;
    long q = qty.setScale(0, RoundingMode.DOWN).longValue();   // 미국주식은 정수 수량
    Double lim = limitPrice == null ? null : limitPrice.doubleValue();
    // M4: 시장가(limitPrice=null) 의도면 현재가를 조회해 그 가격의 지정가로 변환
    if (lim == null) {
        try {
            Map<String, Object> quote = kis.getOverseasQuote(b, symbol);
            Object lp = quote.get("last_price");
            double px = lp instanceof Number n ? n.doubleValue() : Double.parseDouble(String.valueOf(lp));
            if (px > 0) lim = px;
        } catch (Exception ignore) { }
        if (lim == null) {
            return OrderResult.failure("NO_QUOTE",
                    "KIS 지정가 산정 실패: ... 0원 지정가 전송을 막았습니다. ...");
        }
    }

• 수량 정수화: 주식은 0.5주가 없으므로 RoundingMode.DOWN으로 정수화.
• 0원 지정가 방지(M4)가 핵심: KIS 미국주식은 ORD_DVSN=00(지정가)만 쓰므로, 단가 0(=limitPrice null)을 그대로 보내면 0원 지정가로 거부됩니다. 그래서 시장가 의도면 현재가를 조회해 그 값으로 지정가 변환. 조회 실패 시 0원 전송 대신 명확히 실패 반환(KisBrokerAdapter.java:46-49).

// KisBrokerAdapter.java:51-58
Map<String, Object> resp = kis.placeOverseasOrder(b, symbol, ks, q, lim);
String rtCd = String.valueOf(resp.getOrDefault("rt_cd", ""));
if (!"0".equals(rtCd)) {
    String msgCd = String.valueOf(resp.getOrDefault("msg_cd", ""));
    return OrderResult.failure(msgCd, friendlyKisError(msgCd, msg, b));
}
return OrderResult.success(String.valueOf(resp.getOrDefault("kis_order_no", "")), rtCd);

• KIS는 rt_cd="0"이 성공. 그 외는 msg_cd를 사람이 읽을 메시지로 번역(friendlyKisError, EGW00202/00201/00105 등)해 OrderResult.failure로 정규화.

// KisBrokerAdapter.java:64-92 (queryFill 요약)
JsonNode output = resp.path("output");   // inquire-nccs(미체결내역)
... p.getKisOrderNo() 와 일치하는 주문 찾기 ...
if (match != null) {
    filledQty = max(0, 주문수량 - 미체결수량);
    fillStatus = filledQty > 0 ? "PARTIAL" : "OPEN";
} else {
    fillStatus = "FILLED";   // 미체결 목록에 없음 → 전량 체결로 간주(휴리스틱)
}

• KIS는 직접 "체결됐다" API가 없어 미체결내역에 없으면 전량 체결로 보는 휴리스틱. 평균 체결가는 제공 안 함(avgPrice=null).

---

G. BinanceBrokerAdapter — Binance를 Broker로 번역 (BinanceBrokerAdapter.java:37-83)

// BinanceBrokerAdapter.java:37-44
public OrderResult placeOrder(...) {
    if (b.getBinanceMode() == BrokerAccount.BinanceMode.FUTURES) {
        return OrderResult.failure("FUTURES_DISABLED",
                "Binance 선물(FUTURES) 주문은 현재 비활성화 ... 안전을 위해 SPOT(현물)만 지원합니다.");
    }
    if (tradingControl.isKillSwitchOn()) {
        return OrderResult.failure("KILL_SWITCH", "전역 거래 차단(kill-switch) 활성화 — 모든 주문 거부");
    }

• FUTURES 차단이 핵심 안전장치: 위 E에서 봤듯 futuresHost는 MOCK이어도 실거래로 나갑니다. "MOCK인데 진짜 돈이 나가는" 사고를 막기 위해 선물 주문을 어댑터에서 통째로 거부(주석 BinanceBrokerAdapter.java:18-19).
• BinanceApiClient 자체는 kill-switch를 안 보므로, 어댑터에서 재확인(BinanceBrokerAdapter.java:42-44).

// BinanceBrokerAdapter.java:45-71
BinanceApiClient.SymbolFilters f = binance.getSymbolFilters(b, symbol);
BigDecimal q = f.truncateQty(qty);
if (q.signum() <= 0) return OrderResult.failure("LOT_SIZE", "... 최소 주문 단위 미만 ...");
String type = (limitPrice == null) ? "MARKET" : "LIMIT";
... 명목가 = q × refPrice 가 minNotional 미만이면 거부 ...
Map<String, Object> resp = binance.placeSpotOrder(b, symbol, side.name(), type, q.toPlainString(), priceStr);

• 주문 전 거래소 필터로 수량/가격을 절삭·검증해 Binance가 거부할 주문을 미리 거름. limitPrice 유무로 MARKET/LIMIT 결정.
• 체결 조회(queryFill, BinanceBrokerAdapter.java:86-106)는 KIS와 달리 정확한 status + 평균체결가(cummulativeQuoteQty / executedQty)를 제공. mapStatus(BinanceBrokerAdapter.java:121-129)가 Binance status를 정규화(FILLED/PARTIAL/OPEN/CANCELLED).

---

H. OrderFillService.pollFill — 체결 도착 확인 (OrderFillService.java:39-84)

// OrderFillService.java:45-67 (요약)
BrokerAccount b = brokerRepo.findById(p.getBrokerAccountId()).orElse(null);
Broker broker = brokerRouter.forAccount(b);
Broker.FillResult fr = broker.queryFill(b, p);
... p.setFillStatus/filledQty/fillAvgPrice ... proposalRepo.save(p);
// B2: 체결 시 잔고 스냅샷 자동 동기화
if ("FILLED".equals(fr.fillStatus()) || "PARTIAL".equals(fr.fillStatus())) {
    Map<String, Object> bal = broker.getBalance(b);
    b.setLastBalanceJson(om.writeValueAsString(bal));
    b.setLastBalanceAt(LocalDateTime.now());
    brokerRepo.save(b);
}

• EXECUTED(KIS/Binance가 주문을 수락)와 실제 체결(FILLED)은 다릅니다. 주문은 받아졌어도 시장에서 안 채워질 수 있음. 그래서 나중에 폴링으로 진짜 체결을 확인.
• 체결되면 잔고 스냅샷을 자동 갱신(lastBalanceJson) — 이 스냅샷의 total_market_value_usd를 위 게이트 ⑥(손실 서킷브레이커)이 사용. best-effort(잔고 동기화 실패가 체결 판정을 뒤집지 않음).
• OrderFillPollingJob(OrderFillPollingJob.java)이 3분마다 최근 36시간 내 미확정 건만 폴링해 KIS rate-limit 부담 최소화.

---

I. TradingControlService — 런타임 kill-switch (TradingControlService.java:19-47)

// TradingControlService.java:21-38
@Value("${app.trading.kill-switch:false}")
private boolean configKillSwitch;
private volatile Boolean override = null;     // null = 설정값 사용

public boolean isKillSwitchOn() {
    return override != null ? override : configKillSwitch;
}
public void setKillSwitch(boolean on) { this.override = on; ... }

• 기본값은 환경설정(TRADING_KILL_SWITCH). 운영 중 setKillSwitch(true)로 재시작 없이 즉시 전 주문 차단. 모든 주문 경로(ProposalExecutionService·KisApiClient·BinanceBrokerAdapter)가 이걸 보므로 토글 한 번에 전체 적용. volatile은 다른 스레드가 즉시 보게 하는 키워드(가시성).

---

J. PromotionGateService — MOCK→REAL 승격 게이트 (PromotionGateService.java:51-118)

// PromotionGateService.java:51-56
public GateResult evaluate(Long userId, BrokerAccount realAccount) {
    if (realAccount.getEnv() != BrokerAccount.Env.REAL) {
        return new GateResult(true, List.of(), "MOCK 계정은 승격 게이트가 적용되지 않습니다.");
    }

• MOCK은 자유. REAL의 tradingEnabled=true 전환을 허용하기 전 5가지를 검사:
  1. REAL 자체 /test 통과(lastVerifiedAt != null)
  2. 같은 브로커의 MOCK 계정 존재 — findByUserIdAndBrokerTypeAndEnv로 조회(PromotionGateService.java:69; 주석에 *"findByUserIdAndEnv 는 다중브로커 시 NonUnique 500"* — 과거 다중 브로커에서 터지던 버그를 고친 흔적)
  3. MOCK 등록 후 14일 이상(MIN_MOCK_DAYS)
  4. MOCK EXECUTED 5건 이상(MIN_MOCK_EXECUTED)
  5. MOCK 실패율 < 30%(MAX_MOCK_FAIL_RATIO)
• 한 항목이라도 실패하면 무엇이 부족한지 정확히 반환(checks 리스트). BrokerAccountController.setTradingEnabled(BrokerAccountController.java:158-168)가 REAL+KIS일 때 이 게이트를 호출.

주의: 이 게이트는 수동 매매 활성화(tradingEnabled) 용이고, 자동 체결(auto-execute) 은 별도의 더 엄격한 게이트(MOCK 자동매매 14일 + 20회)를 BrokerAccountController.setAutoExecute(BrokerAccountController.java:200-222)가 직접 검사합니다. 두 게이트는 다른 기준입니다.

---

K. 컨트롤러 3종 — 입구

BrokerAccountController — 계좌·한도·스위치 (BrokerAccountController.java)

• 키 등록(upsert): appsecret을 즉시 crypto.encrypt 후 저장(BrokerAccountController.java:119,124). 평문 저장 절대 금지.
• REAL 한도 안전 상한(realCapViolation, BrokerAccountController.java:60-73): 1건당 USD 5만, 일일 USD 20만, 매수 1억원/매도 5억원. 등록·수정 양 경로에서 동일 적용(주석 BrokerAccountController.java:50-54: 과거 patchLimits에만 캡이 있어 upsert로 우회되던 비대칭을 고침).
• setTradingEnabled: REAL은 /test 통과 + KIS면 승격 게이트 통과해야 켜짐.
• testConnection: 토큰 발급만 성공해도 인증 통과로 간주(lastVerifiedAt 기록). 잔고 조회는 best-effort(KIS 초당 호출 제한으로 실패해도 인증은 유지). KIS 에러 코드를 풍부한 사용자 안내로 번역(friendlyKisError, BrokerAccountController.java:358-417).

OrderProposalController — 승인 큐 (OrderProposalController.java)

• create: 수동 제안 생성(source=MANUAL, +24h 만료). 크립토는 분수를 qtyDecimal에, 주식은 정수 qty에(OrderProposalController.java:91-95). 항상 PENDING으로만 생성.
• approve: 소유권 검증(findByIdAndUserId) 후 수동 승인도 자동과 동일한 exec.execute(p, ba, false) 호출(OrderProposalController.java:135). 한도/kill-switch를 우회하는 별도 경로가 없음.
• pollFill: EXECUTED 주문의 체결을 즉시 폴링(스케줄잡과 동일 로직 수동 트리거).

BrokerOrderController — 직접 주문 (BrokerOrderController.java)

• place: 제안을 안 거치는 직접 주문 경로. 그래서 가드를 스스로 전부 수행 — tradingEnabled·lastVerifiedAt·1건당/일일 USD 한도, 그리고 ProposalExecutionService.krwDailyLimitViolation을 재사용(BrokerOrderController.java:198)해 KRW 한도까지. 통과 후 brokerRouter.forAccount(b).placeOrder(...) 직접 호출.
• preview: 실제 주문 없이 한도/예상 비용만 계산. quote/balance/orders/today는 라우터 경유 조회.

---

L. 엔티티 필드 의미

BrokerAccount (BrokerAccount.java) — 계좌 + 한도 + 스위치

필드	의미
env	MOCK(모의/테스트넷) | REAL(실전/메인넷). 기본 MOCK
brokerType	KIS | BINANCE. 기본 KIS
appKey / appSecretEnc	KIS 키. secret은 암호화 저장(*_enc)
cano / acntPrdtCd	KIS 종합계좌번호(8) / 상품코드(보통 "01")
binanceApiKey / binanceApiSecretEnc	Binance 키. secret 암호화 저장
binanceMode	SPOT | FUTURES. FUTURES는 주문 차단됨
maxOrderUsd	1건당 최대(USD), 0=무제한. 기본 5,000
dailyOrderUsd	일일 누적 최대(USD). 기본 20,000. KIS는 KRW 한도 우선
dailyLossLimitUsd	손실 서킷브레이커. 미실현 손실이 이 값 초과 시 신규 매수 차단
dailyBuyKrw / dailySellKrw	KIS 전용 1일 매수/매도 한도(원화)
tradingEnabled	마스터 스위치. false면 모든 승인 거부. 기본 false
autoExecute	자동 체결 스위치. 시그널 PENDING을 사람 승인 없이 실행. 기본 false
lastVerifiedAt	마지막 연결 테스트 성공 시각
lastBalanceJson / lastBalanceAt	체결 후 잔고 스냅샷(손실 서킷브레이커가 읽음)
- 유니크 제약(BrokerAccount.java:20-22): (user_id, broker_type, env) — 한 사용자가 같은 브로커·env 계좌를 중복 등록 못 함.
- USD_KRW_APPROX = 1300.0(BrokerAccount.java:31): KRW 한도 환산용 근사 환율(실시간 아님).

OrderProposal (OrderProposal.java) — 주문 제안

필드	의미
userId	소유자 — 권한 검증 1차 게이트
workspaceId	발생 워크스페이스(수동이면 null 허용)
brokerAccountId	보낼 계좌(반드시 본인 소유)
ticker / side	종목(SPY/BTCUSDT) / BUY|SELL
qty	정수 수량(주식). NOT NULL placeholder
qtyDecimal	분수 수량(크립토). 있으면 실행/체결에서 우선
limitPrice	지정가. null=시장가
source	SIGNAL | MANUAL
status	PENDING→(APPROVED→EXECUTED|EXEC_FAILED)|REJECTED|EXPIRED
kisOrderNo	브로커가 준 주문번호(Binance orderId도 여기)
execError	실패 사유
expiresAt	만료 시각(보통 +24h). OrderProposalExpiryJob이 정리
autoExecuted	사람 승인 없이 자동 체결됐는지(졸업 게이트 집계용)
fillStatus / filledQty / filledQtyDecimal / fillAvgPrice / fillCheckedAt	실제 체결 폴링 결과(EXECUTED와 별개)

---

⚠️ 함정·보안 주의

1. KIS 기본 Java UA 차단 — Spring RestClient의 Java-http-client/... UA를 KIS GW가 403 + EGW00002로 거부. 토큰/승인키 발급은 HttpURLConnection + 브라우저 UA로 우회(KisApiClient.java:222-226, 642). 이 클래스를 손댈 때 UA를 지우면 인증이 통째로 깨집니다. (메모리 교훈과 일치.)

2. KIS chunked 전송 = EGW00202 — Map을 그대로 보내면 chunked로 나가 GW가 거부. 본문을 byte[]로 직렬화해 Content-Length 명시(jsonBytes). 주문 본문도 동일(KisApiClient.java:515-517).

3. Binance env=REAL → 메인넷 / FUTURES는 항상 실거래 — spotHost는 MOCK이면 테스트넷이지만 futuresHost는 MOCK이어도 fapi.binance.com(실거래). 그래서 BinanceBrokerAdapter가 FUTURES 주문을 통째로 차단(BinanceBrokerAdapter.java:38-41). 이 차단을 풀면 모의가 진짜 돈을 씁니다.

4. 두 번째 주문 경로 우회 방지 — 직접 주문(BrokerOrderController.place)이 제안 승인 경로와 다른 한도 정책을 쓰면 우회 구멍이 생깁니다. 그래서 KRW 한도 검사를 ProposalExecutionService.krwDailyLimitViolation public static 메서드로 공유해 양 경로가 같은 규칙을 씁니다(BrokerOrderController.java:198). REAL 한도 캡도 등록·수정 양 경로에서 동일 적용(BrokerAccountController.java:107, 260).

5. 시장가 한도 우회 방지 — 시장가는 금액을 모르므로 현재가를 조회해 추정(estimateUsd). 안 하면 "지정가는 막히고 시장가는 무제한" 구멍.

6. 0원 지정가 사고 — KIS 미국주식은 지정가만 쓰므로 단가 0 전송은 거부됩니다. 시장가 의도면 현재가를 지정가로 변환하고, 조회 실패 시 0원 대신 명확한 실패 반환(KisBrokerAdapter.java:39-49).

7. 키 평문 저장 금지 — appsecret/apiSecret은 등록 즉시 crypto.encrypt 후 *_enc 컬럼에 저장. 로그에도 마스킹(previewWithSecretMasked, KisApiClient.java:155-162).

8. MOCK→REAL 졸업 게이트 — 수동(PromotionGateService: 14일+5건+실패율<30%)과 자동(setAutoExecute: 14일+20회)이 다른 기준. 헷갈리지 말 것.

9. EXECUTED ≠ FILLED — 주문 수락과 실제 체결은 다름. 체결은 OrderFillService/폴링잡으로 별도 확인.

10. kill-switch는 런타임 우선 — TradingControlService.override가 설정값보다 우선. 재시작하면 설정 기본값으로 복귀하므로, 긴급 차단 후 영구 차단이 필요하면 환경변수도 바꿔야 합니다.

---

🚀 고도화 아이디어

• 실시간 환율: USD_KRW_APPROX = 1300 고정 → 환율 API 연동으로 KRW 한도 정확도 향상(TODO 주석 BrokerAccount.java:29).
• 선물 테스트넷 배선: testnet.binancefuture.com 별도 계정 + env 분기를 추가하면 FUTURES 차단을 안전하게 풀 수 있음(현재 미배선이라 차단).
• 체결 WebSocket 정밀화: KIS 체결통보 WS(KisFillWebSocketService)와 Binance user-data-stream을 붙여 폴링 대신 푸시 기반 체결 확인으로 지연/부하 절감.
• 새 브로커 추가: Broker 구현 + @Component 한 개면 BrokerRouter가 자동 인식. 예: Alpaca, IBKR. 라우터/실행서비스 수정 불필요.
• 부분체결 후속 처리: 현재 PARTIAL은 상태만 기록. 미체결 잔량 자동 취소/재주문 정책을 OrderFillService에 추가 가능.
• 한도 정책 엔진화: 게이트 6종이 execute에 인라인. 정책을 OrderGuard 체인으로 분리하면 테스트·확장이 쉬워짐(전략 패턴).
• KIS 거래소 매핑 자동화: EXCHANGE_BY_TICKER 하드코딩 → exchangeInfo류 조회/캐시로 자동 판별.

---

📚 용어 사전 (이 파트 한정)

용어	뜻
Broker (인터페이스)	모든 증권사가 구현하는 공통 계약(주문/체결/잔고/시세)
어댑터(Adapter)	생김새 다른 원본 ApiClient를 Broker 모양으로 변환하는 얇은 래퍼
OrderProposal	실행 전 주문 초안. PENDING→…→EXECUTED 생명주기
안전 게이트	execute가 주문 전 통과시키는 6중 검사(kill-switch·한도·손실 등)
kill-switch	전역 거래 차단 스위치. 재시작 없이 전 주문 즉시 거부
tradingEnabled	계좌별 매매 마스터 스위치
autoExecute	시그널 제안을 사람 승인 없이 자동 체결하는 스위치
MOCK / REAL	모의/테스트넷 ↔ 실전/메인넷
승격 게이트	MOCK 실적을 검증해야 REAL을 켤 수 있게 하는 관문
rt_cd / msg_cd	KIS 응답 코드("0"=성공) / 에러 세부 코드(EGW00xxx)
EGW00202 / 00201 / 00002	KIS GW 라우팅 오류 / 초당 한도 초과 / 자동화 트래픽(UA) 거부
HMAC-SHA256	secret으로 만든 위조 불가 서명. Binance 사적 요청 인증
X-MBX-APIKEY	Binance API Key 전달 헤더(URL 금지)
LOT_SIZE / tickSize / minNotional	크립토 수량·가격 단위·최소 명목가 거래소 필터
FillResult / fillStatus	정규화 체결 결과. FILLED/PARTIAL/OPEN/CANCELLED/UNKNOWN
EXECUTED vs FILLED	주문 수락(접수) ↔ 실제 시장 체결. 다름
lastBalanceJson	체결 후 동기화되는 잔고 스냅샷(손실 서킷브레이커가 읽음)
OrderExecutionAudit	시장에 나간 모든 주문 시도의 불변 감사 기록
TTL / expiresAt	제안 만료 시각. ExpiryJob이 PENDING 만료분을 EXPIRED로 정리

domain/user — 회원 관리 + 신분증(JWT) 발급소 (완전 라인별 해설)

원본: backend/src/main/java/com/DevBridge/devbridge/domain/user/ 전체

• 연관 보안 모듈: backend/src/main/java/com/DevBridge/devbridge/global/security/
  이 문서는 교재 표준 형식(README "3. 공통 형식", 모범 예시 01_backtest/vbt_engine.md)을 따릅니다.
  전제: 스프링 기초(@RestController·@Service·DI·ResponseEntity 등)는 08_backend/00_spring_primer.md에서 다룹니다. 여기서는 user 도메인 코드 그 자체를 한 줄씩 풉니다.

---

📌 이 도메인 한눈에

이 도메인은 "회원 관리 + 신분증 발급소" 입니다. 사람으로 비유하면 주민센터 + 출입증 발급 데스크예요.

• 회원가입(signup) = 주민센터에 새 주민 등록. 비밀번호는 절대 평문으로 보관하지 않고 금고(BCrypt 해시) 에 넣습니다.
• 로그인(login) = 신분 확인 후 출입증(JWT 토큰) 발급. 이 출입증을 봉인된 봉투(HttpOnly 쿠키) 에 담아 브라우저에 줍니다.
• 이후 모든 요청 = 출입증(쿠키)을 매번 들고 오면, 입구의 경비원(JwtAuthenticationFilter) 이 위조 여부를 확인하고 "이 사람은 N번 회원"이라고 요청에 도장(auth.userId 속성)을 찍어줍니다.
• 소셜 로그인(Google·GitHub) = 다른 기관(구글·깃허브)이 발급한 신분증을 우리가 직접 그 기관에 전화해 진위 확인 후 우리 출입증으로 교환.
• 프로필/은행/이메일 인증 = 등록된 주민의 부가 정보 관리.

핵심 클래스 역할표:

클래스	한 줄 역할	비유
AuthController	signup·login·refresh·social·github·logout 의 HTTP 입구. 쿠키 굽기 담당	출입증 발급 창구
AuthService	가입 검증·BCrypt 해싱·로그인 비번 대조·소셜 계정 조회/생성	신원 확인 담당관
JwtUtil	JWT 토큰 발행(issue) · 검증(parse)	출입증 인쇄기 + 위조 감별기
JwtAuthenticationFilter	매 요청마다 쿠키/헤더에서 토큰 꺼내 검증 → 요청에 userId 주입	입구 경비원
AuthContext	컨트롤러에서 "지금 누구?"를 꺼내는 헬퍼	도장 찍힌 userId 판독기
UserController	사용자 검색·조회(채팅용)·GitHub username 수정	주민 조회 창구
ProfileController/ProfileService	프로필 상세 저장/조회/초기화	프로필 관리실
BankVerificationController/Service	입금자명 3자리 코드로 계좌 인증	계좌 본인확인 데스크
EmailVerificationController/Service	6자리 코드로 이메일 인증	이메일 본인확인 데스크
User (엔티티)	회원 1명 = DB USERS 한 행	주민등록 카드
RefreshToken (엔티티)	출입증 자동 갱신용 장기 티켓	재발급 쿠폰

누가 호출하나? → 프론트엔드(React)가 /api/auth/*, /api/users/*, /api/profile/*, /api/bank/*, /api/verify/* 로 REST 요청을 보내면 각 컨트롤러가 받습니다. 출입증(JWT 쿠키)은 한 번 발급되면 이후 모든 도메인(strategy·ai·payment…) 요청에서 "이 요청의 주인"을 식별하는 데 쓰입니다.

⚠️ 중요한 설계 사실: 이 프로젝트는 풀 Spring Security 프레임워크(SecurityFilterChain)를 의도적으로 끄고, 대신 직접 만든 경량 조합(JwtAuthenticationFilter + AuthContext)으로 인증을 처리합니다. PasswordConfig(global/config/PasswordConfig.java)는 그중 BCrypt 해싱 기능만 빌려 씁니다. 이 한 줄이 도메인 전체의 보안 모델을 결정하니 꼭 기억하세요.

---

🧠 사전 지식 (이거 모르면 막힘)

1) JWT 토큰 = "위조 불가능한 코팅 출입증"

JWT(JSON Web Token)는 헤더.페이로드.서명 세 토막을 점(.)으로 이은 문자열입니다.

eyJhbGciOi...   .   eyJ1aWQiOjEyLCJ0eXBlIjoiRlJFRSJ9   .   k3jD9f...
   헤더(알고리즘)            페이로드(uid=12, type=FREE 등)        서명(HMAC)

• 페이로드는 누구나 읽을 수 있습니다(Base64, 암호화 아님). 그래서 비밀번호 같은 건 절대 안 넣습니다.
• 핵심은 서명: 서버만 아는 비밀키(app.jwt.secret)로 HMAC-SHA256을 찍습니다. 누군가 페이로드를 "uid=12 → uid=1(관리자)"로 고치면 서명이 깨져 검증(parse)에서 즉시 탈락합니다. 도장 위조 불가능한 출입증과 같아요.
• "대칭키(HS256)"란: 발행할 때와 검증할 때 같은 비밀키를 씁니다(서버 혼자만 보관).

2) HttpOnly 쿠키 = "자바스크립트가 못 여는 봉인 봉투"

• 일반적으로 토큰을 브라우저 localStorage에 넣으면, XSS(악성 스크립트)가 localStorage.getItem('token')으로 훔쳐갈 수 있습니다.
• HttpOnly 쿠키는 자바스크립트가 읽을 수 없게 브라우저가 막습니다. 오직 브라우저가 요청 보낼 때 자동으로 동봉만 합니다. → XSS 토큰 탈취 방어.
• 추가 속성: Secure(HTTPS에서만 전송), SameSite(다른 사이트가 우리 쿠키를 끼워 보내는 CSRF 방어).

3) BCrypt 해싱 = "되돌릴 수 없는 분쇄 + 소금"

• 비밀번호를 그대로 DB에 저장하면, DB가 유출되는 순간 전원 비번이 새어나갑니다.
• 해싱은 단방향 함수: "hunter2" → $2a$10$N9qo8.... 이 결과로는 원래 비번을 역산할 수 없습니다.
• BCrypt는 ① 솔트(salt, 무작위 소금) 를 매번 섞어 같은 비번도 매번 다른 해시가 나오고(레인보우 테이블 방어), ② 일부러 느리게(work factor) 만들어 무차별 대입을 비싸게 합니다.
• BCrypt 해시는 항상 $2a$/$2b$/$2y$ 같은 $2로 시작합니다. 이 문서 뒤에서 이 접두사로 "해시인가 평문인가"를 구분하는 코드가 나옵니다.

4) OAuth 소셜 로그인 = "다른 기관 신분증으로 입장"

• 사용자는 구글/깃허브에 로그인 → 그 기관이 access_token(임시 출입증)을 발급 → 프론트가 그걸 우리 백엔드로 전달.
• 핵심 보안 원칙: 프론트가 같이 보낸 "이 사람 이메일은 X"라는 말은 믿으면 안 됩니다(위조 가능). 백엔드가 그 access_token을 들고 직접 구글/깃허브에 전화해서 "이 토큰의 진짜 이메일이 뭐냐"를 받아와야 합니다. (이게 아래 C2 취약점 수정의 핵심.)

5) Access Token / Refresh Token 쌍 = "짧은 출입증 + 긴 재발급 쿠폰"

• Access Token(JWT): 수명이 짧음(여기선 1시간). 매 요청마다 제시. 탈취돼도 곧 만료라 피해가 작음.
• Refresh Token: 수명이 김(여기선 15일). DB에 저장. Access가 만료되면 이걸 제시해 새 Access를 받습니다(재로그인 없이). 출입증이 만료되면 안내데스크에 쿠폰을 내밀어 새 출입증을 받는 셈.
• 왜 둘로 나누나? 편의(자주 로그인 안 함) ↔ 보안(짧은 access) 의 균형. Refresh는 자주 안 쓰이고 DB에서 폐기(로그아웃·만료)할 수 있어 통제가 쉽습니다.

---

🗺 요청 흐름도

(A) 회원가입 / 로그인 → 출입증 발급

[프론트] POST /api/auth/login {email, password}
              │
              ▼
        AuthController.login()
              │  authService.login(request)
              ▼
        AuthService.login()
          ├─ findByEmail 으로 User 조회 (없으면 "가입되지 않은 이메일")
          ├─ stored.startsWith("$2") ?
          │     예  → passwordEncoder.matches(raw, stored)   (BCrypt 대조)
          │     아니오 → 평문 비교 → 일치 시 즉시 BCrypt 재해싱 후 저장  ⚠️C1
          └─ 불일치 → "비밀번호가 일치하지 않습니다"
              │  (User 반환)
              ▼
        jwtUtil.issue(uid, email, type)  → access (JWT, 1h)
        issueRefreshToken(uid)           → refresh (UUID, DB저장, 15d)
              │
              ▼
        withTokenCookies(access, refresh)
          ├─ Set-Cookie: DEVBRIDGE_TOKEN   (HttpOnly, path=/)
          └─ Set-Cookie: DEVBRIDGE_REFRESH (HttpOnly, path=/api/auth)
              │
              ▼
        [프론트] 쿠키 2장 저장(자동) + AuthResponse(body) 수신

(B) 이후 매 요청 → 경비원이 신분 확인

[프론트] GET /api/profile/me/detail   (쿠키 DEVBRIDGE_TOKEN 자동 동봉)
              │
              ▼
   ┌──────────────────────────────────────────┐
   │ JwtAuthenticationFilter (모든 요청 1번씩)   │  ← Order: 가장 먼저
   │  extractToken: ①쿠키 DEVBRIDGE_TOKEN        │
   │               ②Authorization: Bearer (레거시)│
   │  jwtUtil.parse(token)  (서명·만료 검증)      │
   │   성공 → request.setAttribute("auth.userId")│
   │   실패 → 조용히 통과(익명)                    │
   └──────────────────────────────────────────┘
              │
              ▼
        ProfileController.myDetail()
          Long userId = AuthContext.currentUserId();  ← 도장 판독
          if (userId == null) → 401
              │
              ▼
        ProfileService.getDetail(userId) → 응답

💡 핵심: 필터는 인증 실패해도 막지 않고 그냥 통과시킵니다("익명 요청"). 실제 차단은 각 컨트롤러가 AuthContext.currentUserId() == null 을 보고 401을 내는 방식입니다. 이게 이 프로젝트의 경량 인증 패턴입니다.

(C) 소셜 로그인 (Google)

[프론트] (구글 로그인) → access_token 획득 → POST /api/auth/social-login {accessToken}
              │
              ▼
        AuthController.socialLogin()
          verifyGoogleAccessToken(accessToken)
            → GET googleapis.com/oauth2/v3/userinfo (Bearer)  ⚠️C2: 서버가 직접 검증
            → email + email_verified 확인
              │  (검증된 email)
              ▼
        authService.socialLogin(email)  → findByEmail (가입돼 있어야 함)
              │
              ▼
        (A)와 동일하게 JWT + Refresh 쿠키 발급

---

📖 핵심 클래스 라인별 심화

A. AuthController — 출입증 발급 창구

A-1. 클래스 선언 + 쿠키 이름 상수 — AuthController.java:30-42

// L30-L42
@Slf4j
@RestController
@RequestMapping("/api/auth")
@RequiredArgsConstructor
public class AuthController {

    public static final String AUTH_COOKIE_NAME    = "DEVBRIDGE_TOKEN";
    public static final String REFRESH_COOKIE_NAME = "DEVBRIDGE_REFRESH";

    private final AuthService authService;
    private final JwtUtil jwtUtil;
    private final RefreshTokenRepository refreshTokenRepository;
    private final UserRepository userRepository;

• @RestController = "이 클래스의 메서드 반환값을 JSON으로 응답한다". @RequestMapping("/api/auth") = 이 클래스의 모든 URL은 /api/auth로 시작.
• @RequiredArgsConstructor(롬복) = final 필드들을 받는 생성자를 자동 생성 → 스프링이 그 생성자로 의존성 주입(DI). new 키워드 없이 authService, jwtUtil 등을 스프링이 채워줍니다.
• AUTH_COOKIE_NAME/REFRESH_COOKIE_NAME 이 public static final 인 이유: 다른 클래스(JwtAuthenticationFilter)도 같은 쿠키 이름을 참조해야 하기 때문(AuthController.AUTH_COOKIE_NAME). 이름을 한 곳에서만 정의해 오타·불일치를 막는 패턴.

💡 초보 포인트: 쿠키 이름이 두 곳(발급=AuthController, 읽기=Filter)에서 쓰이는데 둘이 다르면 "로그인은 되는데 그다음 요청이 익명"이 되는 미묘한 버그가 납니다. 그래서 상수 한 곳에서 공유.

A-2. 설정값 주입 (@Value) — AuthController.java:46-62

// L46-L62
@Value("${app.cookie.secure:false}")
private boolean cookieSecure;

@Value("${app.cookie.same-site:Lax}")
private String cookieSameSite;

@Value("${app.jwt.ttl-hours:1}")
private long jwtTtlHours;

@Value("${app.jwt.refresh-ttl-days:15}")
private long refreshTtlDays;

• @Value("${키:기본값}") = application.properties(또는 환경변수)에서 값을 읽어 필드에 주입. 콜론 뒤가 기본값.
• cookieSecure:false — 로컬(http)에서는 false라야 쿠키가 전송됨. 운영(prod)에서는 반드시 true(HTTPS에서만 쿠키 전송)로 설정해야 합니다. 이게 빠지면 평문 HTTP로 쿠키가 새 나갈 수 있어요.
• jwtTtlHours:1 = Access 토큰 수명 1시간, refreshTtlDays:15 = Refresh 15일. 앞서 사전지식 5번의 "짧은 access / 긴 refresh".

A-3. 쿠키 굽기 헬퍼 — AuthController.java:66-94

// L66-L84
private ResponseCookie buildAuthCookie(String token) {
    return ResponseCookie.from(AUTH_COOKIE_NAME, token)
            .httpOnly(true)
            .secure(cookieSecure)
            .sameSite(cookieSameSite)
            .path("/")
            .maxAge(java.time.Duration.ofHours(jwtTtlHours))
            .build();
}

private ResponseCookie buildRefreshCookie(String token) {
    return ResponseCookie.from(REFRESH_COOKIE_NAME, token)
            .httpOnly(true)
            .secure(cookieSecure)
            .sameSite(cookieSameSite)
            .path("/api/auth")   // refresh 엔드포인트로만 전송
            .maxAge(java.time.Duration.ofDays(refreshTtlDays))
            .build();
}

• .httpOnly(true) — JS가 못 읽음(XSS 방어, 사전지식 2). 두 쿠키 모두 적용.
• .path("/") vs .path("/api/auth") — 여기가 영리한 보안 설계:
  • Access 쿠키는 path=/ → 모든 API 요청에 동봉(어디서나 인증 필요).
  • Refresh 쿠키는 path=/api/auth → 오직 /api/auth/* 요청에만 브라우저가 보냄. 즉 평소 일반 API 요청에는 refresh가 노출조차 안 됨 → 탈취 표면 축소.
• .maxAge(...) — 쿠키 자체의 만료(브라우저가 자동 삭제). Access는 1시간, Refresh는 15일.
• buildClearCookie(L86-94)는 같은 쿠키를 빈 값 + maxAge(0) 으로 다시 구워 즉시 삭제시킵니다(로그아웃용).

⚠️ 함정: 쿠키를 지울 때도 만들 때와 동일한 path/속성으로 구워야 브라우저가 "같은 쿠키"로 인식해 삭제합니다. 그래서 logout에서 buildClearCookie(REFRESH_COOKIE_NAME, "/api/auth") 처럼 path를 정확히 맞춥니다(L364).

A-4. Refresh 토큰 발급 헬퍼 — AuthController.java:98-108

// L98-L108
private String issueRefreshToken(Long userId) {
    String raw = UUID.randomUUID().toString().replace("-", "");
    refreshTokenRepository.save(RefreshToken.of(userId, raw, refreshTtlDays));
    return raw;
}

private ResponseEntity.BodyBuilder withTokenCookies(String accessToken, String refreshToken) {
    return ResponseEntity.ok()
            .header(HttpHeaders.SET_COOKIE, buildAuthCookie(accessToken).toString())
            .header(HttpHeaders.SET_COOKIE, buildRefreshCookie(refreshToken).toString());
}

• Refresh 토큰은 JWT가 아니라 그냥 무작위 UUID 문자열(replace("-","") 로 하이픈 제거 → 32자). JWT와 달리 "의미 없는 임의 값"이고, 유효성은 DB 존재 여부로만 판단합니다(아래 refresh 참고). 그래서 DB에서 지우면 즉시 무효화 가능.
• withTokenCookies — Set-Cookie 헤더를 두 번 추가(access + refresh). HTTP는 Set-Cookie 헤더를 여러 개 보낼 수 있어 쿠키 2장을 동시에 굽습니다.

A-5. 회원가입 signup — AuthController.java:112-135

// L112-L130
@PostMapping("/signup")
public ResponseEntity<AuthResponse> signup(@RequestBody SignupRequest request) {
    try {
        User user = authService.signup(request);
        String userType = user.getUserType() != null ? user.getUserType().name() : "GUEST";
        String access  = jwtUtil.issue(user.getId(), user.getEmail(), userType);
        String refresh = issueRefreshToken(user.getId());
        return withTokenCookies(access, refresh)
                .body(AuthResponse.builder()
                        .userId(user.getId())
                        .email(user.getEmail())
                        ...
                        .token(access)
                        .message("회원가입이 완료되었습니다.")
                        .build());
    } catch (Exception e) {
        return ResponseEntity.badRequest().body(AuthResponse.builder()
                .message(e.getMessage()).build());
    }
}

• @PostMapping("/signup") → POST /api/auth/signup. @RequestBody SignupRequest = 요청 JSON 본문을 SignupRequest 객체로 자동 역직렬화.
• 흐름: 가입은 AuthService.signup에 위임(비즈니스 로직 분리) → 돌아온 User로 즉시 토큰 발급(가입과 동시에 로그인 상태로). 이걸 "auto-login on signup" 패턴이라 합니다.
• userType.name() 이 null이면 "GUEST" 폴백 — 토큰의 type 클레임에 들어갈 문자열.
• .token(access) — 쿠키로도 주지만 응답 본문에도 access 토큰을 같이 담습니다(레거시 호환: 헤더 방식 클라이언트 대비. 아래 필터 2순위 참고).
• 예외 처리: 가입 실패(중복 이메일 등)면 400 Bad Request + 한글 메시지. 컨트롤러가 예외를 잡아 사용자 친화 메시지로 변환.

A-6. 로그인 login — AuthController.java:137-160

구조는 signup과 거의 동일(authService.login → 토큰 발급 → 쿠키). 차이는 진입점이 authService.login이라는 것뿐. 비밀번호 대조의 진짜 로직은 AuthService.login에 있습니다(아래 B-2에서 심화).

A-7. 토큰 재발급 refresh — AuthController.java:166-191

// L166-L191
@PostMapping("/refresh")
public ResponseEntity<?> refresh(HttpServletRequest request) {
    String rawToken = extractCookie(request, REFRESH_COOKIE_NAME);
    if (rawToken == null || rawToken.isBlank()) {
        return ResponseEntity.status(401).body(Map.of("message", "Refresh token 없음"));
    }

    RefreshToken rt = refreshTokenRepository.findByToken(rawToken).orElse(null);
    if (rt == null || rt.isExpired()) {
        if (rt != null) refreshTokenRepository.deleteByToken(rawToken);
        return ResponseEntity.status(401).body(Map.of("message", "Refresh token 만료 또는 유효하지 않음"));
    }

    User user = userRepository.findById(rt.getUserId()).orElse(null);
    if (user == null) {
        refreshTokenRepository.deleteByToken(rawToken);
        return ResponseEntity.status(401).body(Map.of("message", "사용자 없음"));
    }

    String userType = user.getUserType() != null ? user.getUserType().name() : "GUEST";
    String newAccess = jwtUtil.issue(user.getId(), user.getEmail(), userType);

    return ResponseEntity.ok()
            .header(HttpHeaders.SET_COOKIE, buildAuthCookie(newAccess).toString())
            .body(Map.of("message", "토큰 재발급 완료"));
}

• 시나리오: Access(1시간)가 만료되면, 프론트는 재로그인 대신 이 /api/auth/refresh를 호출. (Refresh 쿠키는 path=/api/auth라 여기서만 동봉됨 — A-3의 설계가 빛나는 순간.)
• 검증 3단:
  1. 쿠키에 refresh가 있나 → 없으면 401.
  2. DB에 그 토큰이 존재하고 안 만료됐나(findByToken + isExpired) → 만료면 DB에서 삭제하고 401(쓰레기 청소).
  3. 그 토큰의 주인 User가 실제 존재하나 → 탈퇴한 사용자면 토큰 삭제 후 401.
• 통과하면 새 Access만 발급(buildAuthCookie만). Refresh는 그대로 두어 15일 동안 재사용. (이를 "non-rotating refresh"라 합니다 — 고도화 아이디어에서 회전 방식 논의.)

💡 초보 포인트: refresh 검증이 JWT 파싱이 아니라 DB 조회라는 점이 중요. Access(JWT)는 "서명만 맞으면 통과"(stateless)지만, Refresh는 "DB에 살아있어야 통과"(stateful). 그래서 로그아웃/탈퇴 시 DB에서 지우면 즉시 무효화됩니다.

A-8. 소셜 로그인 socialLogin + 구글 검증 — AuthController.java:193-253

// L193-L210
@PostMapping("/social-login")
public ResponseEntity<AuthResponse> socialLogin(@RequestBody Map<String, String> request) {
    String accessToken = request.get("accessToken");
    if (accessToken == null || accessToken.isBlank()) {
        return ResponseEntity.badRequest().body(AuthResponse.builder()
                .message("소셜 로그인 토큰(accessToken)이 필요합니다.").build());
    }
    // 보안(C2): 클라이언트가 보낸 email 은 신뢰하지 않는다. accessToken 을 Google 에 직접 검증해 verified email 을 얻는다.
    String email;
    try {
        email = verifyGoogleAccessToken(accessToken);
    } catch (Exception e) {
        return ResponseEntity.status(401).body(AuthResponse.builder()
                .message("소셜 인증 검증 실패 — 다시 시도해 주세요.").build());
    }
    ...
}

• 이 4줄짜리 주석이 도메인 전체에서 가장 중요한 보안 한 줄입니다. 프론트가 보낸 email을 절대 안 씁니다. 오직 프론트가 준 accessToken만 받아, 서버가 직접 구글에 물어봅니다.
• 왜? 만약 email = request.get("email")로 클라이언트 말을 믿으면, 공격자가 {accessToken: 내토큰, email: victim@x.com} 을 보내 남의 계정으로 로그인할 수 있습니다(IDOR/계정 탈취). 이게 함정 섹션 C2.

// L238-L253
@SuppressWarnings("unchecked")
private String verifyGoogleAccessToken(String accessToken) {
    var headers = new org.springframework.http.HttpHeaders();
    headers.set("Authorization", "Bearer " + accessToken);
    Map<String, Object> info = restTemplate.exchange(
            "https://www.googleapis.com/oauth2/v3/userinfo",
            HttpMethod.GET, new org.springframework.http.HttpEntity<>(headers), Map.class
    ).getBody();
    if (info == null) throw new RuntimeException("Google userinfo 응답 없음");
    Object email = info.get("email");
    if (email == null || String.valueOf(email).isBlank()) throw new RuntimeException("이메일 정보 없음");
    Object verified = info.get("email_verified");
    boolean isVerified = Boolean.TRUE.equals(verified) || "true".equalsIgnoreCase(String.valueOf(verified));
    if (!isVerified) throw new RuntimeException("이메일 미인증 Google 계정");
    return String.valueOf(email);
}

• restTemplate.exchange(...userinfo..., Bearer accessToken) — 구글의 공식 userinfo 엔드포인트에 그 토큰으로 직접 GET. 토큰이 가짜면 구글이 401을 주고 여기서 예외 → 통과 못 함. 이게 "위조 불가"의 근거.
• email_verified 도 확인 — 구글에서 이메일 인증까지 마친 계정만 허용(미인증 구글 계정으로 남의 이메일 선점 방지).
• 검증된 email로 authService.socialLogin(email) 호출 → 가입돼 있으면 토큰 발급, 없으면 "가입되지 않은 이메일" 예외(소셜은 자동가입 안 함, 깃허브와 차이).

A-9. GitHub 로그인 githubLogin — AuthController.java:258-354

구글과 흐름은 비슷하나 단계가 더 많습니다(GitHub는 code → token → email → profile 4홉):

1. code → access_token 교환(L269-290): 프론트가 받은 code를 우리 client_id/secret과 함께 GitHub에 보내 access_token으로 교환. (secret은 서버만 보관 → 프론트가 흉내 못 냄.)
2. 인증된 primary 이메일 조회(L298-321): /user/emails에서 primary && verified인 이메일 우선, 없으면 verified인 것 — 인증된 이메일만 채택.
3. 프로필 조회(L323-330): /user에서 login(=깃허브 username) 확보.
4. 계정 조회 또는 자동 생성(L332): authService.findOrCreateGithubUser(email, login, token) — 구글과 달리 없으면 자동 가입(B-4 참고).

💡 두 소셜의 차이: 구글은 "이미 가입한 사람만 소셜 로그인 허용", 깃허브는 "없으면 만들어줌(개발자 연동 목적)". 같은 OAuth라도 정책이 다를 수 있음을 보여주는 좋은 예.

A-10. 로그아웃 logout — AuthController.java:356-366

// L356-L366
@PostMapping("/logout")
public ResponseEntity<Map<String, String>> logout(HttpServletRequest request) {
    String rawToken = extractCookie(request, REFRESH_COOKIE_NAME);
    if (rawToken != null && !rawToken.isBlank()) {
        refreshTokenRepository.deleteByToken(rawToken);
    }
    return ResponseEntity.ok()
            .header(HttpHeaders.SET_COOKIE, buildClearCookie(AUTH_COOKIE_NAME, "/").toString())
            .header(HttpHeaders.SET_COOKIE, buildClearCookie(REFRESH_COOKIE_NAME, "/api/auth").toString())
            .body(Map.of("message", "로그아웃 되었습니다."));
}

• 로그아웃은 두 가지를 동시에: ① DB의 refresh 토큰 삭제(서버측 무효화 → 더는 재발급 불가), ② 브라우저 쿠키 2장 삭제(maxAge=0).
• Access(JWT)는 stateless라 서버가 "취소"할 수 없습니다 — 하지만 쿠키를 지우고 1시간 뒤 자연 만료되며, refresh가 죽었으니 갱신도 안 됩니다. 사실상 로그아웃 완료.

A-11. 쿠키 추출 유틸 — AuthController.java:370-378

// L370-L378
private String extractCookie(HttpServletRequest request, String name) {
    Cookie[] cookies = request.getCookies();
    if (cookies == null) return null;
    return Arrays.stream(cookies)
            .filter(c -> name.equals(c.getName()))
            .map(Cookie::getValue)
            .findFirst()
            .orElse(null);
}

• 요청의 쿠키 배열에서 이름이 일치하는 첫 쿠키의 값을 꺼냄. getCookies()는 쿠키가 하나도 없으면 null을 반환하므로 null 체크 필수(흔한 NPE 함정).

---

B. AuthService — 신원 확인 담당관

B-1. 회원가입 signup — AuthService.java:26-59

// L26-L44
@Transactional
public User signup(SignupRequest request) {
    if (userRepository.findByEmail(request.getEmail()).isPresent()) {
        throw new RuntimeException("이미 사용 중인 이메일입니다.");
    }
    if (userRepository.findByUsername(request.getUsername()).isPresent()) {
        throw new RuntimeException("이미 사용 중인 사용자 이름입니다.");
    }

    User user = User.builder()
            .email(request.getEmail())
            .phone(request.getPhone())
            .username(request.getUsername())
            .password(passwordEncoder.encode(request.getPassword()))   // ★ BCrypt 해싱
            .userType(request.getUserType())
            .birthDate(request.getBirthDate())
            .build();

    User savedUser = userRepository.save(user);
    ...
}

• @Transactional = 이 메서드 안의 DB 작업을 하나의 트랜잭션으로 묶음. 중간에 예외가 나면 전부 롤백(예: 유저 저장 후 프로필 저장 실패 시 유저도 취소).
• 중복 검사: 이메일·username 둘 다 unique 제약이 DB에도 있지만(엔티티 참고), 여기서 미리 검사해 친절한 한글 메시지를 줍니다. (DB 제약은 최후의 방어선, 이건 UX 방어선.)
• passwordEncoder.encode(...) = 평문 비번을 BCrypt 해시로 변환해 저장. 이 한 줄이 함정 섹션 C1의 핵심 — DB에 절대 평문이 안 들어갑니다.
• 이후(L46-58): userType == FREE면 ClientProfile 생성, 그리고 Stream Chat에 유저 동기화(실패해도 가입은 진행 — try/catch로 격리).

B-2. 로그인 + 레거시 비번 투명 마이그레이션 — AuthService.java:84-106 ⭐

// L84-L106
@Transactional
public User login(LoginRequest request) {
    User user = userRepository.findByEmail(request.getEmail())
            .orElseThrow(() -> new RuntimeException("가입되지 않은 이메일입니다."));

    String stored = user.getPassword();
    String raw = request.getPassword();
    boolean ok;
    if (stored != null && stored.startsWith("$2")) {
        ok = passwordEncoder.matches(raw, stored);          // BCrypt 해시 비교
    } else {
        // 레거시 평문 비번 — 일치 시 즉시 BCrypt 로 재해싱(투명 마이그레이션)
        ok = stored != null && stored.equals(raw);
        if (ok) {
            user.setPassword(passwordEncoder.encode(raw));
            userRepository.save(user);
        }
    }
    if (!ok) {
        throw new RuntimeException("비밀번호가 일치하지 않습니다.");
    }
    return user;
}

• 이 메서드가 C1 보안 수정의 알맹이입니다. 두 갈래:
  • stored.startsWith("$2") → 이미 BCrypt 해시(사전지식 3의 $2 접두사) → passwordEncoder.matches(raw, stored) 로 안전 비교. (matches는 평문 raw를 같은 솔트로 해싱해 비교 — 평문 비번을 절대 복원하지 않음.)
  • 그 외(레거시 평문) → 과거에 평문으로 저장된 계정. 평문끼리 비교해 맞으면 그 자리에서 즉시 BCrypt로 재해싱해 저장(encode 후 save). 이걸 투명 마이그레이션이라 합니다 — 사용자는 모르는 새, 로그인 성공 순간 그 계정의 비번이 안전한 해시로 업그레이드됩니다.
• 왜 이렇게? DB에 옛 평문 계정이 섞여 있을 때, 전체를 한 번에 재해싱할 수 없으니(평문을 알아야 해시함) 로그인할 때마다 한 명씩 점진 전환. 한 번 로그인하면 영원히 해시로 굳습니다.

⚠️ 함정: stored.startsWith("$2") 판별은 "BCrypt처럼 보이면 해시로 취급"입니다. 만약 어떤 사용자의 평문 비번이 진짜로 $2로 시작한다면(예: $2abc), 레거시 분기를 못 타 로그인 실패할 수 있는 극단 케이스가 있습니다. 실무에선 거의 없지만, 마이그레이션 완료 후 레거시 분기 자체를 제거하는 게 깔끔합니다(고도화).

B-3. 소셜 로그인 조회 socialLogin — AuthService.java:113-116

// L113-L116
public User socialLogin(String email) {
    return userRepository.findByEmail(email)
            .orElseThrow(() -> new RuntimeException("가입되지 않은 이메일입니다."));
}

• 단순함이 핵심: 비밀번호 검증을 건너뛰고(이미 구글이 신원 보증) 이메일로 기존 User만 조회. 없으면 예외 → 컨트롤러가 "가입 안내"로 처리. (자동가입 안 함 — A-8 정책.)
• @Transactional이 없음에 주목: 읽기만 하므로 트랜잭션 없이 단순 조회.

B-4. GitHub 계정 조회/생성 findOrCreateGithubUser — AuthService.java:122-168

// L122-L137
@Transactional
public User findOrCreateGithubUser(String email, String githubLogin, String accessToken) {
    java.time.LocalDateTime now = java.time.LocalDateTime.now();
    byte[] encryptedToken = null;
    if (accessToken != null && !accessToken.isBlank()) {
        try { encryptedToken = crypto.encrypt(accessToken); } catch (Exception ignored) {}
    }
    final byte[] tokenBytes = encryptedToken;

    return userRepository.findByEmail(email)
            .map(existing -> {
                existing.setGithubUsername(githubLogin);
                existing.setGithubConnectedAt(now);
                if (tokenBytes != null) existing.setGithubTokenEncrypted(tokenBytes);
                return userRepository.save(existing);
            })
            .orElseGet(() -> { ... 신규 생성 ... });
}

• GitHub access_token은 평문 저장 금지 → crypto.encrypt(accessToken) 로 AES-GCM 암호화한 바이트를 저장(githubTokenEncrypted). (암호화 서비스는 D-4 참고. CLAUDE.md의 "KIS 자격증명 AES-GCM 암호화"와 같은 원칙.)
• findByEmail(...).map(기존 갱신).orElseGet(신규 생성) 패턴: 이메일로 찾으면 기존 계정에 GitHub 정보만 덧붙임(이미 일반 가입한 사람이 GitHub 연동), 없으면 새 계정 생성.

// L138-L157 (신규 생성)
.orElseGet(() -> {
    String baseUsername = githubLogin.toLowerCase().replaceAll("[^a-z0-9_]", "_");
    String username = baseUsername;
    int suffix = 2;
    while (userRepository.findByUsername(username).isPresent()) {
        username = baseUsername + suffix++;
    }

    User newUser = User.builder()
            .email(email)
            .username(username)
            .password(passwordEncoder.encode(java.util.UUID.randomUUID().toString()))  // ★ 랜덤 더미 비번
            .phone("00000000000")
            .userType(User.UserType.FREE)
            .githubUsername(githubLogin)
            .githubTokenEncrypted(tokenBytes)
            .githubConnectedAt(now)
            .build();
    ...
});

• username 충돌 회피: GitHub login을 소문자+안전문자로 정규화하고, 이미 존재하면 2, 3, 4… 접미사를 붙여 유일한 username을 만듦(username 컬럼이 unique라 충돌 시 저장 실패하므로 사전 회피).
• 비번이 없는 계정 처리: 소셜 가입자는 비번이 없으니 UUID.randomUUID()(아무도 모르는 무작위)를 BCrypt 해싱해 채움. 이렇게 하면 ① password NOT NULL 제약 만족, ② 그 비번으로는 일반 로그인 불가(아무도 그 UUID를 모름) → 오직 GitHub로만 로그인. 영리한 트릭.

---

C. JwtUtil — 출입증 인쇄기 + 위조 감별기

C-1. 비밀키 준비 — JwtUtil.java:25-38

// L25-L38
public JwtUtil(
        @Value("${app.jwt.secret:dev-bridge-default-secret-key-change-in-production-please}") String secret,
        @Value("${app.jwt.ttl-hours:1}") long ttlHours
) {
    byte[] bytes = secret.getBytes(StandardCharsets.UTF_8);
    if (bytes.length < 32) {
        // 32바이트 미만이면 패딩 (개발 편의)
        byte[] padded = new byte[32];
        System.arraycopy(bytes, 0, padded, 0, bytes.length);
        bytes = padded;
    }
    this.key = Keys.hmacShaKeyFor(bytes);
    this.ttlMillis = ttlHours * 60 * 60 * 1000L;
}

• HS256(HMAC-SHA256)은 최소 32바이트(256비트) 키를 요구합니다. 짧으면 라이브러리(JJWT)가 거부하므로, 부족하면 0으로 패딩(개발 편의).
• ⚠️ 운영 주의: 기본값 dev-bridge-default-secret-... 으로 운영하면 누구나 토큰을 위조할 수 있습니다(소스에 키가 공개됨). 운영에서는 JWT_SECRET 환경변수로 강한 키를 반드시 주입해야 합니다(CLAUDE.md 필수 환경변수).
• ttlMillis = 토큰 수명을 밀리초로 환산(시간 × 3,600,000).

C-2. 토큰 발행 issue — JwtUtil.java:46-58

// L46-L58
public String issue(Long userId, String email, String userType) {
    Date now = new Date();
    return Jwts.builder()
            .subject(email)
            .claims(Map.of(
                    "uid", userId,
                    "type", userType
            ))
            .issuedAt(now)
            .expiration(new Date(now.getTime() + ttlMillis))
            .signWith(key)
            .compact();
}

• JWT 페이로드(클레임) 구성:
  • subject(email) — 표준 클레임 sub에 이메일.
  • uid — 사용자 PK(이후 AuthContext/필터가 이걸 꺼냄). 인증의 핵심 식별자.
  • type — userType(FREE/STANDARD/PREMIUM). 권한·구독 기능 게이트에 활용 가능.
  • issuedAt/expiration — 발행시각·만료시각(now + 1시간).
• .signWith(key) — 비밀키로 서명(여기서 위조 불가가 보장됨). .compact() — 최종 a.b.c 문자열로 직렬화.

💡 페이로드는 누구나 읽을 수 있으니(사전지식 1) uid, type 같은 민감하지 않은 식별자만 넣습니다. 비번·전화번호 등은 절대 안 넣습니다.

C-3. 토큰 검증 parse / extractUserId — JwtUtil.java:61-73

// L61-L73
public Claims parse(String token) {
    return Jwts.parser()
            .verifyWith(key)
            .build()
            .parseSignedClaims(token)
            .getPayload();
}

public Long extractUserId(String token) {
    Object uid = parse(token).get("uid");
    if (uid instanceof Number n) return n.longValue();
    return null;
}

• verifyWith(key).parseSignedClaims(token) — 서명 검증 + 만료 검증을 동시에. 서명이 틀리거나(위조) 만료됐으면 예외를 던집니다(이게 보안의 자동 차단막).
• uid instanceof Number 체크 이유: JWT를 JSON으로 역직렬화하면 숫자가 Integer로 올 수도, Long으로 올 수도 있어 Number로 받아 longValue()로 통일. (Integer로 캐스팅하면 큰 id에서 ClassCastException 위험.)

---

D. JwtAuthenticationFilter — 입구 경비원

D-1. 필터 등록 + 실행 순서 — JwtAuthenticationFilter.java:28-37

// L28-L37
@Component
@Order(Ordered.HIGHEST_PRECEDENCE + 10)   // 반드시 AiRateLimitFilter(+20)보다 먼저 실행
@RequiredArgsConstructor
@Slf4j
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    public static final String ATTR_USER_ID = "auth.userId";
    public static final String ATTR_USER_TYPE = "auth.userType";

    private final JwtUtil jwtUtil;

• OncePerRequestFilter = 요청 1개당 정확히 한 번 실행 보장(스프링 내부 forward 등으로 중복 실행 방지).
• @Order(HIGHEST_PRECEDENCE + 10) — 반드시 일찍 실행. 주석대로 AiRateLimitFilter(+20)보다 먼저 돌아야, 레이트리밋 필터가 auth.userId를 읽을 수 있습니다(유저별 한도 적용). 필터 순서 의존성을 보여주는 좋은 예.
• ATTR_USER_ID/ATTR_USER_TYPE 상수 = 요청에 도장 찍을 때 쓰는 키(이름). AuthContext가 같은 키로 꺼냅니다.

D-2. 핵심 — 토큰 검증 후 요청에 도장 — JwtAuthenticationFilter.java:39-60

// L39-L60
@Override
protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
        throws ServletException, IOException {
    String token = extractToken(request);
    if (token != null && !token.isBlank()) {
        try {
            var claims = jwtUtil.parse(token);
            Object uid = claims.get("uid");
            Object type = claims.get("type");
            if (uid instanceof Number n) {
                request.setAttribute(ATTR_USER_ID, n.longValue());
            }
            if (type != null) {
                request.setAttribute(ATTR_USER_TYPE, type.toString());
            }
        } catch (Exception e) {
            // 토큰 파싱 실패: 익명 요청으로 통과
            log.debug("JWT parse failed: {}", e.getMessage());
        }
    }
    chain.doFilter(request, response);
}

• 흐름: 토큰 추출 → parse(검증) → 성공하면 request.setAttribute(ATTR_USER_ID, uid) 로 요청에 도장. 이게 (B) 흐름도의 "도장 찍기".
• 실패해도 막지 않음(catch 후 그냥 통과): 토큰이 없거나 깨졌으면 익명 요청으로 처리. 차단은 컨트롤러가 AuthContext.currentUserId() == null 검사로 합니다(이 프로젝트 경량 인증 철학).
• chain.doFilter(...) — 다음 필터/컨트롤러로 요청 전달(필터 체인 진행).

D-3. 토큰 추출 우선순위 — JwtAuthenticationFilter.java:62-79

// L62-L79
private String extractToken(HttpServletRequest request) {
    // 1순위: HttpOnly 쿠키
    Cookie[] cookies = request.getCookies();
    if (cookies != null) {
        for (Cookie c : cookies) {
            if (AuthController.AUTH_COOKIE_NAME.equals(c.getName())) {
                String v = c.getValue();
                if (v != null && !v.isBlank()) return v.trim();
            }
        }
    }
    // 2순위: Authorization 헤더 (레거시 호환)
    String header = request.getHeader("Authorization");
    if (header != null && header.startsWith("Bearer ")) {
        return header.substring(7).trim();
    }
    return null;
}

• 1순위: HttpOnly 쿠키 DEVBRIDGE_TOKEN(새 표준, XSS 안전). AuthController.AUTH_COOKIE_NAME 상수를 참조 — A-1의 "이름 공유"가 여기서 작동.
• 2순위: Authorization: Bearer <token> 헤더(레거시 호환). 옛 클라이언트나 외부 API 호출이 헤더 방식을 쓸 수 있어 둘 다 지원. substring(7) = "Bearer "(7글자) 잘라내기.

D-4. (연관) AesGcmCryptoService — GitHub 토큰 암호화 — AesGcmCryptoService.java

• GitHub PAT/access_token 같은 민감값을 DB 저장 전 AES-GCM으로 암호화(encrypt → [12B IV][암호문+태그]).
• 키 출처: app.crypto.key(없으면 app.jwt.secret의 SHA-256 폴백, L42-49). 운영에서는 별도 키 권장(주석 명시).
• encrypt(L51-63): 매번 무작위 IV 12바이트 생성 → 같은 평문도 매번 다른 암호문(보안). GCM은 인증태그(128bit)로 변조 탐지까지 제공.

---

E. AuthContext — "지금 누구?" 판독기

E-1. 현재 사용자 ID 조회 — AuthContext.java:27-47

// L27-L47
public static Long currentUserId() {
    Long override = OVERRIDE_USER_ID.get();
    if (override != null) return override;
    HttpServletRequest req = currentRequest();
    if (req == null) return null;
    Object v = req.getAttribute(JwtAuthenticationFilter.ATTR_USER_ID);
    return v instanceof Long ? (Long) v : null;
}
...
public static Long requireUserId() {
    Long id = currentUserId();
    if (id == null) throw new RuntimeException("인증이 필요합니다.");
    return id;
}

• 컨트롤러가 AuthContext.currentUserId() 한 줄로 현재 요청의 주인을 얻습니다 — 내부적으로는 필터가 찍은 request의 auth.userId 속성을 꺼내는 것(D-2와 짝).
• RequestContextHolder로 현재 스레드의 요청을 가져옵니다(컨트롤러 인자로 HttpServletRequest를 안 받아도 어디서나 접근 가능 → 코드 간결).
• OVERRIDE_USER_ID(ThreadLocal): HTTP 요청이 없는 백그라운드 잡(스케줄러 등)에서 임시로 "이 작업은 N번 유저로 친다"를 주입하는 용도. set 후 반드시 finally에서 clear()(ThreadLocal 누수 방지 — 함정).
• requireUserId() = null이면 예외(반드시 로그인 필요한 곳용). 반면 currentUserId() = null 허용(직접 401 분기하고 싶을 때). 컨트롤러들이 둘 중 골라 씁니다.

💡 보안 교훈: 컨트롤러는 절대 클라이언트가 보낸 userId를 신뢰하지 않고, 오직 AuthContext(=서버가 검증한 JWT)에서만 신원을 얻습니다. 최근 커밋 NotificationController IDOR 차단이 바로 이 원칙(신원은 JWT에서만)을 적용한 사례입니다.

---

F. 엔티티 — DB로 굳는 데이터

F-1. User — 회원 1명 = USERS 한 행 — User.java

// L13-L41
@Entity
@Table(name = "USERS")
@Getter @Setter @NoArgsConstructor @AllArgsConstructor @Builder
@EntityListeners(AuditingEntityListener.class)
public class User {

    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true, length = 100)
    private String email;

    @Column(nullable = false, length = 20)
    private String phone;

    @Column(nullable = false, unique = true, length = 50)
    private String username;

    @Column(nullable = false, length = 255)
    private String password;       // ★ BCrypt 해시 저장 (평문 금지)

    @Convert(converter = UserTypeConverter.class)
    @Column(name = "user_type", nullable = false)
    private UserType userType;

• @Entity @Table(name="USERS") = 이 클래스 1개 = DB USERS 테이블, 인스턴스 1개 = 한 행.
• @Id @GeneratedValue(IDENTITY) = PK id를 DB가 auto-increment로 생성. 이 id가 JWT의 uid가 됩니다.
• email/username에 unique = true = DB 차원의 중복 금지(AuthService 사전검사의 최종 방어선).
• password length=255 = BCrypt 해시(약 60자)가 들어가도 넉넉. 여기 절대 평문 안 들어감(C1).
• @EntityListeners(AuditingEntityListener.class) + @CreatedDate/@UpdateTimestamp(L86-92) = 생성·수정 시각 자동 기록.

// L78-L84 (GitHub 연동 필드)
@Column(name = "github_token_encrypted", columnDefinition = "VARBINARY(512)")
private byte[] githubTokenEncrypted;     // ★ AES-GCM 암호화 바이트 (평문 노출 금지)

• GitHub 토큰은 byte[](VARBINARY)로 암호화된 형태만 저장(D-4와 짝). 주석이 "절대 평문 노출 금지"를 못 박음.

// L94-L110 (UserType + 역방향 호환)
public enum UserType {
    FREE, STANDARD, PREMIUM;

    @JsonCreator
    public static UserType fromJson(String value) {
        if (value == null) return null;
        return switch (value.toUpperCase()) {
            case "CLIENT", "USER", "FREE" -> FREE;
            case "PARTNER", "PRO", "STANDARD" -> STANDARD;
            case "PREMIUM" -> PREMIUM;
            default -> FREE;
        };
    }
}

• UserType은 구독 등급(FREE/STANDARD/PREMIUM). @JsonCreator fromJson = 프론트가 옛 값(CLIENT/PARTNER/PRO 등)을 보내도 새 enum으로 매핑(요청 역직렬화 시).
• 짝으로 UserTypeConverter(UserTypeConverter.java)가 DB 읽기/쓰기를 담당: DB의 옛 값(CLIENT/PARTNER…)도 새 enum으로 읽고, 저장은 항상 새 값으로. (CLAUDE.md "구 값 역방향 호환"의 실체.)

💡 왜 이 호환 장치가 두 개(@JsonCreator + Converter)나 있나? 두 경계가 다르기 때문: @JsonCreator는 "HTTP JSON ↔ Java" 경계, Converter는 "Java ↔ DB" 경계. 옛 데이터·옛 클라이언트가 양쪽에 다 있을 수 있어 두 군데를 모두 막은 것.

F-2. RefreshToken — 재발급 쿠폰 — RefreshToken.java

// L8-L40
@Entity
@Table(name = "refresh_tokens", indexes = {
        @Index(name = "idx_rt_user_id", columnList = "user_id"),
        @Index(name = "idx_rt_expires_at", columnList = "expires_at")
})
@Getter @NoArgsConstructor(access = AccessLevel.PROTECTED)
public class RefreshToken {

    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(name = "user_id", nullable = false)
    private Long userId;

    @Column(nullable = false, unique = true, length = 64)
    private String token;

    @Column(name = "expires_at", nullable = false)
    private Instant expiresAt;
    ...
    public static RefreshToken of(Long userId, String token, long ttlDays) {
        RefreshToken rt = new RefreshToken();
        rt.userId = userId;
        rt.token = token;
        rt.expiresAt = Instant.now().plusSeconds(ttlDays * 86400L);
        rt.createdAt = Instant.now();
        return rt;
    }

    public boolean isExpired() {
        return Instant.now().isAfter(expiresAt);
    }
}

• token unique = 같은 토큰 문자열 중복 금지. @Index(user_id, expires_at) = 사용자별 조회·만료 청소를 빠르게(DB 인덱스).
• @NoArgsConstructor(access = PROTECTED) + 정적 팩토리 of(...) = 외부에서 new 막고 항상 of로만 생성하게 강제(유효한 상태로만 만들어지도록). isExpired()는 A-7의 refresh 검증에서 쓰입니다.
• ⚠️ 이 엔티티 테이블은 마이그레이션 V18__refresh_tokens_table.sql로 생성됩니다(함정 섹션 참고).

---

G. 부가 컨트롤러·서비스 (조회·프로필·은행·이메일)

• UserController(/api/users): 채팅 기능용 공개 조회. searchByUsername·findByEmail·findById는 id/username/userType/프로필이미지만 반환하고 email·개인정보는 절대 안 줌(주석 명시 "never returns email"). /me/github-username GET/PATCH는 AuthContext로 본인만 자기 GitHub username 조회·수정.
• ProfileController/ProfileService(/api/profile): 프로필 상세 저장(PUT /me/detail)·조회(GET /me/detail, public GET /{username}/detail)·기본정보 수정(PUT /me/basic)·초기화(POST /me/reset). POST /admin/reset/{username}는 local 프로파일에서만 동작(L78-86에서 활성 프로파일 검사 후 아니면 403) — 운영에서 자동 차단되는 dev 전용 안전장치.
• BankVerificationController/Service(/api/bank): 계좌 인증. send-code가 3자리 코드를 생성해 이메일 발송(시연용이라 응답 본문에도 mockCode 노출), verify-code가 검증 후 계좌정보 저장. 핵심은 verifyAndSave(L84-123)의 codeStore.compute(...) — 동시 요청 레이스를 락 안에서 막고, 만료/시도초과(최대 5회)/1회용 폐기를 한 번에 처리. 코드는 메모리(ConcurrentHashMap)에 저장 → 재기동 시 휘발(시연 범위).
• EmailVerificationController/Service(/api/verify): 회원가입 전 이메일 본인확인. send-code가 6자리 코드 발송, check-code가 검증(일치 시 1회용 제거). 마찬가지로 메모리 저장·휘발.

💡 공통 패턴: bank/email 인증 모두 외부 본인확인 서비스 대신 "코드 메일 발송 → 입력 대조" 라는 목업/시연 방식입니다. 운영 전환 시 ① 코드 저장을 Redis로(다중 인스턴스·재기동 대비), ② mockCode 응답 제거, ③ 실제 본인확인 API 연동이 필요합니다(고도화).

---

⚠️ 함정·보안 주의

#	항목	무엇이 위험했나 / 어떻게 막았나
C1	BCrypt 레거시 재해싱	과거 평문 비번 저장 → DB 유출 시 전원 비번 노출. AuthService.login(B-2)이 $2 접두사로 해시/평문을 구분하고, 평문은 로그인 성공 순간 즉시 BCrypt로 재해싱(투명 마이그레이션). 신규 가입은 처음부터 passwordEncoder.encode(B-1).
C2	소셜 accessToken 서버검증	프론트가 보낸 email을 믿으면 {내토큰, 남의email}로 계정 탈취. socialLogin(A-8)은 클라 email을 버리고, verifyGoogleAccessToken으로 구글 userinfo에 직접 검증해 verified email만 사용. GitHub도 /user/emails에서 verified 이메일만 채택.
3	쿠키 Secure/SameSite	cookieSecure:false 기본값으로 운영하면 평문 HTTP로 쿠키 전송 가능. 운영에서 app.cookie.secure=true 필수. SameSite=Lax로 CSRF 기본 방어.
4	Refresh 쿠키 path 격리	Refresh를 path=/로 깔면 모든 요청에 노출. path=/api/auth로 묶어 갱신 엔드포인트에서만 전송(A-3) → 탈취 표면 최소화.
5	refresh_tokens 마이그레이션	main이 RefreshToken 엔티티를 추가했으나 Flyway 마이그레이션이 없어, ddl-auto=validate인 운영 부팅이 Hibernate validate에서 실패. V18__refresh_tokens_table.sql(CREATE TABLE IF NOT EXISTS, 멱등)로 보강.
6	JWT secret 기본값	JwtUtil의 기본 secret으로 운영하면 누구나 토큰 위조. JWT_SECRET 환경변수로 강한 키 주입 필수(C-1).
7	신원은 JWT에서만	컨트롤러가 클라이언트 userId를 믿으면 IDOR. 항상 AuthContext.currentUserId()(서버 검증값)만 사용(E-1). 최근 NotificationController IDOR 차단 커밋이 같은 원칙.
8	$2 평문 오탐	평문 비번이 우연히 $2로 시작하면 레거시 분기를 못 타 로그인 실패(B-2 함정). 마이그레이션 완료 후 레거시 분기 제거 권장.
9	GitHub 토큰 평문 금지	access_token은 AesGcmCryptoService.encrypt로 암호화 후 byte[] 저장(B-4·F-1). 키는 운영에서 app.crypto.key 별도 발급.
10	인증코드 휘발/노출	bank·email 코드가 메모리(ConcurrentHashMap)라 다중 인스턴스/재기동에 취약. bank mockCode는 시연용 응답 노출 — 운영 전 Redis 이전 + 응답 제거 필요.

---

🚀 고도화 아이디어

• Refresh 토큰 회전(rotation): 현재는 갱신 시 Access만 새로 발급하고 Refresh는 15일 고정 재사용(A-7). 갱신할 때마다 새 Refresh로 교체 + 옛 것 폐기하면, 탈취된 옛 Refresh를 즉시 무력화하고 재사용 탐지(한 번 쓴 토큰이 또 오면 탈취 의심 → 전 세션 강제 로그아웃)가 가능.
• 레거시 평문 분기 제거: B-2의 else 분기는 마이그레이션이 끝나면 불필요 + C8 오탐 위험. 전수 전환 확인 후 삭제해 코드 단순화.
• 로그아웃 = 전 기기 / 단일 기기 선택: 현재는 제시한 Refresh 1개만 삭제. deleteByUserId(이미 리포지토리에 존재)로 "모든 기기 로그아웃" 옵션 추가 가능.
• 권한(Role) 기반 인가: 지금은 type 클레임만 담고 컨트롤러별 검사. 메서드 단위 @PreAuthorize 류로 선언적 인가를 도입(풀 Spring Security 재활성 검토)하면 일관성↑.
• 인증코드 저장 Redis 이전: bank/email 코드를 Redis TTL 키로 옮기면 다중 인스턴스·재기동에도 안전하고 만료 자동화. mockCode 응답 제거.
• rate limit on auth: login/social/verify에 IP·계정별 시도 제한(브루트포스 방어). AiRateLimitFilter처럼 Bucket4j 활용.
• 이메일 인증 ↔ 가입 강결합: 현재 /api/verify는 가입과 분리. 가입 시 "인증 완료 토큰"을 요구하도록 묶으면 가짜 이메일 가입 차단.
• 소셜 신규 자동가입 정책 통일: 구글은 미가입 시 거부, 깃허브는 자동생성(A-8 vs A-9). 제품 정책에 맞게 통일/명문화.

---

📚 용어 사전 (이 도메인 한정)

용어	뜻
JWT	헤더.페이로드.서명 문자열 토큰. 서명으로 위조 방지, 페이로드는 누구나 읽힘(암호화 아님)
HS256	HMAC-SHA256. 발행·검증에 같은 비밀키를 쓰는 대칭 서명
Access Token	짧은 수명(1h) JWT. 매 요청 제시. 탈취돼도 곧 만료
Refresh Token	긴 수명(15d) 무작위 문자열. DB 저장. Access 만료 시 새 Access 발급용. DB에서 지워 무효화
HttpOnly 쿠키	JS가 못 읽는 쿠키. XSS 토큰 탈취 방어
Secure / SameSite	Secure=HTTPS에서만 전송, SameSite=교차사이트 동봉 제한(CSRF 방어)
BCrypt	솔트+느린 단방향 해싱. $2로 시작. 비번 평문 저장 대체
PasswordEncoder.matches	평문을 같은 솔트로 해싱해 저장 해시와 비교(평문 복원 없음)
OAuth access_token	구글·깃허브가 발급한 임시 출입증. 서버가 직접 검증해야 신뢰
투명 마이그레이션	사용자 모르게(로그인 시) 평문→해시로 점진 업그레이드
AES-GCM	대칭 암호화 + 변조탐지. GitHub 토큰 등 민감값 DB 저장용
OncePerRequestFilter	요청당 정확히 1회 실행되는 스프링 필터 베이스
request attribute	한 요청 동안만 유효한 키-값 저장소. 필터→컨트롤러로 userId 전달 통로
ThreadLocal	스레드별 독립 저장소. AuthContext가 백그라운드 잡용 userId 주입에 사용(누수 주의)
@Value("${k:기본값}")	properties/환경변수에서 설정 주입(콜론 뒤가 기본값)
@Transactional	메서드 내 DB 작업을 한 트랜잭션으로 묶음(예외 시 롤백)
정적 팩토리(of)	new 대신 검증된 상태로만 객체 생성하게 하는 패턴(RefreshToken.of)