Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion docs/api-specs/class-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -1190,7 +1190,14 @@ AI가 주제 후보를 제안하면 운영자가 하나를 고르거나 직접
- `insightText`: 200자 이하다.
- `evidence`: 인사이트가 근거로 삼은 공개 글 1~5건이다.
- `highlights`: 운영자에게 추천하는 대표 의견 최대 2건이다. 작성자 정보는 넣지 않는다.
- 의견 작성자가 3명 미만이면 `LIMITED`다.
- `LIMITED`면 `insightText`가 "아직 요약할 의견이 충분하지 않아요"이고 `evidence`가 빈 배열이다. 다음 경우에 `LIMITED`가 된다.
- 의견 작성자가 3명 미만이다.
- 이유를 읽을 수 있는 글을 쓴 사람이 3명 미만이다. "ㅋㅋㅋ", "몰라요 그냥요", "asdfasdf", 같은 글자·숫자 반복처럼 이유가 없는 글은 세지 않는다.
- AI가 무관한 글, 의미 없는 입력, 조롱 글을 빼고 나니 작성자가 3명 미만이다.
- `evidence`와 `highlights`에는 비속어가 든 글, 이유가 없는 글, AI가 부적절하다고 판단한 글(무관한 글, 실명을 부르거나 조롱하는 글)을 넣지 않는다.
- `highlights`가 2건보다 적으면 최신 공개 의견으로 채운다. 이때도 같은 기준으로 거른다.
- 그래서 `LIMITED`여도 `highlights`가 비어 있지 않을 수 있다.
- 인사이트는 `gpt-5.4-mini`로 만든다. 서버 환경변수 `OPENAI_INSIGHT_MODEL`로 바꿀 수 있다. 개인 리포트는 기존 모델을 그대로 쓴다.
- 생성에 실패하면 `FAILED`이고 `retryable`이 true다.
- 운영자가 아니면 403 `CLASS_403_OWNER`다.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
import com.swyp.picke.domain.classroom.service.report.ClassReportSnapshotService;
import com.swyp.picke.domain.classroom.service.report.ClassResultStats;
import com.swyp.picke.domain.classroom.service.report.ClassResultStatsCalculator;
import com.swyp.picke.domain.classroom.service.report.InsightPostRules;
import com.swyp.picke.domain.classroom.service.report.MemberFeedbackInput;
import com.swyp.picke.domain.classroom.service.report.ReportContent;
import com.swyp.picke.domain.perspective.entity.Perspective;
Expand Down Expand Up @@ -306,14 +307,17 @@ private ClassInsightResponse toInsight(Long classId, ClassReport summary, boolea
evidence, highlights);
}

/** 하이라이트가 2건 미만이면 최신 공개 의견으로 채운다 (AI 호출 없음) */
/** 하이라이트가 2건 미만이면 최신 공개 의견으로 채운다 (AI 호출 없음). 비속어·이유 없는 글은 고르지 않는다 (#657) */
private void backfillHighlights(List<ClassInsightResponse.PublicPost> highlights, Long classId) {
if (highlights.size() >= HIGHLIGHT_MAX) {
return;
}
List<Perspective> recent = perspectiveRepository.findByClassroomIdAndStatusOrderByCreatedAtAsc(classId, PerspectiveStatus.PUBLISHED);
for (int i = recent.size() - 1; i >= 0 && highlights.size() < HIGHLIGHT_MAX; i--) {
Perspective p = recent.get(i);
if (!InsightPostRules.isSelectable(p.getContent())) {
continue;
}
boolean exists = highlights.stream().anyMatch(h ->
MemberFeedbackInput.SOURCE_PERSPECTIVE.equals(h.sourceType()) && Objects.equals(h.id(), p.getId()));
if (!exists) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,10 @@ public class ClassReportAiClient {
@Value("${openai.debate.model:gpt-5.4-mini}")
private String debateModel;

/** 클래스 인사이트만 쓰는 모델. 클래스당 1번이라 비용 부담이 작고, 부적절한 글 제외·요약 품질 차이가 커서 따로 둔다 (#657) */
@Value("${openai.insight.model:gpt-5.4-mini}")
private String insightModel;

/** 파싱된 JSON 본문과 토큰 사용량 */
public record AiChatResult(Map<String, Object> json, String rawContent, Integer inputTokens, Integer outputTokens) {
}
Expand All @@ -52,6 +56,10 @@ public String getDebateModel() {
return debateModel;
}

public String getInsightModel() {
return insightModel;
}

public AiChatResult chatJson(String systemPrompt, String userPrompt, int maxOutputTokens) {
return chatJson(model, systemPrompt, userPrompt, maxOutputTokens);
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@

import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.HashSet;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
Expand Down Expand Up @@ -127,12 +128,31 @@ public Map<String, Object> validateMemberFeedback(Map<String, Object> json, Memb
}

public Map<String, Object> validateClassInsight(Map<String, Object> json, ClassInsightInput input) {
if ("INSUFFICIENT".equalsIgnoreCase(ReportContent.str(json, "analysis_status"))) {
return limitedClassInsight(input); // 모든 글이 의미 없는 입력이라 요약하지 않음 (#657)
}
String insightText = requireText(json, "insight_text", INSIGHT_TEXT_MAX);
// AI 가 스스로 부적절하다고 표시한 글은 근거·대표 의견에서 뺀다 (#657)
Set<String> excluded = new HashSet<>();
for (String id : ReportContent.stringList(json, "excluded_ids")) {
excluded.add(id.trim());
}

// AI 제외와 서버 기준을 모두 거친 글의 작성자가 3명 미만이면, AI 요약은 믿지 않고 의견 부족 템플릿으로 바꾼다.
// 의미 없는 글만 있는 반에서 AI 가 없는 주장을 지어내는 경우를 막는다 (#657, PRD §14 작성자 3명 기준)
long usableAuthors = input.posts().stream()
.filter(post -> !excluded.contains(post.sourceId()) && InsightPostRules.isSelectable(post.content()))
.map(ClassInsightInput.PublicPost::authorNo)
.distinct()
.count();
if (usableAuthors < ClassReportSnapshotService.INSIGHT_MIN_AUTHORS) {
log.info("[ClassReport] insight limited usable_authors={}", usableAuthors);
return limitedClassInsight(input);
}
List<String> evidenceIds = new ArrayList<>();
for (String id : ReportContent.stringList(json, "evidence_ids")) {
String trimmed = id.trim();
if (input.findPost(trimmed) != null && !evidenceIds.contains(trimmed) && evidenceIds.size() < INSIGHT_EVIDENCE_MAX) {
if (!excluded.contains(trimmed) && selectable(input, trimmed) && !evidenceIds.contains(trimmed) && evidenceIds.size() < INSIGHT_EVIDENCE_MAX) {
evidenceIds.add(trimmed);
}
}
Expand All @@ -142,7 +162,7 @@ public Map<String, Object> validateClassInsight(Map<String, Object> json, ClassI
List<String> highlightIds = new ArrayList<>();
for (String id : ReportContent.stringList(json, "highlight_ids")) {
String trimmed = id.trim();
if (input.findPost(trimmed) != null && !highlightIds.contains(trimmed) && highlightIds.size() < INSIGHT_HIGHLIGHT_MAX) {
if (!excluded.contains(trimmed) && selectable(input, trimmed) && !highlightIds.contains(trimmed) && highlightIds.size() < INSIGHT_HIGHLIGHT_MAX) {
highlightIds.add(trimmed);
}
}
Expand All @@ -157,6 +177,19 @@ public Map<String, Object> validateClassInsight(Map<String, Object> json, ClassI
return insight;
}

/** 입력에 있는 글이면서 운영자 화면에 근거·대표 의견으로 보여줄 수 있는 글인지 (비속어·이유 없는 글 제외, #657) */
private static boolean selectable(ClassInsightInput input, String sourceId) {
ClassInsightInput.PublicPost post = input.findPost(sourceId);
if (post == null) {
return false;
}
if (!InsightPostRules.isSelectable(post.content())) {
log.warn("[ClassReport] insight post dropped source_id={} reason=NOT_SELECTABLE", sourceId);
return false;
}
return true;
}

// ===== 템플릿 (AI 호출 없음) =====

/** 글 없이 투표만 했을 때의 서버 템플릿 (엣지 케이스 PRD 3.3 Case B). 사고 과정 분석은 하지 않고 선택 기록만 보여준다 */
Expand Down Expand Up @@ -232,6 +265,14 @@ private static List<Map<String, Object>> midChoices(List<ClassMidVoteInfo> choic
return list;
}

/** AI 가 요약할 글이 없다고 판단했을 때의 템플릿. 입력 범위는 그대로 기록한다 */
static Map<String, Object> limitedClassInsight(ClassInsightInput input) {
Map<String, Object> insight = limitedClassInsight();
insight.put("coverage", input.coverage());
insight.put("excluded_count", input.excludedCount());
return insight;
}

/** 유효 공개 글 작성자 3명 미만일 때의 템플릿 (PRD §14 개인정보와 소수 의견) */
public static Map<String, Object> limitedClassInsight() {
Map<String, Object> insight = new LinkedHashMap<>();
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ public void generate(Long reportId, LocalDateTime now) {
ClassReportPrompts.MEMBER_FEEDBACK_MAX_OUTPUT_TOKENS);
validated = validator.validateMemberFeedback(result.json(), prepared.memberInput());
} else {
result = aiClient.chatJson(ClassReportPrompts.CLASS_INSIGHT_SYSTEM,
result = aiClient.chatJson(aiClient.getInsightModel(), ClassReportPrompts.CLASS_INSIGHT_SYSTEM,
ClassReportPrompts.classInsightUser(prepared.insightInput()),
ClassReportPrompts.CLASS_INSIGHT_MAX_OUTPUT_TOKENS);
validated = validator.validateClassInsight(result.json(), prepared.insightInput());
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ private ClassReportPrompts() {
"strength": {"title": "20자 이하", "body": "120자 이하"} 또는 null,
"next_focus": {"title": "20자 이하", "body": "120자 이하"} 또는 null,
"next_question": "100자 이하",
"evidence_refs": [{"field": "judgment_basis 또는 strength 또는 next_focus", "source_id": "p:12 또는 c:34", "quote": "원문 구절"}],
"evidence_refs": [{"field": "judgment_basis 또는 strength 또는 next_focus", "source_id": "p:12 또는 c:34 또는 d:5", "quote": "원문 구절"}],
"analysis_status": "SUFFICIENT 또는 LIMITED"
}
규칙 4 에 해당하면 위 형식 대신 {"analysis_status": "INSUFFICIENT"} 만 출력합니다.
Expand All @@ -48,10 +48,24 @@ private ClassReportPrompts() {
1. 숫자(참여율·비율·인원)는 [집계] 에 있는 값만 그대로 쓰고 새로 계산하거나 추정하지 않습니다. 빈도를 단정하는 "많이 나온 의견" 대신 "눈에 띈 의견" 으로 표현합니다.
2. 이름·개별 참여자의 변화·비공개 내용을 쓰지 않습니다. 특정 작성자를 지목하지 않습니다.
3. evidence_ids 는 [공개 의견] 의 source_id 만 1~5개 씁니다. highlight_ids 는 운영자에게 추천할 대표 의견 1개와 다른 관점의 의견 1개(없으면 생략)로 최대 2개이며 역시 [공개 의견] 의 source_id 만 씁니다.
4. 의견에 등급·우열을 매기지 않습니다. "~했어요" 체로 씁니다.
5. 주제와 무관한 글, 비속어·공격적 표현이 들어간 글은 evidence_ids·highlight_ids 로 고르지 않고 요약에도 쓰지 않습니다.
4. 의견에 등급·우열을 매기지 않습니다.
5. 먼저 [공개 의견] 을 하나씩 보고 아래에 해당하는 글의 source_id 를 모두 excluded_ids 에 적습니다. excluded_ids 에 적은 글은 evidence_ids·highlight_ids 로 고르지 않고 요약에도 쓰지 않습니다.
- 주제와 무관한 글 (예: 급식, 장난, 웃음만 있는 글)
- 의미 없는 입력 (예: "ㅋㅋㅋㅋ", "ㅎㅎ", "asdf", "ㅁㄴㅇㄹ", "qwerasdf", 같은 글자나 숫자 반복, 아무 말이나 적은 글)
- 이유 없이 입장만 말한 글 (예: "몰라요", "그냥요", "당연히 안 되지")
- 비속어(***)·비하·조롱이 들어간 글 (예: "바보냐", "ㅋㅋ 그래서 그런 거지")
- 다른 참여자의 이름(예: "민수야", "지은이 말처럼")을 부르거나 특정 사람을 겨냥한 글
고를 글이 부족하면 개수를 줄입니다. 개수를 채우려고 excluded_ids 의 글을 고르지 않습니다.
6. insight_text 는 2~3문장으로, 운영자가 수업을 되짚는 데 도움이 되도록 씁니다.
- 배틀 제목이나 주제를 다시 설명하지 않습니다. "AI가 쓴 과제를 인정해야 하는지에 대해" 처럼 주제로 시작하지 말고 "찬성 쪽은 ~" 처럼 바로 내용으로 들어갑니다.
- 양쪽이 각각 어떤 기준으로 판단했는지 씁니다. 한쪽 입장만 있으면 그 안에서 나온 서로 다른 이유를 씁니다.
- 댓글로 오간 반박이 있으면 어떤 논점이 맞섰는지 씁니다.
- [집계] 에서 사전→사후 인원이 바뀐 선택지가 있으면 "찬성 3명 → 4명" 처럼 집계 숫자 그대로 한 번 씁니다. 누가 바꿨는지, 모두 바꿨는지는 추정하지 않습니다.
7. 모든 문장을 "~했어요", "~였어요" 처럼 "~요" 로 끝냅니다. "~습니다", "~다" 로 끝내지 않습니다.
8. excluded_ids 를 빼고 나면 요약할 글이 하나도 없으면 다른 내용을 만들지 않고 {"analysis_status": "INSUFFICIENT"} 만 출력합니다. 의미 없는 글로 요약을 지어내지 않습니다.
출력은 아래 형식의 JSON 객체 하나만 씁니다. 다른 텍스트를 붙이지 않습니다.
{
"excluded_ids": ["p:3"],
"insight_text": "200자 이하",
"evidence_ids": ["p:1", "c:2"],
"highlight_ids": ["p:1"]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ public class ClassReportSnapshotService {
static final int INSIGHT_INPUT_MAX_CHARS = 12_000;
static final int INSIGHT_POST_MAX_COUNT = 60;
static final int INSIGHT_POSTS_PER_AUTHOR = 2;
static final int INSIGHT_MIN_AUTHORS = 3;
public static final int INSIGHT_MIN_AUTHORS = 3;
static final int PARENT_CONTEXT_MAX_CHARS = 200;

public static final String KEY_CUTOFF_AT = "cutoff_at";
Expand Down Expand Up @@ -166,7 +166,7 @@ private AiJob startJob(ClassReport report, AiJobType type, LocalDateTime now) {
.classroom(classroom)
.member(member)
.build()));
job.start(aiClient.getModel(), now);
job.start(type == AiJobType.CLASS_INSIGHT ? aiClient.getInsightModel() : aiClient.getModel(), now);
report.startGenerating(job);
return job;
}
Expand All @@ -187,6 +187,8 @@ public void complete(Long reportId, Long jobId, Map<String, Object> validated, C
report.limit(validated, now); // AI 가 분석할 이유가 없다고 판단해 서버 템플릿으로 대체한 경우
} else if (report.getType() == ClassReportType.MEMBER_FEEDBACK) {
report.complete(validated, now);
} else if ("LIMITED".equals(validated.get("analysis_status"))) {
report.limit(withInsight(report.getContent(), validated), now); // 요약할 글이 없어 템플릿으로 대체 (#657)
} else {
report.complete(withInsight(report.getContent(), validated), now);
}
Expand Down Expand Up @@ -348,6 +350,7 @@ private List<MemberFeedbackInput.Statement> debateReplies(Long classId, ClassMem

/**
* 인사이트 입력: 공개 의견·댓글을 작성자별 최신 2건으로 추리고 입장을 번갈아 섞어 최대 60건, 12,000자.
* 이유를 읽을 수 없는 짧은 글은 넣지 않는다 ({@link InsightPostRules#hasReason}).
* 작성자는 익명 번호로만 표기한다 (PRD §14). 한 작성자가 같은 내용을 반복한 글은 처음 것만 남긴다 (RP-10).
*/
public ClassInsightInput buildInsightInput(Classroom classroom, Map<String, Object> snapshot) {
Expand All @@ -362,6 +365,9 @@ record Raw(Long userId, LocalDateTime createdAt, ClassInsightInput.PublicPost po
}
List<Raw> raws = new ArrayList<>();
for (Perspective p : perspectiveRepository.findByClassroomIdAndStatusOrderByCreatedAtAsc(classId, PerspectiveStatus.PUBLISHED)) {
if (!InsightPostRules.hasReason(p.getContent())) {
continue; // 이유를 읽을 수 없는 글은 요약할 내용이 없고 작성자 수에도 넣지 않는다 (#657)
}
raws.add(new Raw(p.getUser().getId(), p.getCreatedAt(), new ClassInsightInput.PublicPost(
MemberFeedbackInput.sourceId(MemberFeedbackInput.SOURCE_PERSPECTIVE, p.getId()),
MemberFeedbackInput.SOURCE_PERSPECTIVE, p.getId(), 0,
Expand All @@ -370,7 +376,7 @@ record Raw(Long userId, LocalDateTime createdAt, ClassInsightInput.PublicPost po
}
for (PerspectiveComment c : perspectiveCommentRepository.findByClassroomIdAndHiddenFalseOrderByCreatedAtAsc(classId)) {
Perspective parent = c.getPerspective();
if (parent == null || parent.getStatus() != PerspectiveStatus.PUBLISHED) {
if (parent == null || parent.getStatus() != PerspectiveStatus.PUBLISHED || !InsightPostRules.hasReason(c.getContent())) {
continue;
}
raws.add(new Raw(c.getUser().getId(), c.getCreatedAt(), new ClassInsightInput.PublicPost(
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
package com.swyp.picke.domain.classroom.service.report;

import java.util.regex.Pattern;

/**
* 클래스 인사이트에 쓸 공개 글 기준 (#657).
* <ul>
* <li>hasReason: 글자·숫자가 {@value #MIN_MEANINGFUL_CHARS}자 이상이고 서로 다른 글자가 {@value #MIN_DISTINCT_CHARS}개 이상인 글만
* AI 입력과 작성자 수에 넣는다. "몰라요 그냥요", "ㅋㅋㅋㅋ", "ㅁㄴㅇㄹ", "asdfasdf", "11111111", "아아아아아아아아" 처럼
* 이유를 읽을 수 없는 글은 요약할 내용이 없다. 자판을 아무렇게나 누른 긴 글("qwerasdf")은 프롬프트에서 제외시킨다</li>
* <li>isSelectable: 근거·대표 의견으로 운영자 화면에 보여줄 수 있는 글. 이유가 있고 비속어가 없어야 한다</li>
* </ul>
* 실명 지목·조롱처럼 서버가 판별하기 어려운 글은 프롬프트로 막는다.
*/
public final class InsightPostRules {

static final int MIN_MEANINGFUL_CHARS = 8;
static final int MIN_DISTINCT_CHARS = 5;

/** 한글 완성형·영문·숫자 외(공백, 문장부호, 이모지, ㅋㅎㅠ 같은 자모)는 글자 수에서 뺀다 */
private static final Pattern NOT_MEANINGFUL = Pattern.compile("[^가-힣A-Za-z0-9]");

private InsightPostRules() {
}

public static boolean hasReason(String content) {
if (content == null) {
return false;
}
String meaningful = NOT_MEANINGFUL.matcher(content).replaceAll("").toLowerCase(java.util.Locale.ROOT);
if (meaningful.length() < MIN_MEANINGFUL_CHARS || meaningful.chars().allMatch(Character::isDigit)) {
return false;
}
return meaningful.chars().distinct().count() >= MIN_DISTINCT_CHARS;
}

/** content 는 원문이어도, 이미 가린 글이어도 된다 */
public static boolean isSelectable(String content) {
return hasReason(content) && !ReportProfanityMasker.mask(content).contains(ReportProfanityMasker.MASK);
}
}
2 changes: 2 additions & 0 deletions src/main/resources/application.yml
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,8 @@ openai:
model: gpt-4o-mini
debate:
model: ${OPENAI_DEBATE_MODEL:gpt-5.4-mini}
insight:
model: ${OPENAI_INSIGHT_MODEL:gpt-5.4-mini}
moderation:
url: https://api.openai.com/v1/moderations
model: omni-moderation-latest
Expand Down
Loading
Loading