Skip to content

Client Details Franquia Filial

Jump to bottom
ControleOnline Agents edited this page Aug 27, 2026 · 1 revision

Client Details — aba Franquia/Filial (PJ → PJ)

Página canônica da aba Franquia/Filial no detalhe de Pessoa Jurídica (client-details).

Objetivo

Registrar regras de negócio, contrato de dados e fronteiras de visão da aba que vincula PJ a PJ como Franquia ou Filial.

  1. Aba visível somente na edição de Pessoa Jurídica.
  2. Vínculos persistidos em people_link com linkType franchisee (Franquia) ou filial (Filial).
  3. CRUD administrativo (vincular / editar tipo / remover) somente quando APP_TYPE=MANAGER.
  4. Picker e listagem somente PJ (peopleType=J); PF e outros linkType ficam fora do escopo desta aba.
  5. Comissão/royalties de franquia não fazem parte desta entrega.

Repositórios afetados

Módulo Papel no fluxo
ui-customers Aba FranchiseLinksTab + modal + helpers no detalhe do cliente
api-platform-people Recurso PeopleLink; enum link_type inclui filial; AuthZ de escrita
app-community Pin do submódulo e fronteira APP_TYPE (MODOS_OPERACAO.md)
api-community Pin de people

Regras de negócio (UI)

Quando a aba aparece

Contexto Aba Franquia/Filial
Pessoa Jurídica (isPessoaJuridica) visível
Pessoa Física não visível
Outras abas (Vendedores, Contatos, etc.) independentes

Permissões por app

Capacidade APP_TYPE=MANAGER Fora de MANAGER
Ver listagem de Franquia / Filial sim sim (somente leitura)
Botão adicionar sim não
Editar tipo / remover vínculo sim não
Modal picker PJ + tipo sim não

Helper de fronteira: canManageFranchiseLinks(appType) — equivalente ao corte da aba Vendedores (canManageSalesmen). A UI não é o enforcement final; escrita em people_link continua no backend (PeopleLink Put ROLE_SUPER | ROLE_OWNER, PeopleLinkService::securityFilter + assertWriteAccess).

Modelo de dados

  • Recurso: people_link
  • company = PJ editada (matriz / empresa âncora)
  • people = PJ vinculada (somente peopleType=J)
  • linkType:
    • franchisee — rótulo UI Franquia
    • filial — rótulo UI Filial (enum estendido pela migration Version20260821190000)
  • Payload de save limitado a company / people / linkType / enable (+ id em edição)

Fluxo (MANAGER)

flowchart TD
  A[Abrir client-details de PJ] --> B{isPessoaJuridica?}
  B -->|não| Z[Aba ausente]
  B -->|sim| C[FranchiseLinksTab]
  C --> D[GET people_links company + linkType franchisee/filial]
  D --> E[Listagem PJ apenas]
  E --> F{APP_TYPE = MANAGER?}
  F -->|não| G[Somente leitura]
  F -->|sim| H[Adicionar / editar tipo / remover]
  H --> I[POST/PUT/DELETE people_links]
Loading
  1. Abrir /client-details de uma PJ no MANAGER.
  2. Aba Franquia/Filial lista vínculos existentes.
  3. Adicionar: picker de PJ + tipo Franquia ou Filial.
  4. Editar: alterar linkType entre franchisee e filial.
  5. Remover: confirmação antes do DELETE / enable=0 conforme o helper da aba.
  6. Fora de MANAGER: mesma listagem sem botões de gestão.

Modularização (UI)

Arquivo Papel
FranchiseLinksTab.js Listagem + empty state + ações
FranchiseLinksManageModal.js Picker PJ + tipo
useFranchiseLinksManage.js Load / save / delete
franchiseLinksTab.helpers.js Normalize PJ-only, labels, payload, canManage
clientDetailsTabContent.js / details.js Wiring da aba

Limite canônico: ≤500 linhas por arquivo.

Testes

  • Unit: franchiseLinksTab.helpers.test.mjs (canManage, normalize PJ-only, linkType, payload, filtro PF).
  • Browser smoke: src/tests/browser/manager/client-details-franchise-links.spec.js (aba, listagem franchisee/filial, PF ausente, testIDs de CRUD, query company=).

O que este módulo não faz

  • Comissão / royalties de franquia (issues filhas / outro fluxo).
  • Onboarding de franquia fora de client-details.
  • Vínculo PF → PJ nesta aba.
  • Substituir a aba Vendedores (sellers-client).

Visões (APP_TYPE)

Visão Papel
MANAGER Dono do CRUD administrativo da aba
CRM e demais Podem ver a listagem se a tela de detalhe for reutilizada; sem botões de gestão
POS / SHOP / DELIVERY Fora do fluxo desta aba

Fronteira: MODOS_OPERACAO.md.

Links cruzados

Clone this wiki locally