Skip to content

coangsang/the-fitusocial

BranchesTags

Repository files navigation

FITUSocial (Xây dựng hệ thống cộng đồng và hỗ trợ học tập thông minh cho sinh viên khoa CNTT)

1. Mục lục

2. Tính năng

FITUSocial là ứng dụng web dành cho cộng đồng sinh viên CNTT, được xây dựng bằng React + TypeScript + Vite và dùng Supabase làm backend chính. Hệ thống đang có các nhóm tính năng sau:

Xác thực và phiên đăng nhập

  • Đăng nhập, đăng ký, xác thực OTP và quên mật khẩu.
  • Kiểm tra phiên đăng nhập qua Supabase Auth trong src/App.tsx và src/lib/supabase.ts.

Bảng tin và bài viết

  • Trang chủ feed với danh sách bài viết.
  • Xem chi tiết bài viết qua route /post/:postId.
  • Tạo, sửa, xóa bài viết và tương tác liên quan trong module src/features/feed.
  • Hỗ trợ hiển thị ảnh, filter và các modal thao tác bài viết.
  • Có thể hiển thị bản tóm tắt AI cho bài viết khi bảng summary_post đã có dữ liệu.

Bình luận

  • Comment gốc và reply theo cây.
  • Vote comment, sửa, xóa, report.
  • Hỗ trợ markdown, attachment, mention người dùng và mention tài liệu.
  • Có realtime/polling sync và đồng bộ badge số lượng comment.
  • Toàn bộ logic nằm ở src/features/comment.

Kho tài liệu học tập

  • Route hiện hành:
    • /docs
    • /docs/:subjectId
    • /docs/:subjectId/:folderSlug
    • /docs/personal
  • Xem danh sách môn học, thư mục tài liệu và tài liệu cá nhân.
  • Upload tài liệu, preview, download, bookmark, rating, report và yêu cầu gỡ tài liệu.
  • Logic chính nằm ở src/features/materials.

Môn học và đánh giá môn học

  • Module src/features/subjects với các route:
    • /subjects
    • /subjects/:subjectId
  • Module này bao gồm:
    • danh sách môn học
    • trang chi tiết môn học
    • đánh giá môn học
    • vote review
    • theo dõi môn học
    • hiển thị bản tóm tắt AI cho review môn học từ summary_review nếu dữ liệu đã có

AI Summary

  • Hệ thống hiện có 2 nhánh tóm tắt bằng AI:
    • tóm tắt bài viết trong feed
    • tóm tắt review môn học ở trang chi tiết môn học
  • Frontend đọc dữ liệu summary từ Supabase:
    • bài viết dùng bảng summary_post
    • môn học dùng bảng summary_review
  • Phần xử lý AI được tách riêng trong thư mục summarizer để frontend không phải gọi model trực tiếp.
  • UI hiện đã có:
    • nút Xem bản tóm tắt AI trong bài viết
    • nút Xem bản tóm tắt trong trang chi tiết môn học
  • Cách tổ chức này giúp có thể chạy AI theo lịch nền bằng GitHub Actions thay vì bắt người dùng chờ khi đang sử dụng app.

Tìm kiếm

  • Trang tìm kiếm tại /search.
  • Module tìm kiếm có các nhánh cho bài viết, tài liệu và môn học trong src/features/search.

Hồ sơ cá nhân và cài đặt

  • Trang hồ sơ người dùng theo route /:username.
  • Thiết lập hồ sơ ban đầu tại /profile/setup.
  • Khu vực cài đặt tài khoản tại /settings.
  • Module nằm ở src/features/profile và src/features/settings.

Thông báo

  • Trang thông báo tại /notifications.
  • Chuông thông báo và dropdown nằm ở layout/header.
  • Logic nằm ở src/features/notifications.

Quản trị

  • Trang quản trị tại /admin.
  • Theo mã nguồn hiện tại, admin có các nhóm quản lý:
    • tài khoản
    • bài viết
    • bình luận
    • report
    • vai trò và quyền
    • môn học, tag, tài liệu
  • Module nằm ở src/features/admin.

Android / Capacitor

  • Repo có thư mục android và các script Capacitor trong package.json.
  • Có thể build/sync sang Android.

3. Công nghệ sử dụng và lý do

Công nghệ Dùng ở đâu Lý do chọn
React 19 Toàn bộ frontend Phù hợp để xây dựng UI theo component và tổ chức app theo từng module tính năng.
TypeScript Toàn bộ src/ Giúp kiểm soát kiểu dữ liệu tốt hơn khi app có nhiều domain như post, comment, materials, subjects và admin.
Vite Môi trường dev và build Khởi động nhanh, build gọn, phù hợp với app React hiện đại.
React Router src/App.tsx và các page Tổ chức điều hướng rõ ràng cho các route như /post, /docs, /subjects, /admin, /notifications.
Supabase Auth, database, storage, realtime Đây là backend chính của hệ thống cho đăng nhập, dữ liệu bảng, upload file, signed URL và đồng bộ realtime.
TanStack Query materials, search và các flow dữ liệu động Hữu ích cho cache server state, refetch, pagination và mutation.
Zustand src/store/ Nhẹ, dễ dùng cho global state như profile, UI state và user stats.
Tailwind CSS Toàn bộ UI Giúp xây giao diện nhanh và giữ style nhất quán giữa nhiều module.
Radix UI Form, modal, dialog, select, toast Cung cấp các primitive UI ổn định cho những thành phần tương tác phức tạp.
Zod auth, materials và các form Dùng để validate dữ liệu đầu vào rõ ràng trước khi gửi lên backend.
Vitest + Testing Library tests/ Phù hợp để test UI React và logic frontend trong hệ sinh thái Vite.
Capacitor android/ và script cap:* Cho phép tái sử dụng code web để build và chạy trên Android.
Python summarizer scripts summarizer/ Tách riêng pipeline AI summary khỏi frontend, giúp phần tạo summary vận hành độc lập với UI.

Stack hiện tại được chọn theo hướng:

  • dễ chia module theo tính năng
  • tận dụng backend-as-a-service để giảm công dựng hạ tầng
  • hỗ trợ được dữ liệu động như comment, thông báo, tài liệu
  • có đường mở rộng sang Android và pipeline AI summary riêng

4. Cấu trúc thư mục

the-fitusocial/
├── src/
│   ├── App.tsx                 # Định nghĩa route và luồng điều hướng chính
│   ├── main.tsx                # Entry point của ứng dụng Vite
│   ├── components/             # UI dùng chung
│   ├── layouts/                # AuthLayout, MainLayout
│   ├── lib/                    # Supabase client, feature flags, utils dùng chung
│   ├── store/                  # Zustand stores
│   ├── types/                  # Kiểu dữ liệu và generated database types
│   ├── utils/                  # Helper functions
│   └── features/
│       ├── admin/              # Trang và logic quản trị
│       ├── auth/               # Đăng nhập, đăng ký, quên mật khẩu, OTP
│       ├── comment/            # Hệ thống comment
│       ├── feed/               # Feed, bài viết, post detail
│       ├── materials/          # Kho tài liệu học tập hiện hành
│       ├── notifications/      # Thông báo
│       ├── profile/            # Hồ sơ cá nhân
│       ├── search/             # Tìm kiếm
│       ├── settings/           # Cài đặt tài khoản
│       └── subjects/           # Môn học, review môn học và tóm tắt review
├── public/                     # Tài nguyên public
├── docs/                       # Tài liệu dự án và tài liệu kỹ thuật
├── supabase/                   # SQL, functions, migrations liên quan Supabase
├── android/                    # Android project của Capacitor
├── summarizer/                 # Script Python phục vụ xử lý/tóm tắt ngoài FE
├── references/                 # Tài liệu tham khảo phụ
├── tests/                      # Thư mục test cấp repo
├── package.json                # Scripts và dependencies
├── vite.config.ts              # Cấu hình Vite
├── tsconfig.json               # Cấu hình TypeScript
├── tailwind.config.js          # Cấu hình Tailwind
└── capacitor.config.ts         # Cấu hình Capacitor

5. Cách chạy

Yêu cầu

  • Node.js >= 24.0.0
  • npm
  • Supabase project hoặc Supabase local đang sẵn sàng

Biến môi trường bắt buộc

Bạn có thể tạo file .env.local ở thư mục gốc để chạy local:

VITE_SUPABASE_URL=your_supabase_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key

Biến môi trường cho pipeline AI summary

Ngoài env cho frontend, các script trong summarizer còn dùng thêm các biến sau:

SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_supabase_anon_key
BOT_EMAIL=bot_account_email
BOT_PASSWORD=bot_account_password
AI_BASE_URL=https://your-openai-compatible-endpoint
AI_API_KEY=your_ai_api_key
AI_MODEL=your_model_name

Chạy môi trường development

npm install
npm run dev

Sau đó mở:

http://localhost:5173

Build production

npm run build

Xem bản build local

npm run preview

Chạy test

npm run test

Các script khác đang có trong repo

npm run lint
npm run test:watch
npm run test:coverage
npm run update-types

Capacitor / Android

Repo hiện có sẵn các script:

npm run cap sync
npm run cap open
npm run cap run
npm run cap build

Lưu ý:

  • các script cap:* đang gọi pnpm exec, nên nếu dùng phần Android bạn cần có pnpm
  • app phụ thuộc dữ liệu từ Supabase, vì vậy thiếu env hoặc backend chưa sẵn sàng thì app sẽ báo lỗi ngay khi khởi động

6. Deploy lên Vercel

Dự án này có thể deploy dễ dàng lên nền tảng Vercel do sử dụng Vite.

Các bước deploy cơ bản

  1. Đăng nhập vào Vercel, chọn Add New... > Project.
  2. Import repository GitHub chứa dự án của bạn.
  3. Vercel sẽ tự động nhận diện Framework Preset là Vite.
  4. Mở phần Environment Variables và thêm các biến môi trường cần thiết (tương tự như trong file .env.local):
    • VITE_SUPABASE_URL
    • VITE_SUPABASE_ANON_KEY
  5. Bấm Deploy và chờ quá trình hoàn tất.

Cấu hình file vercel.json cho React Router

Vì dự án sử dụng React Router (client-side routing), nên mọi request tới các route con (như /docs, /search, ...) cần được trỏ về index.html để tránh lỗi 404 từ phía server Vercel.

Dự án đã có sẵn file vercel.json ở thư mục gốc với cấu hình rewrites sau để xử lý vấn đề này:

{
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ]
}

7. AI Summary và GitHub Actions

Workflow hiện có

Repo đang có 2 workflow trong .github/workflows:

  • summarize_posts.yml: chạy script summarizer/post_summarizer.py để tạo tóm tắt AI cho bài viết.
  • summarize_reviews.yml: chạy script summarizer/review_summarizer.py để tạo tóm tắt AI cho review môn học.

Lịch chạy

  • summarize_posts.yml: chạy mỗi 3 tiếng và có thể bấm chạy tay bằng workflow_dispatch.
  • summarize_reviews.yml: chạy mỗi 12 tiếng và có thể bấm chạy tay bằng workflow_dispatch.

Cấu hình GitHub Actions secrets

Để workflow chạy được trên GitHub, vào:

Repository Settings > Secrets and variables > Actions

Sau đó thêm các Repository secrets:

Secret Mục đích
AI_API_KEY API key để gọi model AI hoặc provider OpenAI-compatible.
AI_BASE_URL Base URL của endpoint AI, ví dụ endpoint OpenAI-compatible hoặc gateway nội bộ.
AI_MODEL Tên model dùng để sinh tóm tắt.
BOT_EMAIL Email tài khoản bot dùng đăng nhập Supabase.
BOT_PASSWORD Mật khẩu tài khoản bot dùng cho pipeline summary.
SUPABASE_ANON_KEY Anon key của Supabase để khởi tạo client.
SUPABASE_URL URL project Supabase.

Luồng hoạt động tổng quát

  1. GitHub Actions kích hoạt workflow theo lịch hoặc chạy tay.
  2. Workflow cài Python, cài supabase package và chạy script trong thư mục summarizer.
  3. Script đăng nhập bằng bot account, đọc bài viết hoặc review cần xử lý.
  4. Script gọi model AI qua AI_BASE_URL, AI_API_KEY, AI_MODEL.
  5. Kết quả được ghi về Supabase:
    • bài viết vào summary_post
    • review môn học vào summary_review
    • log chạy được lưu ở các bảng log tương ứng
  6. Frontend tự đọc các bản summary này để hiển thị nút và nội dung tóm tắt AI.

8. Thành viên

STT MSSV Họ và tên Email
1 24120429 Phạm Quang Sang coangsang19@gmail.com
2 24120097 Nguyễn Hoàng Nam nguyenhoangnam2006tq@gmail.com
3 24120260 Trương Tuấn Anh truongtuananh200806@gmail.com
4 24120387 Trần Nhật Nam trannhatnam891@gmail.com
5 24120423 Đỗ Ngọc Tường Quyên dntq0808@gmail.com
6 24120477 Phan Chí Trung phanchitrung01.st@gmail.com

About

No description, website, or topics provided.

Resources

Readme

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages