Programs (Cursos + Jornadas + Acervo)

Status: 🟢 Estável (currículo modular maduro) Code: backend/app/modules/programs UI: frontend/src/app/(admin)/[slug]/admin/programs + frontend/src/app/(member) Última revisão deste doc: 2026-05-13 por Felipe + Claude Dependências fortes: members (validar matrícula), intelligence (acervo NLP)

1. Identidade

O que faz (uma frase)

Currículo modular completo: programs (formações/cursos/mentorias) com hierarquia period → module → lesson + attachments, journeys paralelas (desafios, avaliações, experiências) com unlock diário, guides semanais estruturados e acervo colaborativo enriquecido por IA (transcript, temas, conceitos).

Por que existe (negócio)

Mais Consciente vende formações estruturadas (Yoga 200h, Mentoria Premium, etc.). Sem este módulo:

• Cursos seriam Notion/Loom soltos sem progresso.
• Jornadas (28 dias do student_mirror) seriam manuais.
• Acervo de aulas gravadas sem busca semântica.

Com Programs:

• Aluno acessa /clube/programs/{slug} → progresso visível.
• Watched_pct nunca rebaixa (monotônico) → completion automática.
• Jornadas com unlock diário (gamification leve).
• Acervo: pesquisa semântica via embeddings (NLP) — "tudo sobre meditação".

Status atual

Estável, em prod desde Suite v2.

2. Cases de uso reais

Case 1: Aluno assiste vídeo

UI player → POST /progress/lesson (pos, watched_pct, watch_count) → ProgramLessonProgress upsert → se watched_pct ≥ 100, marca lesson concluída → recompute enrollment.progress_pct.

Case 2: Jornada 28 dias

Aluno matricula em journey(slug=meditacao-28-dias) → JourneyEnrollment cria → cada dia (1..28), agente student_mirror libera novo JourneyDay (audio + exercício) → tracking via journey_day_progress.

Case 3: Acervo busca semântica

Aluno digita "respiração consciente" → backend chama embeddings → retorna acervo_item ordenados por similaridade.

3. Oportunidades de negócio

• Whitelabel courses platform: vender currículo como SaaS standalone (concorrente Hotmart/Kajabi).
• AI-generated curriculum: input "quero curso de yoga 8 semanas" → backend gera program + periods + modules + lessons template.
• Cohort mode: turmas com data fixa + chat dedicado.

4. Arquitetura interna

Arquivos

• models.py — 15 tabelas.
• routes.py — 54 endpoints.
• service.py — lógica de progresso.

Tasks

Sem Celery. Progress sync síncrono.

5. Tabelas (15)

Programa hierárquico (5)

• program: tipo (formacao/mentoria/curso/intensivo), cadência, rótulos customizáveis (3).
• program_period: período (semana/mes/etc.).
• program_module: módulo dentro do período.
• program_lesson: aula (vídeo/texto/exercício), total_lessons para completion.
• program_lesson_attachment: PDFs/links/recursos extras.

Cohorts + Enrollments + Progress (3)

• program_cohort: turma (started_at, status, max_seats).
• program_enrollment: matrícula, progress_pct calculado.
• program_lesson_progress: posição vídeo, watched_pct (monotônico — nunca rebaixa), watch_count.

Jornadas (4)

• journey: tipo (desafio/avaliacao/experiencia), total_days.
• journey_day: dia da jornada (audio_url, exercicio_md, duracao_min).
• journey_assessment: avaliação ao final.
• journey_enrollment: matrícula, unlock diário automático.

Guides + Acervo (3)

• guide: guia semanal estruturado (conteúdo JSONB).
• acervo_collection: biblioteca colaborativa.
• acervo_item: video/audio/texto/pdf com transcript_status (pending/processing/complete/failed), themes (NLP), concepts (NLP).

Relacionamentos cross-módulo

6. API / Endpoints (54)

Prefixo /api/programs. Lista compacta:

• Programs CRUD (5) + periods/modules/lessons/attachments (14).
• Cohorts + Enrollments (6).
• Progress (5) — incluindo POST /progress/lesson público (anon allowed).
• Journeys (9) — CRUD + days + assessments + enrollments.
• Guides (7).
• Acervo (13) — collections + items + search.

7. Configuração

Sem env vars. Rótulos customizáveis em program (period/module/lesson labels).

8. Operações + Troubleshooting

Sintoma: Vídeo "watched_pct" não atualiza

Causa: Player não está chamando /progress/lesson ou tenant não autenticado. Fix: Verificar logs programs.progress.received.

Sintoma: Acervo item invisível mesmo após upload

Causa: transcript_status=pending ou processing. Fix: Aguardar IA terminar (ou verificar transcript_status=failed).

9. Limitações e débitos técnicos

10. Histórico

Em prod desde Suite v2. Acervo NLP iterado em sprints.