Skip to content

[Feat/#311] AI 서버용 읽기 전용 내부 API 추가 - #312

Open
overhyeon wants to merge 5 commits into
mainfrom
feat/#311-ai-internal-api
Open

overhyeon wants to merge 5 commits into
mainfrom
feat/#311-ai-internal-api

Conversation

@overhyeon

Copy link
Copy Markdown
Contributor

#️⃣연관된 이슈

🎯 해결하려는 문제가 무엇인가요?

챗봇이 공지·행사·아카이빙·열린피드백을 미리 모아 검색 인덱스를 만들어야 하는데, 이 일을 하는 AI 서버 동기화 작업(sync.py)은 학생 질문 없이 혼자 돈다. 넘겨받을 학생 JWT가 없어서 지금 백엔드 API로는 읽어 올 방법이 없다.
(질문할 때 조회하는 재고·내 대여는 학생 JWT 전달로 해결했다 — #310)

❓ 왜 해결해야 하나요?

챗봇은 지금 직접 쓴 시드 문서로만 답한다. 학생회가 실제로 올린 공지·행사로 답해야 슬랑제 시연과 실제 운영이 의미가 있다.

⭐ 어떻게 해결했나요?

1. 새 모듈 api/ai-api (/v1/ai/**) — 컨벤션의 클라이언트 기준(architecture.md 2-2절)에 따라 AI 서버를 세 번째 클라이언트로 뒀다. GET만 있다.

경로 재사용한 서비스 나오는 것
GET /v1/ai/notices NoticeService.getNotices (끝까지 넘김) 삭제 안 된 공지
GET /v1/ai/events EventService.getPublishedEvents → getPublishedByIds 게시된 행사 (소개글·장소·기간)
GET /v1/ai/archives ArchiveService.getArchives(null, null) → getArchive 학생 목록과 같은 아카이빙
GET /v1/ai/feedbacks FeedbackService.search + PageResult.fetchAll 답변 공개된 회차의 답변된 질문
  • 학생 화면이 쓰는 조회 서비스를 그대로 써서 노출 규칙이 학생 화면과 같다
  • 양이 적어(각 수십~수백 건) 페이지 없이 전체를 본문까지 한 번에 준다
  • 작성자 정보(createdBy, answeredBy), 이미지·첨부는 내보내지 않는다. 특히 열린피드백 질문자

2. /v1/ai/** 전용 보안 체인 (gateway:auth) — 기존 SecurityConfig는 건드리지 않고 @Order(1) 체인을 옆에 뒀다.

  • InternalTokenAuthFilter: X-Internal-Token을 설정값과 MessageDigest.isEqual로 비교. 맞으면 AI_SERVER 권한으로 인증
  • AI_SERVER는 Role enum에 넣지 않았다(JWT·PrincipalProvider를 건드리지 않으려고)
  • 설정값이 비어 있으면 전부 401 (fail closed). CORS는 열지 않는다
  • 필터는 빈으로 등록하지 않는다(JwtAuthFilter와 같은 이유 — 빈이면 모든 요청에 걸린다)

3. 토큰: 새 비밀값 없이 기존 STREAM_AI_INTERNAL_TOKEN을 재사용한다(ai-server.internal-token).

🧩 이 PR의 한계 & 트레이드오프

  • 토큰 하나를 양방향에 쓴다. 새면 양쪽이 다 열리지만, 이 API로 나가는 건 학생이 로그인하면 보는 공개 글뿐이라 피해가 작다. 민감한 데이터를 내보내게 되면 그때 나눈다
  • /v1/ai/**는 프록시에서 막지 않아 밖에서 주소는 닿는다. 토큰 하나가 방어선이다. 슬랑제 이후 프록시 내부망 제한을 검토한다
  • 아카이빙은 본문을 한 건씩 상세로 읽는다(N번 조회). 학기에 수십 건이라 그대로 뒀다
  • 페이지 없이 전체를 준다. 500건을 넘으면 페이지를 붙인다

⛓️ 기존 기능에 미치는 영향

  • 기존 학생·운영진 보안 체인과 API는 그대로다. /v1/ai/**만 새 체인이 맡는다
  • 도메인 서비스는 바꾸지 않았다(호출만 한다)
  • 새 환경변수 없음 (STREAM_AI_INTERNAL_TOKEN 재사용)

🔀 Edge Case & 실패 시나리오

  • 토큰 없음·틀림 → 401 (CommonErrorCode.UNAUTHORIZED, 기존 EntryPoint)
  • 학생 JWT로 /v1/ai/** → 401 (새 체인은 JWT 필터가 없다)
  • 내부 토큰으로 /v1/app/** → 기존 체인이라 401
  • STREAM_AI_INTERNAL_TOKEN 미설정 → /v1/ai/** 전부 401

📋 검토한 대안과 선택 이유

  • 챗봇 전용 학생 JWT 발급: 학생 권한(쓰기 포함)이 통째로 들어 있고, 새면 막는 법이 JWT 비밀키 교체(전원 로그아웃)뿐
  • 내부 토큰이면 기존 /v1/app/** GET 허용: 컨트롤러는 안 늘지만 AppApiUser를 기대하는 엔드포인트가 깨지고 role 모델에 예외가 생긴다
  • app-api 안에 패키지로: 경로가 학생 JWT 구역(/v1/app)이 되어 보안 규칙이 헷갈린다
  • 설계안: billilge/stream-ai docs/plans/ai-internal-api-proposal.md (브랜치 docs/#71-agent-plan)

💬 리뷰 포인트

  • [r] AiServerSecurityConfig의 체인 순서(@Order(1) + securityMatcher)가 기존 체인과 겹치지 않는지
  • [c] ai-api 모듈 신설 / 토큰 재사용 결정이 괜찮은지
  • [c] 응답 필드가 충분한지 (승빈 sync.py가 이 모양으로 작업 시작)

확인한 것: 전체 compileJava·compileTestJava, ModularityTests, DomainImplAccessTests 통과
확인 못 한 것: 로컬에서 서버를 띄운 실제 호출(로컬 DB 없음). dev 배포 후 아래로 확인한다

curl -s -o /dev/null -w "%{http_code}\n" https://<dev 백엔드>/v1/ai/notices                                  # 401
curl -s -H "X-Internal-Token: <값>" https://<dev 백엔드>/v1/ai/notices | head -c 300                           # 200 + 공지
curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer <학생 JWT>" https://<dev 백엔드>/v1/ai/notices # 401

@coderabbitai

coderabbitai Bot commented Nov 8, 2026 •

Copy link
Copy Markdown

Important

  • Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

private final RestAccessDeniedHandler accessDeniedHandler;

@Bean
@Order(1)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[a] 리뷰 포인트 주신 체인 순서에 대한 의견이에요. 겹치지 않는 걸 확인했고 좋아 보여요.

  • SecurityConfig.securityFilterChain은 @Order도 securityMatcher도 없어서 가장 낮은 우선순위로 모든 요청에 매칭돼요. FilterChainProxy는 처음 매칭되는 체인 하나만 쓰니 /v1/ai/**는 이 체인만, 나머지는 기존 체인만 탑니다.
  • 두 인증 필터 모두 빈이 아니라 서로의 체인에 섞이지 않아요. 그래서 학생 JWT로 /v1/ai/**, 내부 토큰으로 /v1/app/**를 부르면 둘 다 익명으로 남아 RestAuthenticationEntryPoint의 401로 끝납니다.
  • 하나 걸릴 수 있던 곳이 MdcUserIdFilter예요. 보안 체인 뒤(@Order(-80))에서 principalProvider.userId()를 부르는데, SecurityPrincipalProvider는 UserAuthentication이 아니면 UNAUTHORIZED를 던져요. MdcUserIdFilter.java:45에서 BusinessException을 삼키고 넘어가서 AI 서버 요청도 userId 없이 그대로 진행됩니다.

# AI 서버가 /v1/ai/**를 부를 때 싣는 X-Internal-Token. 백엔드 → AI 서버 방향과 같은 값을 쓴다.
# 비어 있으면 /v1/ai/**는 전부 401이다.
ai-server:
internal-token: ${STREAM_AI_INTERNAL_TOKEN:}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[a] 리뷰 포인트 주신 ai-api 모듈 신설과 토큰 재사용에 대한 의견이에요. 둘 다 좋아 보여요.

  • 모듈: architecture.md 2-2절이 api:*를 클라이언트 기준으로 나누고, 패키지도 api.ai.{팀}.{도메인}으로 같은 규칙을 따르고 있어요. 보안 체인도 /v1/ai/** 단위로 갈리니 모듈 경계와 인가 경계가 같아지는 것도 좋습니다.
  • 토큰: 설정 키는 이미 방향별로 나뉘어 있어요. ai-server.internal-token(여기)과 chat.stream-ai.internal-token(application-infrastructure-client.yml:64)이 같은 환경 변수를 가리킬 뿐이라, 나중에 나눌 때는 코드를 그대로 두고 이 줄의 ${STREAM_AI_INTERNAL_TOKEN:}만 새 변수로 바꾸면 돼요. 지금 하나로 두셔도 나누는 비용이 거의 없습니다.

* <b>질문한 학생({@code createdBy})과 답변한 운영진({@code answeredBy})은 절대 넣지 않는다.</b>
* 열린피드백은 익명으로 받는다. 인덱스에 들어가면 챗봇 답변으로 새어 나갈 수 있다.
*/
public record AiFeedbackResponse(

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[a] 리뷰 포인트 주신 응답 필드에 대한 의견이에요. 공지·행사·아카이빙은 검색과 출처 표시에 쓸 값이 다 들어 있어 보여요.

열린피드백은 year·round를 같이 내려주면 좋겠어요. 학생 앱은 열린피드백을 회차 단위로 보여줘서(FeedbackPeriod 필터, FeedbackResponse.java:8의 year·round) 챗봇도 같은 단위로 말할 수 있어야 할 것 같아요. 예를 들어

  • 2026년 1회차와 2회차에 비슷한 질문이 각각 답변되면
  • 지금 응답으로는 answeredAt으로 회차를 짐작해야 해서, 챗봇이 "2회차 답변에 따르면"처럼 학생 화면과 같은 출처를 대기 어려워요.
// AiFeedbackResponse
public record AiFeedbackResponse(
    Long feedbackId,
    int year,
    int round,
    String question,
    String answer,
    LocalDateTime answeredAt
) {

    public static AiFeedbackResponse from(Feedback feedback) {
        return new AiFeedbackResponse(
            feedback.getId(),
            feedback.getYear(),
            feedback.getRound(),
            feedback.getQuestion(),
            feedback.getAnswer(),
            feedback.getAnsweredAt()
        );
    }
}

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

반영했어요! 57bb9b61에서 year·round를 feedbackId 다음에 추가했어요. AI 서버 동기화 쪽에서도 회차를 메타데이터로 받아 쓰도록 맞출게요.

public ApiResponse<List<AiNoticeResponse>> getNotices() {
List<Notice> notices = new ArrayList<>();
NoticeCursor cursor = null;
do {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[a] 커서를 끝까지 넘기는 반복이 여기와 AiEventController.java:34에 같은 모양으로 있어요. 열린피드백은 main의 PageResult.fetchAll(core:common)로 한 줄에 끝나니, 커서 목록도 CursorSliceResult에 같은 메서드를 두면 두 컨트롤러가 AiFeedbackController처럼 서비스 호출 한 줄로 줄어들 것 같아요.

// core:common — CursorSliceResult
public static <C, T> List<T> fetchAll(Function<String, C> parseCursor, Function<C, CursorSliceResult<T>> fetchSlice) {
    List<T> all = new ArrayList<>();
    C cursor = null;
    do {
        CursorSliceResult<T> slice = fetchSlice.apply(cursor);
        all.addAll(slice.content());
        cursor = slice.hasNext() ? parseCursor.apply(slice.nextCursor()) : null;
    } while (cursor != null);
    return all;
}

// AiNoticeController.getNotices
List<Notice> notices = CursorSliceResult.fetchAll(
    NoticeCursor::from, cursor -> noticeService.getNotices(null, null, cursor, PAGE_SIZE));

// AiEventController.getEvents
List<Long> eventIds = CursorSliceResult.fetchAll(
        EventCursor::from, cursor -> eventService.getPublishedEvents(null, null, cursor, PAGE_SIZE))
    .stream()
    .map(EventSummary::eventId)
    .toList();

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

반영했어요! 7fc76f0a에서 CursorSliceResult.fetchAll을 추가하고 공지·행사 컨트롤러를 서비스 호출 한 줄로 바꿨어요. 동작은 전과 같아요.

@xeoxxn

xeoxxn commented Nov 18, 2026

Copy link
Copy Markdown
Collaborator

재고 조회는 내부용 API로 옮기면 좋을 것 같습니다.
지금은 재고를 조회할 때도 학생 JWT를 넘겨받아 검증하는데, 재고는 학생마다 달라지는 값이 아니라서 내부 토큰 검증만으로 충분해 보입니다.
학생 JWT에는 대여 신청 같은 쓰기 권한도 들어 있어서, 필요 없는 곳에는 넘기지 않는 편이 안전할 것 같습니다.
#312의 ai-api에 GET /v1/ai/billilge/items를 추가하면 될 것 같습니다.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

AI 서버용 읽기 전용 내부 API (공지·행사·아카이빙·열린피드백)

3 participants