UniCareHCMUS — Sổ tay sinh viên 4.0

Ứng dụng web hỗ trợ tân sinh viên HCMUS với kỹ năng cần thiết cho sinh viên, checklist cá nhân, video/infographic, bài trắc nghiệm kỹ năng và trợ lý AI. Dự án được xây dựng trên Next.js 13 (App Router), tối ưu cho mobile-first, tuân thủ accessibility và sẵn sàng PWA.

1) Tổng quan nhanh

• Mục tiêu: Tập trung hóa thông tin học thuật và phúc lợi, cung cấp công cụ chủ động (checklist, đánh giá sức khỏe), cùng trợ lý AI có trích dẫn nguồn.
• Trạng thái dữ liệu: Mock/fixtures thuần frontend, chưa tích hợp backend. Chatbot mô phỏng (không gọi LLM thật).
• Ngôn ngữ: vi-VN (định hướng hỗ trợ en-US trong tương lai).

2) Công nghệ & kiến trúc

• Framework: Next.js 13 (App Router), React 18, TypeScript (strict)
• UI: TailwindCSS, shadcn/ui (Radix UI), Lucide React icons
• Animation: Framer Motion
• Biểu đồ: Recharts
• Form/Validation: React Hook Form, Zod
• Theme: next-themes
• PWA: public/manifest.json (service worker chưa bật)

Cấu trúc chính (đã rút gọn):

project/
  app/                # App Router pages
  components/         # UI components (shadcn/ui + custom)
  hooks/              # Custom hooks
  lib/                # types, fixtures, utils
  public/             # static assets, PWA manifest
  tailwind.config.ts  # Tailwind config
  next.config.js      # Next.js config
  package.json        # scripts & deps

3) Tính năng & routes

• / Trang chủ/Dashboard (hero + quick actions)
• /handbook hoặc /student-skills Kỹ năng cần thiết cho sinh viên (lý thuyết, quiz, lộ trình)
• /infographics Thư viện infographic (lưới, tag)
• /videos Video ngắn Tâm Lý Học và Chữa Lành Tiềm Thức (từ Góc của Min Official)
• /checklists Checklist nhắn nhở (6 chủ đề + lưu trạng thái tick)
• /health-assessment Đánh giá sức khỏe (stress, lo âu, trầm cảm, giấc ngủ và self-care)
• /chatbot Trợ lý AI (RAG mô phỏng, chip nguồn, feedback)
• /profile Cài đặt & quyền riêng tư

Chi tiết schema và sample data: lib/types.ts, lib/fixtures.ts. Mô tả sản phẩm tổng thể: PROJECT_OVERVIEW.md, đặc tả màn hình/luồng: SPEC.json.

4) Yêu cầu hệ thống

• Node.js ≥ 18 (khuyến nghị LTS)
• npm ≥ 9 (hoặc dùng pnpm/yarn tùy môi trường, ví dụ bên dưới dùng npm)
• Quyền chạy trong PowerShell/Terminal trên Windows/macOS/Linux

5) Cài đặt & chạy (Development)

# 1) Cài dependencies
npm install

# 2) Chạy dev server
npm run dev
# Mặc định tại http://localhost:3000

Tùy chọn kiểm tra chất lượng mã:

npm run lint       # ESLint
npm run typecheck  # TypeScript kiểm tra kiểu, không emit file

6) Build & chạy Production

# Build tối ưu
npm run build

# Khởi động server production (sau khi build)
npm run start
# Mặc định tại http://localhost:3000

Triển khai (gợi ý):

• Vercel: Next.js native → chỉ cần import repo, các lệnh build/start được cấu hình sẵn.
• Docker/PM2: tự tạo Dockerfile/PM2 ecosystem cho nhu cầu tự host (chưa có sẵn trong repo).

7) Scripts npm

{
  "dev": "next dev",
  "build": "next build",
  "start": "next start",
  "lint": "next lint",
  "typecheck": "tsc --noEmit"
}

8) Ghi chú & giới hạn

• Dữ liệu hiện tại là fixtures phía client, không có database hay API thật.
• Chatbot là mô phỏng, chỉ minh họa UI/UX và quy trình trích dẫn nguồn.
• PWA mới có manifest; service worker/offline chưa bật.
• Tuân thủ an toàn nội dung: gắn nhãn NORMAL/SENSITIVE/CRISIS, có nút hỗ trợ khẩn cấp.

9) Định hướng mở rộng

• Tích hợp Supabase/Postgres để lưu hồ sơ, checklist, lịch sử chat
• Tích hợp LLM/RAG thật (API key, vector DB)
• Push Notification, Service Worker, i18n en-US
• Xác thực người dùng

10) Liên kết hữu ích trong repo

• PROJECT_OVERVIEW.md: Tổng quan sản phẩm và định hướng thiết kế
• SPEC.json: Sơ đồ trang, luồng người dùng, inventory component, mẫu dữ liệu
• lib/types.ts: Kiểu dữ liệu cốt lõi
• lib/fixtures.ts: Dữ liệu mẫu
• components/ui/*: Thư viện shadcn/ui đã cấu hình

---

Nếu gặp lỗi khi chạy, vui lòng đảm bảo phiên bản Node/npm đúng yêu cầu và xóa cache node_modules + package-lock.json trước khi cài lại (npm ci hoặc npm install).