Documentação — citrg-api

Índice completo da documentação do projeto. O citrg-api é a API Rails que gerencia filiações e a administração dos membros do CBTRG/CITRG.

O primeiro nível desta pasta é um conjunto fechado: specs/, plans/, features/, learnings/, architecture/, guides/, reference/<scope>/ e rules/<scope>/, mais README.md e RULES.md. Toda documentação nova entra neste índice.

Regras de negócio — rules/

Índice canônico, ordenado por ID, em RULES.md.

ID Doc Descrição
R-001 apolo_membership_composed_response A resposta do apolo_membership combina a situação da filiação vigente elegível com a data final da filiação paga mais distante.
R-002 renewal_chains_from_active_validity Uma nova filiação encadeia a partir de qualquer vigência em andamento, exceto estornada.
R-003 v2_memberships_index_only_paid O histórico de filiações no app lista apenas filiações pagas.
R-004 definitive_card_renewal_auto_approval Renovação de membro com carteira definitiva é aprovada automaticamente, sem reenvio de documento.
R-005 membership_expiry_notifies_trg_club O vencimento de filiação dispara webhook para o trg-club rebaixar o perfil PRO.
R-006 suspension_scoped_to_membership Suspender uma filiação marca só aquela filiação; o perfil do usuário não herda a suspensão.
R-007 next_membership_reevaluated_on_card_issue A filiação seguinte é re-avaliada na emissão da carteira, que é onde issued_definitive_card passa a valer true.
R-008 membership_approval_is_idempotent Aprovar uma filiação já aprovada não produz efeito — a carteira emitida não volta para a fila.
R-009 next_membership_auto_approval_requires_definitive_card A filiação seguinte só é auto-aprovada para quem tem carteira definitiva; sem ela, não é auto-aprovada.
R-010 emission_queue_prioritizes_current_month A fila de emissão coloca no topo as filiações vencendo no mês corrente, antes de ordenar as demais por data de aprovação.
R-011 approval_targets_pending_flow_membership A aprovação documental cai na filiação que ainda tem fluxo pendente; se a vigente já foi aprovada e emitida, vai para a seguinte.
R-012 therapist_search_one_result_per_therapist A busca pública devolve uma filiação por terapeuta — a ativa de maior valid_until.

Referência — reference/

Doc Descrição
api/public_endpoints Catálogo dos endpoints expostos para integração externa, com a autenticação de cada um.
api/i18n_error_messages Como a API pública resolve o idioma da resposta e a convenção de chaves api.*.
membership/membership_activation_flow O que acontece entre o webhook do checkout e a filiação ativa, na primeira compra e na renovação.
membership/class_diagram Modelo de dados de User, UserProfile, Membership e o que orbita cada um.

Guias — guides/

Doc Descrição
setup Subir o ambiente, rodar testes, lint, banco e credenciais pelos targets de make.
admin_daily_operations Procedimentos manuais da equipe no Admin: aprovar documentação, criar filiação, rastreio de carteira, PAD.

Aprendizados — learnings/

Doc Descrição
membership_renewal_without_reapproval_blocked_valid_until Condicionar campos de fato (datas) a um gate de aprovação fez consumidor externo rebaixar quem estava pago.
membership_newest_record_breaks_with_future_records “O registro mais recente” deixa de representar a entidade quando passa a existir registro futuro.
derived_parent_state_leaks_across_children Estado derivado de um filho e gravado no pai contamina todos os irmãos e não tem caminho de saída pela interface.
membership_pending_validity_ignored_on_renewal Exigir estado “ideal” ao buscar a vigência anterior exclui estados intermediários legítimos e sobrepõe períodos.
parallel_path_born_without_the_side_effect O caminho automático espelhou a assinatura do manual e não os efeitos colaterais em volta dele — a carteira auto-emitida saiu sem foto.

Specs — specs/

Doc Status Descrição
20250225111201_administrative_procedure_module done Módulo de Procedimento Administrativo (PA) com trilha de auditoria e interface no ActiveAdmin.
20260401000000_allow_multiple_kinds_per_shipment done Permitir a mesma filiação até 3 vezes na mesma remessa, com shipment_kind distinto.
20260406000000_migrate_server_to_app done Trocar server.yml pelos serviços compartilhados app, worker, migrations e seed.
20260507095109_add_created_at_to_memberships_csv done Adicionar a coluna “Criado em” ao CSV de filiações do Admin.
20260703150629_i18n_error_responses done Centralizar as mensagens da API em locale files e resolver o idioma pelo Accept-Language.
20260709122104_fix_status_after_definitive_card_renewal done Membro com carteira definitiva deixa de ver “Documentação pendente” após renovar.
20260709170553_notify_trg_club_on_membership_expiry done Empurrar webhook ao trg-club no vencimento, para o PRO ser rebaixado sem depender de login.
20260717120659_fix_apolo_membership_renewal_approval done Selecionar a filiação paga mais recente e sempre expor a data real de validade.
20260729145634_fix_apolo_access_early_renewal done Compor a resposta do apolo_membership a partir de duas filiações, destravando 192 membros.
20260729164028_fix_membership_suspension_silent_failure done suspend!/unsuspend! passam a levantar em falha, em vez de reportar sucesso falso.
20260730081805_fix_renewal_ignores_pending_membership done Considerar vigência pending/overdue ao encadear datas, evitando sobreposição de período.
20260821103617_webhook_v2_hotmart_membership in_progress POST /api/v2/webhook traduz payload de compra da Hotmart (aprovado/reembolsado/atrasado) para o mesmo fluxo de ativação de filiação.
20260901090342_suspension_scoped_to_membership done A suspensão deixa de ser derivada para o perfil e passa a valer só para a filiação suspensa.
20260904175409_guard_approval_against_issued_card proposed Impedir que a aprovação de documentos rebaixe uma filiação com carteira já emitida.
20260908134527_approval_idempotency_and_definitive_scope done Aprovação de filiação idempotente e auto-aprovação da filiação seguinte restrita a quem tem carteira definitiva.
20260910100239_approval_targets_eligible_membership done A aprovação documental vai para a filiação que ainda não concluiu o fluxo, e não para a que apenas está vigente.
20260914083203_therapist_card_photo_and_unique_search in_progress Foto na carteira digital auto-emitida e resultado único por terapeuta na busca pública.
20260914101440_therapist_search_one_result_per_therapist done A busca pública de terapeuta deixa de duplicar quem tem filiação vigente e renovação aprovada.

Pastas sem conteúdo hoje

plans/, features/ e architecture/ não têm documento neste projeto. Elas fazem parte do conjunto fechado e devem ser usadas quando houver conteúdo — não crie pasta nova fora dele.