academe-kit 0.10.0 → 0.10.2

package/dist/index.d.ts

@@ -10793,6 +10793,77 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/reports/students-journey-status/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Status de jornada dos alunos por bimestre (cards de /students)
+         * @description Recorta os alunos ativos da escola em 4 categorias mutuamente exclusivas
+         *     (notStarted, inJourney, inReview, completed) considerando os challenges
+         *     do bimestre alvo. Cada aluno cai na categoria mais avançada que alcançou.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description UUID do educational_model_period, OU a string literal `"all"` para considerar todos os bimestres. Omitido = corrente. */
+                    periodId?: string;
+                    /** @description Quando presente, restringe o cálculo a UM challenge específico dentro do recorte temporal. */
+                    challengeId?: string;
+                };
+                header?: never;
+                path: {
+                    /** @description UUID da instituição */
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Status agregado */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example success */
+                            status?: string;
+                            data?: components["schemas"]["StudentsJourneyStatusResponse"];
+                        };
+                    };
+                };
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/roles": {
         parameters: {
             query?: never;
@@ -11777,7 +11848,13 @@ interface paths {
                     userId?: string;
                     groupId?: string;
                     institutionId?: string;
+                    institutionClassroomId?: string;
+                    serieId?: string;
                     status?: "submitted" | "ai_evaluated" | "approved" | "rejected";
+                    /** @description Busca por nome ou e-mail do aluno */
+                    search?: string;
+                    /** @description UUID de um educational_model_period. Recorta as submissões cuja data de envio (submittedAt) cai no intervalo [start, end] do período. Omitido = todos os períodos. */
+                    periodId?: string;
                     /** @description Page number */
                     page?: components["parameters"]["page"];
                     /** @description Items per page */
@@ -11798,7 +11875,16 @@ interface paths {
                         "application/json": {
                             /** @example success */
                             status?: string;
-                            data?: components["schemas"]["Submission"][];
+                            data?: (components["schemas"]["Submission"] & {
+                                /** @description Período letivo cujo intervalo contém a data de envio (submittedAt). Null quando a escola não tem períodos ou o envio caiu fora de qualquer período. */
+                                period?: {
+                                    id?: string;
+                                    /** @description 0-based (0 = 1º período) */
+                                    index?: number;
+                                    /** @example 1º Bimestre */
+                                    label?: string;
+                                } | null;
+                            })[];
                             meta?: components["schemas"]["PaginationMeta"] & {
                                 /**
                                  * @description Contagem por status, ignorando o filtro `status`. Útil para
@@ -11814,6 +11900,14 @@ interface paths {
                                     /** @example 2 */
                                     rejected?: number;
                                 };
+                                /** @description Períodos letivos da escola (ORDER BY start ASC) para o dropdown de filtro. */
+                                periods?: {
+                                    id?: string;
+                                    index?: number;
+                                    /** @example 1º Bimestre */
+                                    label?: string;
+                                    isCurrent?: boolean;
+                                }[];
                             };
                         };
                     };
@@ -14762,6 +14856,9 @@ interface components {
             createdAt: string;
             /** Format: date-time */
             updatedAt: string;
+            organization?: components["schemas"]["Organization"] | null;
+            address?: components["schemas"]["Address"] | null;
+            institutionReward?: Record<string, never> | null;
         };
         Organization: {
             /** Format: uuid */
@@ -16554,10 +16651,36 @@ interface components {
             courses?: components["schemas"]["EncourageJourneyCourse"][];
         };
         EncourageSubmissions: {
+            /** @description Total de alunos ativos da escola (denominador para % concluído) */
             total?: number;
-            evaluated?: number;
+            /** @description Última submissão por (aluno, challenge do bimestre corrente) com teacher_score preenchido */
+            finalized?: number;
+            /** @description Última submissão por (aluno, challenge do bimestre corrente) ainda SEM teacher_score */
             awaitingTeacher?: number;
-            awaitingAi?: number;
+        };
+        StudentsJourneyStatusSummary: {
+            /** @description Alunos sem step concluído nos challenges do recorte */
+            notStarted?: number;
+            /** @description Tem step concluído mas sem submissão */
+            inJourney?: number;
+            /** @description Submissão pendente de avaliação (teacher_score nulo) */
+            inReview?: number;
+            /** @description Submissão já avaliada (teacher_score preenchido) */
+            completed?: number;
+        };
+        StudentsJourneyStatusScope: {
+            /** @description UUID do bimestre alvo; null quando allPeriods */
+            periodId?: string | null;
+            /** @description UUID do challenge alvo; null quando todos do recorte */
+            challengeId?: string | null;
+            /** @description Quantidade de challenges no recorte */
+            challengesCount?: number;
+            /** @description Total de alunos ativos da escola — fecha com a soma dos 4 status */
+            totalStudents?: number;
+        };
+        StudentsJourneyStatusResponse: {
+            summary?: components["schemas"]["StudentsJourneyStatusSummary"];
+            scope?: components["schemas"]["StudentsJourneyStatusScope"];
         };
         EncourageClassPerformance: {
             /** Format: uuid */
@@ -20273,6 +20396,73 @@ declare function createReportService(apiClient: AcademeApiClient): {
             } | undefined;
         };
     }, `${string}/${string}`>>;
+    /**
+     * Status de jornada dos alunos para os summary cards da rota /students.
+     *
+     * @param id                  UUID da instituição.
+     * @param params.periodId     UUID do bimestre, ou `"all"` para todos os bimestres
+     *                            do ano letivo. Omitido = bimestre corrente.
+     * @param params.challengeId  UUID de UM challenge específico para restringir o
+     *                            cálculo dentro do recorte temporal.
+     */
+    getStudentsJourneyStatusByInstitution(id: string, params?: {
+        periodId?: string;
+        challengeId?: string;
+    }): Promise<openapi_fetch.FetchResponse<{
+        parameters: {
+            query?: {
+                periodId?: string;
+                challengeId?: string;
+            };
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        status?: string;
+                        data?: components["schemas"]["StudentsJourneyStatusResponse"];
+                    };
+                };
+            };
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    }, {
+        params: {
+            path: {
+                id: string;
+            };
+            query: {
+                periodId?: string;
+                challengeId?: string;
+            } | undefined;
+        };
+    }, `${string}/${string}`>>;
 };
 type ReportService = ReturnType<typeof createReportService>;
 
@@ -26197,7 +26387,11 @@ declare function createSubmissionService(apiClient: AcademeApiClient): {
                 userId?: string;
                 groupId?: string;
                 institutionId?: string;
+                institutionClassroomId?: string;
+                serieId?: string;
                 status?: "submitted" | "ai_evaluated" | "approved" | "rejected";
+                search?: string;
+                periodId?: string;
                 page?: components["parameters"]["page"];
                 limit?: components["parameters"]["limit"];
             };
@@ -26214,7 +26408,13 @@ declare function createSubmissionService(apiClient: AcademeApiClient): {
                 content: {
                     "application/json": {
                         status?: string;
-                        data?: components["schemas"]["Submission"][];
+                        data?: (components["schemas"]["Submission"] & {
+                            period?: {
+                                id?: string;
+                                index?: number;
+                                label?: string;
+                            } | null;
+                        })[];
                         meta?: components["schemas"]["PaginationMeta"] & {
                             statusCounts?: {
                                 submitted?: number;
@@ -26222,6 +26422,12 @@ declare function createSubmissionService(apiClient: AcademeApiClient): {
                                 approved?: number;
                                 rejected?: number;
                             };
+                            periods?: {
+                                id?: string;
+                                index?: number;
+                                label?: string;
+                                isCurrent?: boolean;
+                            }[];
                         };
                     };
                 };
@@ -26235,7 +26441,11 @@ declare function createSubmissionService(apiClient: AcademeApiClient): {
                 userId?: string;
                 groupId?: string;
                 institutionId?: string;
+                institutionClassroomId?: string;
+                serieId?: string;
                 status?: "submitted" | "ai_evaluated" | "approved" | "rejected";
+                search?: string;
+                periodId?: string;
                 page?: components["parameters"]["page"];
                 limit?: components["parameters"]["limit"];
             } | undefined;
@@ -26532,6 +26742,242 @@ declare function createSubmissionService(apiClient: AcademeApiClient): {
 };
 type SubmissionService = ReturnType<typeof createSubmissionService>;
 
+type JourneyView = components["schemas"]["JourneyView"];
+/**
+ * Service do agregado `user-challenge-progress` — o caminho oficial para os
+ * clientes (web/mobile) montarem a jornada e o progresso do usuário. Espelha
+ * app-academe-v2/src/services/academe/user-progress.service.ts.
+ */
+declare function createUserProgressService(apiClient: AcademeApiClient): {
+    /**
+     * Jornada pré-computada do usuário (status, progress, color, icon,
+     * isUpcoming, série) — base de renderização direta da tela de jornada.
+     */
+    getJourney(serieId?: string): Promise<JourneyView>;
+    /**
+     * Visão step-by-step do progresso do usuário em um desafio. Cada step traz
+     * `myStartedAt`, `myCompletedAt` e (em desafios em grupo) os agregados do
+     * grupo.
+     */
+    getChallengeProgress(challengeId: string): Promise<openapi_fetch.FetchResponse<{
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: components["parameters"]["id"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        status?: string;
+                        data?: {
+                            challengeStepId?: string;
+                            stepName?: string;
+                            index?: number;
+                            totalMembers?: number;
+                            completedMembers?: number;
+                            groupCompleted?: boolean;
+                            myStartedAt?: string | null;
+                            myCompletedAt?: string | null;
+                        }[];
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    }, {
+        params: {
+            path: {
+                id: string;
+            };
+        };
+    }, `${string}/${string}`>>;
+    /**
+     * Avança um tick na jornada do usuário no desafio, agnóstico do tipo da
+     * etapa. Cada chamada executa UMA ação:
+     *   - Sem progresso na etapa atual → action='started'
+     *   - Etapa iniciada (sem completedAt) → action='completed'
+     *   - Todas as etapas concluídas → action='finished' (no-op)
+     *
+     * Caminho oficial para clientes (web/mobile). Não usar os endpoints
+     * internos `/steps/{stepId}/start` ou `/steps/{stepId}/complete`.
+     */
+    advance(challengeId: string): Promise<openapi_fetch.FetchResponse<{
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: components["parameters"]["id"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        status?: string;
+                        data?: {
+                            action?: "started" | "completed" | "finished";
+                            challengeId?: string;
+                            currentStep?: {
+                                id?: string;
+                                index?: number;
+                                name?: string;
+                                startedAt?: string | null;
+                                completedAt?: string | null;
+                            } | null;
+                            nextStep?: {
+                                id?: string;
+                                index?: number;
+                                name?: string;
+                                startedAt?: string | null;
+                            } | null;
+                        };
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    }, {
+        params: {
+            path: {
+                id: string;
+            };
+        };
+    }, `${string}/${string}`>>;
+    /**
+     * Status de conclusão do grupo numa etapa. Em desafios em grupo: retorna a
+     * agregação (`canAdvance=true` quando todos concluíram). Em desafios
+     * individuais: retorna o status do próprio usuário.
+     */
+    getStepGroupStatus(stepId: string): Promise<openapi_fetch.FetchResponse<{
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                stepId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        status?: string;
+                        data?: {
+                            isGroupChallenge?: boolean;
+                            totalMembers?: number;
+                            completedMembers?: number;
+                            canAdvance?: boolean;
+                        };
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    }, {
+        params: {
+            path: {
+                stepId: string;
+            };
+        };
+    }, `${string}/${string}`>>;
+    /**
+     * Progresso agregado do usuário em um módulo (ou no curso inteiro quando
+     * `moduleId` é omitido). Usado pelos steps do tipo `course` da jornada.
+     */
+    getCourseProgress(courseId: string, moduleId?: string | null): Promise<openapi_fetch.FetchResponse<{
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                courseId: string;
+                moduleId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        status?: string;
+                        data?: components["schemas"]["UsersCourseLogProgress"];
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    }, {
+        params: {
+            path: {
+                courseId: string;
+                moduleId: string;
+            };
+        };
+    }, `${string}/${string}`>>;
+    /**
+     * [Interno] Força o início de uma etapa específica (idempotente). Clientes
+     * devem preferir `advance`; mantido para casos pontuais (ex.: iniciar a
+     * próxima etapa após concluir um curso aberto a partir da jornada).
+     */
+    start(stepId: string): Promise<openapi_fetch.FetchResponse<{
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                stepId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        status?: string;
+                        data?: components["schemas"]["UserChallengeProgress"];
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    }, {
+        params: {
+            path: {
+                stepId: string;
+            };
+        };
+    }, `${string}/${string}`>>;
+};
+type UserProgressService = ReturnType<typeof createUserProgressService>;
+
 type AcademeApiClient = ReturnType<typeof openapi_fetch__default<paths>>;
 declare function createAcademeApiClient(baseUrl: string): AcademeApiClient;
 interface AcademeServices {
@@ -26556,6 +27002,7 @@ interface AcademeServices {
     challenge: ChallengeService;
     step: StepService;
     submission: SubmissionService;
+    userProgress: UserProgressService;
 }
 
 type AcademeKeycloakContextProps = {