feat: add collaborative document functionality for lessons

- Create migration scripts for lesson_collaborative_docs table in both cms-service and lms-service.
- Implement CollaborativeDocEditor component for real-time editing of collaborative documents.
- Add LessonCollaborativeDocPage for instructors to view and manage collaborative documents.
- Include conflict resolution handling in the editor.
- Enhance UI with status indicators and formatting options for the document editor.

Co-authored-by: Copilot <copilot@github.com>

web/studio/src/app/courses/[id]/lessons/[lessonId]/collaborative-doc/page.tsx

@@ -0,0 +1,172 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import { useParams, useRouter } from "next/navigation";
+import Link from "next/link";
+import { lmsApi, getLessonCollaborativeDoc, CollaborativeDoc } from "@/lib/api";
+import {
+    ArrowLeft,
+    FileText,
+    RefreshCw,
+    Trash2,
+    Eye,
+    Clock,
+    User,
+} from "lucide-react";
+
+export default function LessonCollaborativeDocPage() {
+    const { id: courseId, lessonId } = useParams() as { id: string; lessonId: string };
+    const router = useRouter();
+    const [doc, setDoc] = useState<CollaborativeDoc | null>(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState<string | null>(null);
+    const [clearing, setClearing] = useState(false);
+    const [cleared, setCleared] = useState(false);
+
+    const loadDoc = useCallback(async () => {
+        setLoading(true);
+        setError(null);
+        try {
+            const data = await getLessonCollaborativeDoc(lessonId);
+            setDoc(data);
+        } catch (e) {
+            // El doc puede no existir aún (revision 0)
+            setDoc({ lesson_id: lessonId, organization_id: "", content: "", revision: 0, last_modified_by: null, updated_at: new Date().toISOString() });
+        } finally {
+            setLoading(false);
+        }
+    }, [lessonId]);
+
+    useEffect(() => {
+        void loadDoc();
+    }, [loadDoc]);
+
+    const clearDoc = async () => {
+        const ok = confirm("¿Borrar el contenido del documento colaborativo? Los estudiantes perderán todo el texto.");
+        if (!ok) return;
+        setClearing(true);
+        try {
+            await lmsApi.updateLessonCollaborativeDoc(lessonId, {
+                content: "",
+                base_revision: doc?.revision ?? 0,
+            });
+            setCleared(true);
+            setDoc((prev) => prev ? { ...prev, content: "", revision: (prev.revision || 0) + 1 } : prev);
+        } catch (e) {
+            setError(e instanceof Error ? e.message : "No se pudo borrar el documento");
+        } finally {
+            setClearing(false);
+        }
+    };
+
+    const wordCount = (doc?.content ?? "").trim().split(/\s+/).filter(Boolean).length;
+    const charCount = (doc?.content ?? "").length;
+
+    return (
+        <div className="min-h-screen bg-gray-50 dark:bg-zinc-950 px-4 py-8 max-w-3xl mx-auto">
+            {/* Header */}
+            <div className="flex items-center gap-3 mb-6">
+                <button
+                    onClick={() => router.back()}
+                    className="p-2 rounded-lg hover:bg-black/5 dark:hover:bg-white/10"
+                >
+                    <ArrowLeft className="w-4 h-4" />
+                </button>
+                <div>
+                    <h1 className="text-lg font-black flex items-center gap-2">
+                        <FileText className="w-5 h-5" /> Documento Colaborativo
+                    </h1>
+                    <p className="text-xs text-black/50 dark:text-white/50">
+                        Vista de instructor — lección <span className="font-mono">{lessonId.slice(0, 8)}…</span>
+                    </p>
+                </div>
+                <button
+                    onClick={() => void loadDoc()}
+                    className="ml-auto p-2 rounded-lg hover:bg-black/5 dark:hover:bg-white/10"
+                    title="Recargar"
+                >
+                    <RefreshCw className={`w-4 h-4 ${loading ? "animate-spin" : ""}`} />
+                </button>
+            </div>
+
+            {error && (
+                <div className="mb-4 rounded-xl bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-700 px-4 py-3 text-sm text-red-700 dark:text-red-300">
+                    {error}
+                </div>
+            )}
+
+            {cleared && (
+                <div className="mb-4 rounded-xl bg-green-50 dark:bg-green-900/20 border border-green-200 dark:border-green-700 px-4 py-3 text-sm text-green-700 dark:text-green-300">
+                    Documento borrado correctamente.
+                </div>
+            )}
+
+            {/* Metadatos */}
+            <section className="rounded-2xl border border-black/10 dark:border-white/10 bg-white dark:bg-zinc-900 p-5 mb-4 space-y-3">
+                <div className="grid grid-cols-2 md:grid-cols-4 gap-4 text-xs">
+                    <div>
+                        <div className="text-black/40 dark:text-white/40 mb-0.5">Revisión</div>
+                        <div className="font-black text-lg">{doc?.revision ?? 0}</div>
+                    </div>
+                    <div>
+                        <div className="text-black/40 dark:text-white/40 mb-0.5">Palabras</div>
+                        <div className="font-black text-lg">{wordCount}</div>
+                    </div>
+                    <div>
+                        <div className="text-black/40 dark:text-white/40 mb-0.5">Caracteres</div>
+                        <div className="font-black text-lg">{charCount}</div>
+                    </div>
+                    <div>
+                        <div className="text-black/40 dark:text-white/40 mb-0.5">Última edición</div>
+                        <div className="font-semibold">
+                            {doc?.updated_at ? new Date(doc.updated_at).toLocaleString() : "—"}
+                        </div>
+                    </div>
+                </div>
+                {doc?.last_modified_by && (
+                    <div className="flex items-center gap-1 text-xs text-black/50 dark:text-white/40">
+                        <User className="w-3 h-3" />
+                        Último editor: <span className="font-mono">{doc.last_modified_by}</span>
+                    </div>
+                )}
+            </section>
+
+            {/* Vista previa del contenido */}
+            <section className="rounded-2xl border border-black/10 dark:border-white/10 bg-white dark:bg-zinc-900 p-5 mb-4">
+                <div className="flex items-center justify-between mb-3">
+                    <h2 className="text-xs font-black uppercase tracking-wider text-black/40 dark:text-white/40 flex items-center gap-1">
+                        <Eye className="w-3 h-3" /> Contenido actual
+                    </h2>
+                </div>
+                {loading ? (
+                    <div className="flex justify-center py-8">
+                        <div className="h-5 w-5 animate-spin rounded-full border-2 border-black/20 border-t-black dark:border-white/20 dark:border-t-white" />
+                    </div>
+                ) : doc?.content ? (
+                    <pre className="whitespace-pre-wrap text-sm font-mono leading-relaxed max-h-96 overflow-auto text-black/80 dark:text-white/80">
+                        {doc.content}
+                    </pre>
+                ) : (
+                    <p className="text-sm text-black/40 dark:text-white/40 text-center py-8">
+                        El documento está vacío — los estudiantes aún no han escrito nada.
+                    </p>
+                )}
+            </section>
+
+            {/* Acciones */}
+            <section className="rounded-2xl border border-black/10 dark:border-white/10 bg-white dark:bg-zinc-900 p-5 flex items-center justify-between gap-4">
+                <div className="text-xs text-black/50 dark:text-white/50">
+                    El documento es editable por todos los estudiantes matriculados en el curso en tiempo real via SSE.
+                </div>
+                <button
+                    onClick={() => void clearDoc()}
+                    disabled={clearing || !doc?.content}
+                    className="inline-flex items-center gap-2 px-4 py-2 rounded-xl border border-red-200 dark:border-red-700 bg-red-50 dark:bg-red-900/20 text-red-700 dark:text-red-300 text-sm font-semibold hover:bg-red-100 disabled:opacity-40"
+                >
+                    <Trash2 className="w-4 h-4" />
+                    {clearing ? "Borrando…" : "Borrar documento"}
+                </button>
+            </section>
+        </div>
+    );
+}

web/studio/src/app/courses/[id]/lti-tools/page.tsx

@@ -19,6 +19,8 @@ import {
     KeyRound,
     Copy,
     CheckCheck,
+    ChevronDown,
+    ChevronRight,
 } from "lucide-react";
 
 export default function CourseLtiToolsPage() {
@@ -33,6 +35,7 @@ export default function CourseLtiToolsPage() {
         shared_secret: "",
         enabled: true,
     });
+    const [showAgs, setShowAgs] = useState(false);
 
     // Rotación de secreto
     const [rotateModal, setRotateModal] = useState<{ toolId: string; toolName: string } | null>(null);
@@ -68,6 +71,7 @@ export default function CourseLtiToolsPage() {
             const created = await lmsApi.createCourseLtiTool(id, form);
             setTools((prev) => [...prev, created]);
             setForm({ name: "", launch_url: "", shared_secret: "", enabled: true });
+            setShowAgs(false);
         } catch (e) {
             setError(e instanceof Error ? e.message : "No se pudo crear la herramienta");
         } finally {
@@ -221,6 +225,49 @@ export default function CourseLtiToolsPage() {
                             onChange={(e) => setForm((f) => ({ ...f, shared_secret: e.target.value }))}
                         />
                     </div>
+                    {/* Configuración AGS (OAuth2) — colapsable */}
+                    <div className="mt-3">
+                        <button
+                            type="button"
+                            onClick={() => setShowAgs((v) => !v)}
+                            className="flex items-center gap-1 text-xs text-black/60 dark:text-white/60 hover:text-black dark:hover:text-white"
+                        >
+                            {showAgs ? <ChevronDown className="w-3 h-3" /> : <ChevronRight className="w-3 h-3" />}
+                            Configuración AGS / OAuth2 (opcional)
+                        </button>
+                        {showAgs && (
+                            <div className="mt-3 grid grid-cols-1 md:grid-cols-2 gap-3 p-4 rounded-xl bg-blue-50 dark:bg-blue-900/20 border border-blue-200 dark:border-blue-700">
+                                <p className="md:col-span-2 text-xs text-blue-700 dark:text-blue-300">
+                                    LTI AGS (Assignment and Grade Services) — permite passback de notas sin HMAC, usando OAuth2 client_credentials. Endpoint: <span className="font-mono">/lti/tools/{'{tool_id}'}/ags-score</span>
+                                </p>
+                                <input
+                                    className="rounded-lg border border-black/10 dark:border-white/10 bg-white dark:bg-zinc-900 px-3 py-2 text-sm"
+                                    placeholder="AGS Client ID"
+                                    value={form.ags_client_id ?? ""}
+                                    onChange={(e) => setForm((f) => ({ ...f, ags_client_id: e.target.value || undefined }))}
+                                />
+                                <input
+                                    type="password"
+                                    className="rounded-lg border border-black/10 dark:border-white/10 bg-white dark:bg-zinc-900 px-3 py-2 text-sm"
+                                    placeholder="AGS Client Secret"
+                                    value={form.ags_client_secret ?? ""}
+                                    onChange={(e) => setForm((f) => ({ ...f, ags_client_secret: e.target.value || undefined }))}
+                                />
+                                <input
+                                    className="rounded-lg border border-black/10 dark:border-white/10 bg-white dark:bg-zinc-900 px-3 py-2 text-sm"
+                                    placeholder="Token URL (https://lms.example/oauth/token)"
+                                    value={form.ags_token_url ?? ""}
+                                    onChange={(e) => setForm((f) => ({ ...f, ags_token_url: e.target.value || undefined }))}
+                                />
+                                <input
+                                    className="rounded-lg border border-black/10 dark:border-white/10 bg-white dark:bg-zinc-900 px-3 py-2 text-sm"
+                                    placeholder="LineItem URL (https://lms.example/lineitems/123)"
+                                    value={form.ags_lineitem_url ?? ""}
+                                    onChange={(e) => setForm((f) => ({ ...f, ags_lineitem_url: e.target.value || undefined }))}
+                                />
+                            </div>
+                        )}
+                    </div>
                     <div className="mt-3 flex items-center gap-3">
                         <button
                             onClick={() => void createTool()}
@@ -230,7 +277,7 @@ export default function CourseLtiToolsPage() {
                             {saving ? "Guardando..." : "Crear herramienta"}
                         </button>
                         <p className="text-xs text-black/50 dark:text-white/50">
-                            Passback endpoint: <span className="font-mono">/lti/tools/{'{tool_id}'}/grade-passback</span>. Headers requeridos: <span className="font-mono">x-openccb-lti-timestamp</span> y <span className="font-mono">x-openccb-lti-signature</span> (HMAC-SHA256).
+                            Passback HMAC: <span className="font-mono">/lti/tools/{'{tool_id}'}/grade-passback</span>. Passback AGS: <span className="font-mono">/lti/tools/{'{tool_id}'}/ags-score</span>.
                         </p>
                     </div>
                 </section>

web/studio/src/app/courses/[id]/study-rooms/page.tsx

@@ -3,7 +3,7 @@
 import { useCallback, useEffect, useState } from "react";
 import { useParams } from "next/navigation";
 import CourseEditorLayout from "@/components/CourseEditorLayout";
-import { lmsApi, StudyRoom, CreateStudyRoomPayload } from "@/lib/api";
+import { lmsApi, StudyRoom, BbbRecording, CreateStudyRoomPayload } from "@/lib/api";
 import {
     Video,
     Plus,
@@ -14,6 +14,9 @@ import {
     Clock,
     Users,
     ExternalLink,
+    Film,
+    ChevronDown,
+    ChevronRight,
 } from "lucide-react";
 
 const STATUS_LABEL: Record<string, string> = {
@@ -38,6 +41,9 @@ export default function CourseStudyRoomsPage() {
         description: "",
         max_participants: 50,
     });
+    const [recordings, setRecordings] = useState<Record<string, BbbRecording[]>>({});
+    const [loadingRec, setLoadingRec] = useState<Record<string, boolean>>({});
+    const [expandedRec, setExpandedRec] = useState<Record<string, boolean>>({});
 
     const loadRooms = useCallback(async () => {
         setLoading(true);
@@ -107,6 +113,22 @@ export default function CourseStudyRoomsPage() {
         }
     };
 
+    const toggleRecordings = async (room: StudyRoom) => {
+        const isExpanded = expandedRec[room.id];
+        setExpandedRec((prev) => ({ ...prev, [room.id]: !isExpanded }));
+        if (!isExpanded && !recordings[room.id]) {
+            setLoadingRec((prev) => ({ ...prev, [room.id]: true }));
+            try {
+                const recs = await lmsApi.getStudyRoomRecordings(id, room.id);
+                setRecordings((prev) => ({ ...prev, [room.id]: recs }));
+            } catch {
+                setRecordings((prev) => ({ ...prev, [room.id]: [] }));
+            } finally {
+                setLoadingRec((prev) => ({ ...prev, [room.id]: false }));
+            }
+        }
+    };
+
     return (
         <CourseEditorLayout
             activeTab="study-rooms"
@@ -175,10 +197,8 @@ export default function CourseStudyRoomsPage() {
 
                     <div className="space-y-3">
                         {rooms.map((room) => (
-                            <div
-                                key={room.id}
-                                className="rounded-xl border border-black/10 dark:border-white/10 px-4 py-3 flex flex-wrap items-center justify-between gap-3"
-                            >
+                            <div key={room.id} className="rounded-xl border border-black/10 dark:border-white/10">
+                                <div className="px-4 py-3 flex flex-wrap items-center justify-between gap-3">
                                 <div className="min-w-0 flex-1">
                                     <div className="flex items-center gap-2 flex-wrap">
                                         <span className="text-sm font-semibold truncate">{room.title}</span>
@@ -229,6 +249,14 @@ export default function CourseStudyRoomsPage() {
                                         </button>
                                     )}
                                     {room.status === "ended" && (
+                                        <>
+                                        <button
+                                            onClick={() => void toggleRecordings(room)}
+                                            className="inline-flex items-center gap-1 px-3 py-1.5 rounded-lg border border-blue-200 dark:border-blue-700 bg-blue-50 dark:bg-blue-900/20 text-blue-700 dark:text-blue-300 text-xs font-semibold hover:bg-blue-100"
+                                        >
+                                            {expandedRec[room.id] ? <ChevronDown className="w-3 h-3" /> : <ChevronRight className="w-3 h-3" />}
+                                            <Film className="w-3 h-3" /> Grabaciones
+                                        </button>
                                         <button
                                             onClick={() => void deleteRoom(room)}
                                             className="p-2 rounded-lg hover:bg-red-50 dark:hover:bg-red-900/20"
@@ -236,9 +264,41 @@ export default function CourseStudyRoomsPage() {
                                         >
                                             <Trash2 className="w-4 h-4 text-red-600" />
                                         </button>
+                                        </>
                                     )}
                                 </div>
                             </div>
+
+                            {/* Grabaciones BBB dentro del wrapper */}
+                            {room.status === "ended" && expandedRec[room.id] && (
+                                <div className="px-4 pb-3 rounded-b-xl bg-gray-50 dark:bg-white/5 border-t border-black/5 dark:border-white/5">
+                                    {loadingRec[room.id] ? (
+                                        <p className="text-xs text-black/50 dark:text-white/50 pt-3">Cargando grabaciones…</p>
+                                    ) : recordings[room.id]?.length ? (
+                                        <div className="space-y-2 pt-3">
+                                            {recordings[room.id].map((rec) => (
+                                                <div key={rec.record_id} className="flex items-center justify-between gap-3 text-xs">
+                                                    <div>
+                                                        <span className="font-semibold">{rec.name}</span>
+                                                        <span className="ml-2 text-black/40 dark:text-white/40">{rec.duration_minutes} min · {rec.participants} participantes</span>
+                                                    </div>
+                                                    <a
+                                                        href={rec.playback_url}
+                                                        target="_blank"
+                                                        rel="noopener noreferrer"
+                                                        className="inline-flex items-center gap-1 text-blue-600 dark:text-blue-400 hover:underline shrink-0"
+                                                    >
+                                                        <ExternalLink className="w-3 h-3" /> Ver
+                                                    </a>
+                                                </div>
+                                            ))}
+                                        </div>
+                                    ) : (
+                                        <p className="text-xs text-black/50 dark:text-white/50">No hay grabaciones disponibles para esta sala.</p>
+                                    )}
+                                </div>
+                            )}
+                        </div>
                         ))}
                         {!loading && rooms.length === 0 && (
                             <p className="text-sm text-black/50 dark:text-white/50">No hay salas creadas para este curso.</p>

web/studio/src/lib/api.ts

@@ -1853,6 +1853,8 @@ export const lmsApi = {
         apiFetch(`/courses/${courseId}/study-rooms/${roomId}/end`, { method: 'POST' }, true),
     deleteStudyRoom: (courseId: string, roomId: string): Promise<void> =>
         apiFetch(`/courses/${courseId}/study-rooms/${roomId}`, { method: 'DELETE' }, true),
+    getStudyRoomRecordings: (courseId: string, roomId: string): Promise<BbbRecording[]> =>
+        apiFetch(`/courses/${courseId}/study-rooms/${roomId}/recordings`, {}, true),
 };
 
 export interface StudyRoom {
@@ -1873,6 +1875,18 @@ export interface StudyRoom {
     updated_at: string;
 }
 
+export interface BbbRecording {
+    record_id: string;
+    meeting_id: string;
+    name: string;
+    state: string;
+    start_time: string;
+    end_time: string;
+    participants: number;
+    playback_url: string;
+    duration_minutes: number;
+}
+
 export interface CreateStudyRoomPayload {
     title: string;
     description?: string;
@@ -2063,6 +2077,10 @@ export interface LtiExternalTool {
     launch_url: string;
     enabled: boolean;
     config: Record<string, unknown>;
+    ags_client_id?: string;
+    ags_client_secret?: string;
+    ags_token_url?: string;
+    ags_lineitem_url?: string;
     created_at: string;
     updated_at: string;
 }
@@ -2072,6 +2090,10 @@ export interface CreateLtiExternalToolPayload {
     shared_secret: string;
     enabled?: boolean;
     config?: Record<string, unknown>;
+    ags_client_id?: string;
+    ags_client_secret?: string;
+    ags_token_url?: string;
+    ags_lineitem_url?: string;
 }
 export interface UpdateLtiExternalToolPayload {
     name?: string;
@@ -2079,6 +2101,10 @@ export interface UpdateLtiExternalToolPayload {
     shared_secret?: string;
     enabled?: boolean;
     config?: Record<string, unknown>;
+    ags_client_id?: string;
+    ags_client_secret?: string;
+    ags_token_url?: string;
+    ags_lineitem_url?: string;
 }
 
 export interface LtiDeepLinkingContentItem {
@@ -2326,4 +2352,42 @@ export async function evaluateAudioResponse(
 
 export async function getCourseAudioResponseStats(courseId: string): Promise<AudioResponseStats> {
     return apiFetch(`/courses/${courseId}/audio-responses/stats`, { method: 'GET' }, true);
+}
+
+// ─── Documentos Colaborativos (Fase 40) ──────────────────────────────────────
+
+export interface CollaborativeDoc {
+    lesson_id: string;
+    organization_id: string;
+    content: string;
+    revision: number;
+    last_modified_by: string | null;
+    updated_at: string;
+}
+
+export interface UpdateCollaborativeDocPayload {
+    content: string;
+    base_revision: number;
+}
+
+export interface UpdateCollaborativeDocResponse {
+    lesson_id: string;
+    revision: number;
+    conflict: boolean;
+    server_content?: string;
+    server_revision?: number;
+}
+
+export async function getLessonCollaborativeDoc(lessonId: string): Promise<CollaborativeDoc> {
+    return apiFetch(`/lessons/${lessonId}/collaborative-doc`, {}, true);
+}
+
+export async function updateLessonCollaborativeDoc(
+    lessonId: string,
+    payload: UpdateCollaborativeDocPayload
+): Promise<UpdateCollaborativeDocResponse> {
+    return apiFetch(`/lessons/${lessonId}/collaborative-doc`, {
+        method: 'PUT',
+        body: JSON.stringify(payload),
+    }, true);
 }