과제 관리

K-Lounge의 과제 관리 시스템은 AI 자동 채점을 포함한 포괄적인 과제 관리 기능을 제공합니다.

📋 목차

과제 생성
과제 수정
과제 삭제
AI 자동 채점
제출 현황 확인
API 참조

✨ 과제 생성

접근 경로

커뮤니티 설정 페이지로 이동: /c/{slug}/settings
"과제 관리" 섹션 찾기
"새 과제 추가" 버튼 클릭

입력 필드

1. 과제 제목 (필수)

간단하고 명확한 제목 입력
예시: "한국어 에세이 작성", "문법 연습 문제"

2. 과제 설명 (선택)

BlockNote 에디터 사용
과제의 목적과 개요 설명
이미지 첨부 가능
예시:
이번 과제는 한국 문화에 대한 여러분의 생각을 자유롭게 표현하는 에세이입니다. [한국 전통 건축 이미지 첨부]

3. 과제 안내사항 (선택)

BlockNote 에디터 사용
구체적인 작성 지침 제공
채점 기준 명시
예시:
## 작성 지침 - 최소 500자 이상 작성 - 서론, 본론, 결론 구조 준수 - 최소 3개의 구체적 예시 포함 ## 채점 기준 - 문법 정확성 (30%) - 내용 충실성 (40%) - 창의성 (30%)

4. 마감일 (선택)

datetime-local 입력
마감일 이후 제출 불가
설정하지 않으면 무기한

5. 만점 (기본: 100점)

1점 이상 설정 가능
AI 채점 결과가 이 만점에 맞게 스케일링됨
예시: 50점으로 설정하면 AI 점수 80/100 → 40/50점

6. 연결할 강의 (선택)

드롭다운에서 강의 선택
특정 강의의 과제로 지정
선택하지 않으면 커뮤니티 전체 과제

생성 예시

// 과제 데이터 예시
{
  "title": "한국 문화 에세이",
  "description": "[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"한국 문화에 대한 에세이를 작성하세요.\"}]}]",
  "instructions": "[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"최소 500자 이상 작성해주세요.\"}]}]",
  "dueDate": "2025-12-31T23:59",
  "maxScore": 100,
  "classId": "3"
}

📝 과제 수정

수정 방법

과제 목록에서 수정할 과제의 "수정" 버튼 클릭
폼이 열리며 기존 데이터가 자동으로 채워짐
원하는 필드 수정
"수정" 버튼 클릭하여 저장

주의사항

⚠️ 이미 제출된 과제가 있는 경우에도 수정 가능
⚠️ 만점을 변경하면 기존 제출의 점수는 변경되지 않음
⚠️ 마감일을 연장할 수 있지만, 단축할 경우 혼란 주의

API 엔드포인트

PUT /api/assignments/{id}

🗑 과제 삭제

삭제 방법

과제 목록에서 삭제할 과제의 "삭제" 버튼 (휴지통 아이콘) 클릭
확인 다이얼로그에서 "확인" 클릭

삭제 시 영향

⚠️ 과제와 모든 제출물이 영구 삭제됨
⚠️ CASCADE 설정으로 관련 제출 데이터 자동 삭제
⚠️ 복구 불가능

API 엔드포인트

DELETE /api/assignments/{id}

🤖 AI 자동 채점

K-Lounge의 핵심 기능인 AI 자동 채점 시스템은 GPT-4o-mini를 사용합니다.

작동 흐름

graph TD
    A[학생 과제 제출] --> B[AI 채점 시작]
    B --> C[GPT-4o-mini 분석]
    C --> D[점수 산출 0-100]
    C --> E[피드백 생성]
    C --> F[잘한 점 3가지]
    C --> G[개선할 점 3가지]
    D --> H[만점에 맞게 스케일링]
    E --> I[종합 피드백 저장]
    F --> I
    G --> I
    H --> J[DB 저장]
    I --> J
    J --> K[20 포인트 지급]
    K --> L[학생에게 즉시 결과 표시]

평가 기준

AI는 다음 4가지 기준으로 과제를 평가합니다:

과제 지시사항 준수 여부 (25%)
- 요구사항 충족도
- 형식 준수
- 분량 적절성
한국어 문법과 표현 정확성 (30%)
- 문법 오류 여부
- 어휘 선택의 적절성
- 문장 구조의 자연스러움
내용 충실성 및 논리성 (30%)
- 내용의 깊이
- 논리적 흐름
- 예시의 적절성
창의성과 노력도 (15%)
- 독창적인 시각
- 노력이 드러나는 정도
- 개인적 견해의 표현

채점 결과 구성

1. 점수 (Score)

{
  "score": 85  // 0-100 범위
}

2. 종합 피드백 (Feedback)

{
  "feedback": "전반적으로 한국 문화에 대한 이해가 잘 드러나는 에세이입니다. 문법적으로 큰 오류 없이 자연스럽게 작성하셨습니다."
}

3. 잘한 점 (Strengths)

{
  "strengths": [
    "한국의 전통 문화와 현대 문화를 균형있게 다루었습니다",
    "문단 구성이 논리적이며 흐름이 자연스럽습니다",
    "다양한 어휘를 활용하여 표현력이 풍부합니다"
  ]
}

4. 개선할 점 (Improvements)

{
  "improvements": [
    "일부 조사 사용이 부정확합니다 (예: '에서'와 '에게' 혼동)",
    "구체적인 예시를 더 추가하면 설득력이 높아집니다",
    "결론 부분을 좀 더 강하게 마무리하면 좋겠습니다"
  ]
}

점수 스케일링

만점이 100점이 아닌 경우 자동으로 스케일링됩니다:

// 예시: 만점 50점인 과제
const aiScore = 85;  // AI가 산출한 점수
const maxScore = 50;
const scaledScore = Math.round((aiScore / 100) * maxScore);
// scaledScore = 43점

채점 소요 시간

평균: 3-5초
최대: 10초
네트워크 상태에 따라 변동

비용 (참고용)

GPT-4o-mini 사용
과제당 약 $0.001-0.003 (약 1-4원)
1000개 제출 시 약 1,000-4,000원

코드 위치

/lib/ai-grading.ts          # AI 채점 로직
/api/assignments/[id]/route.ts  # POST 엔드포인트

📊 제출 현황 확인

과제 목록 페이지

경로: /c/{slug}/assignments

표시 정보:

전체 과제 목록
상태 배지:
- 🟢 채점 완료
- 🟡 제출 완료
- 🔴 기한 초과
- ⚪ 제출 대기
통계:
- 전체 과제 수
- 제출한 과제 수
- 채점 완료 과제 수
- 미제출 과제 수

과제 상세 페이지 (학생 뷰)

경로: /c/{slug}/assignments/{id}

표시 정보:

과제 제목
과제 설명 (BlockNote 렌더링)
과제 안내사항 (BlockNote 렌더링)
마감일
만점
연결된 강의 정보
생성자 정보

제출 전:

과제 제출 폼 (Textarea)
제출 버튼

제출 후:

제출 내용
채점 결과:
- 점수 (예: 85/100점)
- 종합 피드백
- 잘한 점 리스트
- 개선할 점 리스트
제출 시간
채점 시간

🔧 API 참조

GET /api/assignments

과제 목록 조회

Query Parameters:

community (required): 커뮤니티 slug

Response:

{
  "assignments": [
    {
      "id": "1",
      "title": "한국어 에세이",
      "description": "[BlockNote JSON]",
      "instructions": "[BlockNote JSON]",
      "dueDate": "2025-12-31T23:59:00.000Z",
      "maxScore": 100,
      "isPublished": true,
      "classId": 3,
      "createdAt": "2025-12-14T00:00:00.000Z",
      "submission": {
        "id": "1",
        "status": "graded",
        "score": 85,
        "submittedAt": "2025-12-20T10:00:00.000Z"
      }
    }
  ],
  "stats": {
    "total": 5,
    "submitted": 3,
    "graded": 2,
    "pending": 2
  }
}

POST /api/assignments

과제 생성

Request Body:

{
  "communitySlug": "c-abc123",
  "title": "한국어 에세이",
  "description": "[BlockNote JSON]",
  "instructions": "[BlockNote JSON]",
  "dueDate": "2025-12-31T23:59",
  "maxScore": 100,
  "classId": 3
}

Response:

{
  "success": true,
  "assignment": {
    "id": "1",
    "title": "한국어 에세이",
    ...
  }
}

GET /api/assignments/{id}

과제 상세 조회

Response:

{
  "assignment": {
    "id": "1",
    "title": "한국어 에세이",
    "description": "[BlockNote JSON]",
    "instructions": "[BlockNote JSON]",
    "dueDate": "2025-12-31T23:59:00.000Z",
    "maxScore": 100,
    "classInfo": {
      "title": "Beginner Korean",
      "titleKr": "초급 한국어"
    },
    "creator": {
      "name": "Min-Ji Park",
      "nameKr": "박민지",
      "avatar": "/avatars/minji.jpg"
    },
    "communitySlug": "c-abc123",
    "createdAt": "2025-12-14T00:00:00.000Z"
  },
  "submission": {
    "id": "1",
    "content": "한국 문화는...",
    "status": "graded",
    "score": 85,
    "feedback": "전반적으로 좋습니다...\n\n✅ 잘한 점:\n• ...",
    "submittedAt": "2025-12-20T10:00:00.000Z",
    "gradedAt": "2025-12-20T10:00:05.000Z"
  }
}

POST /api/assignments/{id}

과제 제출 (AI 자동 채점)

Request Body:

{
  "content": "한국 문화는 오랜 역사를 가지고 있으며..."
}

Response:

{
  "success": true,
  "submission": {
    "id": "1",
    "content": "한국 문화는 오랜 역사를...",
    "status": "graded",
    "score": 85,
    "feedback": "전반적으로 좋습니다...\n\n✅ 잘한 점:\n• 한국의 전통 문화와 현대 문화를 균형있게 다루었습니다\n• 문단 구성이 논리적이며 흐름이 자연스럽습니다\n• 다양한 어휘를 활용하여 표현력이 풍부합니다\n\n💡 개선할 점:\n• 일부 조사 사용이 부정확합니다\n• 구체적인 예시를 더 추가하면 좋겠습니다\n• 결론 부분을 강화하면 좋겠습니다",
    "submittedAt": "2025-12-20T10:00:00.000Z",
    "gradedAt": "2025-12-20T10:00:05.000Z"
  }
}

PUT /api/assignments/{id}

과제 수정 (Owner/Admin만 가능)

Request Body:

{
  "title": "한국 문화 에세이 (수정)",
  "description": "[BlockNote JSON]",
  "instructions": "[BlockNote JSON]",
  "dueDate": "2026-01-15T23:59",
  "maxScore": 100,
  "classId": 3
}

Response:

{
  "success": true
}

DELETE /api/assignments/{id}

과제 삭제 (Owner/Admin만 가능)

Response:

{
  "success": true
}

🧪 E2E 테스트

테스트 파일

e2e/16-assignments.spec.ts

테스트 케이스 (6개)

✅ settings 페이지에 과제 관리 섹션 표시
✅ 새 과제 생성
✅ 과제 수정
✅ 과제 삭제
✅ 마감일 및 만점 설정
✅ 과제 목록 페이지에서 과제 표시

테스트 실행

# 과제 관리 테스트만 실행
npx playwright test e2e/16-assignments.spec.ts

# UI 모드로 실행
npx playwright test e2e/16-assignments.spec.ts --ui

# 특정 테스트만 실행
npx playwright test e2e/16-assignments.spec.ts -g "should create a new assignment"

테스트 결과

Running 6 tests using 1 worker

✓ should display assignment management section in settings
✓ should create a new assignment
✓ should edit an assignment
✓ should delete an assignment
✓ should set due date and max score for assignment
✓ should display assignment in assignments page

6 passed (31.1s)

💡 사용 팁

1. 명확한 지침 제공

과제 안내사항을 상세히 작성하면 AI 채점의 정확도가 높아집니다.

좋은 예:

## 작성 요구사항
- 최소 500자, 최대 1000자
- 서론-본론-결론 구조 필수
- 최소 3개의 구체적 예시 포함
- 개인적 경험 포함 권장

## 채점 기준
- 문법 정확성 30%
- 내용 충실성 40%
- 창의성 30%

2. 적절한 마감일 설정

학생들에게 충분한 시간을 주되, 너무 길지 않게 설정합니다.

에세이: 1-2주
짧은 문제: 3-5일
프로젝트: 2-4주

3. 만점 활용

짧은 과제: 50점
일반 과제: 100점
프로젝트: 200-500점

4. 강의 연결

관련 강의와 연결하면 학생들이 맥락을 이해하기 쉽습니다.

5. 이미지 활용

설명과 안내사항에 이미지를 추가하면 이해도가 높아집니다:

예시 작품
참고 자료
시각적 가이드

⚠️ 주의사항

1. AI 채점의 한계

AI는 완벽하지 않습니다
복잡한 창의적 과제는 한계가 있을 수 있습니다
필요시 선생님이 재채점 가능 (향후 기능)

2. 재제출 불가

현재 한 번만 제출 가능
재제출 기능은 향후 추가 예정
학생들에게 신중히 작성하도록 안내

3. 삭제 주의

과제 삭제 시 모든 제출물도 삭제됨
복구 불가능
삭제 전 백업 권장

4. 마감일 변경

마감일을 단축하면 학생 혼란 가능
연장은 자유롭게 가능
변경 시 학생들에게 공지 권장

🔜 향후 기능

📞 문제 해결

Q: AI 채점이 너무 느려요

A: 일반적으로 3-5초 소요됩니다. 10초 이상 걸린다면 네트워크 상태를 확인해주세요.

Q: AI 채점 결과가 부정확해요

A: 과제 안내사항을 더 구체적으로 작성하면 정확도가 높아집니다. 향후 수동 채점 기능이 추가될 예정입니다.

Q: 학생이 실수로 제출했어요

A: 현재는 재제출 기능이 없습니다. 과제를 삭제하고 다시 생성하는 방법이 있지만, 다른 학생들의 제출도 삭제됩니다.

Q: 마감일이 지났는데 제출이 되나요?

A: 아니요, 마감일 이후에는 제출 불가능합니다.

과제 관리

📋 목차

✨ 과제 생성

접근 경로

입력 필드

1. 과제 제목 (필수)

2. 과제 설명 (선택)

3. 과제 안내사항 (선택)

4. 마감일 (선택)

5. 만점 (기본: 100점)

6. 연결할 강의 (선택)

생성 예시

📝 과제 수정

수정 방법

주의사항

API 엔드포인트

🗑 과제 삭제

삭제 방법

삭제 시 영향

API 엔드포인트

🤖 AI 자동 채점

작동 흐름

평가 기준

채점 결과 구성

1. 점수 (Score)

2. 종합 피드백 (Feedback)

3. 잘한 점 (Strengths)

4. 개선할 점 (Improvements)

점수 스케일링

채점 소요 시간

비용 (참고용)

코드 위치

📊 제출 현황 확인

과제 목록 페이지

과제 상세 페이지 (학생 뷰)

🔧 API 참조

GET /api/assignments

POST /api/assignments

GET /api/assignments/{id}

POST /api/assignments/{id}

PUT /api/assignments/{id}

DELETE /api/assignments/{id}

🧪 E2E 테스트

테스트 파일

테스트 케이스 (6개)

테스트 실행

테스트 결과

💡 사용 팁

1. 명확한 지침 제공

2. 적절한 마감일 설정

3. 만점 활용

4. 강의 연결

5. 이미지 활용

⚠️ 주의사항

1. AI 채점의 한계

2. 재제출 불가

3. 삭제 주의

4. 마감일 변경

🔜 향후 기능

📞 문제 해결

Q: AI 채점이 너무 느려요

Q: AI 채점 결과가 부정확해요

Q: 학생이 실수로 제출했어요

Q: 마감일이 지났는데 제출이 되나요?

📚 관련 문서