@hed-hog/lms 0.0.306 → 0.0.310

package/hedhog/frontend/app/courses/[id]/structure/_data/adapters/course-structure.adapter.ts.ejs

@@ -0,0 +1,347 @@
+/**
+ * Adapter — LMS Course Structure
+ *
+ * Converts between backend API shapes (Portuguese field names) and the
+ * frontend domain types used by the Zustand store and UI components.
+ *
+ * This is the ONLY place where field-name translation happens.
+ *
+ * ⚠️ ADAPTER POINTS — read before changing:
+ *   • If the backend renames a field → update the corresponding function here.
+ *   • If the backend changes a type  → update the cast/conversion here.
+ *   • The store and UI components must NEVER import from api-course.types.ts
+ *     directly; they always receive the normalised frontend types.
+ *
+ * ⚠️ KNOWN MISMATCHES (documented with inline comments):
+ *   1. exameVinculado (number) ↔ linkedExam (string) — converted with String()/Number()
+ *   2. 'exercicio' tipo — exists in backend and is now part of frontend LessonType.
+ *   3. Session.order — not returned by API; inferred from sorted array position.
+ *   4. Session.visibility / published — not in DB schema; defaulted to safe values.
+ *   5. Lesson.status / visibility — not in DB schema; left undefined.
+ *   6. Resource.size / url — not returned by API; left as empty string / undefined.
+ */
+
+import type {
+  Course,
+  Lesson,
+  LessonFormValues,
+  LessonInstructor,
+  LessonType,
+  Resource,
+  Session,
+  SessionFormValues,
+} from '../../_components/types';
+
+// Alias to keep internal adapter code concise when mapping resources.
+type LessonResourceInput = Resource;
+
+import type {
+  ApiCourse,
+  ApiCreateLessonPayload,
+  ApiCreateSessionPayload,
+  ApiGetStructureResponse,
+  ApiLesson,
+  ApiLessonResource,
+  ApiSession,
+  ApiUpdateLessonPayload,
+  ApiUpdateSessionPayload,
+} from '../types/api-course.types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Map backend lesson type to the frontend LessonType union.
+ *
+ * ⚠️ ADAPTER POINT:
+ *   'exercicio' is now part of the frontend LessonType union.
+ */
+function normalizeLessonType(tipo: ApiLesson['tipo']): LessonType {
+  return tipo as LessonType;
+}
+
+/** Normalize a raw API resource to the frontend Resource shape. */
+function normalizeResource(raw: ApiLessonResource): Resource {
+  return {
+    id: String(raw.id),
+    name: raw.nome,
+    type: raw.tipo ?? '',
+    /**
+     * ⚠️ BACKEND NOTE: file size is not returned in the API response.
+     * TODO[BACKEND]: Include `size` in the lesson resource response from
+     * CourseStructureService.getLessonById().
+     */
+    size: '',
+    public: raw.publico,
+    /**
+     * ⚠️ BACKEND NOTE: a pre-signed or static URL is not returned.
+     * TODO[BACKEND]: Include a resolved URL (e.g. `/file/open/:id`) in the
+     * ApiLessonResource response.
+     */
+    url: raw.url,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Backend → Frontend (normalise)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Normalize the API course metadata to the frontend Course shape. */
+export function normalizeCourse(raw: ApiCourse): Course {
+  return {
+    id: raw.id,
+    name: raw.name ?? raw.slug,
+    title: raw.titulo,
+    description: raw.descricao,
+    slug: raw.slug,
+    published: false,
+  };
+}
+
+/**
+ * Normalize a single API session to the frontend Session shape.
+ *
+ * @param raw   - Raw session object from the API response.
+ * @param index - Array position used to infer `order` (backend omits this field).
+ */
+export function normalizeSession(raw: ApiSession, index: number): Session {
+  return {
+    id: raw.id,
+    code: raw.codigo,
+    title: raw.titulo,
+    duration: raw.duracao,
+    /**
+     * ⚠️ BACKEND NOTE: `order` is stored in course_module but not included in
+     * the getStructure response. The backend returns modules already sorted
+     * by `order ASC`, so array position is a reliable proxy.
+     * TODO[BACKEND]: Include `order` in the ApiSession response.
+     */
+    order: index + 1,
+    /**
+     * ⚠️ BACKEND NOTE: visibility and published are not in the backend schema.
+     * Defaulted here. If these fields are added to the DB, read them from `raw`.
+     */
+    visibility: 'publico',
+    published: false,
+  };
+}
+
+/**
+ * Normalize a single API lesson to the frontend Lesson shape.
+ *
+ * @param raw   - Raw lesson object from the API response.
+ * @param order - Position within its session (caller must compute this).
+ */
+export function normalizeLesson(raw: ApiLesson, order = 0): Lesson {
+  const instructors: LessonInstructor[] = (raw.instrutores ?? []).map(
+    (inst) => ({ id: String(inst.id), name: inst.name })
+  );
+
+  return {
+    id: raw.id,
+    code: raw.codigo,
+    title: raw.titulo,
+    publicDescription: raw.descricaoPublica ?? '',
+    privateDescription: raw.descricaoPrivada ?? '',
+    type: normalizeLessonType(raw.tipo),
+    duration: raw.duracao,
+    sessionId: raw.sessaoId,
+    order,
+    videoProvider: raw.videoProvedor,
+    videoUrl: raw.videoUrl,
+    autoDuration: raw.duracaoAutomatica,
+    transcription: raw.transcricao,
+    /**
+     * ⚠️ TYPE MISMATCH: backend sends `exameVinculado` as number;
+     * frontend uses `linkedExam` as string. Converted with String().
+     */
+    linkedExam:
+      raw.exameVinculado != null ? String(raw.exameVinculado) : undefined,
+    postContent: raw.conteudoPost,
+    resources: (raw.recursos ?? []).map(normalizeResource),
+    instructors,
+    /**
+     * ⚠️ BACKEND NOTE: status and visibility are not in the DB schema.
+     * Left undefined. If added to the schema, read them from `raw`.
+     */
+    status: undefined,
+    visibility: undefined,
+  };
+}
+
+/**
+ * Normalize the full GET /lms/courses/:id/structure response.
+ *
+ * Returns flat `sessions` and `lessons` arrays ready to be loaded into the
+ * Zustand store, plus the available `instructors` pool for the lesson form,
+ * and the `course` metadata.
+ */
+export function normalizeStructureResponse(raw: ApiGetStructureResponse): {
+  course: Course | null;
+  sessions: Session[];
+  lessons: Lesson[];
+  instructors: { id: number; name: string }[];
+} {
+  const sessions = raw.sessoes.map((s, i) => normalizeSession(s, i));
+
+  // Track per-session lesson index to infer the per-lesson order field.
+  const lessonIndexPerSession: Record<string, number> = {};
+
+  const lessons = raw.aulas.map((a) => {
+    const idx = lessonIndexPerSession[a.sessaoId] ?? 0;
+    lessonIndexPerSession[a.sessaoId] = idx + 1;
+    return normalizeLesson(a, idx + 1);
+  });
+
+  return {
+    course: raw.curso ? normalizeCourse(raw.curso) : null,
+    sessions,
+    lessons,
+    instructors: raw.instructors ?? [],
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Frontend → Backend (serialise)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Convert SessionFormValues → ApiCreateSessionPayload.
+ * Used for POST /lms/courses/:id/structure/sessions.
+ *
+ * ⚠️ ADAPTER POINT:
+ *   `visibility` and `published` from SessionFormValues are intentionally
+ *   omitted — the backend schema does not have these fields yet.
+ *   TODO[BACKEND]: Add visibility/published to course_module if required.
+ */
+export function toCreateSessionPayload(
+  data: Pick<SessionFormValues, 'title' | 'duration' | 'description' | 'code'>
+): ApiCreateSessionPayload {
+  return {
+    titulo: data.title,
+    duracao: data.duration,
+    ...(data.description?.trim() && { descricao: data.description }),
+    ...(data.code?.trim() && { codigo: data.code }),
+  };
+}
+
+/**
+ * Convert partial SessionFormValues → ApiUpdateSessionPayload.
+ * Used for PATCH /lms/courses/:id/structure/sessions/:sessionId.
+ */
+export function toUpdateSessionPayload(
+  data: Partial<
+    Pick<SessionFormValues, 'title' | 'duration' | 'description' | 'code'>
+  >
+): ApiUpdateSessionPayload {
+  const payload: ApiUpdateSessionPayload = {};
+  if (data.title !== undefined) payload.titulo = data.title;
+  if (data.duration !== undefined) payload.duracao = data.duration;
+  if (data.description !== undefined) payload.descricao = data.description;
+  if (data.code !== undefined) payload.codigo = data.code;
+  return payload;
+}
+
+/**
+ * Convert LessonFormValues → ApiCreateLessonPayload.
+ * Used for POST /lms/courses/:id/structure/sessions/:sessionId/lessons.
+ *
+ * ⚠️ ADAPTER POINT:
+ *   `status` and `visibility` from LessonFormValues are intentionally omitted
+ *   (not in the DB schema). `linkedExam` (string) is converted to number.
+ */
+export function toCreateLessonPayload(
+  data: LessonFormValues & {
+    transcription?: string;
+    instructorIds?: number[];
+    resources?: LessonResourceInput[];
+  }
+): ApiCreateLessonPayload {
+  return {
+    titulo: data.title,
+    // ⚠️ TYPE NOTE: 'exercicio' is not in the frontend LessonType but the
+    // backend accepts it. Cast is safe as long as LessonType ⊆ ApiLesson['tipo'].
+    tipo: data.type as ApiCreateLessonPayload['tipo'],
+    duracao: data.duration,
+    ...(data.publicDescription && { descricaoPublica: data.publicDescription }),
+    ...(data.privateDescription && {
+      descricaoPrivada: data.privateDescription,
+    }),
+    ...(data.videoProvider && { videoProvedor: data.videoProvider }),
+    ...(data.videoUrl && { videoUrl: data.videoUrl }),
+    ...(data.autoDuration !== undefined && {
+      duracaoAutomatica: data.autoDuration,
+    }),
+    ...(data.transcription && { transcricao: data.transcription }),
+    // ⚠️ TYPE MISMATCH: frontend stores linkedExam as string; backend expects number.
+    ...(data.linkedExam && { exameVinculado: Number(data.linkedExam) }),
+    ...(data.postContent && { conteudoPost: data.postContent }),
+    ...(data.code?.trim() && { codigo: data.code }),
+    ...(data.instructorIds?.length && { instructorIds: data.instructorIds }),
+    ...(data.resources?.length && {
+      recursos: data.resources.map((r) => ({
+        nome: r.name,
+        // Only include fileId when the id is a valid server-assigned integer.
+        ...(Number.isInteger(Number(r.id)) && Number(r.id) > 0
+          ? { fileId: Number(r.id) }
+          : {}),
+        ...(r.type ? { tipo: r.type } : {}),
+        publico: r.public,
+      })),
+    }),
+  };
+}
+
+/**
+ * Convert partial LessonFormValues → ApiUpdateLessonPayload.
+ * Used for PATCH /lms/courses/:id/structure/sessions/:sessionId/lessons/:lessonId.
+ */
+export function toUpdateLessonPayload(
+  data: Partial<
+    LessonFormValues & {
+      transcription?: string;
+      instructorIds?: number[];
+      resources?: LessonResourceInput[];
+    }
+  >
+): ApiUpdateLessonPayload {
+  const payload: ApiUpdateLessonPayload = {};
+  if (data.title !== undefined) payload.titulo = data.title;
+  if (data.type !== undefined)
+    payload.tipo = data.type as ApiCreateLessonPayload['tipo'];
+  if (data.duration !== undefined) payload.duracao = data.duration;
+  if (data.publicDescription !== undefined)
+    payload.descricaoPublica = data.publicDescription;
+  if (data.privateDescription !== undefined)
+    payload.descricaoPrivada = data.privateDescription;
+  if (data.videoProvider !== undefined)
+    payload.videoProvedor = data.videoProvider;
+  if (data.videoUrl !== undefined) payload.videoUrl = data.videoUrl;
+  if (data.autoDuration !== undefined)
+    payload.duracaoAutomatica = data.autoDuration;
+  if (data.transcription !== undefined)
+    payload.transcricao = data.transcription;
+  if (data.postContent !== undefined) payload.conteudoPost = data.postContent;
+  if (data.code !== undefined) payload.codigo = data.code;
+  if (data.instructorIds !== undefined)
+    payload.instructorIds = data.instructorIds;
+  // ⚠️ TYPE MISMATCH: frontend stores linkedExam as string; backend expects number.
+  if (data.linkedExam !== undefined) {
+    payload.exameVinculado = data.linkedExam
+      ? Number(data.linkedExam)
+      : undefined;
+  }
+  // Always send resources when provided so the backend can sync (deleteMany + createMany).
+  if (data.resources !== undefined) {
+    payload.recursos = data.resources.map((r) => ({
+      nome: r.name,
+      ...(Number.isInteger(Number(r.id)) && Number(r.id) > 0
+        ? { fileId: Number(r.id) }
+        : {}),
+      ...(r.type ? { tipo: r.type } : {}),
+      publico: r.public,
+    }));
+  }
+  return payload;
+}

package/hedhog/frontend/app/courses/[id]/structure/_data/course-structure-contract.ts.ejs

@@ -0,0 +1,195 @@
+/**
+ * Course Structure — API Contract
+ *
+ * This file is the single source of truth for how the frontend communicates
+ * with the backend for the Course Structure feature.
+ *
+ * It contains:
+ *  1. API response shapes  (what the server returns)
+ *  2. API request shapes   (what we send to the server)
+ *  3. The public hook interface that call sites depend on
+ *
+ * ╔═══════════════════════════════════════════════════════════════════╗
+ * ║  Planned API surface (to be wired in when integrating backend)  ║
+ * ╠═══════════════════════════════════════════════════════════════════╣
+ * ║  GET    /lms/courses/:id/structure         → load full tree      ║
+ * ║  PUT    /lms/courses/:id                   → update course meta  ║
+ * ║  PUT    /lms/courses/:id/order             → save drag-drop order║
+ * ║  POST   /lms/courses/:id/sessions          → create session      ║
+ * ║  PUT    /lms/sessions/:id                  → update session      ║
+ * ║  DELETE /lms/sessions/:id                  → delete session      ║
+ * ║  PUT    /lms/sessions/reorder              → reorder sessions    ║
+ * ║  POST   /lms/sessions/:sessionId/lessons   → create lesson       ║
+ * ║  PUT    /lms/lessons/:id                   → update lesson       ║
+ * ║  DELETE /lms/lessons/:id                   → delete lesson       ║
+ * ║  PUT    /lms/lessons/:id/move              → move to session     ║
+ * ║  POST   /lms/lessons/:id/duplicate         → duplicate lesson    ║
+ * ║  POST   /lms/sessions/:id/duplicate        → duplicate session   ║
+ * ║  POST   /lms/lessons/:id/resources         → upload resource     ║
+ * ║  DELETE /lms/resources/:id                 → delete resource     ║
+ * ║  PUT    /lms/lessons/:id/transcription     → save transcription  ║
+ * ╚═══════════════════════════════════════════════════════════════════╝
+ */
+
+import type {
+  Course,
+  CourseFormValues,
+  Lesson,
+  LessonFormValues,
+  Session,
+  SessionFormValues,
+} from '../_components/types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// API — Response shapes
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Shape returned by GET /lms/courses/:id/structure
+ *
+ * The backend can return sessions with nested lessons (single round-trip),
+ * which this type captures. The hook will flatten them into the store.
+ */
+export interface CourseStructureResponse {
+  course: Course;
+  sessions: SessionWithLessons[];
+}
+
+export interface SessionWithLessons extends Session {
+  lessons: Lesson[];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// API — Request shapes
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * PUT /lms/courses/:id/order
+ *
+ * Sent after drag-and-drop to persist the new visual order.
+ * Sessions carry their own lesson order as a nested list.
+ */
+export interface SaveOrderRequest {
+  sessions: Array<{
+    id: string;
+    order: number;
+    lessons: Array<{ id: string; order: number }>;
+  }>;
+}
+
+/**
+ * PUT /lms/lessons/:id/move
+ *
+ * Moves a lesson to a different session (or a different position).
+ */
+export interface MoveLessonRequest {
+  toSessionId: string;
+  toIndex?: number;
+}
+
+/**
+ * POST /lms/lessons/:id/resources
+ *
+ * Multipart upload of a single resource file attached to a lesson.
+ */
+export interface UploadResourceRequest {
+  file: File;
+  name: string;
+  /** Whether the resource URL is publicly accessible */
+  public: boolean;
+}
+
+/**
+ * PUT /lms/lessons/:id/transcription
+ *
+ * Persists the auto-generated or manually edited lesson transcription.
+ */
+export interface SaveTranscriptionRequest {
+  transcription: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook interface
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The public interface exposed by `useCourseStructure`.
+ *
+ * Shaped to mirror the React Query pattern so that swapping the mock
+ * implementation for real `useQuery` / `useMutation` calls only touches the
+ * hook internals — all call sites stay unchanged.
+ *
+ * ```
+ * // Current implementation (mock):
+ * useCourseStructure(courseId)  →  reads from Zustand store w/ mock data
+ *
+ * // Future implementation (API):
+ * useCourseStructure(courseId)  →  useQuery + useMutation w/ React Query
+ * ```
+ */
+export interface CourseStructureHook {
+  // ── Query state (mirrors useQuery) ──────────────────────────────────────
+  /** True while the initial structure is being fetched (first load) */
+  isLoading: boolean;
+  /** True when the fetch failed */
+  isError: boolean;
+  /** True during background refetches (data is already available) */
+  isFetching: boolean;
+
+  // ── Dirty / saving state ─────────────────────────────────────────────────
+  /** True when local state diverges from the last saved server state */
+  isDirty: boolean;
+  /** True while any mutation (save/create/update/delete) is in-flight */
+  isSaving: boolean;
+
+  // ── Data ─────────────────────────────────────────────────────────────────
+  course: Course;
+  sessions: Session[];
+  lessons: Lesson[];
+
+  // ── Course ───────────────────────────────────────────────────────────────
+  /** PUT /lms/courses/:id */
+  updateCourse: (data: CourseFormValues) => void;
+  /** PUT /lms/courses/:id/order — persists drag-drop order */
+  saveOrder: () => void;
+
+  // ── Sections (sessions) ──────────────────────────────────────────────────
+  /** POST /lms/courses/:id/sessions */
+  createSection: () => void;
+  /** PUT /lms/sessions/:id */
+  updateSection: (id: string, data: SessionFormValues) => void;
+  /** DELETE /lms/sessions/:id */
+  deleteSection: (id: string) => void;
+  /** PUT /lms/sessions/reorder — send new index positions */
+  reorderSections: (fromIndex: number, toIndex: number) => void;
+  /** POST /lms/sessions/:id/duplicate */
+  duplicateSection: (id: string) => void;
+
+  // ── Lessons ──────────────────────────────────────────────────────────────
+  /** POST /lms/sessions/:sessionId/lessons */
+  createLesson: (sessionId: string) => void;
+  /** PUT /lms/lessons/:id */
+  updateLesson: (
+    id: string,
+    data: Partial<LessonFormValues & { transcription?: string }>
+  ) => void;
+  /** DELETE /lms/lessons/:id */
+  deleteLesson: (id: string) => void;
+  /** PUT /lms/lessons/:id/move */
+  moveLesson: (lessonId: string, toSessionId: string, toIndex?: number) => void;
+  /** POST /lms/lessons/:id/duplicate */
+  duplicateLesson: (id: string) => void;
+
+  // ── Bulk operations ──────────────────────────────────────────────────────
+  /** Batch DELETE — fires one request per selected item (or a bulk endpoint) */
+  deleteSelected: () => void;
+  /** Batch duplicate — POST /lms/{sessions|lessons}/:id/duplicate per item */
+  duplicateSelected: () => void;
+  /** Batch move — PUT /lms/lessons/:id/move per lesson */
+  moveLessons: (lessonIds: string[], toSessionId: string) => void;
+
+  // ── Clipboard (client-only — no API equivalent) ──────────────────────────
+  copyItems: (ids: string[], type: 'session' | 'lesson') => void;
+  pasteSessions: () => void;
+  pasteLessons: (toSessionId: string) => void;
+}