Hướng dẫn gọi API qua Gateway: Authentication, Tenant, Robot Type, RAG Curriculum¶

Base URL (dev): https://gateway.ihubtech.dev

Ví dụ trong tài liệu này dựng theo kịch bản: tạo tenant riêng cho SH, robot type cho robot trẻ em, và ingest giáo trình tiếng Anh RAG cho trẻ 1-6 tuổi.

---

0. Authentication¶

0.1. Đăng nhập lấy JWT¶

POST /api/v1/auth/login

• Route public (không cần token trước đó) — nằm trong PUBLIC_PATHS của gateway (services/ihub-gateway/apps/gateway/middleware.py:46-59).
• Nội bộ: services/ihub-auth/apps/auth_core/controllers/views.py:140-153.

Header:

X-Tenant-ID: ihubtech_demo_tenant   # optional, mặc định "default_tenant" nếu bỏ trống
Content-Type: application/json

Body:

{
  "email": "superadmin@raas.com",
  "password": "SecurePassword123!",
  "account_type": "ADMIN"
}

• Account được tra bằng tổ hợp email + account_type + tenant_id (views.py:157), không dùng username.
• account_type ∈ ADMIN | PARENT | ROBOT | PARTNER.

Ví dụ curl:

curl -X POST https://gateway.ihubtech.dev/api/v1/auth/login \
  -H "X-Tenant-ID: ihubtech_demo_tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "superadmin@raas.com",
    "password": "SecurePassword123!",
    "account_type": "ADMIN"
  }'

Response 200:

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi...",
  "expires_in_seconds": 28800,
  "account_type": "ADMIN",
  "session_id": "..."
}

Lỗi có thể gặp: 400 (thiếu field), 401 (sai email/password/account_type), 423 (tài khoản bị khóa sau 5 lần sai).

0.2. Tài khoản demo/seed dùng để test (dev only)¶

Mật khẩu chung: SecurePassword123! (packages/ihub-core/ihub_core/demo_fixtures.py:7).
Tenant seed: ihubtech_demo_tenant, truong-anh-sao.

Email	account_type	role_code (DB)	JWT role claim
superadmin@raas.com	ADMIN	ihubtech_super	SUPER_ADMIN (full quyền, kể cả /api/v1/tenants/*)
ihubadmin@raas.com	ADMIN	ihubtech_admin	ADMIN
admin@raas.com	ADMIN	ADMIN_OPERATOR	ADMIN_OPERATOR
robot_ops_demo@raas.com	ADMIN	super_robot_management	super_robot_management
partner_demo@raas.com	PARTNER	PARTNER	PARTNER

→ Dùng superadmin@raas.com để có quyền cao nhất khi test các bước bên dưới (bước tạo tenant yêu cầu đúng role SUPER_ADMIN hoặc super_robot_management).

0.3. JWT claims (để hiểu vì sao một số API trả 404/403)¶

Sinh tại services/ihub-auth/apps/auth_core/controllers/views.py:65-122:

{
  "sub": "<account_id>",
  "email": "superadmin@raas.com",
  "account_type": "ADMIN",
  "tenant_id": "ihubtech_demo_tenant",
  "role": "SUPER_ADMIN",
  "jti": "...",
  "exp": 1234567890,
  "iat": 1234560000
}

Alg HS256. Gateway đọc account_type/role trực tiếp từ claims đã verify (không tin header client gửi lên) để phân quyền route:

• /api/v1/admin/* → yêu cầu account_type == ADMIN.
• /api/v1/tenants/* (tạo/sửa tenant) → yêu cầu role ∈ (SUPER_ADMIN, super_robot_management), sai role trả về 404 (che giấu lỗi quyền).

0.4. Refresh token¶

POST /api/v1/auth/refresh

Body (tuỳ chọn nếu có cookie session ihub_session):

{ "refresh_token": "eyJhbGciOi..." }

Refresh token cũ bị blacklist ngay sau khi dùng (rotation) — không tái sử dụng được.

---

1. Tạo Robot Type cho robot trẻ em¶

Robot Type là catalog toàn nền tảng (global), không phụ thuộc tenant → có thể tạo trước, độc lập với bước tenant.

POST /api/v1/admin/robot-types/

Nội bộ: services/ihub-b4a/apps/b4a/controllers/robot_types.py:61-127.

curl -X POST https://gateway.ihubtech.dev/api/v1/admin/robot-types/ \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "type_code": "windy_kids",
    "name": "Windy Kids Robot",
    "description": "Robot dong hanh hoc tieng Anh cho tre 1-6 tuoi",
    "is_active": true
  }'

• type_code tự động viết hoa → WINDY_KIDS, phải unique toàn hệ thống.
• Yêu cầu JWT account_type == ADMIN.

---

2. Tenant riêng cho SH¶

⚠️ Cảnh báo: POST /api/v1/admin/tenants/ hiện là stub, chỉ validate và echo lại dữ liệu, không lưu DB (services/ihub-b4a/apps/b4a/controllers/tenants.py:81-90, xác nhận bởi test_tenants_stub.py). Không có bảng Tenant nào thực sự được ghi. Trong thực tế tenant_id chỉ là chuỗi khoá phân vùng tự do dùng ở bước RAG (mục 3) và trong JWT claim tenant_id khi tạo account qua ihub-auth.

Gọi cho đủ quy trình (yêu cầu role ∈ SUPER_ADMIN | super_robot_management, nếu không sẽ nhận 404):

curl -X POST https://gateway.ihubtech.dev/api/v1/admin/tenants/ \
  -H "Authorization: Bearer <SUPER_ADMIN_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SH English Center",
    "tenant_type": "PARTNER",
    "plan_code": "pro_plan",
    "robot_quota": 5,
    "contact_email": "admin@sh.example.com"
  }'

Ghi nhớ tenant_id = SH (tự chọn) để dùng nhất quán ở bước 3, và khi tạo account thật cho SH qua ihub-auth (field Account.tenant_id, services/ihub-auth/apps/auth_core/services/registration.py) nếu cần user đăng nhập dưới tenant này.

---

3. Ingest giáo trình tiếng Anh (RAG) cho trẻ 1-6 tuổi¶

POST /api/v1/tenants/{tenant_id}/departments/{department_id}/documents

Nội bộ: services/ihub-ai-api/apps/ai/routers/document_router.py:38-45. department_id là khoá phân vùng tự chọn (không có bảng validate), ví dụ english_kids_1_6.

curl -X POST "https://gateway.ihubtech.dev/api/v1/tenants/SH/departments/english_kids_1_6/documents" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -F "file=@giao_trinh_tienganh_1_6_tuoi.pdf;type=application/pdf"

Giới hạn: PDF ≤100MB, ≤500 trang; chunk_size=512, overlap=100; xử lý bất đồng bộ (arq job).

Response 202:

{
  "success": true,
  "data": {
    "document_id": "...",
    "tenant_id": "SH",
    "department_id": "english_kids_1_6",
    "status": "processing",
    "created_at": "..."
  },
  "error": null
}

Quản lý/theo dõi:

GET    /api/v1/tenants/SH/departments/english_kids_1_6/documents
GET    /api/v1/tenants/SH/departments/english_kids_1_6/documents/{document_id}
POST   /api/v1/tenants/SH/departments/english_kids_1_6/documents/{document_id}/retry
DELETE /api/v1/tenants/SH/departments/english_kids_1_6/documents/{document_id}

---

4. Truy vấn RAG (Windy trả lời từ giáo trình)¶

POST /api/v1/tenants/SH/departments/english_kids_1_6/ask

curl -X POST "https://gateway.ihubtech.dev/api/v1/tenants/SH/departments/english_kids_1_6/ask" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Day be tu vung ve cac loai dong vat",
    "robot_type": "WINDY_KIDS",
    "language": "en"
  }'

AskRequest còn hỗ trợ unit_id, curriculum_activity, curriculum_target_words, curriculum_instruction (tích hợp với CurriculumStateMachine bên ihub-b4r-conversation — state machine đó chỉ điều phối hội thoại, không lưu curriculum).

---

Tóm tắt thứ tự thực hiện¶

1. Login (/api/v1/auth/login) → lấy access_token.
2. Robot Type (/api/v1/admin/robot-types/) — độc lập, không phụ thuộc tenant.
3. Tenant SH — chọn tenant_id = SH, gọi API stub nếu muốn (không bắt buộc về mặt kỹ thuật vì không có ràng buộc khoá ngoại thực sự).
4. Ingest giáo trình RAG (/api/v1/tenants/SH/departments/english_kids_1_6/documents).
5. Query (/api/v1/tenants/SH/departments/english_kids_1_6/ask).

Không có ràng buộc bắt buộc thật sự giữa bước 2/3/4 (tenant API không validate chéo), nhưng nên theo thứ tự trên cho nhất quán nghiệp vụ.