admin/goodgo-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7cb12be97f0898ff815e29f2c38afd3695b3141b
goodgo-platform/docs/api-endpoints.md
Ho Ngoc Hai d8b409a9ab
Some checks failed
CI / Lint → Typecheck → Test → Build (22) (push) Failing after 18s
Details
CI / E2E Tests (push) Has been skipped
Details
CodeQL Analysis / CodeQL (javascript-typescript) (push) Failing after 2m15s
Details
Deploy / Build API Image (push) Failing after 28s
Details
Deploy / Build Web Image (push) Failing after 16s
Details
Deploy / Build AI Services Image (push) Failing after 17s
Details
E2E Tests / Playwright E2E (push) Failing after 31s
Details
Security Scanning / Dependency Audit (pnpm) (push) Failing after 3s
Details
Security Scanning / Trivy Scan — API Image (push) Failing after 1m46s
Details
Security Scanning / Trivy Scan — Web Image (push) Failing after 1m7s
Details
Security Scanning / Trivy Scan — AI Services Image (push) Failing after 53s
Details
Security Scanning / Trivy Filesystem Scan (push) Failing after 35s
Details
Deploy / Deploy to Staging (push) Has been skipped
Details
Deploy / Smoke Test Staging (push) Has been skipped
Details
Deploy / Deploy to Production (push) Has been skipped
Details
Deploy / Smoke Test Production (push) Has been skipped
Details
Security Scanning / Security Gate (push) Failing after 0s
Details
Deploy / Rollback Staging (push) Has been skipped
Details
Deploy / Rollback Production (push) Has been skipped
Details
docs: dịch 22 file Markdown còn lại sang tiếng Việt có dấu (TEC-2881) 
Hoàn tất đợt cuối của nhiệm vụ chuyển toàn bộ tài liệu sang tiếng Việt.
Đã dịch 22 file `.md` còn sót (~9.7k dòng) — gồm RUNBOOK, audits,
docs/architecture, docs/load-testing, libs READMEs và các quick references.
Giữ nguyên code blocks, đường dẫn, identifier kỹ thuật, URL và biến môi trường.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-04-19 03:26:14 +07:00

253 lines
10 KiB
Markdown
Raw Blame History

# Tham Khảo API Endpoint
Tất cả route được prefix với `/api/v1/` ngoại trừ health check. Authentication dùng Bearer JWT token.
> **Tài liệu tương tác**: Swagger UI có sẵn tại `http://localhost:3001/api/v1/docs` khi chạy API local.
## Auth (`/auth`)
| Method | Path | Auth | Mô tả |
|--------|------|------|-------------|
| POST | `/auth/register` | Public | Đăng ký user mới |
| POST | `/auth/login` | Public | Đăng nhập bằng số điện thoại và mật khẩu |
| POST | `/auth/refresh` | Cookie | Làm mới access token bằng cookie refresh httpOnly |
| POST | `/auth/logout` | JWT | Đăng xuất và xóa cookie auth |
| POST | `/auth/exchange-token` | Public | Trao đổi cặp token OAuth lấy cookie httpOnly |
| GET | `/auth/profile` | JWT | Lấy hồ sơ user hiện tại |
| GET | `/auth/profile/agent` | JWT | Lấy hồ sơ agent của user hiện tại |
| PATCH | `/auth/kyc` | Admin | Verify trạng thái KYC của user |
### OAuth
| Method | Path | Auth | Mô tả |
|--------|------|------|-------------|
| GET | `/auth/google` | Public | Khởi tạo đăng nhập Google OAuth2 |
| GET | `/auth/google/callback` | Public | Callback Google OAuth2 |
| GET | `/auth/zalo` | Public | Khởi tạo đăng nhập Zalo OAuth2 |
| GET | `/auth/zalo/callback` | Public | Callback Zalo OAuth2 |
### Dữ Liệu User (GDPR)
| Method | Path | Auth | Mô tả |
|--------|------|------|-------------|
| DELETE | `/users/me` | JWT | Yêu cầu xóa tài khoản (thời hạn 30 ngày) |
| POST | `/users/me/cancel-deletion` | JWT | Hủy yêu cầu xóa tài khoản đang chờ |
| GET | `/users/me/export` | JWT | Export dữ liệu user (GDPR Điều 20) |
| DELETE | `/users/:id/force` | Admin | Force-delete user ngay lập tức |
---
## Listings (`/listings`)
| Method | Path | Auth | Mô tả |
|--------|------|------|-------------|
| POST | `/listings` | JWT + Quota | Tạo tin đăng bất động sản mới |
| GET | `/listings` | Public | Tìm kiếm và lọc tin đăng |
| GET | `/listings/pending` | Admin | Lấy tin đăng đang chờ duyệt |
| GET | `/listings/:id` | Public | Lấy chi tiết tin đăng theo ID |
| PATCH | `/listings/:id/status` | JWT | Cập nhật trạng thái tin đăng |
| POST | `/listings/:id/media` | JWT | Upload media (multipart file upload) |
| PATCH | `/listings/:id/moderate` | Admin | Duyệt một tin đăng |
---
## Search (`/search`)
| Method | Path | Auth | Mô tả |
|--------|------|------|-------------|
| GET | `/search` | Public | Tìm kiếm bất động sản full-text và faceted |
| GET | `/search/geo` | Public | Tìm kiếm theo bán kính địa lý |
| POST | `/search/reindex` | Admin | Reindex tất cả bất động sản trong Typesense |
### Saved Search (`/saved-searches`)
| Method | Path | Auth | Mô tả |
|--------|------|------|-------------|
| POST | `/saved-searches` | JWT | Lưu bộ lọc tìm kiếm |
| GET | `/saved-searches` | JWT | Liệt kê các tìm kiếm đã lưu |
| GET | `/saved-searches/:id` | JWT | Lấy chi tiết tìm kiếm đã lưu |
| PATCH | `/saved-searches/:id` | JWT | Cập nhật tìm kiếm đã lưu |
| DELETE | `/saved-searches/:id` | JWT | Xóa tìm kiếm đã lưu |
---
## Payments (`/payments`)
| Method | Path | Auth | Mô tả |
|--------|------|------|-------------|
| POST | `/payments` | JWT | Tạo thanh toán mới |
| GET | `/payments` | JWT | Liệt kê giao dịch của user đã xác thực |
| GET | `/payments/:id` | JWT | Lấy trạng thái thanh toán theo ID |
| POST | `/payments/:id/refund` | Admin | Hoàn tiền một thanh toán |
| POST | `/payments/callback/:provider` | Public | Webhook nhà cung cấp thanh toán (VNPay, MoMo, ZaloPay) |
---
## Subscriptions (`/subscriptions`)
| Method | Path | Auth | Mô tả |
|--------|------|------|-------------|
| GET | `/subscriptions/plans` | Public | Liệt kê tất cả plan subscription |
| GET | `/subscriptions/plans/:tier` | Public | Lấy plan subscription theo tier |
| POST | `/subscriptions` | JWT | Tạo subscription mới |
| PUT | `/subscriptions/upgrade` | JWT | Nâng cấp subscription hiện tại |
| DELETE | `/subscriptions` | JWT | Hủy subscription đang hoạt động |
| POST | `/subscriptions/usage` | JWT | Ghi nhận lượng sử dụng metered |
| GET | `/subscriptions/quota/:metric` | JWT | Kiểm tra quota còn lại theo metric |
| GET | `/subscriptions/billing` | JWT | Lấy lịch sử thanh toán |
---
## Admin (`/admin`)
### Quản Lý User
| Method | Path | Auth | Mô tả |
|--------|------|------|-------------|
| GET | `/admin/users` | Admin | Liệt kê user với bộ lọc tùy chọn |
| GET | `/admin/users/:id` | Admin | Lấy chi tiết user theo ID |
| PATCH | `/admin/users/status` | Admin | Cập nhật trạng thái active của user |
| POST | `/admin/users/ban` | Admin | Ban hoặc unban user |
| POST | `/admin/subscriptions/adjust` | Admin | Điều chỉnh plan subscription của user |
| GET | `/admin/dashboard` | Admin | Lấy thống kê dashboard admin |
| GET | `/admin/revenue` | Admin | Lấy thống kê doanh thu theo khoảng ngày |
| GET | `/admin/audit-logs` | Admin | Lấy audit log admin |
### Moderation
| Method | Path | Auth | Mô tả |
|--------|------|------|-------------|
| GET | `/admin/moderation` | Admin | Lấy hàng đợi duyệt tin đăng |
| POST | `/admin/moderation/approve` | Admin | Duyệt một tin đăng |
| POST | `/admin/moderation/reject` | Admin | Từ chối một tin đăng |
| POST | `/admin/moderation/bulk` | Admin | Duyệt hoặc từ chối tin đăng hàng loạt |
| GET | `/admin/kyc` | Admin | Lấy hàng đợi xác minh KYC |
| POST | `/admin/kyc/approve` | Admin | Duyệt xác minh KYC |
| POST | `/admin/kyc/reject` | Admin | Từ chối xác minh KYC |
---
## Notifications (`/notifications`)
| Method | Path | Auth | Mô tả |
|--------|------|------|-------------|
| GET | `/notifications/history` | JWT | Lấy lịch sử thông báo |
| GET | `/notifications/preferences` | JWT | Lấy tùy chọn thông báo |
| PUT | `/notifications/preferences` | JWT | Cập nhật tùy chọn thông báo |
| GET | `/notifications/unread` | JWT | Lấy thông báo chưa đọc |
| PATCH | `/notifications/:id/read` | JWT | Đánh dấu thông báo đã đọc |
| PATCH | `/notifications/read-all` | JWT | Đánh dấu tất cả thông báo đã đọc |
| GET | `/notifications/templates` | JWT | Lấy các template thông báo có sẵn |
---
## Analytics (`/analytics`)
Tất cả endpoint analytics yêu cầu JWT và được giới hạn theo quota.
| Method | Path | Auth | Mô tả |
|--------|------|------|-------------|
| GET | `/analytics/market-report` | JWT + Quota | Lấy báo cáo thị trường cho một thành phố |
| GET | `/analytics/price-trend` | JWT + Quota | Lấy xu hướng giá cho một quận |
| GET | `/analytics/heatmap` | JWT + Quota | Lấy heatmap giá cho một thành phố |
| GET | `/analytics/district-stats` | JWT + Quota | Lấy thống kê theo quận |
| GET | `/analytics/valuation` | JWT + Quota | Lấy định giá bất động sản tự động (AVM) |
---
## Agents (`/agents`)
| Method | Path | Auth | Mô tả |
|--------|------|------|-------------|
| GET | `/agents/me/dashboard` | Agent | Lấy thống kê dashboard agent |
| POST | `/agents/:agentId/recalculate-score` | Admin | Tính lại điểm chất lượng agent |
---
## Inquiries (`/inquiries`)
| Method | Path | Auth | Mô tả |
|--------|------|------|-------------|
| POST | `/inquiries` | JWT | Tạo inquiry cho một tin đăng |
| GET | `/inquiries/listing/:listingId` | JWT | Liệt kê inquiry theo tin đăng |
| GET | `/inquiries/agent/me` | Agent | Liệt kê inquiry cho agent hiện tại |
| PATCH | `/inquiries/:id/read` | Agent | Đánh dấu inquiry đã đọc |
---
## Leads (`/leads`)
| Method | Path | Auth | Mô tả |
|--------|------|------|-------------|
| POST | `/leads` | Agent | Tạo lead |
| GET | `/leads` | Agent | Liệt kê lead cho agent |
| GET | `/leads/stats` | Agent | Lấy thống kê lead |
| PATCH | `/leads/:id/status` | Agent | Cập nhật trạng thái lead |
| DELETE | `/leads/:id` | Agent | Xóa lead |
---
## Reviews (`/reviews`)
| Method | Path | Auth | Mô tả |
|--------|------|------|-------------|
| POST | `/reviews` | JWT | Tạo một review |
| GET | `/reviews` | Public | Liệt kê review theo target |
| GET | `/reviews/stats` | Public | Lấy thống kê đánh giá tổng hợp cho một target |
| GET | `/reviews/me` | JWT | Lấy review của user đã xác thực |
| DELETE | `/reviews/:id` | JWT | Xóa review của chính mình |
---
## Health (`/health`)
Endpoint health **không** prefix với `/api/v1/`.
| Method | Path | Auth | Mô tả |
|--------|------|------|-------------|
| GET | `/health` | Public | Liveness probe |
| GET | `/health/ready` | Public | Readiness probe (DB + Redis) |
| GET | `/health/db` | Public | Kiểm tra kết nối database |
| GET | `/health/redis` | Public | Kiểm tra kết nối Redis |
---
## MCP (`/mcp`)
| Method | Path | Auth | Mô tả |
|--------|------|------|-------------|
| GET | `/mcp/servers` | JWT | Liệt kê các MCP server có sẵn |
| GET | `/mcp/:serverName/sse` | JWT | Mở kết nối SSE đến MCP server |
| POST | `/mcp/:serverName/messages` | JWT | Gửi message tới session MCP server |
---
## Metrics
| Method | Path | Auth | Mô tả |
|--------|------|------|-------------|
| POST | `/web-vitals` | Public | Ingest metric Core Web Vitals |
---
## Tóm Tắt Authentication
| Loại Auth | Mô tả |
|-----------|-------------|
| **Public** | Không yêu cầu authentication |
| **JWT** | Yêu cầu header `Authorization: Bearer <token>` |
| **Admin** | JWT + role `ADMIN` |
| **Agent** | JWT + role `AGENT` |
| **Quota** | JWT + giới hạn quota subscription |
| **Cookie** | Dùng cookie refresh token httpOnly |
## Rate Limiting
Các endpoint sau có rate limit nghiêm ngặt hơn:
- Endpoint Auth (register, login, refresh): `10 req/60s`
- OAuth callback: `10 req/60s`
- Payment callback: `60 req/60s`
- Endpoint MCP: `30 req/60s`
- Mặc định: `60 req/60s`
Reference in New Issue View Git Blame Copy Permalink