@controleonline/ui-customers 1.0.81

package/.github/agents/developer.agent.md

@@ -0,0 +1,30 @@
+---
+name: Developer
+description: Executor autônomo de issues do repositório ControleOnline/ui-customers, com fonte canônica centralizada no cto-mcp.
+target: github-copilot
+---
+
+## Fonte canônica
+
+Este wrapper é intencionalmente fino. Antes de agir, leia e siga, nesta ordem:
+
+1. `https://github.com/ControleOnline/cto-mcp/blob/master/agents/agent/developer/agent.md`
+
+Esse arquivo central referencia as regras-base de `automation/` no `cto-mcp`. Se este wrapper local divergir do conteúdo canônico do `cto-mcp`, prefira o `cto-mcp`, salvo quando o estado real deste repositório exigir adaptação operacional explícita.
+
+## Contexto local
+
+Você está operando no repositório `ControleOnline/ui-customers`.
+
+Você conhece o ecossistema completo da ControleOnline. Este checkout define o ponto principal de escrita e validação para esta execução, não o limite do seu entendimento sobre o sistema.
+
+- Checkout local: `app-community/modules/controleonline/ui-customers`
+- Tipo: submódulo de app-community
+- Família: frontend
+- Branch base operacional: `master`
+- Alvo preferencial de PR: `dev`
+- `AGENTS.md` local: presente
+
+Leia o `AGENTS.md` mais próximo antes de editar código. Se esta alteração tocar apenas o repositório atual, trabalhe aqui; se também exigir atualização do superprojeto que consome este repositório, registre ou entregue a composição necessária sem perder a separação de ownership.
+
+_Arquivo gerado por `cto-mcp/scripts/sync-copilot-agents.mjs`._

package/.github/agents/devops.agent.md

@@ -0,0 +1,30 @@
+---
+name: DevOps
+description: Operador de fluxo e automações do repositório ControleOnline/ui-customers, com fonte canônica centralizada no cto-mcp.
+target: github-copilot
+---
+
+## Fonte canônica
+
+Este wrapper é intencionalmente fino. Antes de agir, leia e siga, nesta ordem:
+
+1. `https://github.com/ControleOnline/cto-mcp/blob/master/agents/agent/devops/agent.md`
+
+Esse arquivo central referencia as regras-base de `automation/` no `cto-mcp`. Se este wrapper local divergir do conteúdo canônico do `cto-mcp`, prefira o `cto-mcp`, salvo quando o estado real deste repositório exigir adaptação operacional explícita.
+
+## Contexto local
+
+Você está operando no repositório `ControleOnline/ui-customers`.
+
+Você conhece o ecossistema completo da ControleOnline. Este checkout define o ponto principal de escrita e validação para esta execução, não o limite do seu entendimento sobre o sistema.
+
+- Checkout local: `app-community/modules/controleonline/ui-customers`
+- Tipo: submódulo de app-community
+- Família: frontend
+- Branch base operacional: `master`
+- Alvo preferencial de PR: `dev`
+- `AGENTS.md` local: presente
+
+Leia o `AGENTS.md` mais próximo antes de editar código. Se esta alteração tocar apenas o repositório atual, trabalhe aqui; se também exigir atualização do superprojeto que consome este repositório, registre ou entregue a composição necessária sem perder a separação de ownership.
+
+_Arquivo gerado por `cto-mcp/scripts/sync-copilot-agents.mjs`._

package/.github/agents/qa.agent.md

@@ -0,0 +1,30 @@
+---
+name: Quality Assurance
+description: Revisor técnico de entregas do repositório ControleOnline/ui-customers, com fonte canônica centralizada no cto-mcp.
+target: github-copilot
+---
+
+## Fonte canônica
+
+Este wrapper é intencionalmente fino. Antes de agir, leia e siga, nesta ordem:
+
+1. `https://github.com/ControleOnline/cto-mcp/blob/master/agents/agent/qa/agent.md`
+
+Esse arquivo central referencia as regras-base de `automation/` no `cto-mcp`. Se este wrapper local divergir do conteúdo canônico do `cto-mcp`, prefira o `cto-mcp`, salvo quando o estado real deste repositório exigir adaptação operacional explícita.
+
+## Contexto local
+
+Você está operando no repositório `ControleOnline/ui-customers`.
+
+Você conhece o ecossistema completo da ControleOnline. Este checkout define o ponto principal de escrita e validação para esta execução, não o limite do seu entendimento sobre o sistema.
+
+- Checkout local: `app-community/modules/controleonline/ui-customers`
+- Tipo: submódulo de app-community
+- Família: frontend
+- Branch base operacional: `master`
+- Alvo preferencial de PR: `dev`
+- `AGENTS.md` local: presente
+
+Leia o `AGENTS.md` mais próximo antes de editar código. Se esta alteração tocar apenas o repositório atual, trabalhe aqui; se também exigir atualização do superprojeto que consome este repositório, registre ou entregue a composição necessária sem perder a separação de ownership.
+
+_Arquivo gerado por `cto-mcp/scripts/sync-copilot-agents.mjs`._

package/.github/agents/security.agent.md

@@ -0,0 +1,30 @@
+---
+name: Security
+description: Revisor de segurança do repositório ControleOnline/ui-customers, com fonte canônica centralizada no cto-mcp.
+target: github-copilot
+---
+
+## Fonte canônica
+
+Este wrapper é intencionalmente fino. Antes de agir, leia e siga, nesta ordem:
+
+1. `https://github.com/ControleOnline/cto-mcp/blob/master/agents/agent/security/agent.md`
+
+Esse arquivo central referencia as regras-base de `automation/` no `cto-mcp`. Se este wrapper local divergir do conteúdo canônico do `cto-mcp`, prefira o `cto-mcp`, salvo quando o estado real deste repositório exigir adaptação operacional explícita.
+
+## Contexto local
+
+Você está operando no repositório `ControleOnline/ui-customers`.
+
+Você conhece o ecossistema completo da ControleOnline. Este checkout define o ponto principal de escrita e validação para esta execução, não o limite do seu entendimento sobre o sistema.
+
+- Checkout local: `app-community/modules/controleonline/ui-customers`
+- Tipo: submódulo de app-community
+- Família: frontend
+- Branch base operacional: `master`
+- Alvo preferencial de PR: `dev`
+- `AGENTS.md` local: presente
+
+Leia o `AGENTS.md` mais próximo antes de editar código. Se esta alteração tocar apenas o repositório atual, trabalhe aqui; se também exigir atualização do superprojeto que consome este repositório, registre ou entregue a composição necessária sem perder a separação de ownership.
+
+_Arquivo gerado por `cto-mcp/scripts/sync-copilot-agents.mjs`._

package/.scrutinizer.yml

@@ -0,0 +1,20 @@
+checks:
+  javascript: true
+
+build:
+  nodes:
+    analysis:
+      environment:
+        node: v16
+      project_setup:
+        override: true
+      tests:
+        override:
+          - js-scrutinizer-run
+
+filter:
+  excluded_paths:
+    - "build/*"
+    - "coverage/*"
+    - "dist/*"
+    - "node_modules/*"

package/AGENTS.md

@@ -0,0 +1,50 @@
+
+## Ponto de entrada
+
+- A documentação funcional e de regras deste modulo vive na **wiki do proprio repositório** e na wiki principal do app.
+- Regras transversais de qualidade, modularizacao e limites de componente vivem em `https://github.com/ControleOnline/agents-mcp/blob/master/skills/shared/code-quality.md`.
+- Quando houver detalhe especifico de implementacao, prefira comentar no codigo em ingles perto da regra.
+- Este arquivo deve ficar curto e servir apenas como ponte para as fontes oficiais.
+
+## Documentação (navegação humana)
+
+Sempre comece pela **Home** da wiki e siga as categorias abaixo.
+
+| Categoria | Destino |
+| --- | --- |
+| Home do módulo | https://github.com/ControleOnline/ui-customers/wiki |
+| Wiki principal do app | https://github.com/ControleOnline/app-community/wiki |
+| Wiki da API | https://github.com/ControleOnline/api-community/wiki |
+| Visões do app (`APP_TYPE`) | https://github.com/ControleOnline/app-community/blob/master/MODOS_OPERACAO.md |
+
+### Por categoria — cadastro e detalhe de clientes
+
+| Página | O que documenta |
+| --- | --- |
+| [Cliente × Vendedor — vínculo e permissões](https://github.com/ControleOnline/ui-customers/wiki/Cliente-Vendedor-Vinculo-e-Permissoes) | Aba Vendedores no detalhe; corte MANAGER vs CRM/outros |
+| [Client Details — aba Franquia/Filial (PJ → PJ)](https://github.com/ControleOnline/ui-customers/wiki/Client-Details-Franquia-Filial) | Vínculos franchisee/filial no detalhe de PJ; CRUD só MANAGER |
+| [Client Details — preservação de capitalização (nome/alias)](https://github.com/ControleOnline/ui-customers/wiki/Client-Details-People-Name-Case) | Nome/alias de pessoa/colaborador sem forçar CAIXA ALTA (UI + API) |
+| Página canônica do fluxo (CRM) | https://github.com/ControleOnline/ui-crm/wiki/Cliente-Vendedor-Vinculo-e-Permissoes |
+
+Cópia versionada no Git: `docs/technical/Cliente-Vendedor-Vinculo-e-Permissoes.md`, `docs/technical/Client-Details-Franquia-Filial.md`, `docs/technical/Client-Details-People-Name-Case.md`
+
+### Visão deste módulo
+
+`ui-customers` é o **detalhe e cadastro de pessoas/clientes** reutilizado por várias visões do app (`CRM`, `MANAGER`, `POS`, etc.).
+
+- Dono da tela `ClientDetails` e abas (geral, contatos, documentos, **vendedores**, **Franquia/Filial**, etc.).
+- No fluxo comercial, recebe handoff do `ui-crm`.
+- Gestão administrativa de vendedores, comissões e vínculos franquia/filial: apenas quando `APP_TYPE=MANAGER`.
+- Fora de `MANAGER` (ex.: CRM): pode identificar o vendedor / ver listagem de franquia, sem CRUD administrativo.
+
+## Regras específicas
+
+- No contexto `provider`, a aba de produtos do detalhe da pessoa juridica deve permitir criar um novo produto sem sair do fluxo do fornecedor.
+
+### Módulos relacionados (mesmo fluxo)
+
+| Módulo | Papel | Entrada da documentação |
+| --- | --- |
+| `ui-crm` | Entrada comercial / handoff | https://github.com/ControleOnline/ui-crm/wiki |
+| `api-platform-people` | Backend `people_link` / SalesmanService | https://github.com/ControleOnline/api-platform-people/wiki |
+| `app-community` | Home do app e mapa de submódulos | https://github.com/ControleOnline/app-community/wiki |

package/FUNDING.yml

@@ -0,0 +1 @@
+github: [controleonline]

package/README.md

@@ -0,0 +1,23 @@
+# UI Customers
+
+Modulo React Native/Web para listagens e detalhes compartilhados de clientes, fornecedores e franquias.
+
+## Relacionamentos
+
+As abas de vendedores e contatos consultam o store `people_link`. Filtros de colecao usam IDs numericos; gravacoes preservam as IRIs exigidas pelo contrato JSON-LD.
+
+## Validacao
+
+Na raiz do `app-community`:
+
+```sh
+npm test -- --runInBand modules/controleonline/ui-customers/src/tests/react
+npm run test:browser:manager -- --grep "scopes sellers and contacts"
+```
+
+## Links obrigatorios
+
+- [Documentacao para clientes](http://ajuda.controleonline.com/)
+- [Site institucional](http://controleonline.com/)
+- [Wiki tecnica](https://github.com/ControleOnline/ui-customers/wiki)
+

package/docs/technical/Client-Details-Franquia-Filial.md

@@ -0,0 +1,18 @@
+# Client Details — aba Franquia/Filial (PJ → PJ)
+
+Espelho versionado da wiki:
+https://github.com/ControleOnline/ui-customers/wiki/Client-Details-Franquia-Filial
+
+Issue: https://github.com/ControleOnline/app-community/issues/453
+
+## Resumo
+
+Aba no detalhe de **Pessoa Jurídica** para vínculos PJ→PJ (`people_link.linkType` `franchisee` = Franquia, `filial` = Filial).
+CRUD administrativo somente em `APP_TYPE=MANAGER`. Picker e listagem somente PJ. Comissão/royalties fora de escopo.
+
+## Contrato
+
+- `company` = PJ editada; `people` = PJ vinculada (`peopleType=J`).
+- AuthZ de escrita no backend (`PeopleLink` + `securityFilter`); UI não é enforcement final.
+- Componentes: `FranchiseLinksTab`, `FranchiseLinksManageModal`, `useFranchiseLinksManage`, `franchiseLinksTab.helpers`.
+- Smoke: `src/tests/browser/manager/client-details-franchise-links.spec.js`.

package/docs/technical/Client-Details-People-Name-Case.md

@@ -0,0 +1,103 @@
+# Client Details — preservação de capitalização em nome/alias (People)
+
+## Objetivo
+
+Documentar a regra de negócio e o contrato técnico para **campos nominais** de pessoa/colaborador (`name`, `alias` / fantasia): o valor digitado pelo usuário é **persistido e relido com a mesma capitalização**, sem forçar CAIXA ALTA na UI nem no backend.
+
+Origem: residual de [app-community#376](https://github.com/ControleOnline/app-community/issues/376) coberto em [app-community#626](https://github.com/ControleOnline/app-community/issues/626) (cadastro/detalhe de colaborador em `client-details` / EmployeesTab).
+
+## Escopo
+
+| Área | Comportamento canônico |
+| --- | --- |
+| UI (`ui-customers`) | Inputs de nome/alias **não** aplicam `toUpperCase` / `formatDisplayUppercase` / CSS `text-transform: uppercase` no fluxo de cadastro/edição de colaborador e detalhe de pessoa |
+| Backend (`api-platform-people`) | `People::getName()` e `People::getAlias()` retornam o valor **armazenado** (sem `mb_strtoupper` na leitura) |
+| Persistência | O payload de escrita grava o texto como recebido (após trim/whitespace apenas, quando aplicável) |
+| Exibição | Listas e headers usam o valor retornado pela API, preservando capitalização |
+| Busca | Continua case-insensitive no backend (não depende de caixa no valor gravado) |
+
+### Fora de escopo / exceções legítimas
+
+- Campos cujo domínio **exige** caixa alta (ex.: UF de endereço) continuam normalizados — a regra deve ser **explícita** no código e, se necessário, documentada localmente.
+- Documentos fiscais (CNPJ/CPF) e formatação numérica/máscara não entram nesta regra de capitalização de nomes.
+- Reforma geral de i18n.
+
+## Fluxo (colaborador em client-details)
+
+```text
+Usuário digita "Maria Silva" (nome) / "Mari" (alias)
+        │
+        ▼
+  UI: normalizeIdentityValue = String(value)  [sem uppercase]
+        │
+        ▼
+  POST/PUT people (payload com capitalização original)
+        │
+        ▼
+  Banco: name / alias gravados como enviados
+        │
+        ▼
+  GET: People::getName / getAlias → valor armazenado
+        │
+        ▼
+  UI lista / header / detalhe → "Maria Silva" / "Mari"
+```
+
+## Modularização (UI)
+
+| Arquivo | Papel na regra |
+| --- | --- |
+| `src/react/components/tabs/employeesTabHelpers.js` | `normalizeIdentityValue` → identidade (sem uppercase); helpers de create/display |
+| `src/react/components/tabs/EmployeesTab.js` | Inputs de nome/alias no modal create **sem** forçar caixa alta no `onChangeText` |
+| `src/react/components/tabs/generalTabHelpers.js` | Mesma política de identidade no detalhe PF |
+| `src/react/pages/details.js` | Header / título de contato preservam capitalização gravada |
+
+Limite absoluto do projeto: **≤ 500 linhas** por arquivo.
+
+## Backend (`api-platform-people`)
+
+- `People::getName(): string` — retorna `(string) ($this->name ?? '')` (comentário de referência a #626 / #376).
+- `People::getAlias()` — idem para alias.
+- Removido o uso de helper privado `uppercaseText` / `mb_strtoupper` na **leitura** desses getters.
+- Setters gravam o valor recebido; a normalização de caixa **não** é aplicada na saída.
+
+## Critérios de aceite (referência)
+
+- É possível gravar `"Maria Silva"` e reler `"Maria Silva"` (não `"MARIA SILVA"`).
+- Campos que legitimamente exigem caixa alta (se houver) continuam normalizados e documentados.
+- Busca por nome não deixa de encontrar o registro por causa da capitalização.
+- Sem regressão no save de colaborador / people.
+
+## Testes
+
+| Tipo | Cobertura |
+| --- | --- |
+| Unit (ui-customers) | Helpers de identidade com exemplos mistos (`Maria Silva` / `Mari`) |
+| Unit / API (api-platform-people) | Getters de name/alias preservam case |
+| Browser smoke | Fluxo de create/edit de colaborador (EmployeesTab) com nome misto, quando presente no suite de client-details |
+
+## Visões do app (`APP_TYPE`)
+
+- `MANAGER` / `CRM` / demais que usam `client-details` e aba Colaboradores: a regra vale para o detalhe compartilhado de pessoa — o módulo **não** deve reintroduzir uppercase em display ou input de nome/alias.
+- `ui-customers` é o dono da UI de detalhe; `api-platform-people` é o dono da persistência e dos getters.
+
+## O que este módulo **não** faz
+
+- Não redefine busca full-text ou índices no backend.
+- Não altera máscaras de documento (CNPJ/CPF).
+- Não aplica title-case ou outras transformações “bonitas” automaticamente — apenas **preserva** o que o usuário digitou.
+
+## Links cruzados
+
+| Destino | URL |
+| --- | --- |
+| Home deste módulo | https://github.com/ControleOnline/ui-customers/wiki |
+| Client Details — aba Colaboradores (refresh) | https://github.com/ControleOnline/ui-customers/wiki/Client-Details-EmployeesTab-Refresh |
+| Client Details — criar usuário | https://github.com/ControleOnline/ui-customers/wiki/Client-Details-Criar-Usuario |
+| Backend people (wiki) | https://github.com/ControleOnline/api-platform-people/wiki |
+| App home | https://github.com/ControleOnline/app-community/wiki |
+| Issue residual | https://github.com/ControleOnline/app-community/issues/626 |
+| Issue original | https://github.com/ControleOnline/app-community/issues/376 |
+| Visões do app | https://github.com/ControleOnline/app-community/blob/master/MODOS_OPERACAO.md |
+
+Cópia versionada no Git (quando espelhada): `docs/technical/Client-Details-People-Name-Case.md`

package/docs/technical/Cliente-Vendedor-Vinculo-e-Permissoes.md

@@ -0,0 +1,152 @@
+# Cliente × Vendedor — vínculo e permissões
+
+Documentação técnica do papel de **`ui-customers`** no fluxo de vínculo cliente↔vendedor (trilha `ui-crm#2` + gestão administrativa `ui-customers#20`).
+
+## Como este módulo se encaixa
+
+| Visão (`APP_TYPE`) | Uso de `ui-customers` neste fluxo |
+| --- | --- |
+| **CRM** | Recebe handoff do `ui-crm` e mostra o detalhe do cliente; lista o vendedor **sem** gestão administrativa (sem botão +, edit, delete, modal) |
+| **MANAGER** | Detalhe administrativo: vincular, editar, remover vendedores; ver e editar comissão / mínimo (conforme regras de role) |
+| Outros (POS, etc.) | Reutilizam o detalhe conforme permissão; não assumem regras comerciais do CRM nem CRUD de vendedores |
+
+Página canônica do fluxo completo (CRM / backend):  
+- [ui-crm — Cliente × Vendedor](https://github.com/ControleOnline/ui-crm/wiki/Cliente-Vendedor-Vinculo-e-Permissoes)  
+- [api-platform-people — Cliente × Vendedor](https://github.com/ControleOnline/api-platform-people/wiki/Cliente-Vendedor-Vinculo-e-Permissoes)
+
+## Objetivo
+
+Registrar regras de negócio, modularização e contratos da aba **Vendedores** no detalhe do cliente:
+
+1. listagem de vínculos `sellers-client` via store `people_link`;
+2. gestão administrativa (vincular / editar / remover) **somente** quando `APP_TYPE=MANAGER`;
+3. edição de comissão / mínimo (override) restrita a roles adequadas (`ROLE_SUPER` / `ROLE_OWNER` em MANAGER);
+4. modularização dos componentes ≤ 500 linhas e testes focais.
+
+## Repositórios afetados
+
+| Módulo | Papel no fluxo |
+| --- | --- |
+| `ui-crm` | Handoff do CRM para o detalhe do cliente com contexto de vendedores |
+| `ui-customers` | Aba `Vendedores` no detalhe do cliente (listagem + gestão UI) |
+| `api-platform-people` | Vínculo automático, distribuição de vendedores e recurso `people_link` |
+| `app-community` | Fronteira de apps (`MANAGER` vs `CRM`) em `MODOS_OPERACAO.md` |
+
+## Regras de negócio (UI)
+
+### Permissões por app
+
+| Capacidade | `APP_TYPE=MANAGER` | Fora de `MANAGER` (ex.: CRM) |
+| --- | --- | --- |
+| Ver quem é o vendedor vinculado | sim | sim |
+| Botão **+** (vincular novo) | sim | não |
+| Edit / delete por linha | sim | não |
+| Modal de gestão (picker + comissão / mínimo) | sim | não |
+| Ver % de comissão / mínimo | sim | não |
+| Editar comissão (override) | sim (ROLE_SUPER / ROLE_OWNER) | não |
+
+A fronteira oficial de **CRUD administrativo** é por **app** (`APP_TYPE === MANAGER`), via helper `canManageSalesmen(appType)`. A UI **não** é o enforcement final — escrita em `people_link` e comissão devem ser filtradas no backend.
+
+### Modelo de dados (vínculos)
+
+- `PeopleLink` com `linkType`:
+  - `client` — empresa ↔ cliente
+  - `salesman` — empresa ↔ vendedor
+  - `sellers-client` — vendedor ↔ cliente
+- Campos sensíveis no vínculo: `comission`, `minimum_comission`
+
+### Fluxo de gestão (MANAGER)
+
+1. `SalesmanTab` carrega vínculos `sellers-client` do cliente.
+2. Se `canManageSalesmen(appType)`:
+   - exibe botão **+** (`salesman-manage-add-btn`);
+   - por linha: ações de editar e remover;
+   - abre `SalesmanManageModal` com picker de vendedores da empresa (já com `linkType=salesman`) e campos de comissão / mínimo.
+3. Save usa `people_link` actions (`save` / `remove`) com payload montado por `buildSalesmanSavePayload`.
+4. Fora de MANAGER: apenas listagem + navegação para o detalhe da pessoa vinculada; nenhum controle de CRUD.
+
+## Modularização (`ui-customers`)
+
+Arquivos principais (todos ≤ 500 linhas):
+
+| Arquivo | Responsabilidade |
+| --- | --- |
+| `src/react/components/tabs/SalesmanTab.js` | Aba: listagem, gate MANAGER, integração com modal e bloco de comissão |
+| `src/react/components/tabs/useSalesmanManage.js` | Hook de gestão administrativa (load options, open/save/remove modal state) |
+| `src/react/components/tabs/SalesmanManageModal.js` | Modal de vincular/editar (picker + comissão / mínimo) |
+| `src/react/components/tabs/SalesmanCommissionBlock.js` | Bloco de exibição/edição de comissão (override por role) |
+| `src/react/components/tabs/salesmanTab.helpers.js` | Helpers puros: `canManageSalesmen`, normalize, options, save payload |
+| `src/react/components/tabs/salesmanTabHelpers.js` | Helpers de comissão / display (legado + override) |
+| `src/react/components/tabs/salesmanTabMedia.js` | Media / avatar collection helpers |
+| `src/react/components/tabs/salesmanTabSession.js` | `resolveAppType` (localStorage `app-type`) e session user |
+
+Gate principal:
+
+```js
+export const canManageSalesmen = appType =>
+  normalizeAppType(appType) === 'MANAGER';
+```
+
+`APP_TYPE` é lido de `localStorage.getItem('app-type')` via `resolveAppType()`.
+
+## Contratos com outros módulos
+
+| Origem | Expectativa |
+| --- | --- |
+| `ui-crm` | chega com `clientId`, `contextKey=client`, opcionalmente `initialTab=sellers` |
+| `api-platform-people` | leitura/escrita de `people_link`; vínculo automático e campos de comissão; enforcement no backend |
+| `app-community` | composição do submodule; `MODOS_OPERACAO.md` define fronteira MANAGER vs CRM |
+
+```mermaid
+flowchart LR
+  CRM["ui-crm\nCRM list/detail entry"]
+  NAV["clientDetailsNavigation\nclientId + contextKey + initialTab"]
+  DET["ui-customers\nClientDetails"]
+  TAB["SalesmanTab"]
+  HOOK["useSalesmanManage\n+ SalesmanManageModal"]
+  API["api-platform-people\nPeopleLink + SalesmanService"]
+
+  CRM --> NAV --> DET --> TAB
+  TAB -->|"APP_TYPE=MANAGER"| HOOK
+  TAB --> API
+  HOOK --> API
+  API -->|"auto-link on client"| API
+```
+
+## Segurança (pontos de atenção)
+
+1. Restrição de CRUD e comissão fora de `MANAGER` **não** pode depender só de UI.
+2. Escrita em `people_link` deve respeitar menor privilégio (evitar que “pode ler” vire “pode escrever” em outros `linkType`).
+3. Escopo multiempresa: gestor de uma empresa não deve herdar gestão de `sellers-client` de outra empresa só porque o vendedor é compartilhado.
+4. Commission override continua nas regras já aceitas (`ui-customers#10` / `#12`); manage não amplia privilégio além do contexto MANAGER.
+
+## Testes
+
+- Unit: `npm run test:salesman-tab` (helpers + gate `canManageSalesmen`).
+- Browser smoke (MANAGER):
+  - `src/tests/browser/manager/client-details-salesman-manage.spec.js` — + / edit / delete + modal.
+  - `src/tests/browser/manager/client-details-salesman-commission.spec.js` — comissão.
+- non-MANAGER: ausência de controles CRUD coberta nos smokes.
+
+## Instalação / operação
+
+Não há pacote isolado. O fluxo depende dos submódulos front (`ui-crm`, `ui-customers`) compostos no app e do módulo PHP `api-platform-people` na API.
+
+Config relevante por empresa (backend):
+
+- chave `salesman-distribution-strategy` (default `random`)
+
+## Manutenção
+
+Ao alterar este fluxo:
+
+1. atualizar esta página e as cópias nos módulos afetados (`docs/technical/` + wiki);
+2. manter testes focais de helpers da aba e smoke MANAGER vs non-MANAGER;
+3. validar enforcement de `people_link` no backend antes de liberar exposição de comissão ou CRUD.
+
+## Referências internas
+
+- Issues: `ControleOnline/ui-crm#2` (fluxo original), `ControleOnline/ui-customers#20` (gestão administrativa MANAGER), `#10` / `#12` (comissão)
+- PRs históricos: `ui-customers#3`, `ui-crm#10`, `api-platform-people#4`
+- Fronteira de apps: [app-community/MODOS_OPERACAO.md](https://github.com/ControleOnline/app-community/blob/master/MODOS_OPERACAO.md)
+- Cópia versionada no Git: `docs/technical/Cliente-Vendedor-Vinculo-e-Permissoes.md`

package/docs/wiki.md

@@ -0,0 +1 @@
+https://github.com/ControleOnline/ui-customers/wiki

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@controleonline/ui-customers",
+  "version": "1.0.81",
+  "author": "ControleOnline",
+  "description": "ControleOnline customers Quasar UI Component",
+  "license": "MIT",
+  "main": "src/react/index.js",
+  "scripts": {
+    "test": "npm run test:supplier-product-flow && npm run test:fiscal-shortcut && npm run test:documents && npm run test:employee-link-types && npm run test:salesman-tab",
+    "test:supplier-product-flow": "node --test src/tests/react/domain/productSupplierFlow.test.mjs",
+    "test:fiscal-shortcut": "node --test src/tests/react/components/tabs/fiscalTabContract.test.mjs",
+    "test:documents": "node --test src/tests/react/components/tabs/documentsTabHelpers.test.mjs src/tests/react/components/tabs/documentsTabContract.test.mjs",
+    "test:employee-link-types": "node --test src/tests/react/components/tabs/employeeLinkTypes.contract.test.mjs",
+    "test:salesman-tab": "node --test src/tests/react/components/tabs/salesmanTab.helpers.test.mjs src/tests/react/components/tabs/salesmanTabHelpers.test.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/controleonline/conline-quasar-ui"
+  },
+  "bugs": "",
+  "homepage": "https://www.controleonline.com/devs/plugins",
+  "browserslist": [
+    "last 1 version, not dead, ie >= 11"
+  ],
+  "dependencies": {
+    "@controleonline/ui-accounting": "*",
+    "@controleonline/ui-common": "*",
+    "@controleonline/ui-contracts": "*",
+    "@controleonline/ui-crm": "*",
+    "@controleonline/ui-people": "*"
+  }
+}

package/scripts/validate-wiki-pointer.cjs

@@ -0,0 +1,13 @@
+const fs = require('fs');
+const path = require('path');
+const root = path.resolve(__dirname, '..');
+const repo = path.basename(root);
+const pointer = fs.readFileSync(path.join(root, 'docs/wiki.md'), 'utf8');
+const expected = `https://github.com/ControleOnline/${repo}/wiki\n`;
+if (pointer !== expected) throw new Error(`docs/wiki.md must contain only ${expected.trim()}`);
+const gitmodulesPath = path.join(root, '.gitmodules');
+if (fs.existsSync(gitmodulesPath)) {
+  const gitmodules = fs.readFileSync(gitmodulesPath, 'utf8');
+  if (/path\s*=\s*docs\/wiki/.test(gitmodules) || new RegExp(`${repo}\\.wiki\\.git`).test(gitmodules)) throw new Error('docs/wiki must not be configured as a wiki submodule');
+}
+console.log(`Validated wiki pointer for ${repo}.`);