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 (verprofile_view_dtoatual:user_id,fullname,
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):
- Frontend sobe o arquivo pro draft file area do usuário via
webservice/upload.php(endpoint padrão do Moodle pra upload autenticado porwstoken) → recebe umdraftitemid. - Frontend chama
POST /api/v1/platform/profile/avatar(profile_api_controller::update_avatar()) com{draftitemid, delete}— delega emcore_user_external::update_picture()em-processo (chamada PHP direta, não viawebservice/rest/server.php) e, se salvar com sucesso, despachaavatar_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:
core_user_external::update_picture()montaprofileimageurlviauser_picture::get_url($PAGE)semincludetoken— URLpluginfile.phpbaseada em sessão/cookie, nunca carrega pro Frontend (só temwstoken). É código vendor, não dá pra corrigir direto.- 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, semuser_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) — carregagender,birth_date(via meta),secondary_email,mobile_phone(serializado como string dophone_number_vo),status,lattes_url,nickname,occupation,has_no_occupation,children_count,exercise_frequency,hobbies,bio.cpfvai no campo nativoidnumberdehelico_items(não emhelico_itemmeta) — ver CPF. - Item type
user_academic_formation(N por usuário,parent= item id douser_profile) —institution,degree_type,start_date,end_date,description. Segue o mesmo padrão de hierarquiaparentque outras entities do engine já usam (ver ADR-10). Concreto: cada formação é uma linha emhelico_items(type = user_academic_formation,userid= dono,parent= id da linhauser_profile), com seus campos escalares emhelico_itemmeta(uma linha pormeta_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 umarray<object>caber nesse modelo. Fica só no EAV. full_nameeemailnão duplicam no EAV — são sóuser.firstname/user.lastname/user.email, lidos direto da tabelauser(comoprofile_view_servicejá faz hoje).- Histórico vem de graça:
ItemService::create()/update()/delete()(base EAV,middag-php-core) chamamItemRevisionService::createRevision()incondicionalmente nas três operações, ecreateFromItem()grava snapshot emhelico_item_revision+ todos os metadados emhelico_item_revision_meta. Contanto que a escrita do Perfil (e de cada Formação Acadêmica) passe peloItemServicepadrã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 disparauser_updated— o form chamauser_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 editandocpf/gender/birth_datepela 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 leruser_info_dataà parte pra pegar o valor atual. - Nosso próprio mirror EAV→Moodle: pra
mobile_phone/bio(colunas nativas) chamauser_update_user()direto → disparauser_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). Pracpf/gender/birth_date(custom fields) chamauser_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_createdcobre 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 outroidnumberjá existente (unique constraint), não grava o campo no EAV (loga/reporta — mesmo padrão desentry_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 construirphone_number_voa 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.gendernã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óduloidentityjá existente) grava o PK do Authentik emuser.idnumber— coluna nativa do Moodle. Não tem relação com oidnumberdehelico_itemsusado 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 emmiddag-php-core, usarespect/validation). Não reimplementar dígito verificador. - Unicidade: não existe hoje em nenhum lugar (nem o
profileguard_service::update_user_field()dolocal_middagvalida — só checa username duplicado, numa rota não-relacionada). Implementado como: gravarcpf(normalizado, só dígitos) na colunaidnumberdehelico_items(já existe,char(191), comentário “Functional identifier used by integrations or extensions” — serve exatamente pra isso) do itemuser_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 umuser_profileexistente com o mesmoidnumberantes de gravar e lança422 validation_errorse 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_fieldconfigurado (ver tabela acima) — sem unicidade nova ali, já que o Moodle não tem constraint nativa emuser_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_contextganha 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 umprofile_completeness_servicenovo (lê o itemuser_profileno 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/emailsempre vêm preenchidos, são a própria conta Moodle).academic_formationsconta como preenchido com pelo menos 1 item — sem estado “não tenho formação” (diferente deoccupation/has_no_occupation); quem tem só ensino médio fica com o alerta ativo até adicionar alguma formação. - Prioridade sugerida:
50— depois denext_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_fieldsemalert_context+ resolução emalerts_generator_service::build_context()(nova dependência:profile_completeness_service_interface). profile_incomplete_ruleentra na lista default do construtor dealerts_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 | Não — 422 validation_error se presente |
|
secondary_email |
string | null | Sim | 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" } }emailnã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
datacompleto 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 (POSTimplícito — novouser_academic_formationno EAV). - Item com
idexistente → atualiza os campos. idexistente que não aparece no array enviado → apaga.- Chave
academic_formationsausente no payload → não mexe em nada (mesma regra geral de PATCH parcial — omitir ≠ esvaziar). - Cada create/update/delete individual ainda passa pelo
ItemServicepadrã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
idrecebido é validado contraparent = <id do item user_profile do usuário-alvo>(o autenticado, ou o deuser_idquando é edição por admin) antes de tocar em qualquer coisa.idque existe mas pertence a outro usuário é tratado igual aidinexistente —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 (fieldusa 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_idausente ou0→ age no usuário autenticado (wstoken), fluxo normal do Aluno.user_idexplícito e diferente do autenticado → checamoodle/user:editprofile(a mesma capability nativa quecore_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_idde 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: qualqueruser_idque não seja o do própriowstokené 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 — esseuser_idno 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
ItemServiceestá 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_disableddireto, 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 decpf.lib/db/install.xml(Moodle core) — colunas nativas deuserreferenciadas aqui (phone1/phone2,description,institution,picture).user/lib.php/user/profile/lib.php/user/editadvanced.php(Moodle core) — confirma quando\core\event\user_updateddispara: 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, ouprofile_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
/alertse do vocabulárioaction.kind. classes/extensions/infra/feature_flags/(feature_flags_service_interface, facadeflags) — infra de feature flags já existente (OpenFeature + AWS AppConfig Agent), reusada pra gatear o Perfil.- onboarding.md (
GET /onboarding/{enrolment_id}) — precedente do shapeoptions: [{value, label}]embutido na resposta de leitura, reusado no GET do Perfil.