Yimaru-BackEnd/docs/HUMAN_LANGUAGE_MOBILE_INTEGRATION_GUIDE.md

Human Language Mobile Integration Guide

This guide explains how to integrate the new Human Language feature in the Yimaru learner mobile app (not admin).

It is designed to keep the existing non-language hierarchy intact while introducing a dedicated CEFR-based flow for language learning.

---

1) Scope and Goals

What is new

• A dedicated backend API namespace for Human Language:
  • GET /api/v1/course-management/human-language/courses/:courseId/lessons?cefr_level=A1..C3
  • POST /api/v1/course-management/human-language/lessons (admin/instructor side)
  • PATCH /api/v1/course-management/human-language/lessons/:id (admin/instructor side)
• CEFR levels are fixed to:
  • A1, A2, A3, B1, B2, B3, C1, C2, C3
• No custom sub-levels in Human Language flow.

What remains unchanged

• Existing non-human-language content hierarchy and APIs.
• Existing course/category/sub-course endpoints for non-language domains (programming, etc.).

---

2) Target Hierarchy for Human Language

• Course Category (Human Language)
  • Course (e.g., English)
    • CEFR Lesson Unit (A1..C3 only)
      • Intro/lesson videos
      • Practices
        • Audio questions

Backend implementation stores CEFR lesson units using the existing sub-course model, with CEFR mapped internally and validated strictly.

---

3) Authentication and Access

All Human Language endpoints are under /api/v1 and require bearer token auth.

• Header:
  • Authorization: Bearer <access_token>

Permission notes

• Learner mobile app typically needs only the GET endpoint.
• POST and PATCH are content-management endpoints and should generally be used by admin/instructor clients, not learner clients.

If learner roles do not currently have learning_tree.get, coordinate RBAC assignment for read-only access to the GET endpoint.

---

4) Endpoint Contracts

4.1 Fetch lessons by CEFR level (learner-facing)

Request

GET /api/v1/course-management/human-language/courses/{courseId}/lessons?cefr_level={A1|A2|A3|B1|B2|B3|C1|C2|C3}

Example

GET /api/v1/course-management/human-language/courses/12/lessons?cefr_level=B1

Response (success)

{
  "message": "Human-language lessons retrieved successfully",
  "data": {
    "course_id": 12,
    "course_title": "English",
    "cefr_level": "B1",
    "lessons": [
      {
        "id": 201,
        "course_id": 12,
        "title": "B1 Module 1",
        "description": "Intermediate conversational patterns",
        "thumbnail": "https://.../thumb.jpg",
        "display_order": 1,
        "level": "B1",
        "video_count": 3,
        "practice_count": 2,
        "videos": [
          {
            "id": 9001,
            "title": "B1 Intro",
            "description": "Lesson intro",
            "video_url": "https://...",
            "duration": 420,
            "resolution": "1080p",
            "display_order": 1
          }
        ],
        "practices": [
          {
            "id": 4401,
            "title": "B1 Speaking Practice",
            "status": "PUBLISHED",
            "question_count": 10
          }
        ]
      }
    ]
  },
  "success": true,
  "status_code": 200,
  "metadata": null
}

Validation errors

• Invalid CEFR level:
  • 400 with error message: Use one of: A1,A2,A3,B1,B2,B3,C1,C2,C3
• Course not in human language category:
  • 400 with error message indicating invalid human-language course.

---

4.2 Create Human Language lesson unit (admin/instructor)

Request

POST /api/v1/course-management/human-language/lessons

{
  "course_id": 12,
  "title": "A2 Module 1",
  "description": "A2 speaking fundamentals",
  "thumbnail": "https://...",
  "display_order": 1,
  "cefr_level": "A2"
}

Response

Returns created lesson metadata with CEFR-normalized level behavior.

---

4.3 Update Human Language lesson unit (admin/instructor)

Request

PATCH /api/v1/course-management/human-language/lessons/{lessonId}

{
  "title": "A2 Module 1 - Updated",
  "description": "Updated description",
  "cefr_level": "A3",
  "is_active": true
}

---

5) Recommended Mobile App Integration Flow

Step 1: Discover courses under Human Language category

Use existing endpoints:

1. GET /course-management/categories
2. Pick category where name indicates human language.
3. GET /course-management/categories/:categoryId/courses

Step 2: Select CEFR level in UI

Use static list in app:

• A1, A2, A3, B1, B2, B3, C1, C2, C3

Do not allow custom levels in mobile UI.

Step 3: Fetch lessons by selected CEFR level

Call:

• GET /course-management/human-language/courses/:courseId/lessons?cefr_level=<selected>

Render grouped lessons with nested videos/practices from response.

Step 4: Navigate to learning/practice screens

• Lesson video playback uses returned videos[].
• Practice entry uses returned practices[] IDs and existing practice-question endpoints.

---

6) Mobile UI/UX Recommendations

• Use CEFR tabs/segmented control (A1...C3) at top.
• Cache last selected level per course.
• Show empty state per level:
  • "No lessons available for this level yet."
• Sort by display_order and maintain backend order.
• Show badges:
  • video count
  • practice count

---

7) Error Handling and Resilience

• 400 invalid level: reset selection to previous valid CEFR value and show toast/snackbar.
• 401/403: trigger token refresh / re-login flow.
• 5xx: show retry UI with exponential backoff.
• If category/course fetch succeeds but level fetch fails, keep course visible and allow manual retry.

---

8) Data Model Mapping (Mobile DTO)

Suggested DTO for learner app:

type CefrLevel = "A1"|"A2"|"A3"|"B1"|"B2"|"B3"|"C1"|"C2"|"C3";

interface HumanLanguageLessonDTO {
  id: number;
  courseId: number;
  title: string;
  description?: string;
  thumbnail?: string;
  order: number;
  level: CefrLevel;
  videoCount: number;
  practiceCount: number;
  videos: {
    id: number;
    title: string;
    url: string;
    duration: number;
    order: number;
  }[];
  practices: {
    id: number;
    title: string;
    status: string;
    questionCount: number;
  }[];
}

---

9) Backward Compatibility

• Existing non-language content (programming and other categories) continues to use current APIs and hierarchy unchanged.
• New Human Language endpoint is additive and isolated.
• Mobile app can progressively enable the new flow for language categories only.

---

10) QA Checklist for Mobile Team

• Category discovery correctly identifies Human Language category.
• CEFR selector only allows A1..C3.
• Fetch by CEFR level returns only matching lessons.
• Video/practice counts match rendered lists.
• Empty-level state works.
• Unauthorized/session-expired flow works.
• Non-language courses still load via existing app flow.

---

11) Example Call Matrix

• Load language categories/courses:
  • GET /course-management/categories
  • GET /course-management/categories/:id/courses
• Load A1 lessons:
  • GET /course-management/human-language/courses/:courseId/lessons?cefr_level=A1
• Load B2 lessons:
  • GET /course-management/human-language/courses/:courseId/lessons?cefr_level=B2

---

For backend ownership questions, refer to:

• internal/web_server/handlers/course_management.go
• internal/web_server/routes.go