Gerenciar equipeManage staffGestionar equipo

Clean Architecture + Riverpod + Freezed + gRPC + ObjectBox. A equipe do varejo não é um agregado próprio: ela vive aninhada dentro da Visit — VisitsEntity → VisitEntity.accountData → .staff → .contacts[] / .clerks[]. Logo a leitura é cache-only (projeção do cache da Visit) e a escrita é remote-first pelo Dispatcher, com o cache local mutado só depois do ack. São dois grafos distintos.Clean Architecture + Riverpod + Freezed + gRPC + ObjectBox. The retail team is not its own aggregate: it lives nested inside the Visit — VisitsEntity → VisitEntity.accountData → .staff → .contacts[] / .clerks[]. So reads are cache-only (a projection of the Visit cache) and writes are remote-first through the Dispatcher, with the local cache mutated only after the ack. Two distinct graphs.Clean Architecture + Riverpod + Freezed + gRPC + ObjectBox. El equipo del punto de venta no es un agregado propio: vive anidado dentro de la Visit — VisitsEntity → VisitEntity.accountData → .staff → .contacts[] / .clerks[]. Por eso la lectura es cache-only (proyección del caché de la Visit) y la escritura es remote-first por el Dispatcher, con el caché local mutado solo tras el ack. Son dos grafos distintos.

1 · Leitura (projeção do cache da Visit)1 · Read (projection of the Visit cache)1 · Lectura (proyección del caché de la Visit)

Nenhum RPC próprio: os contatos chegam no getVisitList da Visit e são gravados no ObjectBox como parte dela. As duas telas leem só do cache (getCachedVisitBySfid) — o único fetch remoto acontece no pull-to-refresh da lista, que passa DataSourceType.remote para o container de visitas.No RPC of its own: contacts arrive in the Visit's getVisitList and are written to ObjectBox as part of it. Both screens read from cache only (getCachedVisitBySfid) — the only remote fetch happens on the list's pull-to-refresh, which passes DataSourceType.remote to the visits container.Ningún RPC propio: los contactos llegan en el getVisitList de la Visit y se graban en ObjectBox como parte de ella. Ambas pantallas leen solo del caché (getCachedVisitBySfid) — el único fetch remoto ocurre en el pull-to-refresh de la lista, que pasa DataSourceType.remote al container de visitas.

• VisitReplygRPC proto · getVisitList
  • toVisitsDTOVisitsDTO → StaffDTODTO · Freezed
    • toDomainStaffEntitydomain
      • toModelStaffModelObjectBox · Account.staff
        • toDomainStaffEntitydomain · cache
          • getCachedVisitBySfidGetStaffsByVisitUseCasevisit.accountData.staff
            • watchManageStaffNotifier + State
              • → UIManageStaffPage
                • goToStaffDetailsStaffDetailsPageStaffDetailsNotifier + State

2 · Escrita (remote-first via Dispatcher)2 · Write (remote-first via the Dispatcher)2 · Escritura (remote-first vía Dispatcher)

O StaffOrchestrator é o dono da escrita: monta o envelope com o builder, envia pelo DispatcherOrchestrator e só grava no ObjectBox depois do ack de sucesso. São três transações distintas — o contato (RetailerUploadAPI, contrato wire em Account Contact Upload) e as duas do Conecta Você (ContactConectaVoce e ContactUpdateStatus).The StaffOrchestrator owns the write: it builds the envelope with the builder, sends it through the DispatcherOrchestrator and only writes to ObjectBox after a successful ack. There are three distinct transactions — the contact one (RetailerUploadAPI, wire contract in Account Contact Upload) and the two Conecta Você ones (ContactConectaVoce and ContactUpdateStatus).El StaffOrchestrator es el dueño de la escritura: arma el envelope con el builder, lo envía por el DispatcherOrchestrator y solo graba en ObjectBox tras el ack de éxito. Son tres transacciones distintas — la del contacto (RetailerUploadAPI, contrato wire en Account Contact Upload) y las dos de Conecta Você (ContactConectaVoce y ContactUpdateStatus).

• StaffDetailsNotifiersaveContact · deleteContact · saveClerk · setClerkStatus
  • composeStaffOrchestratorContactEntity / ClerkEntity
    • buildBuild*DispatcherPayloadUseCaseDispatcherEnvelope
      • submitSubmit*UseCase → DispatcherOrchestratorsendTransaction
        • ack okSaveStaffUpdateUseCaseRetailUpdateRepository
          • upsert / removeVisitLocalDataSourceObjectBox · ContactModel / ClerkModel

A mesma equipe existe em quatro representações quase idênticas ao longo das camadas — Proto (wire gRPC) → DTO (Freezed) → Model (ObjectBox) → Entity (domínio) — e cada fronteira é atravessada por um mapper. Os nomes dos campos se mantêm quase em todas as camadas; muda pouco (enums tipados, datas parseadas, dois renames de id, relações). O fetch é write-through: todo retorno do getVisitList é gravado no ObjectBox e a UI passa a ler do cache.The same team exists in four near-identical representations across the layers — Proto (gRPC wire) → DTO (Freezed) → Model (ObjectBox) → Entity (domain) — and each boundary is crossed by a mapper. Field names stay nearly the same across layers; little changes (typed enums, parsed dates, two id renames, relations). Fetch is write-through: every getVisitList response is written to ObjectBox and the UI then reads from cache.El mismo equipo existe en cuatro representaciones casi idénticas a lo largo de las capas — Proto (wire gRPC) → DTO (Freezed) → Model (ObjectBox) → Entity (dominio) — y cada frontera se cruza con un mapper. Los nombres se mantienen casi en todas las capas; cambia poco (enums tipados, fechas parseadas, dos renames de id, relaciones). El fetch es write-through: toda respuesta de getVisitList se graba en ObjectBox y la UI lee del caché.

Não há container próprio nem lastSyncAt próprio: a raiz é Staff (3 campos), pendurada em Account.staff dentro de Visit, e o lastSyncAt exibido vem do container VisitsEntity — gerado no mapper com DateTimeUtils.now(), porque o proto não traz o campo. Staff tem duas coleções: Contact (14 campos, o cadastro CRM) e Clerk (9 campos, o cadastro Conecta Você). Os enums só existem tipados na Entity; em Proto/DTO/Model trafegam como String. A seguir, na ordem: o proto que transporta tudo, as estruturas de dados campo-a-campo por camada, e os mappers que ligam as camadas.There is no container of its own and no lastSyncAt of its own: the root is Staff (3 fields), hanging off Account.staff inside Visit, and the displayed lastSyncAt comes from the VisitsEntity container — generated in the mapper with DateTimeUtils.now(), because the proto does not carry the field. Staff has two collections: Contact (14 fields, the CRM record) and Clerk (9 fields, the Conecta Você record). Enums are only typed in the Entity; in Proto/DTO/Model they travel as String. Next, in order: the proto that carries everything, the field-by-field data structures per layer, and the mappers that link the layers.No hay container propio ni lastSyncAt propio: la raíz es Staff (3 campos), colgada de Account.staff dentro de Visit, y el lastSyncAt mostrado viene del container VisitsEntity — generado en el mapper con DateTimeUtils.now(), porque el proto no trae el campo. Staff tiene dos colecciones: Contact (14 campos, el registro CRM) y Clerk (9 campos, el registro Conecta Você). Los enums solo están tipados en la Entity; en Proto/DTO/Model viajan como String. A continuación, en orden: el proto que transporta todo, las estructuras de datos campo a campo por capa, y los mappers que unen las capas.

Proto

VisitConectaRep.proto · proto3 · package mn.bat.conectarep.streambridge. Um serviço (VisitConectaRepService), um método unário — não há RPC de contato:One service (VisitConectaRepService), a single unary method — there is no contact RPC:Un servicio (VisitConectaRepService), un método unario — no hay RPC de contacto:

As opções de role e languagePreference do formulário vêm de um segundo proto: ReferenceDataConectaRep.proto · rpc getReferenceData(ReferenceDataRequest) returns (ReferenceDataReply), campos repeated string contactRoles = 11 e repeated string languagePreferences = 12.The form's role and languagePreference options come from a second proto: ReferenceDataConectaRep.proto · rpc getReferenceData(ReferenceDataRequest) returns (ReferenceDataReply), fields repeated string contactRoles = 11 and repeated string languagePreferences = 12.Las opciones de role y languagePreference del formulario vienen de un segundo proto: ReferenceDataConectaRep.proto · rpc getReferenceData(ReferenceDataRequest) returns (ReferenceDataReply), campos repeated string contactRoles = 11 y repeated string languagePreferences = 12.

Estruturas de dadosData structuresEstructuras de datos

Um dropdown por estrutura, aninhados pela hierarquia (as linhas ligam pai e filhos). Cada tabela tem uma coluna por camada — Proto · DTO · Model · Entity; a célula em accent marca onde o tipo primeiro muda (relação ToMany/ToOne no Model, parse de data no Model, enum na Entity, rename onde ocorre).One dropdown per structure, nested by hierarchy (lines link parent and children). Each table has one column per layer — Proto · DTO · Model · Entity; the accent cell marks where the type first changes (ToMany/ToOne relation in the Model, date parse in the Model, enum in the Entity, rename where it happens).Un dropdown por estructura, anidados por jerarquía (las líneas unen padre e hijos). Cada tabla tiene una columna por capa — Proto · DTO · Model · Entity; la celda en accent marca dónde primero cambia el tipo (relación ToMany/ToOne en el Model, parseo de fecha en el Model, enum en la Entity, rename donde ocurre).

• Visits VisitsEntity · container · lastSyncAt · VisitEntity → AccountData.staff 2 campos

  Campo	Proto	DTO	Model	Entity
  lastSyncAt	—	DateTime	DateTime	DateTime
  visits	repeated Visit visitList	List<VisitDTO> visits	ToMany<VisitModel>	List<VisitEntity>

• Staff Account.staff · raiz 3 campos

  Campo	Proto	DTO	Model	Entity
  contacts	repeated Contact	List<ContactDTO>	ToMany<ContactModel>	List<ContactEntity>
  clerks	repeated Clerk	List<ClerkDTO>	ToMany<ClerkModel>	List<ClerkEntity>
  isRegisteredInConectaVoce	bool	bool	bool	bool

  • Contact Staff.contacts[] · CRM 14 campos

    Campo	Proto	DTO	Model	Entity
    id	string #1	String	contactId String	String
    name	string #2	String	String	String
    role	string #3	String?	String?	ContactRole?
    phone	string #4	String?	String?	String?
    email	string #5	String?	String?	String?
    birthdate	string #6	String?	DateTime?	DateTime?
    taxId	string #7	String?	String?	String?
    isMainContact	bool #8	bool	bool	bool
    b2bPortalStatus	string #9	String?	String?	B2bPortalStatus?
    status	string #10	String	String	String
    contactDesignation	string #11	String?	String?	ContactDesignation?
    languagePreference	string #12	String?	String?	LanguagePreference?
    preferredMethodOfContact	string #13	String?	String?	PreferredContactMethod?
    isRewardNominated	bool #14	bool?	bool?	bool?

  • Clerk Staff.clerks[] · Conecta Você 9 campos

    Campo	Proto	DTO	Model	Entity
    id	string #1	String	clerkId String	String
    taxId	string #2	String?	String?	String?
    name	string #3	String	String	String
    programLayerCode	string #4	String?	String?	programLayer ClerkProgramLayer
    phone	string #5	String?	String?	String?
    email	string #6	String?	String?	String?
    birthday	string #7	String?	DateTime?	DateTime?
    status	string #8	String?	String?	ClerkStatus?
    isEngaged	bool #9	bool?	bool?	bool?

• StaffConfig EMC · accountEditionConfig.staffConfig 11 campos

  Configuração de mercado (não é dado do varejo, não tem proto nem ObjectBox) — decide quais campos aparecem e o que vai no payload.Market configuration (not retail data, no proto and no ObjectBox) — decides which fields show and what goes in the payload.Configuración de mercado (no es dato del punto de venta, sin proto ni ObjectBox) — decide qué campos aparecen y qué va en el payload.

  Campo	TipoTypeTipo	DefaultDefaultDefault
  contactDesignations	List<String>	[]
  preferredContactMethods	List<String>	[]
  hasConectaVoceStaff	bool	false
  contactRecordTypeId	String	""
  contactPreferredLanguage	String	""
  generatesMainContactCpid	bool	false
  sendsPreferredContactMethod	bool	false
  sendsContactDesignationAndLanguagePreference	bool	false
  deactivatesB2bStatusOnDelete	bool	false
  contactFields	List<StaffFieldConfig>	[]
  clerkFields	List<StaffFieldConfig>	[]

  StaffFieldConfig = field StaffFieldType (default unknown) · isVisible bool (default true) · isEditable bool (default true). Métodos: contactFieldVisible, contactFieldEditable, clerkFieldVisible, clerkFieldEditable — campo ausente ⇒ false (escondido).Methods: contactFieldVisible, contactFieldEditable, clerkFieldVisible, clerkFieldEditable — absent field ⇒ false (hidden).Métodos: contactFieldVisible, contactFieldEditable, clerkFieldVisible, clerkFieldEditable — campo ausente ⇒ false (oculto).

Mappers

As conversões entre as camadas, todas como extension em data/mappers/visit/ (staff_mapper.dart, contact_mapper.dart, clerk_mapper.dart) — 5 direções por tipo:The conversions between layers, all as extensions in data/mappers/visit/ (staff_mapper.dart, contact_mapper.dart, clerk_mapper.dart) — 5 directions per type:Las conversiones entre capas, todas como extension en data/mappers/visit/ (staff_mapper.dart, contact_mapper.dart, clerk_mapper.dart) — 5 direcciones por tipo:

Não existe StaffRepository. A feature usa dois repositories: o VisitRepositoryImpl (leitura, pois a equipe vive na Visit) e o RetailUpdateRepositoryImpl (gravação local após o ack do Dispatcher). Um terceiro, o DispatcherRepositoryImpl, é o transporte da escrita remota.There is no StaffRepository. The feature uses two repositories: VisitRepositoryImpl (read, since the team lives in the Visit) and RetailUpdateRepositoryImpl (local write after the Dispatcher ack). A third one, DispatcherRepositoryImpl, is the remote-write transport.No existe StaffRepository. La feature usa dos repositories: VisitRepositoryImpl (lectura, ya que el equipo vive en la Visit) y RetailUpdateRepositoryImpl (grabación local tras el ack del Dispatcher). Un tercero, DispatcherRepositoryImpl, es el transporte de la escritura remota.

Um dropdown por método — assinatura, retorno e comportamento. O getVisits() traz a árvore de decisão de fonte dentro do próprio detalhe.One dropdown per method — signature, return and behavior. getVisits() carries the source decision tree inside its own detail.Un dropdown por método — firma, retorno y comportamiento. getVisits() trae el árbol de decisión de fuente dentro de su propio detalle.

Leitura ·Read ·Lectura · VisitRepositoryImpl

VisitRepositoryImpl implementaimplementsimplementa VisitRepositoryInterface e injeta os 3 datasources (mock/local/remote) + ConnectivityService + a flag useMockData + Ref. Só os métodos usados por esta feature:and injects the 3 datasources (mock/local/remote) + ConnectivityService + the useMockData flag + Ref. Only the methods used by this feature:e inyecta los 3 datasources (mock/local/remote) + ConnectivityService + la flag useMockData + Ref. Solo los métodos usados por esta feature:

Escrita local ·Local write ·Escritura local · RetailUpdateRepositoryImpl

RetailUpdateRepositoryImpl implementaimplementsimplementa RetailUpdateRepositoryInterface e injeta apenas o RetailUpdateLocalDataSource — sem mock, sem remote, sem ConnectivityService: o envio ao backend é responsabilidade do Dispatcher. Todos os métodos compartilham o mesmo catch → FailureMapper.fromException + AppLogger.logError(category: LogCategory.dataSync) → Error(failure).and injects only RetailUpdateLocalDataSource — no mock, no remote, no ConnectivityService: sending to the backend is the Dispatcher's job. All methods share the same catch → FailureMapper.fromException + AppLogger.logError(category: LogCategory.dataSync) → Error(failure).e inyecta solo el RetailUpdateLocalDataSource — sin mock, sin remote, sin ConnectivityService: el envío al backend es responsabilidad del Dispatcher. Todos los métodos comparten el mismo catch → FailureMapper.fromException + AppLogger.logError(category: LogCategory.dataSync) → Error(failure).

Escrita remota ·Remote write ·Escritura remota · DispatcherRepositoryImpl

Um card por datasource (dropdown). No corpo: método, envio, retorno, fluxo de uso e tratamento de erro.One card per datasource (dropdown). In the body: method, what it sends, return, usage flow and error handling.Un card por datasource (dropdown). En el cuerpo: método, envío, retorno, flujo de uso y manejo de errores.

Os enums de dado só existem tipados na camada Entity; em DTO/Model/Proto trafegam como String. Os de controle (StaffSource, StaffFieldType, ContactUploadAction, StaffDetailsConfirmAction) nunca saem do app; ClerkStatusAction é de controle mas seu wireValue vai cru no payload. Lista completa de valores:Data enums are only typed in the Entity layer; in DTO/Model/Proto they travel as String. The control ones (StaffSource, StaffFieldType, ContactUploadAction, StaffDetailsConfirmAction) never leave the app; ClerkStatusAction is a control enum but its wireValue goes raw into the payload. Full value list:Los enums de dato solo están tipados en la capa Entity; en DTO/Model/Proto viajan como String. Los de control (StaffSource, StaffFieldType, ContactUploadAction, StaffDetailsConfirmAction) nunca salen de la app; ClerkStatusAction es de control pero su wireValue va crudo en el payload. Lista completa de valores:

Um dropdown por UseCase; dentro, cada método com assinatura, o que retorna e uso. Os de leitura delegam ao repository sem lógica extra; os de escrita são coordenados pelo StaffOrchestrator. Quase todos os providers são keepAlive — a exceção é o getReferenceDataUseCaseProvider.One dropdown per UseCase; inside, each method with its signature, what it returns and use. The read ones delegate to the repository with no extra logic; the write ones are coordinated by the StaffOrchestrator. Almost every provider is keepAlive — the exception is getReferenceDataUseCaseProvider.Un dropdown por UseCase; dentro, cada método con su firma, qué devuelve y uso. Los de lectura delegan al repository sin lógica extra; los de escritura son coordinados por el StaffOrchestrator. Casi todos los providers son keepAlive — la excepción es getReferenceDataUseCaseProvider.

São dois Notifiers independentes, ambos famílias @riverpod chaveadas por parâmetros de rota (§17: a page recebe só identificadores). O ManageStaffNotifier (with AsyncGuard<ManageStaffState>) é o cérebro da lista — leitura pura, com refresh() canônico. O StaffDetailsNotifier (sem AsyncGuard) é o cérebro do formulário: mantém o rascunho, valida por campo, calcula "sujo" a cada tecla e dispara as quatro escritas. Cada State Freezed é a fonte única de verdade da sua page.There are two independent Notifiers, both @riverpod families keyed by route parameters (§17: the page receives identifiers only). ManageStaffNotifier (with AsyncGuard<ManageStaffState>) is the list's brain — pure read, with the canonical refresh(). StaffDetailsNotifier (without AsyncGuard) is the form's brain: it holds the draft, validates per field, recomputes "dirty" on every keystroke and fires the four writes. Each Freezed State is its page's single source of truth.Son dos Notifiers independientes, ambos familias @riverpod indexadas por parámetros de ruta (§17: la page recibe solo identificadores). El ManageStaffNotifier (with AsyncGuard<ManageStaffState>) es el cerebro de la lista — lectura pura, con refresh() canónico. El StaffDetailsNotifier (sin AsyncGuard) es el cerebro del formulario: mantiene el borrador, valida por campo, calcula "sucio" en cada tecla y dispara las cuatro escrituras. Cada State Freezed es la fuente única de verdad de su page.

Métodos ·Methods ·Métodos · ManageStaffNotifier

manageStaffProvider(visitSfid:) — build({required String visitSfid}) observa getVisitsUseCaseProvider e getStaffsByVisitUseCaseProvider e retorna guardedBuild(body: () => _load(...)).watches getVisitsUseCaseProvider and getStaffsByVisitUseCaseProvider and returns guardedBuild(body: () => _load(...)).observa getVisitsUseCaseProvider y getStaffsByVisitUseCaseProvider y retorna guardedBuild(body: () => _load(...)).

State disponível para a Page ·State available to the Page ·State disponible para la Page · ManageStaffState

Métodos ·Methods ·Métodos · StaffDetailsNotifier

staffDetailsProvider(visitSfid:, source:, staffId:) — build({required String visitSfid, required StaffSource source, String? staffId}) observa os 3 UseCases + o marketConfigurationProvider, busca os dados de referência (falha tolerada) e chama _load(...). Não há refresh(): a recuperação de erro é ref.invalidate pelo FailureStateView.watches the 3 UseCases + marketConfigurationProvider, fetches reference data (failure tolerated) and calls _load(...). There is no refresh(): error recovery is ref.invalidate from FailureStateView.observa los 3 UseCases + el marketConfigurationProvider, busca los datos de referencia (fallo tolerado) y llama _load(...). No hay refresh(): la recuperación de error es ref.invalidate por el FailureStateView.

State disponível para a Page ·State available to the Page ·State disponible para la Page · StaffDetailsState

Duas pages, ambas ConsumerWidget, ambas com AppPageShell(displayBackButton: true) e sem backgroundColor próprio (§19). Loading e erro são globais (stateAsync.when); o conteúdo existe só no ramo data. Os modais aparecem aninhados sob o widget que os abre.Two pages, both ConsumerWidget, both with AppPageShell(displayBackButton: true) and no backgroundColor of their own (§19). Loading and error are global (stateAsync.when); content exists only in the data branch. The modals appear nested under the widget that opens them.Dos pages, ambas ConsumerWidget, ambas con AppPageShell(displayBackButton: true) y sin backgroundColor propio (§19). Loading y error son globales (stateAsync.when); el contenido existe solo en la rama data. Los modales aparecen anidados bajo el widget que los abre.

Lista ·List ·Lista · ManageStaffPage

• ManageStaffPage visitSfid · watch manageStaffProvider
  • AppPageShell displayBackButton · drawer
    • CustomLoadingIndicator loading
    • FailureStateView error → ref.invalidate(manageStaffProvider)
    • CustomPullToRefresh data → refresh()
      • DataLoadInfo state.lastSyncAt · "-" quando null
      • AccountHeaderCard nome · SAP · isOverdue
      • ManageStaffBodyWidget StatefulWidget · _selectedIndex
        • CustomText título "Equipe do Varejo"
        • CustomTabBar só se showsConectaVoce · Cadastro / Conecta Você → setState
        • ManageStaffContactsSectionWidget aba 0 (ou única)
          • ManageStaffEmptyWidget CustomEmptyState (lista vazia)
          • ManageStaffContactCardWidget por contato → goToStaffDetails(source: contact, staffId)
            • ManageStaffCardWidget shell · Wrap de pills + nome/cargo + caret
              • CustomTag B2B (se isAccountB2B) · B2bPortalStatus.pillVariant
          • ManageStaffAddButtonWidget → goToStaffDetails(source: contact, sem staffId)
        • ManageStaffClerksSectionWidget aba 1 · só com showsConectaVoce
          • ManageStaffEmptyWidget CustomEmptyState (lista vazia)
          • ManageStaffClerkCardWidget por clerk → goToStaffDetails(source: clerk, staffId)
            • ManageStaffCardWidget shell reusado
              • CustomTag ClerkStatus.pillVariant · "Não engajado" se isEngaged == false
          • ManageStaffAddButtonWidget → goToStaffDetails(source: clerk, sem staffId)

A lista não tem modais próprios e nunca chama AppRouter.backWithResult. A aba ativa é estado local do ManageStaffBodyWidget (um setState), não do Notifier — logo o pull-to-refresh não a reseta. O modal "iniciar visita" que aparece antes desta tela pertence ao VisitStartGuard, no detalhe do varejo.The list has no modals of its own and never calls AppRouter.backWithResult. The active tab is local state of ManageStaffBodyWidget (a setState), not of the Notifier — so pull-to-refresh doesn't reset it. The "start visit" modal that appears before this screen belongs to VisitStartGuard, in the retail detail.La lista no tiene modales propios y nunca llama AppRouter.backWithResult. La pestaña activa es estado local del ManageStaffBodyWidget (un setState), no del Notifier — por eso el pull-to-refresh no la resetea. El modal "iniciar visita" que aparece antes de esta pantalla pertenece al VisitStartGuard, en el detalle del punto de venta.

Detalhe ·Detail ·Detalle · StaffDetailsPage

• StaffDetailsPage visitSfid · source · staffId? · watch staffDetailsProvider + currentMarketProvider
  • AppPageShell displayBackButton
    • CustomLoadingIndicator loading
    • FailureStateView error → ref.invalidate(staffDetailsProvider)
    • SingleChildScrollView data · sem pull-to-refresh
      • DataLoadInfo state.lastSyncAt
      • _contactFields source == contact · cada campo sob fieldVisible(...)
        • StaffDetailsTextFieldWidget fullName · firstName · lastName · cellPhone · email · b2bStatus (readOnly)
        • CustomDropdown<ContactDesignation> opções de staffConfig.contactDesignations
        • CustomDropdown<LanguagePreference> opções de state.languagePreferences
        • CustomDropdown<PreferredContactMethod> opções de staffConfig.preferredContactMethods
        • StaffDetailsRoleAndMainContactRow ConsumerWidget · sob fieldVisible(role)
          • CustomDropdown<ContactRole> opções de state.contactRoles
          • StaffDetailsMainContactSwitchWidget CustomSwitch → updateMainContact
        • StaffDetailsDateFieldWidget dateOfBirth → updateDateOfBirth
          • CustomCalendarModalContent modal · ConectaModal.show<DateTime> · lastDate = idade mínima 18
        • StaffDetailsActionsRowWidget Salvar (canSave = isFormDirty) · Excluir (showDelete = hasContact) · só callbacks; os modais são abertos pela Page
      • _clerkFields source == clerk
        • StaffDetailsClerkFormWidget state · notifier · market
          • CustomTag _statusRow · ClerkStatus + "Não engajado" (só se hasClerk)
          • StaffDetailsTextFieldWidget clerkName · clerkCpf (DocumentUtils) · clerkPhone · clerkEmail
          • CustomDropdown<ClerkProgramLayer> opções fixas: attendant · manager
          • StaffDetailsDateFieldWidget clerkBirthday
            • CustomCalendarModalContent modal · ConectaModal.show<DateTime>
        • CustomButton Ativar/Inativar (só se hasClerk && clerkStatus != null) + Salvar (enable = isFormDirty) · modal aberto pela Page
  • StaffDetailsMainContactSwitchModalContent modal · _confirmMainContactSwitch (Page) · conflito de principal → backWithResult<bool>
  • StaffDetailsActionConfirmModalContent modal · _confirm (Page) · create / edit / delete / activate / inactivate → backWithResult<bool>

Fluxo de ação (§39): o widget só orquestra UI — validate*() → modal de confirmação → método de escrita do Notifier → _notifyResult, que em sucesso mostra ConectaNotice.success e faz AppRouter.back, e em falha mostra ConectaNotice.error mantendo a tela. Todo await é seguido de guarda context.mounted. Widgets auxiliares: StaffDetailsFieldLabelWidget (o rótulo bold12 reusado por todos os campos) e StaffDetailsTextFieldWidget, que é StatefulWidget porque mantém o TextEditingController e reaplica a máscara (o State guarda o valor cru; a máscara é só apresentação).Action flow (§39): the widget only orchestrates UI — validate*() → confirmation modal → the Notifier's write method → _notifyResult, which on success shows ConectaNotice.success and calls AppRouter.back, and on failure shows ConectaNotice.error keeping the screen. Every await is followed by a context.mounted guard. Helper widgets: StaffDetailsFieldLabelWidget (the bold12 label reused by every field) and StaffDetailsTextFieldWidget, which is a StatefulWidget because it holds the TextEditingController and re-applies the mask (the State keeps the raw value; the mask is presentation only).Flujo de acción (§39): el widget solo orquesta UI — validate*() → modal de confirmación → método de escritura del Notifier → _notifyResult, que en éxito muestra ConectaNotice.success y hace AppRouter.back, y en fallo muestra ConectaNotice.error manteniendo la pantalla. Todo await va seguido de una guarda context.mounted. Widgets auxiliares: StaffDetailsFieldLabelWidget (la etiqueta bold12 reutilizada por todos los campos) y StaffDetailsTextFieldWidget, que es StatefulWidget porque mantiene el TextEditingController y reaplica la máscara (el State guarda el valor crudo; la máscara es solo presentación).