Console/ Planning/ Wizard Runtime

Wizard Runtime 05 · Premium Wizard · 8-step personal view · trilingual · AI-assisted · not tenant

Planning · v0.2
Premium Wizard เป็น customer subscriber runtime · output = personal KB-view bundle · ไม่ใช่ tenant · ไม่ publish อัตโนมัติ. ทุก AI suggestion ต้องผ่าน human review · faithfulness floor 0.70 · sensitive-surface escalation dual. B shell at /kb/wizard renders the contract only.
Binding: live mock mapped-not-bound placeholder derived

Context

Phase 12F เปิด Premium Wizard contract: 8 steps (profile → goal → pain → target → service → outcome → upload → review) · trilingual TH/EN/ZH · 4 approval gates · output bundle shape กำหนด. เป้าหมาย: ให้ Premium subscribers กรอก input แล้วระบบ map → persona + journey + dashboard + service → output เป็น personal KB-view bundle. ไม่ใช่ tenant factory · ใช้สำหรับ individual user customisation เท่านั้น.

docs/kb/data/premium_wizard.json8 steps · personas · approval_gates · output_bundle_shape · trilingual_policy
docs/kb/data/journeys.json7 persona journeys · map wizard input → journey
docs/kb/data/lexicon.json80 entries · terminology for AI suggestion grounding
docs/kb/data/dashboard_contract.jsonpersonal_dashboard_model · wizard outputs feed preset storage
docs/kb/data/approval_matrix.jsonSensitive-surface + ai-faithfulness gates

Scope

Field Mapping — Wizard Steps 8-step contract → A form + state

Source: premium_wizard.steps[*] (each step has id · order · labels × 3 · purpose × 3 · fields · validation_rules · related_* · required_review · honest_note).

B Field B Type A Runtime Target A Owner Approval Gate Binding Notes
id string Route param · /app/wizard/{step_id} Frontend none mapped-not-bound Deep-linkable per step · resume draft
order integer Step indicator · progress bar Frontend none mapped-not-bound 1..8
label_th / label_en / label_zh string × 3 i18n dict · step title in current lang Frontend none mapped-not-bound Trilingual parity enforced
purpose_th / purpose_en / purpose_zh string × 3 Step header subtitle · hint system Frontend none mapped-not-bound Never hand-typed in A code
fields[] array<field> Dynamic form generator · component per field type Frontend none mapped-not-bound Validation rules picked up from contract
validation_rules object Client-side + server-side validator · Zod-like schema Backend + FE none mapped-not-bound Both layers must enforce · never trust client alone
related_truth_nodes array<id> Deep-link to KB truth tree entry Frontend none mapped-not-bound Context panel · "learn more" link
related_lexicon array<id> Glossary popover on term hover Frontend none mapped-not-bound Uses lexicon.json
related_journeys array<id> Persona match hint · feeds output bundle Backend gate-ai-faithfulness mapped-not-bound AI inference · faithfulness floor enforced
related_services array<id> Service recommendation in output bundle Backend gate-ai-faithfulness mapped-not-bound From services.json current state
related_dashboards array<id> Dashboard preset targets Backend none mapped-not-bound Feeds personal_dashboard_model preset
required_review boolean Yellow review banner on step · blocks progress Frontend gate-review mapped-not-bound Typically on sensitive steps · user + reviewer confirmation
honest_note_th / honest_note_en string × 2 Footer caption on step · verbatim Frontend none mapped-not-bound Must render as-authored

Field Mapping — Approval Gates 4 gates per contract

Source: premium_wizard.approval_gates.

Gate (B) A Runtime Enforcement A Owner Binding Notes
gate-sensitiveSensitive-flag detection → dual-approval pathBackendmapped-not-bound Per approval_matrix.sensitive_surface_markers
gate-ai-faithfulnessRAGAS ≥0.70 per AI suggestionBackendmapped-not-bound Retry 1 · decline + fallback to user-input if still <0.70
gate-upload-piiPII scan before persist uploadBackendmapped-not-bound OCR output scrubbed too
gate-finalizeStep-8 user confirmation checkbox + signatureFrontendmapped-not-bound Cannot finalize without explicit user review

Field Mapping — Output Bundle what A produces at step 8

Source: premium_wizard.output_bundle_shape.

B Field A Runtime Storage A Owner Binding Notes
id_patternBundle ID generator (e.g., PWB-YYMMDD-{user}-{seq})Backendmapped-not-bound Deterministic + auditable
fieldswizard_bundles table · JSONB shapeBackendmapped-not-bound Persona · journey · dashboards · services · upload refs · AI suggestions + RAGAS scores
not_allowedValidation blocklist · rejects attempts to set forbidden fieldsBackendmapped-not-bound E.g., tenant_id, auto-publish, cross-tenant share — all blocked

A-owned Runtime Boundary ขอบเขต A vs B

B owns (read-only for A)

  • Contract JSON (all fields listed in "Context" block above)
  • Trilingual label parity
  • honest_note + requires_human_review flags
  • Contract evolution (schema-versioned)

A owns (this runtime)

  • All tables + indexes for entities in ER diagram below
  • API endpoints in API Sketch block
  • Frontend components + chart/form rendering
  • Cache + feature flag integration
  • Auth + sign-off capture
  • Audit trail

ER Diagram A-owned tables · Wizard · draft + bundle + suggestions

Wizard · draft + bundle + suggestions
wizard_drafts ● id user_id step (1..8) locale answers JSONB uploads[] ai_suggestions[] sensitive_flag saved_at · expires_at (7d) wizard_bundles (output) ● id (PWB-YYMMDD-U-N) user_id persona_match journey_match dashboard_preset_ref service_recs[] ragas_scores[] finalized_at wizard_uploads ● id s3_url (scanned) pii_scan_result ocr_output_ref pdf_parsed_ref ai_suggestions ● id draft_id · step prompt_hash response ragas_faithfulness accepted_by_user retry_count (0..1) declined_reason

API Sketch FastAPI endpoints

POST/api/wizard/draft
Create/resume draft · Premium tier required
PATCH/api/wizard/draft/{id}
Save step answers · validate against contract
POST/api/wizard/draft/{id}/upload
Upload file · PII scan · OCR · PDF parse
POST/api/wizard/draft/{id}/suggest
AI suggestion for current step · RAGAS ≥0.70
POST/api/wizard/draft/{id}/finalize
Finalize → bundle · writes Dashboard preset

Sequence Flow Wizard flow · suggestion + faithfulness + finalize

Wizard flow · suggestion + faithfulness + finalize
Premium User Wizard API Claude · RAGAS PII scan · OCR Preset store 1 PATCH step=3 answers 2 suggest · prompt with lexicon grounding response · ragas=0.82 ✓ 3 upload file (step 7) 4 scan PII · OCR · PDF parse clean · no PII residue 5 finalize · user signs step 8 6 create bundle · Dashboard preset

Dependencies

Upstream

  • Auth + JWT with Premium tier
  • File upload + S3 storage
  • PII scanner
  • Claude API integration (Layer F)
  • RAGAS faithfulness evaluator
  • Dashboard Runtime (preset storage consumer)

Downstream

  • Personal dashboard rendering (uses wizard preset)
  • Service recommendations surface
  • Journey personalisation

Human Approval Gates

Risks

AI suggestion fabricates persona match
High
Faithfulness ≥0.70 enforced · retry 1 · decline-to-answer if below · user sees score
Upload contains PII that leaks into vector store
High
PII scan pre-OCR · pre-embed · SHA-256 for any identifier fields per CLAUDE.md
Sensitive-surface path bypassed
High
Sensitive flag detected at step-ingest · dual-approval path enforced at API · cannot finalize without
Trilingual parity breaks mid-wizard
Med
Language toggle locked mid-wizard · switch only between steps · contract validator ensures all labels present
Wizard abandoned mid-flow loses data
Low
Auto-save draft to server every step · resume on return · 7-day draft retention
User grants output bundle tenant-level scope (not allowed)
Med
not_allowed validation · output scoped to user · UI cannot expose tenant-grant

Definition of Done

  1. All 8 steps renderable in TH · EN · ZH with trilingual parity
  2. Dynamic form generator builds from contract · validation bi-layer
  3. Auth-guarded to Premium+ tier · draft autosave
  4. File upload pipeline: PII scan + OCR + PDF parse end-to-end
  5. AI suggestion engine enforces RAGAS 0.70 floor with retry
  6. Sensitive-flag triggers dual-approval path · blocks finalize
  7. Output bundle persisted to wizard_bundles + Dashboard preset
  8. not_allowed fields rejected at API layer
  9. All 5 approval gates signed off · WORM audit log
  10. Feature flag wizard.runtime_v1 staged rollout + rollback drill

Deferred

Wizard Runtime Planning · v0.2 · Session A · A-owned ← Planning hub · B contract ↗