Surveys

Status: 🔵 MVP (modo anônimo entregue, devolutivas IA em produção) Code: backend/app/modules/surveys UI: frontend/src/app/(admin)/[slug]/admin/surveys + frontend/src/app/(public)/s Última revisão deste doc: 2026-05-13 por Felipe + Claude Dependências fortes: fonte da biblioteca de instrumentos (consumida por NR-01)

1. Identidade

O que faz (uma frase)

Pesquisas identificadas (mentoria, lead, checkin) e anônimas (NR-01, clima cego), com biblioteca compartilhada de instrumentos psicométricos (COPSOQ-III, CBI, ERI, BAT, GHQ-12), devolutivas IA aprovadas por operador, e conformidade LGPD nativa (anti-reID, retention policy).

Por que existe (negócio)

Mais Consciente faz pesquisas regulares (NPS, mentoria pós-aula, clima organizacional). Sem este módulo:

• Google Forms sem IA + sem LGPD adaptada.
• Devolutivas manuais.

Com Surveys:

• Modo anônimo blindado (rejeita PII em schema + trigger DB).
• Biblioteca de instrumentos validados (catálogo global tenant_id=NULL).
• Devolutiva IA: rascunho → operador revisa/aprova → enviada → lida.

Status atual

MVP em prod. Funcionalidades anônimas validadas no projeto NR-01 Colorado (memória [[nr01-colorado]]).

Próxima mudança: Sprint 4 — analytics anti-reID com n<5 cell hiding.

2. Cases de uso reais

Case 1: Pesquisa identificada (mentoria)

Aluno responde form /r/surveys/mentoria-pos-aula → answers + submission identificada (email, member_id) → IA gera survey_devolutiva rascunho → operador revisa em /admin/surveys/devolutivas → aprova → membro lê em /me/devolutivas.

Case 2: Pesquisa anônima (NR-01 base)

Aluno acessa link → session_token UUID gerado client-side → submission sem email/IP/member_id (trigger DB rejeita) → answers ligadas a session_token → submit → survey_dimension_score calculado → analytics agregada.

Case 3: Biblioteca de instrumento

Operador cria form com source_type=from_instrument, base_instrument_id=copsoq-iii → questions auto-importadas com source_item_id → respondendo, dimension resolvida automaticamente.

3. Oportunidades de negócio

• Vertical surveys (RH, saúde, educação): templates pré-aprovados.
• NR-01 as a service: módulo dedicado pra empresas obrigadas pela NR-01 (memória [[nr01-consultoria]]).
• Anti-reID compliance: premium feature pra setores regulados.
• Devolutiva IA: "consultoria automática" pós-pesquisa.

4. Arquitetura interna

Arquivos

• models.py — 16 tabelas.
• service.py — CRUD + IA.
• service_instrument.py — biblioteca.
• routes.py — 39 endpoints.

5. Tabelas (16)

Forms + Submissões + Answers (4)

• survey_form: mode (identified/anonymous), source_type (from_instrument/custom/hybrid), status, retention_until, consent_term_version, lgpd_*.
• survey_question: tipo (short_text/long_text/choice/scale/...), source_item_id (opcional da biblioteca), dimension_id.
• survey_submission: session_token (anônimo) ou respondent_email/member_id (identificado), confirmation_token workflow.
• survey_answer: text/numeric/options/json.

Devolutiva (3)

• survey_devolutiva: workflow ai_draft → em_revisao → aprovado → enviado → lido. mentor_vision + operator_notes privados.
• survey_ai_instruction: instruções de tom/análise customizadas (tom_de_voz/etc.).
• survey_reference_file: contexto pra IA (PDFs).

Biblioteca de Instrumentos (4)

• survey_dimension: demandas, controle, apoio, etc. tenant_id=NULL é catálogo global.
• survey_item: item reutilizável (texto, tipo, scale, reverse_coded, source_instrument_slug).
• survey_instrument: preset (COPSOQ-III, CBI, ERI, BAT, GHQ-12), scoring_definition JSONB, versão semver.
• survey_instrument_item: junção instrument↔item com posição + dimensão.

LGPD + Demographic + Scoring + Retention (5)

• survey_demographic_config: unit, area, tenure_band, role_level. anti_reid_min_n=5.
• survey_demographic_answer: respostas demográficas separadas (agregáveis sem reID).
• survey_consent_log: SEM PII — apenas timestamp + term_version + session_token.
• survey_dimension_score: raw + normalized [0-100], threshold_zone (green/yellow/red).
• survey_retention_policy: retenção + descarte automático.

Relacionamentos cross-módulo

6. API / Endpoints (39)

Prefixo /api/surveys. Endpoints compactos:

• Público: /public/{slug} submit (sem auth), confirm email.
• Admin forms (6): CRUD + activate/archive.
• Submissions (4): list, detail, export.
• Devolutivas (7): workflow completo (rascunho → aprovado → enviado → lido).
• AI instructions (4): CRUD.
• References (2): upload + list.
• Stats: agregados.
• Membro (6): ver próprias submissions + devolutivas.

7. Configuração

LGPD metadata em survey_form:

• lgpd_controller
• lgpd_legal_basis (consent / contract / legal)
• consent_term_text
• retention_until

8. Operações + Troubleshooting

Sintoma: Submit em form anônimo retorna 422

Causa: Cliente está enviando email/member_id (rejeitado pelo schema + trigger). Fix: Garantir frontend não envia esses campos em modo anonymous.

Sintoma: Devolutiva travada em em_revisao

Causa: Operador não aprovou. Fix: UI /admin/surveys/devolutivas → revisar + aprovar.

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

10. Histórico

MVP em prod desde Sprint 3. Memória [[nr01-estado-2026-05-11]] documenta entrega validada.