Skip to content

Plano de modularização por sessões

Plano concluído — sem próxima sessão pendente neste inventário. Sessões 1–31 e os recortes adicionais estão implementados e validados. A auditoria final cobre nove domínios, 208 arquivos e 42 fluxos em src/application; os serviços e fluxos entram automaticamente na verificação transitiva, incluindo imports dinâmicos. Não há ciclos nem imports entre domínios para serviços internos. HTTP, cache, armazenamento, lifecycle e plataformas permanecem nos adaptadores.

Última entrega validada. npm run check:full aprovado: 7.755 testes em 1.286 arquivos, quatro typechecks, lint, formato, Knip, auditoria de segurança e orçamento. Primeiro carregamento: 311,1 kB gzip, limite 311,2 kB. Os últimos recortes cobrem check-in/check-out, conclusão simples e incidentes; o transporte individual/em lote protege sessão, remoções e edições mais recentes. Integração/publicação seguem main + ship:all; produção só está confirmada quando /api/deployment devolve o SHA completo da entrega.

Decisões para preservar. Não refazer os fluxos já extraídos. Finish visit mantém seu fluxo completo de horas e cobrança; checklist/evidência continuam comandos finos para o store. Incidentes usam identidade estável do formulário e append idempotente no servidor; entram no estado somente após uma confirmação autoritativa. A revisão funcional posterior identificou seis lacunas: rollback concorrente, projeção do cache, retry de incidente, aceite do resgate, finalização após remoção e estado documental. As correções incluem regressões dos fluxos e adaptadores; npm run check:full desta revisão foi aprovado. A revisão cruzada seguinte fecha permissões e preservação de incidentes no endpoint genérico, respostas financeiras fora de ordem e confirmação autoritativa antes de rollback; o bypass de criação de visita por cliente também foi removido. Reemissão/correções e recibos preservam alterações posteriores de folha; emissão retorna aceite explícito e lotes anunciam somente o total de recibos aceitos. O gate completo dessa rodada foi aprovado. Novas mudanças seguem as mesmas fronteiras e verificações.

Um monólito modular: um repositório, o banco e os endpoints existentes, uma publicação. Cada domínio possui suas regras e expõe contratos explícitos; a coordenação entre domínios fica em src/application com efeitos fornecidos pelos adaptadores. Stores, hooks, cache, rede e notificações continuam nas suas camadas de integração. Independência aqui significa fronteiras verificáveis, não serviços ou publicações separados.

Não alterar regras financeiras, permissões, versões, transações ou contratos HTTP apenas para facilitar a reorganização. Não trocar imports por wrappers sem remover o acoplamento real. Não declarar um módulo concluído só por mover arquivos ou por não existir ciclo direto: dependências transitivas via shared/stores também precisam ser examinadas.

  • Trabalhar em um fluxo e em poucos arquivos centrais. Referências/imports podem exigir ajustes adicionais; se aparecer um segundo fluxo ou outra responsabilidade, registrar a pendência e deixar para outra sessão.
  • No início, ler CLAUDE.md, agents.md, esta retomada e somente o Estado actual da página do módulo. Inspecionar status, ramo e diff antes de escrever; preservar trabalho anterior.
  • Testar a regra com efeitos substituíveis, validar o adaptador existente e manter os contratos de arquitetura. Rodar tipos e Biome do que mudou, os testes relevantes e o gate exigido para integração/publicação.
  • Encerrar a sessão após validar o fluxo, sem começar o próximo. Salvar um commit ou indicar precisamente o que continua sem commit. Atualizar apenas o estado da sessão e a Retomada atual nesta página; comportamento vai na página do módulo, regras em CLAUDE.md quando necessário.
  • A passagem de bastão contém: ramo/commit, o que foi validado, limitações, próximo fluxo e estado da publicação. Não depender do histórico desta conversa ou de uma compactação para retomar.
  • Publicação segue a autorização humana e ship:all; salvar código e publicar são estados diferentes. Não refazer automaticamente uma publicação já confirmada.

São 25 recortes iniciais, não uma promessa de que a auditoria não encontrará trabalho adicional. A ordem reduz acoplamentos comuns primeiro. Cada linha é uma sessão independente; dividir novamente se o inventário revelar mais de um fluxo.

Sessão Área Fluxo e ponto de partida Evidência de conclusão Estado
1 billing Recebimento manual: application/settleManualInvoice.ts, billing/manualSettlement.ts e adaptador billing/api/recordManualSettlement.ts Coordenação sem store/rede concreta; testes de recusa, sessão, parcial, reemissão, consentimento, comprovante e lote; fronteira transitiva verificada Implementada e validada
2 billing Preparação de drafts: prepareDraftInvoiceSelection.ts e sua entrada em useInvoiceGeneration.ts Seleção/preparo em application/generateDraftInvoice e prepareDraftSelection, contrato @billing/draftInvoices, adaptador HTTP em billing/api; 34 testes (fluxos, hook, seleção e fronteiras), tipos e Biome aprovados Implementada e validada
3 billing Envio de invoices: useInvoiceDispatch.ts application/dispatchInvoice e sendInvoiceEmail, efeitos no hook; PDF/destinatário/BCC, aceite e sessão preservados; 30 testes e tipos aprovados Implementada e validada
4 billing Anulação em useInvoiceDispatch.ts application/voidInvoice: optimismo, rollback dirigido, versão, trava por invoice e sessão preservados; 23 testes e tipos aprovados Implementada e validada
4a billing Aviso de transferência em useInvoiceStateTransitions.ts application/claimInvoiceTransfer, contrato de seleção de invoices de lote; aceite/sessão antes do aviso; 13 testes e tipos aprovados Implementada e validada
4b billing Recebimento direto da equipe em useInvoiceStateTransitions.ts Contrato @billing/directStaffPayment e application/recordDirectStaffPayment; recebedor único, saldo, sessão e recebimento manual preservados; testes de fluxo e hook aprovados Implementada e validada
4c billing Início de checkout em paymentSettlementUtils.ts application/startInvoiceCheckout, contrato @billing/paymentConfirmation; URL/retorno/lote e SUBMITTED sem baixa local, sessão protegida; testes de fluxo/adaptador e tipos aprovados Implementada e validada
5 field-operations Finalização da equipe: finalizeCrewVisit.ts application/completeCrewVisit e adaptador field-operations/api/finalizeCrewVisit; sessão, rollback, evidências e recebimento preservados; 31 testes e tipos aprovados Implementada e validada
6 field-operations Recebimento pela equipe: CrewCollectionApiService.ts application/recordCrewCollection e @field-ops/crewCollection; valores/provas e recibo estável preservados, adaptador em api/; 58 testes e tipos aprovados Implementada e validada
6a field-operations Lembrete de recebimento em CrewCollectionApiService.remind application/remindCrewPayment; cooldown do servidor, recusa e sessão preservados; testes de fluxo/adaptador aprovados Implementada e validada
6b field-operations Correção de recebedor em CrewCollectionApiService application/changeCrewCollector; prévia, token, versão, folha/histórico e sessão preservados; 30 testes e tipos aprovados Implementada e validada
7 field-operations Materiais: ShoppingListApiService.ts application/changeSupplyList e contrato @field-ops/supplies; transporte/cache em api/, estoque e avisos preservados; 31 testes e tipos aprovados Implementada e validada
8 field-operations Custódia: KeyCustodyApiService.ts Auditoria: regras já puras em shared/keyCustody e servidor; contrato @field-ops/keyCustody, transporte em api/; sem duplicar regras, permissões/confirmacão/histórico preservados; 32 testes de domínio/API/backend aprovados Implementada e validada
9 scheduling Mudança de horário: useSchedulingOperations.ts @scheduling/rescheduling e application/rescheduleVisit; versões, ritmo e rollback preservados, sessão protegida, sucesso integral recusado em falha parcial; testes de domínio/fluxo/hook aprovados Implementada e validada
9a scheduling Pedido de semana/período e checklist do cliente, writer applyClientChange application/changeClientVisit e @scheduling/clientVisitChange; endpoint próprio, taxa do servidor, checklist incremental e rollback por versão preservados; testes de fluxo/hook aprovados Implementada e validada
9b scheduling Cancelamento e série em useSchedulingOperations application/cancelVisit e @scheduling/visitCancellation; permissões, taxa, compensação e rollback preservados; série aguardada antes de anunciar e falha parcial explícita Implementada e validada
9c scheduling Aprovar/rejeitar mudança e reverter cancelamento application/reviewVisitChange e @scheduling/visitReview; versão, restauração financeira e equipe preservadas; teste de decisões e sessão Implementada e validada
10 scheduling Alocação: useExecutionOperations.ts application/allocateVisitCrew e @scheduling/allocation; trava, disponibilidade cumulativa, rollback e versões preservados, notificações no hook; testes de fluxo/contratos aprovados Implementada e validada
11 scheduling Propagação recorrente: RecurrenceService.ts e seus consumidores Auditoria: propagação já pura; contrato @scheduling/recurrence e preço/logística por @billing/visitPricing; consumidor filtra elegíveis e mantém instante/versão; testes existentes preservados Implementada e validada
12 scheduling Resgate/conflitos: useConflictRescue.ts, conflictsState.ts application/schedulingConflicts, proposeRosterRescue e applyRosterRescue; cálculo cancelável, sessão e versão protegidas, resultado explícito da alocação; recusa mantém a prévia para retry Implementada e validada
13 payroll Preparação: usePayrollGeneration.ts application/generatePayrollCycle e @payroll/generation; datas de Londres, autor do servidor, seleção e deduplicação preservados; 33 testes e tipos aprovados Implementada e validada
13a payroll Recálculo de período em usePayrollGeneration application/recalculatePayrollPeriod e @payroll/recalculation; linhas manuais/histórico/deltas do servidor e falhas parciais preservados Implementada e validada
14 payroll Mudança de estado: usePayrollStatus.ts application/transitionPayrollEntry e @payroll/entryTransitions; predecessor fixado, recusa reconciliada, saldo transportado e sessão preservados; 46 testes e tipos aprovados Implementada e validada
14a payroll Cancelamento de holerite em usePayrollStatus application/cancelPayrollEntry; recusa, sessão e invalidação após aceite preservados Implementada e validada
15 communication Histórico/paginação: messageHistory.ts, entradas de useMessages.ts application/messageHistory com transporte injetado e adaptador communication/api; paginação, watermark, snapshots e envios concorrentes preservados; 58 testes e tipos aprovados Implementada e validada
16 communication Envio/fila: offlineMessageQueue.ts e o fluxo de envio application/sendChatMessage, deliverChatMessage, flushChatOutbox e @communication/outbox; ID estável, confirmação por socket, ordem e escopo preservados; testes sem mensagens reais Implementada e validada
17 communication Seleção/canais: useChannels.ts, useChatSelection.ts application/readChannelSnapshot, readChannelReceipt e contratos channelState/chatSelection; identidade, push concorrente, prévia removida e links preservados; 72 testes e tipos aprovados Implementada e validada
18 banking Saldos e movimentos: bankingService.ts e contratos de folha/faturamento Auditoria: cálculos já puros; contratos de recibos/transferências explícitos e compatíveis com Worker; abertura, dinheiro real e saldos preservados Implementada e validada
19 banking Conciliação e seus adaptadores application/reconcileBankCommands, matcher existente e adaptador da tela; revisão fixada, parada na primeira recusa e aceites parciais preservados; testes de fluxo/UI/backend aprovados Implementada e validada
20 carpet Auditoria de CarpetSettlementLogic e consumidores Auditoria: cálculos já puros, consumidor de logística usa @carpet; comissão/rateio/VAT preservados. calculateCarpetSettlement é helper testado, não uma nova integração de ledger; testes existentes aprovados Implementada e validada
21 analytics Agregação: FinancialStatsAggregationService.ts, DashboardIntelligenceService.ts Agregação já pura; @analytics/financialStats, @billing/reporting e @field-ops/issues substituem imports internos; cálculos, permissões e leitores preservados Implementada e validada
22 analytics Busca: SearchIntelligenceService.ts @analytics/search retorna descritores; ícones, handlers e comandos em components/search/searchResults; resultados/permissões preservados, testes de domínio/UI aprovados Implementada e validada
23 system Integridade: StabilityService.ts, FiscalIntegrity.ts Auditoria: diagnóstico já puro; @system/integrity e contrato fiscal compatível com Worker, execução continua explícita nos adaptadores; provas e reparações existentes preservadas Implementada e validada
24 system Alertas/auditoria: shellAlerts.ts e consumidores Auditoria: composição já pura; saúde de comunicação expõe contrato independente do cliente HTTP; alertas/diagnóstico aprovados em 81 testes Implementada e validada
25 Todos Auditoria final das nove áreas e caminhos transitivos Serviços/fluxos inventariados automaticamente, imports cruzados internos zerados, adaptadores separados; gate completo aprovado. Pendências adicionais de campo encerradas nas sessões 28–30 Concluída: auditoria dos recortes e pendências registradas
26 billing Carteira: useWalletPayment.ts application/payInvoiceWithWallet; IDs reais do lote, aceite do servidor e sessão preservados; testes de fluxo e gate completo aprovados Implementada e validada
27 billing Conferência de pagamento: useBillingVerification.ts application/verifyInvoicePayment; consentimento, aprovação/rejeição/reversão, folha e recibos preservados; rollback restrito às cópias otimistas próprias; fluxo/hook/gate aprovados Implementada e validada
27a billing/field-operations Lote da equipe em useBillingVerification.reconcileStaffBatch application/reconcileStaffReceipts; rota/recebedor/versão reais, parada na recusa e sessão preservados; fluxo/hook/gate aprovados Implementada e validada
28 field-operations Check-in/check-out: useShiftOperations.recordGeoPoint application/recordVisitClock; relógio injetado, eventos sequenciais, antecipação, versão, aceite e rollback por snapshot/sessão; 127 testes e tipos aprovados Implementada e validada
29 field-operations Marcação simples de trabalho concluído: useExecutionOperations.markWorkDone application/markVisitWorkDone; trava por visita, aceite, rollback por snapshot/sessão e transporte sem publicação tardia; 18 testes e tipos aprovados; Finish visit preservado Implementada e validada
30 field-operations Registro de incidente: useExecutionOperations.addIncident application/reportVisitIncident; ID/instante estáveis do formulário, append idempotente em /field/incidents, recibo autoritativo e trava por visita/sessão; retry após resposta perdida sem duplicação, com testes de fluxo/API/formulário/servidor Implementada e validada
31 Todos Repetir auditoria após os recortes 28–30 Nove domínios/208 arquivos/42 fluxos auditados; fronteiras transitivas e imports internos protegidos, revisão funcional com regressões de cache, concorrência, respostas perdidas e aceite explícito; gate completo da revisão aprovado Concluída e validada
  1. Regras identificadas e testáveis sem montar React, Zustand, contextos ou serviços externos.
  2. Contratos usados por outros domínios são explícitos e não carregam hooks/UI pela raiz de um barrel.
  3. Coordenação e efeitos têm responsabilidades claras; autenticação, cache, persistência e notificações não ficam escondidos nas funções de cálculo.
  4. Grafo direto sem ciclos e caminhos transitivos relevantes inspecionados; as verificações automáticas cobrem a fronteira adotada, sem listas silenciosas de exceções.
  5. Comportamento, permissões e invariantes preservados por testes do fluxo e do adaptador; build dentro do orçamento.
  6. Documentação do estado atual correta. O estado local, o estado integrado e o estado publicado são informados separadamente.

Continuar a modularização do Prime Crown pela Retomada atual de docs_src/content/docs/modularization-plan.md. Leia primeiro CLAUDE.md e docs_src/content/docs/agents.md; confira ramo, status e alterações existentes. Execute somente a próxima sessão planejada, preservando comportamento, transações e contratos HTTP. Valide o fluxo e os adaptadores, atualize o plano e encerre com ramo/commit, testes, limites e próximo passo. Não publicar sem autorização.