Planning Notes: Reusable CRP Scope¶

Estas notas preservam a direção técnica sugerida pelo responsável pelo produto. Elas devem ser investigadas e validadas durante $speckit-plan; não substituem requisitos nem constituem contrato fechado.

Proposed Request Scope¶

A interface pode enviar o CRP selecionado em um header de escopo comum.
A ausência do header representa o filtro “Todos”.
A API pode resolver o valor em um middleware reutilizável, confirmar que o CRP pertence ao usuário autenticado e disponibilizar um escopo normalizado aos endpoints.
Endpoints sensíveis devem consumir um filtro comum para evitar implementações divergentes.
“Todos” significa ausência de restrição adicional por CRP, nunca ausência da restrição obrigatória por ownerUserId.
Um valor de CRP controlado pelo cliente pode apenas reduzir o conjunto já autorizado; nunca pode ampliar acesso.

Proposed Migration Strategy¶

Favorecer a atribuição de CRP em entidades-raiz e derivação segura nas dependentes.
Evitar adicionar a mesma referência a todas as tabelas quando um relacionamento obrigatório já determina o CRP sem ambiguidade.
Manter registros ainda não classificados visíveis somente em “Todos” até atribuição explícita.
Criar inventário por endpoint e por entidade para decidir onde o filtro é direto, derivado ou não aplicável.
Criações realizadas sob “Todos” devem receber CRP explícito no comando; o backend não deve escolher um registro silenciosamente.

Proposed Data Shape¶

O isolamento não requer banco, schema ou infraestrutura separados por CRP.
Uma referência de CRP em uma entidade-raiz pode ser suficiente quando as entidades dependentes conseguem derivar o escopo por relacionamento obrigatório.
Para esta primeira versão, cada paciente pertence a exatamente um CRP; uma coluna de referência no paciente é a direção preferida.
A cota continua sendo consultada por proprietário sem filtro CRP, somando todos os pacientes ativos da conta.
Entidades dependentes do paciente devem derivar o CRP por relacionamento sempre que isso for inequívoco, evitando replicar a coluna.
Suporte futuro a um mesmo paciente simultaneamente em vários CRPs exigirá nova decisão de produto e possível mudança de cardinalidade; não faz parte desta feature.

Proposed Future-Task Flow¶

Uma associação provisória deve persistir graceStartedAt, graceExpiresAt, estado atual, última tentativa e próximo momento elegível.
O fluxo deve agendar novas tentativas de validação e aceitar repetição idempotente.
O vencimento não pode depender apenas de uma tarefa executada exatamente no quinto dia; toda avaliação de operação deve reconhecer um prazo já expirado mesmo que a fila esteja atrasada.
Uma tentativa bem-sucedida deve cancelar ou tornar inofensivos os trabalhos futuros já agendados para o mesmo vínculo.
Política de intervalo, backoff, quantidade de tentativas e recuperação de trabalhos mortos deve ser decidida em $speckit-plan.

Proposed Capability Decision¶

Não modelar um único userStatus que misture cadastro, CRP e plano.
Manter estados independentes e calcular uma decisão por ação, por exemplo patient.create.
Uma decisão pode retornar múltiplos motivos, como PLAN_PATIENT_LIMIT_REACHED e CRP_VALIDATION_EXPIRED.
O tier pertence ao usuário; os identificadores iniciais são free e standard.
Esta feature implementa somente a regra conhecida do free (cinco pacientes) e a fundação extensível. Catálogo, cobrança e benefícios do standard devem constituir uma feature/spec própria.

Questions for Planning¶

O escopo selecionado deve persistir por sessão, dispositivo ou preferência do usuário?
Quais endpoints podem aplicar filtro direto e quais precisam derivá-lo por paciente ou outra entidade-raiz?
Como impedir que cache, jobs, exportações e integrações reutilizem dados de outro filtro?
Como executar com segurança uma futura troca de CRP do paciente preservando todo o histórico derivado?
Quais eventos e qual periodicidade devem disparar a revalidação de CRP?
Qual será o catálogo de capacidades do standard quando a feature comercial de planos for especificada?