Threads API v2 QA Project Documentation

MODULE 01

Authentication & Session

Completed

Module xác thực chịu trách nhiệm đăng ký, đăng nhập, refresh token, logout, xác minh email, quên mật khẩu và cập nhật hồ sơ cơ bản. QA cần kiểm tra kỹ định dạng email, username, độ dài mật khẩu, token hết hạn, token bị blacklist sau logout và các phản hồi khi thiếu Bearer token.

Registration & Login

Người dùng đăng ký bằng username, email, password và đăng nhập bằng email hoặc username để nhận token pair.

✓ POST /api/v1/auth/register with valid body → 201 + success true + user data
✓ POST /api/v1/auth/register with mismatched confirmPassword → 400 Validation failed
✓ POST /api/v1/auth/login with valid login/password → 200 + token pair in data
✓ POST /api/v1/auth/login with wrong password → 401 Invalid credentials

Token Lifecycle

Access token được kiểm tra qua middleware, refresh token được hash và dùng để tạo token pair mới.

✓ POST /api/v1/auth/refresh-token with valid refresh token → 200 + new token pair
✓ POST /api/v1/auth/logout with valid Bearer + refresh token → 200 Logout success
✓ Reuse blacklisted access token after logout → 401 TOKEN_INVALID
✓ Missing Authorization header on protected route → 401 TOKEN_INVALID

Email & Password Recovery

Luồng email xác minh và đặt lại mật khẩu dùng token, validate schema và queue gửi email nền.

✓ POST /api/v1/auth/forgot-password with valid email → 200 Forgot password success
✓ GET /api/v1/auth/reset-password/validate with valid token → 200 token validation result
✓ POST /api/v1/auth/reset-password with password shorter than 8 → 400 Validation failed
✓ POST /api/v1/auth/verify-email with empty token → 400 Validation failed

Availability & Profile

API kiểm tra email/username và API cập nhật profile hỗ trợ frontend validate dữ liệu trước khi submit.

✓ POST /api/v1/auth/validate/email with valid email → 200 + availability result
✓ POST /api/v1/auth/validate/username with invalid characters → 400 Validation failed
✓ GET /api/v1/auth/me with valid Bearer → 200 + current user profile
✓ POST /api/v1/auth/profile with bio over 500 chars → 400 Validation failed

API Endpoints

Method	Endpoint	Description	Auth	Status
POST	`/api/v1/auth/register`	Đăng ký tài khoản mới, validate username/email/password và trả về dữ liệu user.	No	Done
POST	`/api/v1/auth/login`	Đăng nhập bằng email hoặc username, trả về token pair khi hợp lệ.	No	Done
POST	`/api/v1/auth/forgot-password`	Tạo yêu cầu quên mật khẩu và kích hoạt luồng email đặt lại mật khẩu.	No	Done
POST	`/api/v1/auth/profile`	Cập nhật hồ sơ người dùng hiện tại với name, bio, location, website hoặc avatar.	Bearer	Done
POST	`/api/v1/auth/refresh-token`	Làm mới access token bằng refresh token hợp lệ.	Refresh token	Done
GET	`/api/v1/auth/me`	Lấy thông tin người dùng từ Bearer token hiện tại.	Bearer	Done
POST	`/api/v1/auth/logout`	Đăng xuất, thu hồi refresh token và blacklist access token.	Bearer + refresh token	Done
POST	`/api/v1/auth/resend-verify-email`	Gửi lại email xác minh cho tài khoản đang đăng nhập.	Bearer	Done
POST	`/api/v1/auth/verify-email`	Xác minh email bằng token trong body.	No	Done
POST	`/api/v1/auth/validate/email`	Kiểm tra định dạng và trạng thái tồn tại của email.	No	Done
POST	`/api/v1/auth/validate/username`	Kiểm tra định dạng và trạng thái tồn tại của username.	No	Done
GET	`/api/v1/auth/reset-password/validate`	Kiểm tra token reset password qua query string.	No	Done
POST	`/api/v1/auth/reset-password`	Đặt lại mật khẩu bằng email, token, password và confirmPassword.	No	Done

MODULE 02

Platform Health & Docs

Completed

Module nền tảng cung cấp health check cho uptime monitoring và Swagger UI để QA rà soát contract API. Health endpoint trả về tên service, môi trường và timestamp; Swagger được mount trực tiếp dưới API gateway.

Health Probe

Endpoint kiểm tra tình trạng service dùng cho smoke test, deployment check và monitoring.

✓ GET /api/v1/health → 200 Service is healthy
✓ Response data includes service threads-api-v2, status ok, environment, timestamp
✓ No Authorization header required for health checks

Swagger UI

Swagger UI được serve bởi `swagger-ui-express` để test thủ công các API đã khai báo trong code.

✓ GET /api/v1/docs → Swagger UI loads without authentication
✓ Swagger server list includes local and production base URLs
✓ Tags include Auth, Post, User, Upload, Circle, Admin and integrations

API Endpoints

Method	Endpoint	Description	Auth	Status
GET	`/api/v1/health`	Trả về trạng thái sống của service và metadata runtime.	No	Done
GET	`/api/v1/docs`	Mở Swagger UI cho tài liệu OpenAPI của dự án.	No	Done

MODULE 03

User Profile & Social Graph

Completed

Module user gom các API hồ sơ công khai, mention username, chỉ số karma/badge/status profile, follower/following và friend request. QA cần phân biệt route public, route optional token và route bắt buộc Bearer để kiểm thử dữ liệu theo ngữ cảnh người xem.

Public Profile Lookup

Cho phép lấy profile bằng username và tìm username để mention trong nội dung.

✓ GET /api/v1/users/:username with existing username → 200 + user profile
✓ GET /api/v1/users/:username with unknown username → 404 User not found
✓ GET /api/v1/users/mention?q=a → 200 + username suggestion list
✓ GET /api/v1/users/mention without q → 400 Validation failed

Follower Graph

Theo dõi quan hệ follower/following và thao tác follow/unfollow giữa người dùng.

✓ GET /api/v1/user/:username/followers → 200 + paginated followers
✓ GET /api/v1/user/:username/following → 200 + paginated following
✓ POST /api/v1/user/:username/follower with Bearer → 200 + follow state result
✓ POST /api/v1/user/:username/follower without Bearer → 401 TOKEN_INVALID

Friend Requests

Hỗ trợ gửi, hủy, chấp nhận hoặc từ chối lời mời kết bạn và xem danh sách request.

✓ POST /api/v1/me/:username/friend-requests with Bearer → 200 Send request
✓ PATCH /api/v1/me/friend-requests/:username/accept with isAccept true → 200 processed
✓ PATCH /api/v1/me/friend-requests/:username/cancel → 200 processed
✓ GET /api/v1/me/friend-requests/received → 200 + paginated rows

User Progress

Các API cá nhân trả về karma, badges và status profile cho trải nghiệm gamification.

✓ GET /api/v1/users/me/karma with Bearer → 200 + karma payload
✓ GET /api/v1/users/me/badges with Bearer → 200 + badges payload
✓ GET /api/v1/users/me/status-profile with Bearer → 200 + status profile
✓ Any /users/me route with banned account → 403 USER_BANNED

API Endpoints

Method	Endpoint	Description	Auth	Status
GET	`/api/v1/users/mention`	Tìm username gợi ý theo query `q` để mention.	No	Done
GET	`/api/v1/users/:username`	Lấy hồ sơ người dùng theo username, có thể đọc ngữ cảnh viewer nếu có token.	Optional Bearer	Done
GET	`/api/v1/users/me/karma`	Lấy karma của người dùng hiện tại.	Bearer	Done
GET	`/api/v1/users/me/badges`	Lấy danh sách badge của người dùng hiện tại.	Bearer	Done
GET	`/api/v1/users/me/status-profile`	Lấy trạng thái hồ sơ cá nhân của người dùng hiện tại.	Bearer	Done
GET	`/api/v1/user/:username/followers`	Lấy danh sách follower của username.	No	Done
GET	`/api/v1/user/:username/following`	Lấy danh sách tài khoản mà username đang follow.	No	Done
POST	`/api/v1/user/:username/friend-request`	Gửi lời mời kết bạn đến username từ route social công khai.	Bearer	Done
POST	`/api/v1/user/:username/follower`	Follow hoặc toggle quan hệ follower với username.	Bearer	Done
GET	`/api/v1/me/followers`	Lấy follower của chính người dùng đang đăng nhập.	Bearer	Done
POST	`/api/v1/me/:username/friend-requests`	Gửi lời mời kết bạn đến username từ route cá nhân.	Bearer	Done
PATCH	`/api/v1/me/friend-requests/:username/cancel`	Hủy lời mời kết bạn đã gửi cho username.	Bearer	Done
PATCH	`/api/v1/me/friend-requests/:username/accept`	Chấp nhận hoặc từ chối lời mời kết bạn từ username theo `isAccept`.	Bearer	Done
GET	`/api/v1/me/friend-requests/received`	Lấy danh sách lời mời kết bạn đã nhận.	Bearer	Done
GET	`/api/v1/me/friend-requests/sent`	Lấy danh sách lời mời kết bạn đã gửi.	Bearer	Done

MODULE 04

Upload & Media

Completed

Module upload nhận file bằng multer memory storage, resize ảnh qua middleware shape và lưu lên Cloudflare R2/S3-compatible storage. QA cần kiểm tra field name đúng (`file` cho avatar, `medias` cho post media), giới hạn số lượng media và quyền truy cập với route media.

Avatar Upload

Upload một ảnh avatar, xử lý resize và trả về metadata file đã lưu.

✓ POST /api/v1/upload/avatar with multipart field file → 201 Upload avatar success
✓ Missing file in multipart request → middleware/controller error path is returned
✓ Non-image mime type should be rejected by upload/shape middleware

Post Media Upload

Upload tối đa 5 media cho bài viết và trả về danh sách object để gắn vào post payload.

✓ POST /api/v1/upload/media with Bearer + medias[] → 201 Upload media success
✓ More than 5 files in medias[] → upload middleware rejects request
✓ Missing Bearer token on media upload → 401 TOKEN_INVALID

API Endpoints

Method	Endpoint	Description	Auth	Status
POST	`/api/v1/upload/avatar`	Upload một file avatar bằng multipart field `file`.	No	Done
POST	`/api/v1/upload/media`	Upload tối đa 5 media bằng multipart field `medias`.	Bearer	Done

MODULE 05

Posts, Feed & Interactions

Completed

Module post xử lý news feed, đọc post công khai, tạo bài viết, reply, quote, repost, like, save, hide, report, sửa và xóa post. QA cần kiểm tra cursor pagination, quyền chủ sở hữu khi sửa/xóa, validate content tối đa 5000 ký tự, poll trong post và các side effect bất đồng bộ như sync like hoặc indexing semantic search.

Feed & Read APIs

Các route đọc post hỗ trợ khách hoặc optional token để cá nhân hóa trạng thái like/save.

✓ GET /api/v1/posts/news-feed?take=20 → 200 + pagination
✓ GET /api/v1/posts/:publicId with existing post → 200 Posts retrieved
✓ GET /api/v1/posts/:publicId with unknown post → 404 Post not found
✓ GET /api/v1/posts/user/:username with unknown username → 404 User not found

Create, Reply, Quote & Repost

Người dùng đăng nhập có thể tạo post thường, reply, quote và repost; nội dung được validate bằng Zod.

✓ POST /api/v1/posts with valid content → 201 Post created
✓ POST /api/v1/posts with empty content → 400 Validation failed
✓ POST /api/v1/posts/:publicId/reply → 201 Post created
✓ POST /api/v1/posts/:publicId/quote → 201 Post created

Engagement Actions

Các hành động like, save, hide, report trả về trạng thái rõ ràng để frontend cập nhật UI.

✓ POST /api/v1/posts/:publicId/like with isLiked true → 200 + liked true
✓ POST /api/v1/posts/:publicId/save → 200 + saved true
✓ POST /api/v1/posts/:publicId/hide → 200 + hidden true
✓ POST /api/v1/posts/:publicId/report without reason → 400 Validation failed

Edit, Delete & Search

Post có thể sửa content/visibility, xóa mềm và tìm kiếm bằng query hoặc semantic similarity.

✓ PATCH /api/v1/posts/:publicId with content or visibility → 200 + updated post
✓ PATCH /api/v1/posts/:publicId with empty body → 400 Validation failed
✓ DELETE /api/v1/posts/:publicId by owner → 200 + deleted true
✓ POST /api/v1/posts/:publicId/similar with content/topic → 200 + similar posts

API Endpoints

Method	Endpoint	Description	Auth	Status
GET	`/api/v1/posts/news-feed`	Lấy news feed với cursor pagination và filter type tùy chọn.	Optional Bearer	Done
GET	`/api/v1/posts/search`	Tìm post bằng query `q`, topics, limit và page.	No	Done
GET	`/api/v1/posts/:publicId/replies`	Lấy reply của một post theo publicId.	Optional Bearer	Done
GET	`/api/v1/posts/me`	Lấy post của người dùng đang đăng nhập.	Bearer	Done
GET	`/api/v1/posts/:publicId`	Lấy chi tiết post theo publicId.	Optional Bearer	Done
GET	`/api/v1/posts/user/:username`	Lấy post của một username.	Optional Bearer	Done
GET	`/api/v1/posts/user/:username/replies`	Lấy reply của một username.	Optional Bearer	Done
GET	`/api/v1/posts/user/:username/quotes`	Lấy quote post của một username.	Optional Bearer	Done
POST	`/api/v1/posts/:publicId/similar`	Tìm post tương tự dựa trên content và topic truyền vào body.	No	Done
GET	`/api/v1/posts/:postId/judge-status`	Lấy trạng thái đánh giá/judge của post theo id số.	Bearer	Done
GET	`/api/v1/posts/me/replies`	Lấy reply của người dùng hiện tại.	Bearer	Done
GET	`/api/v1/posts/me/quote`	Lấy quote post của người dùng hiện tại.	Bearer	Done
POST	`/api/v1/posts`	Tạo post mới với content, topic, mentions, media, poll và visibility.	Bearer	Done
POST	`/api/v1/posts/:publicId/reply`	Tạo reply cho post theo publicId.	Bearer	Done
POST	`/api/v1/posts/:publicId/like`	Set trạng thái like/unlike cho post.	Bearer	Done
POST	`/api/v1/posts/:publicId/repost`	Repost một post hiện có.	Bearer	Done
POST	`/api/v1/posts/:publicId/quote`	Tạo quote post kèm content mới.	Bearer	Done
POST	`/api/v1/posts/:publicId/save`	Lưu post vào danh sách cá nhân.	Bearer	Done
POST	`/api/v1/posts/:publicId/hide`	Ẩn post khỏi trải nghiệm của người dùng hiện tại.	Bearer	Done
POST	`/api/v1/posts/:publicId/report`	Báo cáo post/user/circle với reason và type.	Bearer	Done
PATCH	`/api/v1/posts/:publicId`	Cập nhật content hoặc visibility của post.	Bearer	Done
DELETE	`/api/v1/posts/:publicId`	Xóa post theo publicId.	Bearer	Done

MODULE 06

Topics & Search

Completed

Module topic và search phục vụ tìm kiếm post, username, topic và tạo/upsert topic. QA cần kiểm tra query bắt buộc, giới hạn `take` tối đa 100, cursor pagination và sự khác biệt giữa search public `/posts/search` với search có auth dưới `/search`.

Topic Lookup & Upsert

Topic có thể được tìm bằng tên và tạo mới hoặc tăng counter khi submit cùng tên.

✓ GET /api/v1/topic?q=dev → 200 Topics retrieved successfully
✓ GET /api/v1/topic without q → 400 Validation failed
✓ POST /api/v1/topic with name → 201 Topic upserted
✓ POST /api/v1/topic with empty name → 400 Validation failed

Authenticated Search

Search module yêu cầu Bearer để trả kết quả theo ngữ cảnh người dùng.

✓ GET /api/v1/search/posts?q=hello with Bearer → 200 + paginated posts
✓ GET /api/v1/search/posts?take=101 → 400 Validation failed
✓ GET /api/v1/search/username?q=h → 200 + usernames
✓ GET /api/v1/search/topic without Bearer → 401 TOKEN_INVALID

API Endpoints

Method	Endpoint	Description	Auth	Status
POST	`/api/v1/topic`	Tạo hoặc tăng lượt dùng topic theo field `name`.	No	Done
GET	`/api/v1/topic`	Tìm topic theo query `q`.	No	Done
GET	`/api/v1/search/posts`	Tìm post theo query, cursor và serp_type.	Bearer	Done
GET	`/api/v1/search/username`	Tìm username theo query `q`.	Bearer	Done
GET	`/api/v1/search/topic`	Tìm topic theo query `q`.	Bearer	Done

MODULE 07

Circles & Communities

Completed

Module circle quản lý cộng đồng riêng gồm tạo circle, lời mời, join request, thành viên, phân quyền, bài viết trong circle, reply, điểm năng lượng, CPR, sacrifice karma, thống kê và hỗ trợ AI định dạng nội dung. Tất cả route circle yêu cầu Bearer; QA cần kiểm tra quyền owner/admin/member và trạng thái invitation/join request theo từng vai trò.

Circle Discovery & Creation

Người dùng đăng nhập xem danh sách circle, circle đã tham gia, circle sở hữu và tạo circle mới.

✓ GET /api/v1/circle with Bearer → 200 + paginated circle list
✓ POST /api/v1/circle with description shorter than 40 chars → 400 Validation failed
✓ GET /api/v1/circle/:publicId with valid membership context → 200 circle detail
✓ Any /api/v1/circle route without Bearer → 401 Unauthorized

Invitations & Join Requests

Circle hỗ trợ mời user, phản hồi lời mời, gửi join request, duyệt/từ chối request và gửi lại invitation.

✓ POST /api/v1/circle/send-invitation with circleId/userId → 200 invitation sent
✓ POST /api/v1/circle/response-invitation with ACCEPTED → 200 invitation accepted message
✓ POST /api/v1/circle/:publicId/join-request → 200 sent or cancelled state
✓ POST /api/v1/circle/:publicId/manage/join-request/respond with isAccept → 200 response result

Circle Management

Owner/admin quản lý member, role, ban/kick, invitation stats và log chất lượng post.

✓ GET /api/v1/circle/:publicId/manage/members → 200 + paginated members
✓ PATCH /api/v1/circle/:publicId/manage/members/role with role → 200 updated role
✓ POST /api/v1/circle/:publicId/manage/members/ban with expiresAt datetime → 200 banned result
✓ POST /api/v1/circle/:publicId/manage/members/kick without userId → 400 Validation failed

Circle Posts & Runtime Stats

Circle có bài viết riêng, reply, judge status thông qua log, energy, CPR, sacrifice karma và thống kê theo thời gian.

✓ POST /api/v1/circle/:publicId/posts with content → 202 Post accepted for judging
✓ GET /api/v1/circle/:publicId/posts?sort=quality → 200 + paginated circle posts
✓ POST /api/v1/circle/:publicId/cpr with targetComments → 201 CPR session created
✓ POST /api/v1/circle/:publicId/sacrifice with karmaAmount → 200 Karma sacrificed successfully

API Endpoints

Method	Endpoint	Description	Auth	Status
GET	`/api/v1/circle`	Lấy danh sách circle theo cursor và visibility tùy chọn.	Bearer	Done
GET	`/api/v1/circle/me-join`	Lấy các circle mà người dùng hiện tại đã tham gia.	Bearer	Done
GET	`/api/v1/circle/me/owner-circle`	Lấy các circle do người dùng hiện tại sở hữu.	Bearer	Done
GET	`/api/v1/circle/request-invitation`	Lấy danh sách invitation/join request liên quan đến người dùng hiện tại.	Bearer	Done
GET	`/api/v1/circle/invitations/me/:publicId`	Lấy chi tiết invitation của người dùng hiện tại trong một circle.	Bearer	Done
POST	`/api/v1/circle`	Tạo circle mới với name, description, avatarEmoji, visibility và mediaUrls.	Bearer	Done
POST	`/api/v1/circle/send-invitation`	Gửi invitation đến userId cho circleId.	Bearer	Done
POST	`/api/v1/circle/response-invitation`	Chấp nhận hoặc từ chối invitation bằng status ACCEPTED/REJECTED.	Bearer	Done
POST	`/api/v1/circle/:publicId/level-up`	Nâng cấp level circle nếu đủ điều kiện.	Bearer	Done
GET	`/api/v1/circle/:publicId/energy`	Lấy trạng thái energy của circle.	Bearer	Done
GET	`/api/v1/circle/:publicId/user-quantity-post`	Lấy số lượng post của user hiện tại trong circle.	Bearer	Done
GET	`/api/v1/circle/:publicId/manage/exp-log`	Lấy log điểm kinh nghiệm của circle.	Bearer	Done
GET	`/api/v1/circle/:publicId/manage/post-quality-log`	Lấy log chất lượng post của circle.	Bearer	Done
GET	`/api/v1/circle/:publicId/manage/members`	Lấy danh sách member cho màn quản trị circle.	Bearer	Done
PATCH	`/api/v1/circle/:publicId/manage/members/role`	Cập nhật role của member trong circle.	Bearer	Done
POST	`/api/v1/circle/:publicId/manage/members/ban`	Ban member khỏi circle với reason và expiresAt tùy chọn.	Bearer	Done
POST	`/api/v1/circle/:publicId/manage/members/kick`	Kick member khỏi circle.	Bearer	Done
GET	`/api/v1/circle/:publicId/manage/invitations/stats`	Lấy thống kê invitation của circle.	Bearer	Done
GET	`/api/v1/circle/:publicId/manage/invitations`	Lấy danh sách invitation trong màn quản trị circle.	Bearer	Done
GET	`/api/v1/circle/:publicId/manage/join-requests`	Lấy danh sách join request đang chờ duyệt.	Bearer	Done
POST	`/api/v1/circle/:publicId/manage/resend`	Gửi lại invitation theo id invitation.	Bearer	Done
POST	`/api/v1/circle/:publicId/manage/join-request/respond`	Admin/manager duyệt hoặc từ chối join request.	Bearer	Done
POST	`/api/v1/circle/:publicId/send-invitation/manage`	Admin gửi invitation theo username, role và description.	Bearer	Done
POST	`/api/v1/circle/:publicId/posts`	Tạo post trong circle và đưa vào luồng judging.	Bearer	Done
GET	`/api/v1/circle/:publicId/posts`	Lấy danh sách post trong circle theo sort latest hoặc quality.	Bearer	Done
POST	`/api/v1/circle/:publicId/join-request`	Gửi hoặc hủy join request của user hiện tại.	Bearer	Done
POST	`/api/v1/circle/:publicId/join-request/respond-invitation`	User phản hồi invitation/join request bằng isAccept.	Bearer	Done
POST	`/api/v1/circle/:publicId/posts/:postPublicId/reply`	Tạo reply cho post trong circle và đưa vào luồng judging.	Bearer	Done
GET	`/api/v1/circle/:publicId/posts/:postPublicId/replies`	Lấy reply của một post trong circle.	Bearer	Done
POST	`/api/v1/circle/:publicId/cpr`	Tạo CPR session với targetComments.	Bearer	Done
GET	`/api/v1/circle/:publicId/cpr/status`	Lấy trạng thái CPR của circle.	Bearer	Done
POST	`/api/v1/circle/:publicId/sacrifice`	Hy sinh karma cá nhân để hỗ trợ circle.	Bearer	Done
GET	`/api/v1/circle/:publicId/stats`	Lấy thống kê circle theo khoảng 7days, 30days hoặc 90days.	Bearer	Done
GET	`/api/v1/circle/:publicId/members`	Lấy member của circle theo cursor pagination.	Bearer	Done
GET	`/api/v1/circle/:publicId`	Lấy chi tiết circle theo publicId.	Bearer	Done
POST	`/api/v1/circle-ai/generate-response`	Định dạng hoặc hiệu đính content thành Markdown bằng AI cho circle content.	Bearer	Done

MODULE 08

Polls & Quests

Completed

Module poll ghi nhận vote cho survey/poll gắn với post, còn quest quản lý daily quest và claim thưởng karma. QA cần kiểm tra mỗi vote có pollId và pollOptionId hợp lệ, quest code đúng định dạng và không claim trùng khi business rule không cho phép.

Poll Voting

Người dùng đăng nhập chọn một option trong poll, service trả về trạng thái vote đã ghi nhận.

✓ POST /api/v1/polls/:pollId/vote with pollOptionId → 200 Vote created successfully
✓ POST /api/v1/polls/:pollId/vote with non-number pollId → 400 Validation failed
✓ POST /api/v1/polls/:pollId/vote without Bearer → 401 TOKEN_INVALID

Daily Quest Claim

Daily quest hiển thị nhiệm vụ khả dụng và cho phép claim reward theo code.

✓ GET /api/v1/quests/daily with Bearer → 200 Daily quests retrieved successfully
✓ POST /api/v1/quests/:code/claim with valid code → 200 Quest claimed successfully
✓ POST /api/v1/quests/:code/claim with empty code path → route not matched or validation error

API Endpoints

Method	Endpoint	Description	Auth	Status
POST	`/api/v1/polls/:pollId/vote`	Tạo hoặc cập nhật vote của user cho một poll option.	Bearer	Done
GET	`/api/v1/quests/daily`	Lấy danh sách daily quest của user hiện tại.	Bearer	Done
POST	`/api/v1/quests/:code/claim`	Claim reward cho daily quest theo code.	Bearer	Done

MODULE 09

Messaging & Realtime

Completed

Module messaging quản lý nhóm chat, gửi tin nhắn, trạng thái delivery, danh sách member, notification unread và cấp quyền Pusher private channel. QA cần kiểm tra membership của message group trước khi đọc/gửi tin và xác thực channel name đúng với user hoặc group.

Message Groups

Tạo private/crowd group, liệt kê group của user và đọc member trong group.

✓ POST /api/v1/message-groups with type private and members[] → 201 created
✓ POST /api/v1/message-groups with invalid type → 400 Validation failed
✓ GET /api/v1/message-groups → 200 + paginated groups
✓ GET /api/v1/message-groups/:publicId/members as non-member → 403 or Unauthorized path

Messages & Delivery

Tin nhắn yêu cầu content và clientMessageId để chống gửi trùng từ client.

✓ POST /api/v1/message-groups/:publicId/messages with content/clientMessageId → 201 Message sent
✓ POST message with content over 1000 chars → 400 Validation failed
✓ PATCH /api/v1/message-groups/:publicId/messages/:messagePublicId/status with isDelivery true → 200 updated
✓ GET /api/v1/message-groups/:publicId/messages → 200 + paginated messages

Notifications

Notification APIs trả về list notification, trạng thái unread, số group chat chưa đọc và số friend request.

✓ GET /api/v1/notification → 200 + paginated notifications
✓ GET /api/v1/notification/unread → 200 + isNotification boolean
✓ POST /api/v1/notification/read → 200 + isRead true
✓ GET /api/v1/notification/message → 200 + unreadGroupCount

Pusher Private Auth

Pusher auth kiểm tra private channel, socket id và membership trước khi trả signature.

✓ POST /api/v1/pusher/auth with private notification channel for same user → Pusher auth payload
✓ POST /api/v1/pusher/auth with public channel name → 400 Only private channels are supported
✓ POST /api/v1/pusher/auth for inaccessible chat channel → 403 Channel is not accessible

API Endpoints

Method	Endpoint	Description	Auth	Status
GET	`/api/v1/notification`	Lấy danh sách notification của user hiện tại.	Bearer	Done
GET	`/api/v1/notification/unread`	Kiểm tra user có notification chưa đọc hay không.	Bearer	Done
POST	`/api/v1/notification/read`	Đánh dấu notification group là đã đọc.	Bearer	Done
GET	`/api/v1/notification/message`	Lấy số lượng message group chưa đọc.	Bearer	Done
GET	`/api/v1/notification/friend-request`	Lấy số lượng friend request đã nhận.	Bearer	Done
POST	`/api/v1/message-groups`	Tạo message group private hoặc crowd.	Bearer	Done
GET	`/api/v1/message-groups`	Lấy danh sách message group của user.	Bearer	Done
POST	`/api/v1/message-groups/:publicId/messages`	Gửi message vào group theo publicId.	Bearer	Done
PATCH	`/api/v1/message-groups/:publicId/messages/:messagePublicId/status`	Cập nhật trạng thái delivery của message.	Bearer	Done
GET	`/api/v1/message-groups/:publicId/messages`	Lấy tin nhắn trong group theo cursor.	Bearer	Done
GET	`/api/v1/message-groups/:publicId/members`	Lấy danh sách member của group.	Bearer	Done
POST	`/api/v1/pusher/auth`	Cấp quyền subscribe Pusher private channel nếu user hợp lệ.	Bearer	Done

MODULE 10

Museum Archive

Completed

Module museum cung cấp danh sách và chi tiết item lưu trữ theo publicId. Cả hai endpoint đều yêu cầu Bearer token; QA cần kiểm tra query filter, pagination nếu có trong DTO và hành vi khi publicId không tồn tại.

Archive Listing

Người dùng đăng nhập xem danh sách museum theo query đã validate.

✓ GET /api/v1/museum with Bearer → 200 Museum list retrieved successfully
✓ GET /api/v1/museum without Bearer → 401 TOKEN_INVALID
✓ Invalid query values → 400 Validation failed

Archive Detail

Chi tiết museum trả dữ liệu theo publicId đã validate trong params.

✓ GET /api/v1/museum/:publicId with valid id → 200 Museum detail retrieved successfully
✓ GET /api/v1/museum/:publicId with empty segment → route not matched
✓ Unknown publicId should return the service error defined by repository lookup

API Endpoints

Method	Endpoint	Description	Auth	Status
GET	`/api/v1/museum`	Lấy danh sách item museum theo query.	Bearer	Done
GET	`/api/v1/museum/:publicId`	Lấy chi tiết một item museum theo publicId.	Bearer	Done

MODULE 11

AI & Webhooks

Completed

Module integration gồm tạo job image AI qua Leonardo/OpenRouter flow và nhận webhook từ HLS/Leonardo để cập nhật trạng thái media hoặc generation metadata. QA cần kiểm tra bảo mật webhook bằng header, xử lý event không hỗ trợ và payload trả về khi job được tạo.

Image Generation Job

Người dùng đăng nhập gửi content để tạo image generation job; response không trả các field cost nhạy cảm.

✓ POST /api/v1/ai/generate-image with content → 200 Image generation job created
✓ Response data.sdGenerationJob does not expose apiCreditCost or cost
✓ Missing Bearer token → 401 TOKEN_INVALID
✓ Missing content → 400 Validation failed

HLS Media Webhook

Webhook HLS xác thực bằng `x-webhook-signature` và cập nhật status media theo event ready, errored hoặc deleted.

✓ POST /api/v1/webhooks/hls with valid signature and video.asset.ready → 200 Webhook received
✓ Missing x-webhook-signature → 400 Missing signature
✓ Invalid x-webhook-signature → 401 Invalid signature
✓ Unsupported event type → 200 with empty response body

Leonardo Webhook

Webhook Leonardo xác thực bằng Bearer hoặc `x-leonardo-webhook-api-key`, cập nhật generation metadata và phát Pusher event.

✓ POST /api/v1/webhooks/leonardo with valid key → 200 Leonardo webhook received
✓ Invalid Leonardo key → 401 Invalid webhook key
✓ Payload object other than generation → 200 + received true

API Endpoints

Method	Endpoint	Description	Auth	Status
POST	`/api/v1/ai/generate-image`	Tạo job sinh ảnh từ content của user hiện tại.	Bearer	Done
POST	`/api/v1/webhooks/hls`	Nhận webhook HLS để cập nhật trạng thái media video.	x-webhook-signature	Done
POST	`/api/v1/webhooks/leonardo`	Nhận webhook Leonardo để cập nhật metadata generation và trigger realtime event.	Webhook key	Done

MODULE 12

Admin Operations

Completed

Module admin cung cấp đăng nhập admin, quản lý user ban/unban, report moderation, trending hashtag, dashboard statistics và daily quest. Ngoại trừ `/admin/login`, các route admin đều đi qua authorization và `checkRole(UserRoleType.ADMIN)`, nên QA cần kiểm tra cả token hợp lệ và role admin.

Admin Login & User Controls

Admin đăng nhập bằng credential hợp lệ và quản lý trạng thái ban của user.

✓ POST /api/v1/admin/login with admin credentials → 200 + token pair
✓ GET /api/v1/admin/users with admin Bearer → 200 + paginated users
✓ PATCH /api/v1/admin/users/:userId/ban with durationHours → 200 banned result
✓ Non-admin Bearer on /api/v1/admin/users → 403 Forbidden

Report Moderation

Admin xem danh sách report, xem chi tiết và xử lý report bằng action hợp lệ.

✓ GET /api/v1/admin/reports?type=post → 200 + paginated reports
✓ GET /api/v1/admin/reports/:reportId → 200 Report details retrieved successfully
✓ PATCH /api/v1/admin/reports/:reportId with action → 200 Report moderated successfully
✓ PATCH report with invalid action → 400 Validation failed

Dashboard & Trends

Admin lấy số liệu tổng quan và hashtag trending phục vụ CMS/dashboard.

✓ GET /api/v1/admin/stats with admin Bearer → 200 Admin statistics retrieved successfully
✓ GET /api/v1/admin/hashtags/trending → 200 + paginated hashtags
✓ Invalid page or limit query → 400 Validation failed

Daily Quest Administration

Admin tạo, liệt kê, xem action options và disable daily quest theo code.

✓ POST /api/v1/admin/daily-quests with valid payload → 201 Daily quest created successfully
✓ GET /api/v1/admin/daily-quests/actions → 200 Daily quest actions retrieved successfully
✓ GET /api/v1/admin/daily-quests → 200 + paginated daily quests
✓ PATCH /api/v1/admin/daily-quests/:code/disable → 200 Daily quest disabled successfully

API Endpoints

Method	Endpoint	Description	Auth	Status
POST	`/api/v1/admin/login`	Đăng nhập admin và trả về token khi credential hợp lệ.	No	Done
GET	`/api/v1/admin/users`	Lấy danh sách user cho CMS admin.	Bearer + Admin role	Done
PATCH	`/api/v1/admin/users/:userId/ban`	Ban user trong khoảng thời gian `durationHours`.	Bearer + Admin role	Done
PATCH	`/api/v1/admin/users/:userId/unban`	Gỡ ban user.	Bearer + Admin role	Done
PATCH	`/api/v1/admin/users/:userId/ban-unlimited`	Ban user vô thời hạn.	Bearer + Admin role	Done
GET	`/api/v1/admin/reports`	Lấy danh sách report theo type/status và pagination.	Bearer + Admin role	Done
GET	`/api/v1/admin/reports/:reportId`	Lấy chi tiết một report.	Bearer + Admin role	Done
PATCH	`/api/v1/admin/reports/:reportId`	Moderate report bằng action và adminNote tùy chọn.	Bearer + Admin role	Done
GET	`/api/v1/admin/hashtags/trending`	Lấy danh sách hashtag trending cho admin.	Bearer + Admin role	Done
GET	`/api/v1/admin/stats`	Lấy số liệu dashboard tổng quan.	Bearer + Admin role	Done
POST	`/api/v1/admin/daily-quests`	Tạo daily quest mới.	Bearer + Admin role	Done
GET	`/api/v1/admin/daily-quests/actions`	Lấy danh sách action type hợp lệ cho daily quest.	Bearer + Admin role	Done
GET	`/api/v1/admin/daily-quests`	Lấy danh sách daily quest trong CMS admin.	Bearer + Admin role	Done
PATCH	`/api/v1/admin/daily-quests/:code/disable`	Disable daily quest theo code.	Bearer + Admin role	Done

QA Project Documentation

System Architecture Map

Authentication & Session

API Endpoints

Platform Health & Docs

API Endpoints

User Profile & Social Graph

API Endpoints

Upload & Media

API Endpoints

Posts, Feed & Interactions

API Endpoints

Topics & Search

API Endpoints

Circles & Communities

API Endpoints

Polls & Quests

API Endpoints

Messaging & Realtime

API Endpoints

Museum Archive

API Endpoints

AI & Webhooks

API Endpoints

Admin Operations

API Endpoints