RaonNuri_Public_Documents/REFACTOR-NOTES.md

Studio Curriculum Refactor — Notes

Branch: feat/studio-curriculum

Phase 1 (prior, by remover)

• c977e0b chore: remove gamification curriculum/lesson feature — removed the unrelated gamification Curriculum/Lesson feature, freeing the Curriculum name and src/types/curriculum.ts path. tsc/build green.

Phase 2 (this work) — data-driven studio Curriculum (회차) entity

Three green-gated steps, commit after each (tsc --noEmit = 0):

• 2-1 a4aa1db feat(studio): add Curriculum entity, role icon registry, 3학년 1회차 seed

  • src/types/curriculum.ts — Curriculum + CurriculumRole/Meta/AI/Rewards/Copy (+ Localized<T>). Stages are NOT modeled here (fixed at 6 — locked decision).
  • src/components/writing/studio/roleIconRegistry.ts — string icon key → IconType (mapPin/heart/question/default).
  • src/data/studioCurricula/grade3-session1.ts — seed; role label/guide/placeholder/examples copied verbatim from messages/*.json; ai.keywordCount = 5; meta from the lesson plan (ko; en/ja = ko + // TODO i18n).
  • Pure addition; studio did not consume it yet.

• 2-2 3536c8d feat(studio): make writing frame data-driven via Curriculum roles

  • Removed the StudioSentenceKey union + STUDIO_SENTENCE_ORDER.
  • Generalized every Record<StudioSentenceKey, …> → Record<string, …> (StudioSegment/SuggestResponse.bySentence, StudioResult.sentencesV1/V2, StudioCompleteRequest.sentencesV1/V2, segment/suggest request key, flow state sentencesV2, tokensBySentence, stage props).
  • StudioBlank.sentenceKey → roleKey: string (no back-compat — locked decision).
  • templates.ts (studioBlankId/getStudioBlanks/composeStudioSentences) now takes CurriculumRole[] (slotId-driven). studioRoleMeta.ts deleted.
  • studioService.ts: SEGMENT_SCHEMA/SUGGEST_SCHEMA built at runtime from role keys (Gemini structured output); emptyTokenMap/emptySuggestionMap and all loops derive from the role keys carried by the request; keywordCount injected (was STUDIO_KEYWORD_COUNT, pickFiveKeywords→pickKeywords).
  • segmentation.ts/suggestion.ts: output-key instruction generated from role keys.
  • Routes resolve the Curriculum from curriculumId and add manual runtime key-validation (repo's existing validationErrorResponse style, not zod):
    • analyze — feeds ai.keywordCount.
    • segment/suggest — reject sentences whose key is not a curriculum role key.
    • complete — require all role keys present in sentencesV1/V2; <p> body assembly + safeSentences iterate role keys in frame order; roleKey saved.
  • page.tsx + stages render from state.curriculum.frame.roles via roleIconRegistry; studio loads the Curriculum with getCurriculum(?curriculumId=) → falls back to the grade3-session1 seed.
  • 3학년 1회차 renders identically to before. tsc 0, npm run build exit 0.
  • New code-seed registry: src/data/studioCurricula/index.ts (getCurriculum, getCurriculumRoleKeys, DEFAULT_CURRICULUM_ID).

• 2-3 feat: data-driven studio Curriculum entity (3학년 1회차 seed)

  • ICU-templated copy in messages/{ko,en,ja}.json, values fed from data:
    • complete.title {session} ← meta.sessionOrdinal
    • keywords.title {count} ← ai.keywordCount
    • secondWriting.subtitle {count} ← frame.roles.length
  • Removed migrated keys from all three locales: studio.roles.*, studio.firstWriting.{guides,placeholders,examples}. Platform-chrome keys kept (stepper, reward, actions, imageUpload, etc.). CRLF + tab + trailing newline preserved; key sets identical across the 3 locales (2080 each).
  • tsc 0, build exit 0.

What is data-driven now

• Writing-frame roles (key/slotId/icon/label/guide/placeholder/examples) — variable count & names, sourced from Curriculum.frame.roles.
• AI keyword count (ai.keywordCount), AI structured-output schemas & prompt output keys (built from role keys at runtime).
• Session/count copy (complete.title/keywords.title/secondWriting.subtitle) via ICU + data.
• Lesson-plan meta (sessionLabel/topic/objective/achievementStandard/flow/materials/ emotionCards) — present as data on the entity.

What is intentionally FIXED (not data-driven)

• The 6-stage flow STUDIO_STAGE_ORDER / goNext / StageStepper and stepper.* i18n labels (locked decision: stages fixed at 6).
• Reward UI engine + default motion/sprite preset pools (rewards left undefined → shared platform pool).

STOP points (product decisions — NOT built, per locked decisions)

1. Management layer — no Firestore curriculums collection, CRUD API, teacher authoring console, or security rules. Curricula live only as code seeds today. A real authoring flow needs a schema + rules + UI decision.
2. Curriculum entry/routing — studio reads ?curriculumId= and falls back to grade3-session1. How students actually receive a curriculumId (team assignment link / home card / Topic linkage) is undecided.

   Resolved 2026-08-10 — a student arrives from the class session. The notice board and the classroom both link with the in-progress session's teamId+topicId, and _flow/liveCurriculum.ts overlays the live week/topic onto the code seed. Note that meta.sessionOrdinal (2-3 above) is now seeded from TeamSession.order — the confirmed class number — rather than being the seed's own constant. There is no "assignment link"; assignments were deleted (see DATA_MODELS.md → TeamSession).

3. Existing published works — NO back-compat/migration was built (locked decision #2). Old studio writings stored with situation/emotion/reason keys and blanks[].sentenceKey may not render correctly under the new roleKey shape. If preserving old works matters, a migration/back-fill is required.
4. Multilingual authorship for meta — en/ja for meta are ko + // TODO i18n (meta is data-only, not surfaced in UI yet). Translation authorship is out of scope.
5. copy overrides — CurriculumCopy type exists but the seed leaves it undefined; ICU templates live in i18n. Per-curriculum copy override wiring is not built (not needed for the seed).
6. Topic relationship — Curriculum.topicId? left as an optional aggregation FK; Topic itself unchanged.

Verify

• npx tsc --noEmit → 0 errors.
• npm run build → exit 0 (run after Remove-Item -Recurse -Force .next once to clear a stale route-validator cache).
• Pre-existing unrelated lint warnings may remain; none introduced.