Documentação — TRG Club API

Índice completo da documentação do projeto. Toda doc vive aqui, em .project/docs/.

O primeiro nível é um conjunto fechado: specs/, plans/, features/, learnings/, architecture/, guides/, reference/<scope>/ e rules/<scope>/, mais os arquivos reservados README.md, RULES.md e modules.md. Nenhuma pasta nova no nível 1.

Neste repo existem hoje: specs/, learnings/, guides/, reference/ e rules/.

Regras de negócio — rules/<scope>/

Índice dedicado, ordenado por ID: RULES.md.

ID Título Scope Certainty Arquivo
R-001 Expiração de pagamento PIX e cancelamento de sessões payments high pix_payment_expiration.md
R-002 Confirmação de pagamento por webhook e ativação de sessões payments high webhook_confirmation_and_meeting_activation.md
R-003 Expiração da assinatura PRO por inelegibilidade no CITRG subscriptions high pro_expiration_on_citrg_ineligibility.md
R-004 Elegibilidade PRO exige filiação válida e documentação aprovada subscriptions high pro_eligibility_validity_and_documentation.md
R-005 Feature flags para visitantes anônimos feature_flags high anonymous_global_flags.md
R-006 Anotações do cliente pertencem ao terapeuta que as escreveu clients high client_annotations.md

Como o sistema funciona — reference/<scope>/

Doc Scope Certainty Descrição
invoice_payment_flow.md payments high Ciclo completo de repasse ao terapeuta: elegibilidade, cálculo, criação mensal, retry diário e ações no Avo
enotas_csv_layout.md payments high Layout das 50 colunas do CSV de importação do eNotas e o mapeamento de cada coluna preenchida pelo export
pro_downgrade_on_citrg_expiry.md subscriptions high Os dois gatilhos do rebaixamento de PRO (login e webhook da citrg-api), contrato e propriedades de segurança
room_ping_quality.md meetings high Como a qualidade de rede e o navegador são derivados do payload diagnostics e exibidos no Avo
public_endpoints.md api medium Endpoints de verificação de telefone, perfil e terapeuta, mais os parâmetros de busca via Ransack

Guias operacionais — guides/

Doc Certainty Descrição
getting_started.md high Subir o ambiente de desenvolvimento do zero com Docker e Overmind
pro_eligibility_audit.md high Varredura em duas fases no console para auditar e rebaixar PROs inelegíveis no CITRG

Aprendizados — learnings/

Doc Scope Data Certainty Descrição
payments_pix_expiration_race_condition.md payments 2026-03-14 high PIX pago dentro da janela de 30 min foi expirado e as sessões destruídas; investigação e reparo manual
sessions_ghost_pings_and_missing_connection_data.md sessions 2026-05-11 high Endpoint de ping sem guarda de janela produz pings fantasma, e pings sem contexto não provam qualidade de sessão
subscriptions_invert_where_association_conditions.md subscriptions 2026-07-17 high invert_where nega a condição user_id da associação e fez o rebaixamento atingir o usuário errado
subscriptions_pro_access_never_expired.md subscriptions 2026-07-07 high Elegibilidade era calculada e descartada; sem passo de reconciliação, o acesso PRO era permanente

Mudanças — specs/

Doc Status Certainty Descrição
20260127170116_payment_invoiceability_refactor.md done medium Concerns de invoiceabilidade, wrapper Therapist e mínimo de R$ 100 (parte 1 de 4)
20260127171922_simplify_invoice_creation.md done medium Consolida 5 use cases em 1 e remove o model InvoiceError (parte 2 de 4)
20260203095020_enhance_invoice_avo_interface.md done medium Badges de status, campos de retry e actions condicionais no Avo (parte 3 de 4)
20260203165036_add_monthly_metrics_to_payment_screens.md done medium Cards de métricas mensais nas três telas de pagamento (parte 4 de 4)
20260424111747_show_therapist_regardless_of_availabilities.md done high Terapeuta aparece na busca mesmo sem disponibilidade cadastrada
20260514180301_avatar_cache_ttl.md done high Cache do endpoint de avatar de 1 minuto para 1 hora
20260514180302_http_client_timeout.md done high Timeouts de conexão e leitura em todas as chamadas HTTParty
20260514180303_update_pix_async.md done high Payments::UpdatePix sai do ciclo do request e vira background job
20260514180304_meeting_n1_fix.md done high Inclui user_profile no includes da query de meetings
20260514180305_database_pool.md proposed high Pool de conexões do banco de 5 para 10
20260514180306_goodjob_cron_race.md proposed high Elimina erros de chave duplicada no cron do GoodJob
20260522000001_datadog_replace_appsignal.md proposed high Remove o AppSignal e adiciona APM e logs do Datadog
20260604180000_meeting_paid_at_on_invoice_paid.md proposed high Preenche paid_at/paid_total das sessões quando a invoice é paga
20260605120000_stuck_created_transfers.md done high Transfers travadas há mais de 24 h passam a failed, destravando o retry
20260610171233_goodjob_queue_isolation_and_cron_dyno.md proposed high Pools de threads por fila e process type priority dedicado a pagamentos
20260611103300_refresh_job_subjobs_per_therapist.md proposed high RefreshJob passa a enfileirar um sub-job por terapeuta, estabilizando a memória
20260612084141_skip_update_pix_when_already_present.md proposed high Não enfileira UpdatePixJob quando o pix já está preenchido
20260612161956_terapeuta_signin_orphan_user.md proposed high CPF inválido no CITRG cria User sem UserProfile e quebra o login para sempre
20260707151623_expire_pro_when_citrg_ineligible.md done high Expira o PRO e restaura o plano regular quando a filiação CITRG caduca
20260709170553_downgrade_on_citrg_expiry_webhook.md done high Webhook da citrg-api rebaixa o PRO mesmo sem o usuário logar
20260717112846_fix_non_expired_scope_invert_where.md done high Corrige o invert_where do scope non_expired e normaliza planos no login
20260722135700_faixa_etaria_terapeuta.md in_progress high Campo age_range no perfil, exibido na PDP do terapeuta
20260727165953_admin_taxes_endpoint.md done high Endpoint e tela admin de impostos retidos, com filtro e paginação
20260729143000_meeting_ping_diagnostics.md done high Tabela meeting_participant_pings com payload diagnostics por heartbeat
20260731120000_remove_ping_diagnostics_schema_version.md done high Remove schema_version, que nunca versionou nada de fato
20260803140000_room_ping_network_quality_avo.md done high Flag de qualidade de rede e navegador nos pings exibidos no Avo
20260811153509_admin_taxes_enotas_export.md done high Tela admin de impostos passa a listar sessões no layout de importação do eNotas, filtrando por período em vez de ano
20261002100729_client_annotations_crud.md in_progress high CRUD de anotações do cliente em /me/clients/:client_id/comments, sem depender de sessão e só do autor

Rascunhos — specs/drafts/

Specs aprovadas mas não iniciadas.

Doc Status Certainty Descrição
20260511112716_ping_connection_data_and_audit.md proposed high Contexto de conexão e auditoria por ping; parcialmente superado, auditoria e guarda de janela seguem pendentes

Distribuição de certainty

44 documentos indexados (fora os índices README.md e RULES.md).

Certainty Docs Significado
high 39 conteúdo veio do documento original ou de código verificado
medium 5 parcialmente reconstruído a partir do código
low 0 —

Quatro dos medium são as partes da iniciativa de invoiceabilidade (jan–fev/2026): as specs originais descreviam o estado pretendido, e a verificação contra o código mostrou desvios entre o proposto e o entregue. Cada uma carrega uma nota “Desvio verificado em 2026-08-06” apontando o que divergiu. O quinto é public_endpoints.md, herdado do README.md da raiz — notas escritas à mão, não verificadas linha a linha contra as rotas.

Onde não fica documentação

  • CLAUDE.md na raiz e .project/ai/ — instruções para agentes de IA, não são documentação
  • spec/ — suíte RSpec
  • .github/PULL_REQUEST_TEMPLATE.md — template do GitHub