Skip to content

Contrato — Perfil do Usuário

Contrato — Perfil do Usuário

Status: Implementado (atrás da feature flag helico_profile_editing, desligada por padrão) Termos: Perfil do Usuário Figma: Perfil (node 5934:49853)

Escopo

Este documento define os campos da tela Perfil do Usuário e o esboço dos endpoints que os servem. Cobre o Cartão do usuário (avatar, status), Dados pessoais, Sobre mim, Formação Acadêmica e Currículo Lattes — além da arquitetura de persistência, sincronização com Moodle, o alerta de perfil incompleto, os endpoints (GET + PATCH parcial) e a feature flag que os protege.

Fora de escopo deste doc: a seção Roteiro de Estudos (horas semanais + histórico de alterações) já está implementada — ver study.md / onboarding.md; a ação “Deletar conta”, que é um fluxo próprio, não um campo de formulário; e sincronizar o avatar com o Authentik, decisão explícita de não fazer (ver Upload de avatar).

Hoje o composable mais próximo é profile_view_dto, que só carrega user_id, fullname, email, matrículas ativas e plan_settings — nenhum dos campos abaixo (CPF, gênero, celular, formação acadêmica, hobbies etc.) existe hoje em nenhuma tabela do local_helico nem em campo nativo do Moodle usado pela plataforma. São todos net-new.

Convenção de tipos

Tipo Significado
string Texto livre
enum Conjunto fechado de opções — ver Enums
date Data completa, ISO 8601 (YYYY-MM-DD)
boolean Verdadeiro/falso
array<string> Lista de strings
array<object> Lista de registros (objeto com campos próprios)
file Upload de arquivo — não é campo JSON normal, fluxo próprio (ver Upload de avatar)
vo Value Object tipado (ver Value Objects) — usado sempre que o dado é composto (mais de um valor junto). Nunca array solto nem objeto/JSON sem tipagem.

Nomenclatura: nomes de campo (Campo) em inglês — convenção do backend (ver profile_view_dto atual: user_id, fullname, email…). Labels e descrições ficam em PT-BR, como o resto da doc (convenção do repo).

Cartão do usuário (sidebar, comum a todas as sub-telas)

Campo Tipo Obrigatório Descrição
avatar file Não Foto de perfil (upload via ícone de câmera sobre o avatar). Ver Upload de avatar.
status enum Não “Como você se sente hoje?” — ver Enums → status.

Nome exibido abaixo do avatar é derivado de Dados pessoais.full_name — não é campo próprio.

Upload de avatar

Upload de arquivo, dois passos — o passo 1 reusa o webservice nativo do Moodle (upload de draft file, genérico, nada de avatar nele); o passo 2 é endpoint próprio do local_helico (não mais a wsfunction nativa direto — ver “Por que não a wsfunction nativa direto” abaixo):

  1. Frontend sobe o arquivo pro draft file area do usuário via webservice/upload.php (endpoint padrão do Moodle pra upload autenticado por wstoken) → recebe um draftitemid.
  2. Frontend chama POST /api/v1/platform/profile/avatar (profile_api_controller::update_avatar()) com {draftitemid, delete} — delega em core_user_external::update_picture() em-processo (chamada PHP direta, não via webservice/rest/server.php) e, se salvar com sucesso, despacha avatar_updated_signal (assíncrono) pro sync com o Authentik (ver “Sincronização com o Authentik” abaixo).

Testado de ponta a ponta contra o dev DB (usuário real, imagem de teste, Authentik real) — os passos abaixo são o request/response exatos, não hipotéticos.

Passo 1 — POST /webservice/upload.php (multipart, não JSON):

token=<wstoken>
filepath=/
file_1=<binário>

Resposta (200, array — um item por arquivo enviado):

[
  {
    "component": "user",
    "contextid": 291,
    "userid": "36",
    "filearea": "draft",
    "filename": "avatar.png",
    "filepath": "/",
    "itemid": 729469317,
    "license": "allrightsreserved",
    "author": "Karina Lopes",
    "source": "O:8:\"stdClass\":1:{s:6:\"source\";s:15:\"avatar.png\";}",
    "filesize": 69
  }
]

itemid é o draftitemid do passo 2.

Passo 2 — POST /api/v1/platform/profile/avatar:

{
  "draftitemid": 729469317,
  "delete": false
}

Resposta (200):

{
  "data": { "success": true },
  "success": true
}

Não traz avatar_url — Passo 3, depois de success: true: chamar GET /api/v1/platform/me de novo e usar o avatar_url de lá (ver me.md), que já vem pronta (tokenpluginfile.php + includetoken, funciona sem sessão). GET /profile (wire_with_avatar()) também expõe avatar_url corrigida, mas está atrás da feature flag helico_profile_editing — /me é a fonte confiável independente da flag.

user_id explícito via query string (mesmo padrão do GET/PATCH desta classe) edita outro usuário — checagem de capability é a própria resolve_target_user_id() compartilhada (moodle/user:editprofile).

Por que não a wsfunction nativa direto (core_user_update_picture via webservice/rest/server.php)? Duas razões, achadas implementando:

  1. core_user_external::update_picture() monta profileimageurl via user_picture::get_url($PAGE) sem includetoken — URL pluginfile.php baseada em sessão/cookie, nunca carrega pro Frontend (só tem wstoken). É código vendor, não dá pra corrigir direto.
  2. O Moodle não dispara nenhum evento quando o avatar muda — core_user::update_picture() (lib/classes/user.php) só faz $DB->set_field('user', 'picture', ...) cru, sem user_update_user(), sem hook, sem \core\event\user_updated. Sem gancho nativo, não tinha como disparar o sync assíncrono com o Authentik a partir de uma chamada nativa feita direto pelo Frontend — daí o endpoint próprio, que processa em-processo e dispara o sinal logo depois.

Gotcha de implementação: core_user_external (a classe do user/externallib.php) não é autoloaded fora do dispatch nativo do webservice — só external_api::call_external_function() faz o require_once dela. Chamar a classe direto (como o endpoint acima faz) precisa do mesmo require_once($CFG->dirroot . '/user/externallib.php') manual, senão dá Class "core_user_external" not found.

Pré-requisito de configuração: webservice/upload.php (passo 1) recusa o upload se o serviço do wstoken (helico_platform) não tiver a flag uploadfiles ligada — WebServiceDefinition não expõe esse campo, então ele é declarado direto no array $services de services.php ('uploadfiles' => 1). functions: [] nesse serviço de propósito — nenhuma wsfunction nativa é mais chamada via webservice/rest/server.php por ele (ver ponto 2 acima).

Sincronização com o Authentik

Os dois sentidos foram implementados (revisão da decisão original de “não sincronizar” — ver histórico do doc):

Moodle → Authentik (escrita). avatar_updated_signal, assíncrono (outbox), consumido por avatar_authentik_sync_listener_service: lê o maior arquivo de user/icon, resolve o PK do Authentik via user.idnumber (identity_state_mirror_service), e chama authentik_client_interface::update_avatar($pk, $bytes, $mimetype) — grava attributes.avatar como Data URI (data:<mime>;base64,...), preservando attributes.helico e o resto. Roda inteiramente fora do request do Aluno — nem o round-trip HTTP nem uma indisponibilidade do Authentik podem travar o upload. Guarda anti-loop: não escreve se o Data URI já for idêntico (evita realimentar o webhook model_updated do Authentik, incidente #50 do módulo identity).

Authentik → Moodle (leitura/fallback). avatar_authentik_fallback_service, chamado de me_api_controller::me() e profile_api_controller::wire_with_avatar() sempre que o Moodle não tem avatar (user.picture == 0): busca attributes.avatar do Authentik e, se existir, decodifica o Data URI e salva como avatar real via process_new_icon() (a mesma função que core_user::update_picture() usa internamente). Só tenta uma vez por usuário — marcador em user preference (local_helico_authentik_avatar_checked) grava ANTES de tentar, mesmo se falhar ou não achar nada, pra nunca bater no Authentik em toda chamada de quem genuinamente não tem foto lá (a maioria dos Alunos reais — essa foto só existe pra contas de teste/staff que alguém colocou manualmente no Authentik, docker-authentik-helico/docs/decisions.md#avatares).

Testado de ponta a ponta contra o Authentik real: escrita confirmada lendo attributes.avatar de volta via authentik_connector::get(); leitura confirmada com demo04@helico.dev (tinha foto real no Authentik, nenhuma no Moodle — ensure_avatar_from_authentik() puxou e salvou, picture foi de 0 pra um itemid real, arquivo abre via HTTP).

avatar_url em /me//profile usa includetoken = <user_id explícito>, não includetoken = true — true resolve pro $USER GLOBAL (make_pluginfile_url()), que só coincide com o alvo quando não é edição por admin; passar o ID explícito evita esse bug latente no caso de admin editando o perfil de outro usuário.

Dados pessoais

Campo Tipo Obrigatório Descrição
full_name string Sim Nome completo. Grava split em firstname+lastname do Moodle — não é escolha, é a própria tabela user nativa que não tem coluna única de nome completo.
gender enum Não Ver Enums → gender.
birth_date date Sim Input com ícone de calendário, exibido como DD/MM/AAAA.
cpf string Sim Documento, máscara 000.000.000-00. Validação de formato via Middag\Core\Validation\DocumentNumberValidator::isValid($cpf, 'BR', 'cpf') (já existe, reusar). Unicidade — ver CPF: validação e unicidade.
email string Sim E-mail primário (user.email do Moodle). Hint no protótipo: “Este é o e-mail necessário para acessar o sistema.” — somente leitura: aparece no form mas não é gravável por este endpoint. Trocar e-mail de login é fluxo próprio, fora de escopo aqui.
secondary_email string Não E-mail alternativo, sem validação de login associada. Editável. Sem coluna nativa no Moodle — fica só no EAV do local_helico.
mobile_phone vo Sim phone_number_vo (country_code + number, com __toString() formatado). Mapeia pra user.phone2 (coluna nativa do Moodle — phone1/phone2 já existem em lib/db/install.xml).

Formação Acadêmica

array<object> — lista de formações do usuário, cada uma com CRUD próprio (editar via lápis, excluir via lixeira, criar via botão “Adicionar Formação” → modal “Adicionar formação academica”). Sem campo de “situação” (cursando/concluído) no protótipo — datas resolvem isso (término vazio/futuro = em andamento).

Campo Tipo Obrigatório Descrição
institution string Sim Nome da instituição de ensino, texto livre. Não confundir com user.institution (coluna nativa do Moodle, campo livre de afiliação institucional do usuário — conceito diferente, não usar).
degree_type enum Sim Select fechado — ver Enums → degree_type.
start_date vo Sim month_year_vo (mês + ano, sem dia). Selects separados de Mês e Ano no Figma.
end_date vo Sim month_year_vo — “Data de término (ou prevista) *”; aceita data futura (formação em andamento).
description string Não Textarea livre.

Currículo Lattes

Campo Tipo Obrigatório Descrição
lattes_url string Não Provavelmente URL do currículo Lattes. Confirmar se precisa validação de formato (URL lattes.cnpq.br).

Sobre mim

Campo Tipo Obrigatório Descrição
nickname string Não “Como você prefere ser chamado?”
occupation string Não “Qual é sua profissão ou ocupação atual?” — desabilitado/limpo quando has_no_occupation = true.
has_no_occupation boolean Não Checkbox “Atualmente não estou exercendo nenhuma profissão.” — mutuamente exclusivo com occupation.
children_count enum Não Seletor de chips de opção única: 0, 1, 2, 3, 4+.
exercise_frequency enum Não Seletor de chips de opção única: Não pratico, 1–2x por semana, 3–4x por semana, 5x ou mais.
hobbies array<string> Não Tags multi-seleção. Catálogo aberto — dropdown com sugestões pré-definidas (ver Enums → hobbies) + opção de digitar um valor livre quando não está na lista.
bio string Não “Fale um pouco sobre você” — textarea longa. Mapeia pra user.description (coluna nativa do Moodle, mesmo propósito — decisão tomada).

Enums

Valores fechados dos campos enum. Chave (value) em inglês/snake_case pra uso no backend e no contrato da API; label é o texto exibido no Figma.

children_count

Chips de opção única, campo Sobre mim.

value label
0 0
1 1
2 2
3 3
4_plus 4+

exercise_frequency

Chips de opção única, campo Sobre mim.

value label
none Não pratico
weekly_1_2 1–2x por semana
weekly_3_4 3–4x por semana
weekly_5_plus 5x ou mais

status

Dropdown, campo do cartão do usuário (“Como você se sente hoje?”). Fechado, sem texto livre.

value label
great Ótimo
good Bem
neutral Neutro
bad Mal
terrible Péssimo

gender

Dropdown, campo Dados pessoais. Fechado, sem texto livre (diferente de hobbies).

value label
male Masculino
female Feminino
non_binary Não binário
prefer_not_to_say Prefiro não informar
other Outro

degree_type

Select fechado, campo Formação Acadêmica. Sem texto livre.

value label
technical Técnico
technologist Tecnólogo
bachelor Bacharelado
licentiate Licenciatura
specialization Especialização
mba MBA
master Mestrado
doctorate Doutorado
postdoctoral Pós-doutorado

hobbies

Igual aos outros enums da lista (value inglês/snake_case pro backend, label PT-BR exibido). Diferença: é um catálogo aberto — o campo hobbies (array<string>) guarda uma lista de values daqui; se o usuário digitar algo fora da tabela, entra como texto livre (sem value — grava o texto exatamente como digitado). Não precisa de flag “é catálogo ou é livre”: um valor bate com algum value da tabela ou não bate, e pronto.

Mantido como constante em código (enum ou const array no service), sem tabela própria — não há indício de necessidade de administração via UI por enquanto (YAGNI). Se isso mudar (ex. time de conteúdo precisar editar sem deploy), migra pra EAV (item_type novo) depois.

value label value label
football Futebol crochet Crochê
running Corrida knitting Tricô
walking Caminhada sewing Costura
gym Academia woodworking Marcenaria
yoga Yoga handicrafts Artesanato
pilates Pilates calligraphy Caligrafia
swimming Natação video_games Jogos eletrônicos
cycling Ciclismo board_games Jogos de tabuleiro
martial_arts Artes marciais chess Xadrez
volleyball Vôlei technology Tecnologia
basketball Basquete programming Programação
tennis Tênis cooking Culinária
surfing Surfe traveling Viagens
climbing Escalada gardening Jardinagem
reading Leitura movies Cinema
writing Escrita tv_shows Séries
poetry Poesia podcasts Podcasts
playing_instrument Tocar instrumento volunteering Voluntariado
listening_to_music Ouvir música meditation Meditação
singing Canto languages Idiomas
drawing Desenho fishing Pesca
painting Pintura camping Acampamento
photography Fotografia pets Animais de estimação
dancing Dança collecting Colecionismo
theater Teatro astronomy Astronomia

Value Objects

Requisito de arquitetura: nenhum campo composto vira array solto ou objeto/JSON sem tipagem. Todo campo que junta mais de um valor é um Value Object dedicado — final readonly class, snake_case (convenção do plugin, não PascalCase de lib), auto-validando no construtor, numa pasta vo/ nova (irmã de dto/, entity/, enums/ nos domínios existentes — ex. classes/extensions/platform/vo/).

VO Campos Usado em
month_year_vo int $month (1–12), int $year start_date, end_date (Formação Acadêmica)
phone_number_vo string $country_code, string $number mobile_phone
academic_formation_vo ?int $id, string $institution, degree_type $degree_type, month_year_vo $start_date, month_year_vo $end_date, ?string $description academic_formations[] — shape usado no service/API (GET, diff do PATCH); não precisa de entity EAV própria além do item genérico — basta virar esse VO quando for lido/usado.

hobbies continua array<string> — isso não fere a regra: é uma lista homogênea de escalares tipados (string[]), não um array associativo/JSON solto. A regra de “nada de array/JSON sem tipagem” é sobre estrutura heterogênea (tipo o plan_settings do profile_view_dto atual, que é um blob decodificado de JSON sem shape definido) — Formação Acadêmica em si (array<object>) também é coberta: cada item vira academic_formation_vo quando usado, não array cru.

Arquitetura de persistência

EAV do local_helico é a fonte canônica (ADR-10) — é de lá que a API lê de volta pro form. Campos com equivalente nativo/custom-field no Moodle são espelhados de forma assíncrona, não gravados só lá.

EAV (fonte canônica)

  • Item type user_profile (1 por usuário) — carrega gender, birth_date (via meta), secondary_email, mobile_phone (serializado como string do phone_number_vo), status, lattes_url, nickname, occupation, has_no_occupation, children_count, exercise_frequency, hobbies, bio. cpf vai no campo nativo idnumber de helico_items (não em helico_itemmeta) — ver CPF.
  • Item type user_academic_formation (N por usuário, parent = item id do user_profile) — institution, degree_type, start_date, end_date, description. Segue o mesmo padrão de hierarquia parent que outras entities do engine já usam (ver ADR-10). Concreto: cada formação é uma linha em helico_items (type = user_academic_formation, userid = dono, parent = id da linha user_profile), com seus campos escalares em helico_itemmeta (uma linha por meta_key, ex. itemid=101, meta_key=institution, meta_value=USP) — nada de tabela nova. Sem espelho no Moodle — user_info_field/user_info_data é um valor escalar por (usuário, campo), sem conceito de lista/repetição; não tem como um array<object> caber nesse modelo. Fica só no EAV.
  • full_name e email não duplicam no EAV — são só user.firstname/ user.lastname/user.email, lidos direto da tabela user (como profile_view_service já faz hoje).
  • Histórico vem de graça: ItemService::create()/update()/delete() (base EAV, middag-php-core) chamam ItemRevisionService::createRevision() incondicionalmente nas três operações, e createFromItem() grava snapshot em helico_item_revision + todos os metadados em helico_item_revision_meta. Contanto que a escrita do Perfil (e de cada Formação Acadêmica) passe pelo ItemService padrão — não por SQL direto — toda alteração já gera revisão completa automaticamente, sem código extra.

Espelho no Moodle (assíncrono, via evento)

Campo Destino Moodle Tipo de destino
full_name user.firstname / user.lastname Coluna nativa (grava síncrono, é a mesma escrita que já existe pro update de usuário)
email (não gravado) Somente leitura — endpoint expõe user.email na resposta mas rejeita alteração no payload de escrita (422 validation_error, ver Erros).
cpf user_info_field/user_info_data, shortname cpf, datatype text Custom field net-new, categoria “Perfil HÉLICO” (nova, criada idempotente em db/upgrade.php — check-then-insert, sem duplicar se já existir). Reusa o mesmo campo que profileguard_userfield já aponta, quando configurado (decisão já tomada — evita CPF duplicado/divergente do gate de compliance do local_middag); se profileguard_userfield estiver configurado com outro shortname num ambiente específico, o admin reaponta a config pro shortname cpf — não o contrário.
gender user_info_field/user_info_data, shortname gender, datatype menu Custom field net-new, categoria “Perfil HÉLICO”. Opções (param1, uma por linha) = os 5 valores de Enums → gender.
birth_date user_info_field/user_info_data, shortname birth_date, datatype datetime Custom field net-new, categoria “Perfil HÉLICO”. Tipo nativo do Moodle pra data.
mobile_phone user.phone2 Coluna nativa (já existe, sem precisar criar nada).
bio user.description Coluna nativa (já existe, sem precisar criar nada).

O espelho roda fora do request de save: o service de escrita do Perfil grava no EAV (síncrono, é a fonte de verdade) e dispara um sinal — profile_data_updated_signal (nome sugerido, implements AsyncSignalInterface, payload flat: user_id, e os campos que mudaram) — via SignalDispatcher. Um listener dedicado consome com #[AsyncOn(signal: profile_data_updated_signal::class)] (atributo real, já usado no repo — Middag\Core\Bus\Signal\Attribute\AsyncOn, ver enrolment_reset_and_complete_onboarding_listener_service como referência de padrão) e faz a escrita no Moodle usando o facade que já existe (local_middag\base\facade\moodle\user_field_support::save_user_data() pros custom fields; user_update_user() pras colunas nativas). Isso deixa o listener como o único ponto de acoplamento com local_middag/Moodle nativo, e qualquer outro consumidor (relatórios, sync externo) também pode assinar o mesmo sinal sem tocar no service de escrita do Perfil.

Sincronização reversa (Moodle → EAV)

Edição pode acontecer fora da tela de Perfil — admin editando o usuário direto no Moodle, SSO reenviando atributos, outro plugin gravando em user_info_data. Quando isso acontece nos campos espelhados (cpf/gender/birth_date/mobile_phone/bio), o EAV (fonte canônica) fica desatualizado se nada reagir.

O padrão do repo pra escutar evento nativo do Moodle não é assinar \core\event\user_updated direto num #[On]/#[AsyncOn] — é dois hops, confirmado no código de enrolment (que escuta user_enrolment_created pra criar matrícula, ver moodle_enrolment_created_signal): uma classe *_signal implementando AggregateSignalInterface, decorada #[MoodleEvent(\core\event\X::class)], que embrulha o evento cru (public base $event); o service assina essa classe própria (#[On(...)] síncrono ou #[AsyncOn(...)]), nunca o evento do Moodle. Aqui, cria-se moodle_user_updated_signal (#[MoodleEvent(\core\event\user_updated::class)], aggregate = 'moodle_user', type = 'user', action = Signal::Update) e um listener novo assina #[On(Signal::Update, type: 'user', aggregate: 'moodle_user')] — síncrono, não #[AsyncOn]: o atributo AsyncOn só aceita signal: <FQCN de uma classe AsyncSignalInterface>, sem type/aggregate (dispara por FQCN exato, não por tupla (aggregate, type, action)); um AggregateSignalInterface como este só é endereçável via #[On], mesmo padrão do enrolment_service pro moodle_enrolment_created_signal — e, quando o campo alterado é um dos espelhados, normaliza/valida o valor (mesma lógica do seed — DocumentNumberValidator pro cpf, phone_number_vo pro mobile_phone, parse de data pro birth_date; falha = loga e não grava, não derruba o listener) e só então atualiza o meta correspondente no item user_profile via ItemService::update() — mantendo o histórico automático (ver Histórico vem de graça).

Risco de loop não é igual pra todos os campos — confirmei no core do Moodle (user/lib.php, user/profile/lib.php, user/editadvanced.php):

  • Edição pela tela normal do Moodle (user/edit.php/editadvanced.php, qualquer campo, core ou custom) sempre dispara user_updated — o form chama user_update_user($usernew, false, false) com o evento suprimido (3º parâmetro), salva os custom fields (profile_save_data()), e só depois dispara \core\event\user_updated::create_from_userid()->trigger() manualmente, uma vez, de propósito, cobrindo os dois grupos de campo junto (comentário no source: “Trigger update/create event, after all fields are stored”). Ou seja: admin editando cpf/gender/birth_date pela tela do Moodle dispara sim e a sincronização reversa pega — o evento não carrega o valor do custom field no payload, então o listener precisa ler user_info_data à parte pra pegar o valor atual.
  • Nosso próprio mirror EAV→Moodle: pra mobile_phone/bio (colunas nativas) chama user_update_user() direto → dispara user_updated → re- aciona o listener reverso (risco de loop real). Por isso ele compara antes de escrever (skip se o meta atual já bate com o valor do evento). Pra cpf/gender/birth_date (custom fields) chama user_field_support::save_user_data() → profile_save_custom_fields() direto, pulando o form inteiro e o trigger manual do evento — não dispara nada, zero risco de loop por esse caminho.
  • Lacuna real, estreita: só existe pra quem grava custom field via API de baixo nível fora do form (não dispara evento nenhum) — é o caso do field_mapping_signal_handler (checkout) mexendo num custom field de usuário já existente (fora da criação). Esse caso específico não é capturado pela sincronização reversa. Provisão de usuário novo não conta aqui — user_created cobre isso separadamente (ver seed abaixo).

full_name e email não precisam de nada disso: nunca duplicam no EAV (lidos direto de user.firstname/lastname/email), então uma edição Moodle-side já “sincroniza” sozinha, por construção.

Seed inicial na criação do usuário

Mesmo mecanismo, evento \core\event\user_created — cobre qualquer caminho de criação (a provisão via e-commerce já existe em helico_provision_user_signal_handler/identity_resolver_service, mas criação também acontece por SSO no primeiro login, admin manual, CLI/import; o evento nativo do Moodle cobre todos, não só o caminho e-commerce). No user_created, cria o item user_profile (idempotente — check-then-create, já que mais de um caminho de provisão pode, em teoria, competir) semeado com o que já existir nos campos nativos naquele momento.

Correção importante: cpf/birth_date/mobile_phone não nascem necessariamente vazios. Achei local_middag\extensions\ecommerce\listener\field_mapping_signal_handler — roda no mesmo fluxo de provisionamento (ecommerce_user_provisioned), mapeamento configurável por loja (store->getMeta('field_mapping'), external_field → moodle_field), e escreve $customer_data[$external_field] direto em user_update_user() — sem nenhuma normalização/validação. Se uma loja mapear CPF/telefone/data de nascimento do checkout pra profilefield_<id>/phone2, esses campos já chegam preenchidos no user_created — só que sujos (CPF com pontuação, telefone em qualquer formato, data em string livre) e, no caso do CPF, sem checar unicidade (escreve em user_info_data, nunca passa pelo índice único de helico_items.idnumber).

Por isso o seed normaliza antes de gravar no EAV, nunca copia valor cru:

  • cpf → DocumentNumberValidator::normalize() + isValid(); se inválido ou colide com outro idnumber já existente (unique constraint), não grava o campo no EAV (loga/reporta — mesmo padrão de sentry_service::debug() já usado em outros listeners assíncronos do repo) e segue sem CPF — usuário completa depois pela tela de Perfil, que aí sim valida no fluxo síncrono normal.
  • mobile_phone → tenta construir phone_number_vo a partir do valor cru; se não parsear, mesmo tratamento (não grava, loga, segue vazio).
  • birth_date → mesma lógica com parse de data.
  • gender não tem esse risco — não há mapeamento de checkout típico pra gênero, mas o seed trata do mesmo jeito por uniformidade (se algum dia vier de algum lugar, também passa por validação antes de virar meta).

Essa mesma regra de “normalizar/validar antes, nunca gravar cru” vale pro listener de sincronização reversa (seção anterior) também — qualquer valor vindo do lado Moodle (seed ou edição posterior) passa pelas mesmas validações do fluxo de escrita normal do Perfil antes de tocar o EAV.

Nota pra não confundir: identity_state_mirror_service (módulo identity já existente) grava o PK do Authentik em user.idnumber — coluna nativa do Moodle. Não tem relação com o idnumber de helico_items usado pro CPF (ver seção seguinte) — são tabelas e conceitos diferentes, mesmo nome de coluna.

CPF: validação e unicidade

  • Formato: reusar Middag\Core\Validation\DocumentNumberValidator::isValid($cpf, 'BR', 'cpf') (já existe em middag-php-core, usa respect/validation). Não reimplementar dígito verificador.
  • Unicidade: não existe hoje em nenhum lugar (nem o profileguard_service::update_user_field() do local_middag valida — só checa username duplicado, numa rota não-relacionada). Implementado como: gravar cpf (normalizado, só dígitos) na coluna idnumber de helico_items (já existe, char(191), comentário “Functional identifier used by integrations or extensions” — serve exatamente pra isso) do item user_profile. Sem índice único de banco — idnumber é um identificador genérico compartilhado por muitos outros item types no repo (discipline, notebook_artifact, exam_submission, slot etc.), então um índice (type, idnumber) tocaria dado de fora do escopo desta feature (decisão explícita do usuário, 2026-09-25). A unicidade é garantida só na aplicação: profile_service::validate_cpf() consulta por um user_profile existente com o mesmo idnumber antes de gravar e lança 422 validation_error se achar um de outro usuário; os listeners de seed/sincronização reversa fazem a mesma checagem antes de semear/sincronizar um CPF vindo do lado Moodle. Sem proteção de banco contra a race condition de dois saves simultâneos com o mesmo CPF — risco aceito.
  • Isso também é o valor que o listener assíncrono espelha pro user_info_field configurado (ver tabela acima) — sem unicidade nova ali, já que o Moodle não tem constraint nativa em user_info_data.data.

Alerta de perfil incompleto

Reusa o sistema de Alertas do Estudo já existente (GET /study/{enrolment_id}/alerts, local_helico\extensions\engine\alerts\*) — não é o mesmo sistema de “Notificações” do sino (esse é cross-product, notification_api_controller, coisa diferente). Alertas do Estudo é o motor de regras plugável (alert_rule_interface) que já gera CTAs como “Retome sua sessão”/“Correção pendente” — “Complete seu perfil” entra como mais uma regra.

Regra nova: profile_incomplete_rule

Segue o mesmo contrato das 5 regras existentes — evaluate(alert_context): ?alert_dto puro, sem I/O. Como as regras não podem chamar serviço nenhum, quem resolve “o perfil está incompleto?” é o alerts_generator_service::build_context(), do mesmo jeito que já faz pra retrospective_eligible (pré-resolvido antes de passar pro contexto).

  • alert_context ganha um campo novo: profile_missing_required_fields: array<string> (nomes de campo em inglês, ex. ['cpf', 'mobile_phone']; array vazio = perfil completo). Calculado por um profile_completeness_service novo (lê o item user_profile no EAV + user.firstname/lastname/email).
  • Campos considerados pra essa checagem (decisão revista — Formação Acadêmica e Gênero entram, ao contrário do que a primeira versão deste doc dizia): birth_date, cpf, mobile_phone, gender, academic_formations (full_name/email sempre vêm preenchidos, são a própria conta Moodle). academic_formations conta como preenchido com pelo menos 1 item — sem estado “não tenho formação” (diferente de occupation/has_no_occupation); quem tem só ensino médio fica com o alerta ativo até adicionar alguma formação.
  • Prioridade sugerida: 50 — depois de next_block_unlocked (40), já que é lembrete de baixa urgência comparado a ação de estudo pendente. Ajustável.
final readonly class profile_incomplete_rule implements alert_rule_interface
{
    public function get_id(): string { return 'profile_incomplete'; }
    public function get_priority(): int { return 50; }

    public function evaluate(alert_context $context): ?alert_dto
    {
        if ($context->profile_missing_required_fields === []) {
            return null;
        }

        return new alert_dto(
            id: $this->get_id(),
            title: 'Complete seu perfil',
            variant: alert_variant::WARNING,
            action_kind: action_kind::OPEN_PROFILE,
            action_label: 'Completar perfil',
            action_params: ['missing_fields' => $context->profile_missing_required_fields],
        );
    }
}

action_kind novo: open_profile

Não existe ainda em local_helico\extensions\engine\enum\action_kind. Segue o mesmo vocabulário semântico do resto (docs/.../actions.md):

kind params Mapeamento Frontend (referencial)
open_profile { missing_fields: string[] } /perfil (destaca os campos faltando)

Onde isso é registrado (quando for implementar)

  • Novo case em action_kind.php + linha na tabela de vocabulário em actions.md.
  • Novo campo profile_missing_required_fields em alert_context + resolução em alerts_generator_service::build_context() (nova dependência: profile_completeness_service_interface).
  • profile_incomplete_rule entra na lista default do construtor de alerts_generator_service, junto das outras 5.
  • Linha nova na tabela de regras/prioridades de study.md.

Endpoints

2 endpoints só — GET (dados + opções pra preencher os campos fechados, mesmo padrão que onboarding.md já usa — options: [{value, label}] junto com os dados) e PATCH parcial. Formação Acadêmica não é sub-recurso próprio — o botão único “Salvar Alterações” manda o formulário inteiro, academic_formations incluído, então vira só mais uma chave do mesmo PATCH (backend faz o diff, ver abaixo). O lápis/lixeira por item no Figma mexe no estado local do form no Frontend; a persistência de verdade só acontece no PATCH, junto com o resto.

Método Path Função
GET /api/v1/platform/profile Dados salvos + options dos campos fechados
PATCH /api/v1/platform/profile Atualiza só os campos enviados no payload

Upload de avatar continua fora disso — é o fluxo de 2 passos já documentado em Upload de avatar (webservice nativo do Moodle), não um campo do PATCH (arquivo binário não cabe em JSON, e o Moodle já resolve isso sozinho).

GET /profile — Response 200

{
  "data": {
    "avatar_url": "https://plataforma.helico.com.br/avatar/42.jpg",
    "status": "good",
    "full_name": "João Silva",
    "gender": "male",
    "birth_date": "1996-11-08",
    "cpf": "98123148298",
    "email": "joao@exemplo.com",
    "secondary_email": null,
    "mobile_phone": { "country_code": "BR", "number": "11998765432" },
    "academic_formations": [
      {
        "id": 1,
        "institution": "USP",
        "degree_type": "bachelor",
        "start_date": "2015-01",
        "end_date": "2019-12",
        "description": null
      }
    ],
    "lattes_url": null,
    "nickname": "Silva",
    "occupation": "Advogado",
    "has_no_occupation": false,
    "children_count": "2",
    "exercise_frequency": "weekly_1_2",
    "hobbies": ["football", "yoga"],
    "bio": null
  },
  "options": {
    "status": [{ "value": "great", "label": "Ótimo" }, "..."],
    "gender": [{ "value": "male", "label": "Masculino" }, "..."],
    "degree_type": [{ "value": "bachelor", "label": "Bacharelado" }, "..."],
    "children_count": [{ "value": "0", "label": "0" }, "..."],
    "exercise_frequency": [{ "value": "none", "label": "Não pratico" }, "..."],
    "hobbies": [{ "value": "football", "label": "Futebol" }, "..."]
  }
}

options é o conteúdo literal das tabelas em Enums — mesmo value/label, backend nunca manda a lista errada porque é a mesma fonte (enum::cases() de cada campo). mobile_phone serializa o phone_number_vo como objeto {country_code, number} na API (o VO é interno; ver Value Objects — a API não usa string formatada solta).

Schema — data

Referência campo a campo do wire format, tanto na resposta do GET quanto no corpo do PATCH (mesmas chaves nos dois — PATCH é só um subconjunto). Aceito no PATCH = Não significa 422 se a chave aparecer no payload; os outros campos simplesmente são ignorados/sobrescritos se enviados fora do schema (chave desconhecida → 422 validation_error, não passa silenciosa).

Chave Tipo JSON Nulo? Formato / valores aceitos Aceito no PATCH
avatar_url string Não URL absoluta Não — ver Upload de avatar
status string | null Sim value de Enums → status Sim
full_name string Não texto livre Sim
gender string | null Sim value de Enums → gender Sim
birth_date string | null Sim YYYY-MM-DD (ISO 8601) Sim
cpf string | null Sim 11 dígitos, sem máscara (98123148298, não 981.231...) Sim
email string Não e-mail Não — 422 validation_error se presente
secondary_email string | null Sim e-mail Sim
mobile_phone object | null Sim { country_code: string, number: string } Sim
academic_formations array<object> Não (array vazio, não null) ver sub-schema abaixo Sim — diff por id, ver academic_formations — diff por id
lattes_url string | null Sim URL Sim
nickname string | null Sim texto livre Sim
occupation string | null Sim texto livre; ignorado/limpo se has_no_occupation = true Sim
has_no_occupation boolean Não — Sim
children_count string | null Sim value de Enums → children_count Sim
exercise_frequency string | null Sim value de Enums → exercise_frequency Sim
hobbies array<string> Não (array vazio, não null) value do catálogo Enums → hobbies OU texto livre Sim
bio string | null Sim texto livre Sim

Sub-schema — item de academic_formations[]

Chave Tipo JSON Nulo? Formato / valores aceitos
id integer omitido/null = item novo id existente = atualiza (ver diff por id)
institution string Não texto livre
degree_type string Não value de Enums → degree_type
start_date string Não YYYY-MM (mês+ano, sem dia)
end_date string Não YYYY-MM
description string | null Sim texto livre

start_date/end_date como YYYY-MM é a serialização de wire do month_year_vo (o VO é interno — ver Value Objects — sobre o fio sempre string, nunca {month, year} objeto solto).

Schema — options

Chave Tipo JSON Conteúdo
status array<{value, label}> igual Enums → status
gender array<{value, label}> igual Enums → gender
degree_type array<{value, label}> igual Enums → degree_type
children_count array<{value, label}> igual Enums → children_count
exercise_frequency array<{value, label}> igual Enums → exercise_frequency
hobbies array<{value, label}> igual Enums → hobbies — só o catálogo, texto livre não aparece aqui (não tem value pra listar)

options só existe no GET — PATCH não devolve/aceita esse bloco.

PATCH /profile — parcial

Corpo é um subconjunto de data — só as chaves que mudaram:

{ "mobile_phone": { "country_code": "BR", "number": "11991234567" } }
  • email não pode aparecer no payload — presente = 422 validation_error (errors[].field = "email"), mesmo vazio. Fail loud, não ignora silenciosamente (silêncio esconde erro de integração do Frontend).
  • Campos não citados no payload não mudam — não é PUT, não substitui o objeto inteiro.
  • Response 200 devolve o data completo e atualizado (mesmo shape do GET), não só o que foi enviado — Frontend não precisa fazer merge manual.
  • Cada campo aplica sua própria validação (CPF formato+unicidade, VOs, enums fechados rejeitam valor fora da lista) antes de gravar — tudo síncrono no mesmo request; o espelho pro Moodle é que é assíncrono (ver Espelho no Moodle).

academic_formations — diff por id

Diferente dos outros campos (substituição direta), academic_formations é tratado como lista autoritativa quando a chave está presente no payload — o backend reconcilia contra o que já existe pro usuário, por id:

  • Item sem id → cria (POST implícito — novo user_academic_formation no EAV).
  • Item com id existente → atualiza os campos.
  • id existente que não aparece no array enviado → apaga.
  • Chave academic_formations ausente no payload → não mexe em nada (mesma regra geral de PATCH parcial — omitir ≠ esvaziar).
  • Cada create/update/delete individual ainda passa pelo ItemService padrão (create/update/delete), então cada formação continua ganhando histórico de revisão próprio — reconciliar em lote não perde o rastro por item (ver Histórico vem de graça).
  • IDOR guard, obrigatório: todo id recebido é validado contra parent = <id do item user_profile do usuário-alvo> (o autenticado, ou o de user_id quando é edição por admin) antes de tocar em qualquer coisa. id que existe mas pertence a outro usuário é tratado igual a id inexistente — 422 validation_error (nunca edita/apaga registro de outro usuário só porque o número bateu; nunca revela se o id existe ou é de outra pessoa).
{
  "academic_formations": [
    { "id": 1, "institution": "USP", "degree_type": "bachelor", "start_date": "2015-01", "end_date": "2019-12", "description": null },
    { "institution": "Estácio", "degree_type": "specialization", "start_date": "2021-03", "end_date": "2022-12", "description": null }
  ]
}

No exemplo: item id: 1 é atualizado (ou fica igual, se nada mudou); o segundo item (sem id) é criado; qualquer formação que o usuário tinha salva e não está nesse array é apagada.

Erros (GET e PATCH)

HTTP error Causa
401 unauthorized wstoken ausente/inválido
403 forbidden user_id informado mas quem chama não tem moodle/user:editprofile
404 feature_disabled Feature flag desligada — ver Feature flag
422 validation_error Qualquer campo inválido — email presente no PATCH, CPF mal formatado/duplicado, enum com valor fora da lista, VO malformado, academic_formations[].id de outro usuário. Sempre com errors[] detalhando campo a campo — ver abaixo.

Detalhe do 422

Mesmo shape que onboarding.md já usa — um error genérico

  • errors[] com o detalhe por campo (field usa dot/index path pra campos aninhados, ex. academic_formations[0].degree_type):
{
  "error": "validation_error",
  "message": "Campos inválidos.",
  "errors": [
    { "field": "email", "message": "Campo somente leitura — não pode ser enviado no PATCH." },
    { "field": "cpf", "message": "CPF inválido." },
    { "field": "academic_formations[0].degree_type", "message": "Valor fora da lista aceita." }
  ]
}

Edição por admin

Não existe hoje nenhum padrão de “admin edita perfil de outro usuário” no local_helico (o módulo admin que já existe é só ferramentas DEV de lifecycle — reset de matrícula, forçar CDA — nada de perfil). Em vez de criar endpoint/tela admin separada, o mesmo GET/PATCH ganha um user_id opcional — mesmo padrão que o próprio Moodle usa no webservice nativo de avatar (core_user_external::update_picture($draftitemid, $delete, $userid = 0), userid = 0 é o usuário autenticado, um id explícito edita outro usuário).

  • user_id ausente ou 0 → age no usuário autenticado (wstoken), fluxo normal do Aluno.
  • user_id explícito e diferente do autenticado → checa moodle/user:editprofile (a mesma capability nativa que core_user_external::update_picture() já usa pra esse caso) no contexto do usuário alvo; sem a capability, 403 forbidden. Com a capability, aplica no usuário alvo em vez de si mesmo.
  • Vale pros dois verbos, sem exceção — GET com user_id de outra pessoa também exige a capability (ler CPF/data de nascimento/celular de outro usuário sem permissão é vazamento de dado pessoal, não só escrita indevida). Não é feature “escreve com permissão, lê livre” — os dois checam igual, default-deny: qualquer user_id que não seja o do próprio wstoken é tratado como pedido de acesso a outro usuário e passa pela capability antes de tocar em qualquer dado, sem exceção pra rota nenhuma.
  • Cobre os dois grupos de campo igual: pros campos espelhados (cpf/gender/birth_date/mobile_phone/bio/full_name) o admin já conseguia editar via tela nativa do Moodle hoje (a sincronização reversa já documentada pega essa edição); pros campos EAV-only (nickname, occupation, hobbies, Formação Acadêmica etc.) o Moodle não tem onde editar — esse user_id no PATCH é o único jeito de um admin mexer neles, já que não são custom field.
  • Reusa toda a validação/normalização/histórico de revisão automático já desenhado — não é um caminho de código separado, só troca de qual usuário o ItemService está escrevendo.

Feature flag

A tela inteira de Perfil (leitura, escrita, e o alerta de perfil incompleto) fica atrás de uma feature flag — kill switch pra rollout gradual/desligar rápido se algo quebrar logo após o lançamento.

Reusa a infra de feature flags que já existe (classes/extensions/infra/feature_flags/, OpenFeature + AWS AppConfig Agent sidecar) — sem chamada nenhuma no local_helico ainda, mas o mecanismo está pronto: flags::get_bool(string $key, bool $default): bool.

  • Chave: helico_profile_editing.
  • Desligada → controller de GET/PATCH retorna 404 feature_disabled direto, antes de tocar em EAV/Moodle (kill switch real, não só esconder no Frontend).
  • profile_incomplete_rule (Alerta de perfil incompleto) também checa a flag — sem sentido cobrar perfil completo numa tela que está desligada.
  • Persistência (EAV, mirror assíncrono, sincronização reversa, seed) não fica atrás da flag — só a superfície de API/alerta. Assim, dado que já foi gravado continua íntegro/sincronizando mesmo com a flag off; só a edição fica bloqueada.

Ação: Deletar conta

Fora de escopo de implementação agora — só o método/endpoint com // TODO, sem lógica. Não existe nenhuma implementação hoje (nem local_helico, nem local_middag) — é fluxo próprio (provavelmente GDPR/anonimização, não um DELETE simples), a ser especificado separadamente.

Decisões pendentes

Nenhuma — todos os campos, enums, arquitetura de persistência, esboço de endpoints e a feature flag (helico_profile_editing) estão fechados. Este doc está pronto pra virar implementação.

Referências

  • Figma: node 5934:49853 (fluxo “Perfil”, 6 telas: visão inicial, modal de formação acadêmica, visão completa Dados pessoais + Formação Acadêmica, variante com 2+ formações, Sobre mim, Roteiro de Estudos — fora de escopo).
  • profile_view_dto.php / profile_view_service.php — composable atual, será estendido ou substituído.
  • me.md — contrato /me, hoje a única superfície de identidade implementada.
  • onboarding.md — Questionário de Perfil do onboarding (conceito de “perfil” distinto: perguntas de contexto de estudo, não dados cadastrais).
  • Middag\Core\Bus\Signal\Attribute\AsyncOn / AsyncSignalInterface (middag-php-core) — mecanismo de evento assíncrono a reusar.
  • Middag\Core\Validation\DocumentNumberValidator (middag-php-core) — validação de CPF (e outros documentos) por país.
  • local_middag\base\facade\moodle\user_field_support — facade de leitura/escrita de campo nativo e custom profile field do Moodle.
  • local_middag\extensions\enrolment\compliance\profileguard_service — gate de compliance CPF existente (dormant), campo Moodle a reusar/alinhar pro espelho de cpf.
  • lib/db/install.xml (Moodle core) — colunas nativas de user referenciadas aqui (phone1/phone2, description, institution, picture).
  • user/lib.php / user/profile/lib.php / user/editadvanced.php (Moodle core) — confirma quando \core\event\user_updated dispara: sempre pelo form padrão (core + custom juntos, trigger manual no fim), nunca pela API de baixo nível (user_update_user() com evento suprimido, ou profile_save_custom_fields() direto) — base de todo o raciocínio de loop/lacuna acima.
  • local_middag\middag_observer / db/events.php — bridge catch-all de eventos Moodle pro bus de sinais, usado pra sincronização reversa e seed inicial.
  • classes/extensions/platform/identity/ — módulo de provisionamento/identidade já existente (identity_resolver_service, identity_state_mirror_service, helico_provision_user_signal_handler); referência de padrão pra escuta de eventos Moodle e criação de usuário.
  • local_middag\extensions\ecommerce\listener\field_mapping_signal_handler — mapeamento genérico checkout→Moodle, escreve sem normalizar; é por causa dele que o seed/sincronização reversa precisam normalizar antes de gravar no EAV.
  • classes/extensions/engine/alerts/ — sistema de Alertas do Estudo já existente (alert_rule_interface, alerts_generator_service), reusado pro alerta de perfil incompleto.
  • study.md / actions.md — contratos de /alerts e do vocabulário action.kind.
  • classes/extensions/infra/feature_flags/ (feature_flags_service_interface, facade flags) — infra de feature flags já existente (OpenFeature + AWS AppConfig Agent), reusada pra gatear o Perfil.
  • onboarding.md (GET /onboarding/{enrolment_id}) — precedente do shape options: [{value, label}] embutido na resposta de leitura, reusado no GET do Perfil.
Navigation

Type to search…

↑↓ navigate↵ selectEsc close