AssessmentReport

학습 평가 보고서 — payload 검증 + aggregated_scores 추출 + brief/full 직렬화

상태

항목	값
Layer	domain
Tier	L1
Status	deprecated
Version	0.9.0
가격	Free (free)
**카�
�고리**	Learning

개요

⛔ Deprecated (ADR-039 사례 8)

ADR-039: Plugin Scope 원칙 적용 — 단일 도메인 전용 plugin 부적격 판정.

부적격 근거

음성평가 도메인 — apis.how 의 session_id / rubric / utterance_count / aggregated_scores (mean/min/max overall + total_duration_ms) 모두 음성 평가 한정 패턴. ReportSerializer brief/full 모드만 일반화 가능하나 ~30 LOC 로 단� plugin ROI 낮음.

현재 상태 (중요)

⚠️ 'SaaS 이전' 작� 불필요. 본 plugin 의 원본 코드는 추출 작� 중에 apis.how 코드에 그대로 남아있습니다.

• 원본 위치: workspace/apis.how/web/app/Http/Controllers/AssessmentReportController.php (외 Model/Service)
• plugin 추출본: platform/web/laravel/plugins/AssessmentReport/ (Phase 1+2 추출만 완료, Phase 4 어댑터 미진행)
• apis.how 의 동작: 추출 작� 이후에도 자기 코드를 그대로 사용 중 (변경 없음)

Deprecated 의 의미

• ❌ 본 plugin 추출본을 더 이상 발전시키지 않음 (Phase 3 / Phase 4 진행 안 함)
• ❌ plugin store 카탈로그 � �출 안 함 (운영자 검색 결과에서 숨김)
• � apis.how 의 원본 코드는 그대로 사용 — 변경 불필요
• � plugin 폴더는 reference 로 보존 (다른 SaaS 가 유사 기능 작성 시 참고용)

다른 SaaS 가 유사 기능을 만든다면

본 plugin 폴더의 Pure 코드를 참고해서 자기 SaaS 의 app/Sites/{Name}/ 안에 자체 구현. plugin 으로 활용하지 않음.

이력

• 2026-04-30: AssessmentReport plugin RC 0.9.0 추출 (apis.how 출처)
• 2026-05-02: ADR-039 적용 — deprecated. apis.how 원본 코드는 그대로 사용 (이전 작� 불필요).

---

(이전) 개요

개요

AssessmentReport 는 multi-saas-kit 의 Layer 3 Domain Plugin � 니다. apis.how 의 pronunciation-service 가 생성하는 세� � � 합 평가 결과를 영속 저장하기 위한 표준 검증 / 추출 / 직렬화 로직을 제공합니다.

Eloquent Model 의존을 제거하고 Pure validator + extractor + serializer 로 분리해 다른 평가 도메인 (writing/listening/reading 등) 에도 재사용 가능.

핵심 컴포넌트 (3 Pure Service)

AggregatedScoreExtractor

apis.how AssessmentReportController::store 의 mean_overall / min_overall / max_overall / total_duration_ms 추출 로직 분리. payload 의 aggregated_scores 객체에서 4개 표준 컬럼 값 추출:

• 누락 / non-numeric → null (caller 가 nullable column 으로 저장)
• 문자열 numeric ('85.5') → float 자동 cast
• duration 은 int, score 는 float

AssessmentPayloadValidator

apis.how AssessmentReportController::store 의 검증 로직 추출. AssessmentReport 모델 fillable 호환 array 반환:

| 검증 | 설� | |------|------| | session_id 필수 + 형식 (/^[A-Za-z0-9_\-]{1,191}$/) + max 191 | apis.how pronunciation-service session ID 호환 | | rubric 기본값 | 'session_general' | | utterance_count / valid_count / processing_ms | non-negative int (음수/non-numeric reject) | | aggregated_scores | AggregatedScoreExtractor 위임 | | weak_patterns / per_mode / narrative / learner_context / metadata | array 만 통과, 그 외 null | | store_raw | false 면 raw_utterances null (개인정보/저장공간 보호) |

ReportSerializer

apis.how AssessmentReportController::serialize 추출.

두 모드:

• full (default) — 모든 필드 포함
• brief — 목록 화면용 핵심 메타만 (id / session_id / rubric / scores / created_at)

serializeMany([...]) 헬퍼 — 목록은 default brief, 상세는 full.

numeric 필드는 출력 시 type cast ('15' → 15, '85.5' → 85.5).

Exception

InvalidAssessmentPayloadException — reason 필드 (i18n 가능): session_id_required, invalid_session_id, negative_utterance_count 등.

설정 (config/assessment-report.php)

return [
    'enabled' => env('PLG_ASSESSMENT_REPORT_ENABLED', true),
    'session_id' => [
        'pattern' => '/^[A-Za-z0-9_\-]{1,191}$/',
        'max_length' => 191,
    ],
    'default_rubric' => 'session_general',
    'store_raw_default' => false,  // 개인정보 보호 default
];

사용 예시

use App\Plugins\AssessmentReport\Services\{AssessmentPayloadValidator, ReportSerializer};

$validator = AssessmentPayloadValidator::fromConfig(config('assessment-report'));
$serializer = new ReportSerializer;

// 1) Controller 진�
 — 정규화된 array 반환
$normalized = $validator->validate($request->all());

// 2) DB 에 저장
$report = AssessmentReport::create([
    ...$normalized,
    'tenant_id' => $tenantId,
    'user_id' => $userId,
    'api_token_id' => $tokenId,
]);

// 3) Response 직렬화
return response()->json([
    'status' => 'success',
    'data' => $serializer->serialize($report->toArray()),  // full
], 201);

// 4) 목록 화면 — brief 직렬화
$list = $serializer->serializeMany($reports->toArray());  // brief default

출처

apis.how 의 App\Models\AssessmentReport (105줄) + App\Http\Controllers\Api\AssessmentReportController (318줄) 에서 추출. Eloquent / RLS / Policy / 인증 로직은 프로젝트 � 임으로 분리, Pure 검증 + 추출 + 직렬화 만 plugin.

의존성

• 없음 (자기완결, PromptTemplating 은 향후 narrative 합성 시 optional)

다른 Plugin 과의 관계

• AiRelay — narrative 자동 생성 시 LLM 호출 (선택)
• AiTracking — 평가 호출 이력 기록 (Phase 2)

다음 단계 (Phase 3+)

• 표준 AssessmentReport Model + Migration (선택 활성, RLS policy 포함)
• Filament Resource (목록 + 상세 뷰)
• ApiToken ability 통합 (assessment:report:save / read)
• Narrative 자동 생성 (PromptTemplating + AiRelay)
• Writing/Reading 평가 도메인 확장 (rubric 분기)

라이선스

MIT

의존성

• PromptTemplating (optional)

데모

• Platform 관리자 패널에서 메타 확인 🔒 로그인 필요
• 사용 예시 (PHP)

---

🛒 Plugin Store에서 보기: store.codebase.how/plugins/assessment-report