SPEC.json

{
  "project": "UniCareHCMUS — Sổ tay sinh viên 4.0",
  "site_map": [
    {
      "path": "/",
      "name": "Home/Dashboard",
      "description": "Hero banner, search bar, 5 feature cards, quick actions"
    },
    {
      "path": "/handbook",
      "name": "Handbook Hub",
      "description": "Category navigation to graduation, English credits, departments, procedures"
    },
    {
      "path": "/handbook/[category]",
      "name": "Handbook Detail",
      "description": "Detailed content with breadcrumbs, last-reviewed badge, related links"
    },
    {
      "path": "/infographics",
      "name": "Infographics Library",
      "description": "Grid view with filters, tags, search; click for detail modal"
    },
    {
      "path": "/videos",
      "name": "Video Library",
      "description": "Grid of counseling/skill videos with transcripts, alt-text"
    },
    {
      "path": "/checklists",
      "name": "Checklist Templates",
      "description": "Gallery of templates; click to add to My Checklists"
    },
    {
      "path": "/checklists/my",
      "name": "My Checklists",
      "description": "Active checklists with progress, reminders, streaks"
    },
    {
      "path": "/checklists/[id]",
      "name": "Checklist Detail",
      "description": "Individual checklist with steps, notes, progress ring"
    },
    {
      "path": "/health-assessment",
      "name": "Health Assessment",
      "description": "Comprehensive mental health assessment with multiple scales, history tracking, and safety alerts"
    },
    {
      "path": "/chatbot",
      "name": "AI Chatbot",
      "description": "RAG interface with citations, feedback, disclaimer, crisis handoff"
    },
    {
      "path": "/search",
      "name": "Global Search",
      "description": "Search across all modules with filters, empty/error states"
    },
    {
      "path": "/profile",
      "name": "Profile & Settings",
      "description": "Notifications, consent, language, saved items"
    },
    {
      "path": "/admin",
      "name": "Admin Dashboard",
      "description": "Content management table (UI only)"
    }
  ],
  "user_flows": {
    "checklist_create": "START → Checklists page → Browse templates → Click 'Add to My Checklist' → Customize (optional) → Save → My Checklists (with new item)",
    "chatbot_question": "START → Chatbot page → Read disclaimer → Type question → Submit → Loading → Response with source chips → Click source chip (modal) → Feedback (thumbs up/down) → Continue or Contact counselor"
  },
  "component_inventory": [
    {
      "name": "AppHeader",
      "props": {
        "showSearch": "boolean",
        "showProfile": "boolean"
      },
      "states": ["default", "scrolled"]
    },
    {
      "name": "AppNav",
      "props": {
        "activeTab": "string"
      },
      "states": ["default", "mobile", "desktop"]
    },
    {
      "name": "FeatureCard",
      "props": {
        "title": "string",
        "description": "string",
        "icon": "LucideIcon",
        "href": "string",
        "color": "string"
      },
      "states": ["default", "hover", "focus"]
    },
    {
      "name": "ContentCard",
      "props": {
        "content": "ContentItem",
        "variant": "grid | list"
      },
      "states": ["default", "loading", "error"]
    },
    {
      "name": "ChatLayout",
      "props": {
        "messages": "Message[]",
        "onSend": "function",
        "isLoading": "boolean"
      },
      "states": ["empty", "conversation", "loading", "error"]
    },
    {
      "name": "MessageBubble",
      "props": {
        "message": "Message",
        "sources": "Source[]",
        "onFeedback": "function"
      },
      "states": ["user", "assistant", "system"]
    },
    {
      "name": "SourceChips",
      "props": {
        "sources": "Source[]",
        "onSourceClick": "function"
      },
      "states": ["default", "expanded"]
    },
    {
      "name": "ChecklistCard",
      "props": {
        "checklist": "Checklist",
        "progress": "number",
        "onToggle": "function"
      },
      "states": ["default", "completed", "in-progress"]
    },
    {
      "name": "QuizCard",
      "props": {
        "question": "QuizQuestion",
        "onAnswer": "function"
      },
      "states": ["unanswered", "answered", "correct", "incorrect"]
    },
    {
      "name": "ConsentDialog",
      "props": {
        "onAccept": "function",
        "onDecline": "function"
      },
      "states": ["privacy", "notifications", "complete"]
    },
    {
      "name": "CrisisHelpDialog",
      "props": {
        "hotlines": "Hotline[]"
      },
      "states": ["default"]
    },
    {
      "name": "EmptyState",
      "props": {
        "title": "string",
        "description": "string",
        "action": "ReactNode"
      },
      "states": ["default"]
    },
    {
      "name": "ErrorState",
      "props": {
        "error": "Error",
        "onRetry": "function"
      },
      "states": ["network", "server", "not-found"]
    }
  ],
  "data_models": "// Core Content Model\nexport interface ContentItem {\n  id: string;\n  title: string;\n  summary: string;\n  body: string;\n  module: 'handbook' | 'infographic' | 'video' | 'checklist';\n  tags: string[];\n  aliases: string[];\n  source: {\n    org: string;\n    doc: string;\n    year: number;\n    url?: string;\n  };\n  media?: {\n    img?: string;\n    video?: string;\n    transcript?: string;\n    alt?: string;\n  };\n  when_to_use: string[];\n  contraindications: string[];\n  tone: 'neutral' | 'supportive' | 'instructional';\n  safety_level: 'NORMAL' | 'SENSITIVE' | 'CRISIS';\n  version: string;\n  last_reviewed_at: string;\n  created_at: string;\n  updated_at: string;\n}\n\nexport interface Checklist extends ContentItem {\n  module: 'checklist';\n  steps: ChecklistStep[];\n  estimated_time: number;\n  difficulty: 'easy' | 'medium' | 'hard';\n}\n\nexport interface ChecklistStep {\n  id: string;\n  title: string;\n  description?: string;\n  completed: boolean;\n  notes?: string;\n  order: number;\n}\n\nexport interface QuizQuestion {\n  id: string;\n  question: string;\n  options: QuizOption[];\n  correct_answer_id: string;\n  explanation: string;\n  order: number;\n}\n\nexport interface QuizOption {\n  id: string;\n  text: string;\n}\n\nexport interface Video extends ContentItem {\n  module: 'video';\n  duration_seconds: number;\n  thumbnail_url: string;\n}\n\nexport interface Infographic extends ContentItem {\n  module: 'infographic';\n  image_url: string;\n  download_url?: string;\n}\n\nexport interface RAGChunk {\n  id: string;\n  content: string;\n  metadata: {\n    module: string;\n    tags: string[];\n    source: {\n      org: string;\n      doc: string;\n      year: number;\n      url?: string;\n    };\n    when_to_use: string[];\n    contraindications: string[];\n    locale: string;\n    version: string;\n  };\n  embedding?: number[];\n}\n\nexport interface UserProfile {\n  id: string;\n  name: string;\n  email?: string;\n  locale: 'vi-VN' | 'en-US';\n  consent: {\n    privacy: boolean;\n    notifications: boolean;\n    consented_at?: string;\n  };\n  saved_items: string[];\n  preferences: {\n    theme: 'light' | 'dark' | 'system';\n    notifications_enabled: boolean;\n  };\n  created_at: string;\n  updated_at: string;\n}\n\nexport interface Message {\n  id: string;\n  role: 'user' | 'assistant' | 'system';\n  content: string;\n  sources?: Source[];\n  feedback?: 'positive' | 'negative';\n  safety_level?: 'NORMAL' | 'SENSITIVE' | 'CRISIS';\n  created_at: string;\n}\n\nexport interface Source {\n  id: string;\n  title: string;\n  url?: string;\n  excerpt: string;\n  module: string;\n}",
  "sample_fixtures": {
    "content": [
      {
        "id": "hb-grad-001",
        "title": "Điều kiện tốt nghiệp",
        "summary": "Quy định về số tín chỉ, GPA tối thiểu, và các điều kiện khác để được xét tốt nghiệp",
        "body": "Để được xét tốt nghiệp, sinh viên cần đạt tối thiểu 120 tín chỉ (tùy ngành), GPA >= 2.0, hoàn thành khóa luận/đồ án, và các môn học bắt buộc...",
        "module": "handbook",
        "tags": ["tốt nghiệp", "quy định", "tín chỉ"],
        "aliases": ["graduation requirements", "điều kiện ra trường"],
        "source": {
          "org": "HCMUS",
          "doc": "Quy chế đào tạo 2023",
          "year": 2023,
          "url": "https://hcmus.edu.vn/quy-che"
        },
        "when_to_use": ["Năm cuối", "Lập kế hoạch học tập"],
        "contraindications": [],
        "tone": "instructional",
        "safety_level": "NORMAL",
        "version": "1.0",
        "last_reviewed_at": "2025-09-01",
        "created_at": "2025-01-15",
        "updated_at": "2025-09-01"
      },
      {
        "id": "hb-eng-001",
        "title": "Tín chỉ Tiếng Anh",
        "summary": "Quy định về số tín chỉ Tiếng Anh bắt buộc và các chứng chỉ thay thế được chấp nhận",
        "body": "Sinh viên cần hoàn thành 10 tín chỉ Tiếng Anh hoặc chứng chỉ TOEIC >= 550, IELTS >= 5.0...",
        "module": "handbook",
        "tags": ["tiếng anh", "tín chỉ", "chứng chỉ"],
        "aliases": ["English credits", "yêu cầu ngoại ngữ"],
        "source": {
          "org": "HCMUS",
          "doc": "Quy chế đào tạo 2023",
          "year": 2023
        },
        "when_to_use": ["Năm 1-2", "Lập kế hoạch học"],
        "contraindications": [],
        "tone": "instructional",
        "safety_level": "NORMAL",
        "version": "1.0",
        "last_reviewed_at": "2025-09-01",
        "created_at": "2025-01-15",
        "updated_at": "2025-09-01"
      }
    ],
    "checklists": [
      {
        "id": "cl-freshmen-001",
        "title": "Checklist tân sinh viên",
        "summary": "Danh sách công việc cần hoàn thành trong tháng đầu tiên",
        "body": "Hướng dẫn từng bước cho sinh viên năm nhất",
        "module": "checklist",
        "tags": ["tân sinh viên", "năm 1"],
        "aliases": ["freshman checklist"],
        "source": {
          "org": "HCMUS Student Affairs",
          "doc": "Hướng dẫn SV K2024",
          "year": 2024
        },
        "steps": [
          {
            "id": "step-1",
            "title": "Làm thẻ sinh viên",
            "description": "Đến phòng Công tác SV, mang theo 2 ảnh 3x4",
            "completed": false,
            "order": 1
          },
          {
            "id": "step-2",
            "title": "Kích hoạt email @student.hcmus.edu.vn",
            "description": "Truy cập portal, làm theo hướng dẫn",
            "completed": false,
            "order": 2
          },
          {
            "id": "step-3",
            "title": "Tham gia nhóm lớp trên Facebook",
            "completed": false,
            "order": 3
          }
        ],
        "estimated_time": 120,
        "difficulty": "easy",
        "when_to_use": ["Tháng đầu tiên"],
        "contraindications": [],
        "tone": "supportive",
        "safety_level": "NORMAL",
        "version": "1.0",
        "last_reviewed_at": "2025-08-15",
        "created_at": "2025-01-10",
        "updated_at": "2025-08-15"
      }
    ],
    "videos": [
      {
        "id": "vid-stress-001",
        "title": "Quản lý căng thẳng mùa thi",
        "summary": "Video hướng dẫn 5 kỹ thuật giảm stress hiệu quả",
        "body": "Transcript đầy đủ...",
        "module": "video",
        "tags": ["sức khỏe tinh thần", "stress", "thi cử"],
        "aliases": ["exam stress management"],
        "source": {
          "org": "HCMUS Counseling Center",
          "doc": "Mental Health Series 2024",
          "year": 2024
        },
        "media": {
          "video": "https://example.com/stress-management.mp4",
          "thumbnail_url": "https://images.pexels.com/photos/3771069/pexels-photo-3771069.jpeg",
          "transcript": "Xin chào các bạn sinh viên. Hôm nay chúng ta sẽ cùng tìm hiểu 5 kỹ thuật giảm stress...",
          "alt": "Video hướng dẫn kỹ thuật thư giãn cho sinh viên"
        },
        "duration_seconds": 420,
        "thumbnail_url": "https://images.pexels.com/photos/3771069/pexels-photo-3771069.jpeg",
        "when_to_use": ["Trước kỳ thi", "Khi cảm thấy áp lực"],
        "contraindications": ["Nếu có triệu chứng lo âu nghiêm trọng, hãy liên hệ tư vấn viên"],
        "tone": "supportive",
        "safety_level": "SENSITIVE",
        "version": "1.0",
        "last_reviewed_at": "2025-07-15",
        "created_at": "2025-03-01",
        "updated_at": "2025-07-15"
      }
    ],
    "infographics": [
      {
        "id": "inf-gpa-001",
        "title": "Cách tính GPA",
        "summary": "Infographic minh họa công thức tính GPA và ví dụ cụ thể",
        "body": "Hướng dẫn chi tiết về cách tính điểm trung bình tích lũy",
        "module": "infographic",
        "tags": ["học tập", "GPA", "điểm số"],
        "aliases": ["GPA calculation"],
        "source": {
          "org": "HCMUS Academic Affairs",
          "doc": "Student Guide 2024",
          "year": 2024
        },
        "media": {
          "img": "https://images.pexels.com/photos/5905857/pexels-photo-5905857.jpeg",
          "alt": "Infographic minh họa công thức tính GPA với ví dụ cụ thể"
        },
        "image_url": "https://images.pexels.com/photos/5905857/pexels-photo-5905857.jpeg",
        "when_to_use": ["Khi cần hiểu quy định điểm"],
        "contraindications": [],
        "tone": "instructional",
        "safety_level": "NORMAL",
        "version": "1.0",
        "last_reviewed_at": "2025-09-01",
        "created_at": "2025-01-20",
        "updated_at": "2025-09-01"
      }
    ]
  },
  "copy_placeholders": {
    "consent_privacy_vi": "Chúng tôi thu thập và xử lý dữ liệu cá nhân của bạn (tên, email, lịch sử sử dụng) để cải thiện trải nghiệm. Dữ liệu được lưu trữ an toàn và không chia sẻ với bên thứ ba. Bạn có thể rút lại sự đồng ý bất cứ lúc nào trong Cài đặt.",
    "consent_notifications_vi": "UniCareHCMUS muốn gửi thông báo về deadline, sự kiện, và lời nhắc checklist. Bạn có thể thay đổi tùy chọn này sau.",
    "disclaimer_vi": "UniCareHCMUS cung cấp thông tin tham khảo và không thay thế cho tư vấn chuyên nghiệp. Nếu bạn đang gặp khó khăn về sức khỏe tinh thần, vui lòng liên hệ với Trung tâm Tư vấn HCMUS hoặc đường dây nóng.",
    "crisis_hotline_vi": "Đường dây nóng hỗ trợ sức khỏe tinh thần 24/7",
    "crisis_contacts_vi": [
      {
        "name": "Trung tâm tư vấn Tâm Lý Sinh Viên HCMUS - Cơ sở 1",
        "phone": "0366.812.741",
        "hours": "7h30 - 17h00, từ thứ 2 đến thứ 6 (phòng F.106A)"
      },
      {
        "name": "Trung tâm tư vấn Tâm Lý Sinh Viên HCMUS - Cơ sở 2",
        "phone": "0918.207.126",
        "hours": "8h00 - 16h00, từ thứ 2 đến thứ 6 (phòng C.101)"
      }
    ],
    "chatbot_disclaimer_vi": "Trợ lý AI này cung cấp thông tin từ Sổ tay sinh viên. Câu trả lời chỉ mang tính tham khảo. Nếu bạn cần hỗ trợ khẩn cấp, hãy nhấn nút 'Cần trợ giúp ngay'.",
    "mental_health_intro_vi": "Bài đánh giá này giúp bạn hiểu tâm trạng hiện tại. Đây KHÔNG phải là chẩn đoán y khoa. Nếu bạn có suy nghĩ tự làm hại bản thân, vui lòng liên hệ ngay với chuyên gia.",
  }
}