Bạn Cóc is an assistant for FPT University students. It lets students ask natural-language questions about their own FAP data, curriculum, syllabus, and receive notifications when schedules, attendance, marks, or exam information change.
FAP remains the source of truth for personal academic records. The assistant only reads private FAP data belonging to the linked Zalo user.
- Natural-language FAP queries for semesters, class schedules, attendance, marks, exam schedules, and activity scores
- Curriculum and syllabus Q&A powered by
flm-rag - Private FeID account linking with
/login, account inspection with/me, and durable remote revocation with/logout - Opt-in academic notifications and class/exam reminders with
/notify on - Queue-first message processing with per-conversation ordering and input coalescing
- Transactional outbox delivery for recoverable assistant replies and proactive notifications
- Google Gemini and OpenAI-compatible chat model providers
- Encrypted FAP credentials, FeID refresh tokens, PKCE verifiers, and sensitive callback payloads
- Optional authenticated Bull Board dashboard for queue inspection
- NestJS 11 and TypeScript
- PostgreSQL and TypeORM
- BullMQ with two Redis instances
- LangChain
- Google Gemini or an OpenAI-compatible provider
zalo-bot-jsfap-sdk
- Node.js 22 or newer
- pnpm 11 or newer
- PostgreSQL
- Docker with Docker Compose, or two independently managed Redis instances
- A Zalo Bot token
- A Gemini API key or an OpenAI-compatible API key
| Command | Description |
|---|---|
/help |
List available commands |
/login <campusCode> |
Link the user's FAP account through FeID |
/me |
Show the currently linked FAP profile |
/notify <on|off> |
Enable or disable proactive notifications |
/logout |
Disconnect the account and revoke the FeID session |
Supported campus codes are APHL, HCM, DN, CT, and QN. Account commands and FeID callback submission are restricted to private chats.
To link an account, send /login <campusCode> in a private chat, open the returned FeID authorization URL, complete the login, then paste the full redirect URL back into the same private chat.
Opted-in users can receive:
- class schedule and exam schedule changes
- attendance confirmations
- newly published or changed marks
- class reminders 24 hours and 2 hours before a class block
- exam reminders 72 hours and 2 hours before an exam
Background processors persist change events before delivery. A notification remains recoverable through PostgreSQL even if a queue worker restarts between detection and sending.
- FAP tools are bound server-side to the verified sender; tool schemas do not accept a user ID, roll number, or arbitrary credential.
- FAP credentials, refresh tokens, PKCE verifiers, and FeID callback URLs are encrypted with AES-256-GCM and contextual additional authenticated data.
- Queue payloads contain identifiers and minimal routing metadata, not plaintext credentials or full FAP payloads.
- The LLM receives only the context and tool results needed to answer the current user's request.
- Login, account inspection, logout, and callback completion are private-chat-only.
- Proactive notifications require an active FAP session and explicit user opt-in.
- PostgreSQL cursor checks, conditional delivery claims, and deterministic queue jobs provide ordering and idempotency boundaries.
The delivery model is intentionally at least once. If Zalo accepts a message immediately before a worker crashes, a retry may produce a duplicate rather than silently lose the notification.
MIT