@controleonline/ui-customers 1.0.81 → 1.0.82

package/.github/workflows/integration-source-gate.yml

@@ -0,0 +1,68 @@
+name: Integration source gate
+
+on:
+  pull_request:
+    branches: [dev, staging, master]
+    types: [opened, synchronize, reopened, edited, ready_for_review]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  source-policy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Enforce task or frozen RC source
+        env:
+          HEAD_REF: ${{ github.head_ref }}
+          BASE_REF: ${{ github.base_ref }}
+        run: |
+          set -eu
+          if [ "$BASE_REF" = "dev" ]; then
+            echo "$HEAD_REF" | grep -Eq '^task-[1-9][0-9]*$' || {
+              echo "::error::dev only accepts task-<numeric issue>."
+              exit 1
+            }
+            exit 0
+          fi
+          echo "$HEAD_REF" | grep -Eq '^rc/[0-9]+\.[0-9]+\.[0-9]+-rc\.[1-9][0-9]*$' || {
+            echo "::error::$BASE_REF only accepts a frozen rc/X.Y.Z-rc.N source."
+            exit 1
+          }
+
+      - uses: actions/checkout@v4
+        if: github.base_ref != 'dev'
+        with:
+          ref: ${{ github.head_ref }}
+
+      - name: Validate frozen RC manifest
+        if: github.base_ref != 'dev'
+        env:
+          HEAD_REF: ${{ github.head_ref }}
+        run: |
+          set -eu
+          test -f .release/rc-manifest.json || {
+            echo "::error::Missing .release/rc-manifest.json"
+            exit 1
+          }
+          node --input-type=module <<'NODE'
+          import fs from 'node:fs';
+          const m = JSON.parse(fs.readFileSync('.release/rc-manifest.json', 'utf8'));
+          const branch = process.env.HEAD_REF;
+          const match = /^rc\/(\d+\.\d+\.\d+)-rc\.([1-9][0-9]*)$/.exec(branch);
+          if (!match) throw new Error('invalid RC branch');
+          if (m.branch !== branch || m.version !== match[1] || Number(m.rc) !== Number(match[2])) throw new Error('manifest identity mismatch');
+          if (m.frozen !== true) throw new Error('manifest is not frozen');
+          if (!Array.isArray(m.tasks) || m.tasks.length < 1 || m.tasks.length > 5) throw new Error('RC must contain 1..5 tasks');
+          const tasks = m.tasks.map(Number);
+          if (tasks.some((id) => !Number.isInteger(id) || id < 1)) throw new Error('invalid task id');
+          if (new Set(tasks).size !== tasks.length) throw new Error('duplicate RC tasks');
+          if (!/^[0-9a-f]{40}$/i.test(String(m.baseMaster || ''))) throw new Error('invalid baseMaster');
+          const repos = m.repositories || {};
+          if (!Object.keys(repos).length) throw new Error('empty repositories manifest');
+          for (const [repo, sha] of Object.entries(repos)) {
+            if (!/^ControleOnline\/[A-Za-z0-9_.-]+$/.test(repo) || !/^[0-9a-f]{40}$/i.test(String(sha))) throw new Error('invalid repository manifest entry');
+          }
+          console.log('Frozen RC manifest valid:', branch, tasks);
+          NODE

package/.github/workflows/publish-npm.yml

@@ -0,0 +1,91 @@
+name: Publish Package to npmjs
+
+on:
+  push:
+
+permissions:
+  contents: write
+  id-token: write
+
+concurrency:
+  group: ${{ github.repository }}-npm-release
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    if: ${{ github.repository_owner == 'ControleOnline' && (github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/v')) }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref }}
+          fetch-depth: 0
+      - name: Validate package metadata and create version tag
+        id: release
+        env:
+          REF_TYPE: ${{ github.ref_type }}
+          REF_NAME: ${{ github.ref_name }}
+          EXPECTED_REPOSITORY: ${{ github.repository }}
+        run: |
+          node <<'NODE'
+          const fs = require('node:fs');
+          const cp = require('node:child_process');
+          const pkg = require('./package.json');
+          const expectedUrl = `https://github.com/${process.env.EXPECTED_REPOSITORY}`;
+          if (!/^\d+\.\d+\.\d+$/.test(String(pkg.version))) throw new Error(`Expected stable X.Y.Z, got ${pkg.version}`);
+          if (pkg.repository?.url !== expectedUrl) throw new Error(`repository.url must be ${expectedUrl}; got ${pkg.repository?.url}`);
+          const sourceSha = cp.execFileSync('git', ['rev-parse', 'HEAD'], {encoding:'utf8'}).trim();
+          let tag = '';
+          if (process.env.REF_TYPE === 'tag') {
+            tag = process.env.REF_NAME;
+            if (tag !== `v${pkg.version}`) throw new Error(`Tag ${tag} does not match package version ${pkg.version}`);
+          } else {
+            let previous = '';
+            try { previous = JSON.parse(cp.execFileSync('git', ['show', `${sourceSha}^:package.json`], {encoding:'utf8'})).version || ''; } catch {}
+            if (previous === pkg.version) { fs.appendFileSync(process.env.GITHUB_OUTPUT, 'release_tag=\n'); process.exit(0); }
+            const parts = String(pkg.version).split('.').map(Number);
+            if (previous) {
+              const old = String(previous).split('.').map(Number);
+              let cmp = 0; for (let i=0;i<3;i++) { if ((parts[i]||0)!==(old[i]||0)) { cmp=(parts[i]||0)>(old[i]||0)?1:-1; break; } }
+              if (cmp <= 0) throw new Error(`Version ${pkg.version} must be greater than first-parent version ${previous}`);
+            }
+            tag = `v${pkg.version}`;
+            const existing = cp.spawnSync('git', ['ls-remote', '--exit-code', '--refs', 'origin', `refs/tags/${tag}`], {encoding:'utf8'});
+            if (existing.status === 0) {
+              cp.execFileSync('git', ['fetch', 'origin', `refs/tags/${tag}:refs/tags/${tag}`], {stdio:'inherit'});
+              const tagged = cp.execFileSync('git', ['rev-parse', `${tag}^{commit}`], {encoding:'utf8'}).trim();
+              if (tagged !== sourceSha) throw new Error(`Immutable tag ${tag} already points at ${tagged}, not ${sourceSha}`);
+            } else {
+              cp.execFileSync('git', ['config', 'user.name', 'github-actions[bot]']);
+              cp.execFileSync('git', ['config', 'user.email', '41898282+github-actions[bot]@users.noreply.github.com']);
+              cp.execFileSync('git', ['tag', '-a', tag, sourceSha, '-m', `Release ${pkg.name}@${pkg.version}`], {stdio:'inherit'});
+              cp.execFileSync('git', ['push', 'origin', `refs/tags/${tag}`], {stdio:'inherit'});
+            }
+          }
+          fs.appendFileSync(process.env.GITHUB_OUTPUT, `release_tag=${tag}\n`);
+          console.log(`Validated ${pkg.name}@${pkg.version} from ${sourceSha}; release tag ${tag}`);
+          NODE
+      - uses: actions/setup-node@v4
+        if: steps.release.outputs.release_tag != ''
+        with:
+          node-version: 24
+      - name: Ensure npm 11.5.1+ (OIDC support)
+        if: steps.release.outputs.release_tag != ''
+        run: |
+          npm install --global npm@latest
+          npm --version
+      - name: Skip if version is already on npm
+        id: registry
+        if: steps.release.outputs.release_tag != ''
+        run: |
+          PACKAGE_NAME=$(node -p "require('./package.json').name")
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          if npm view "$PACKAGE_NAME@$PACKAGE_VERSION" version >/dev/null 2>&1; then
+            echo 'published=true' >> "$GITHUB_OUTPUT"
+            echo "$PACKAGE_NAME@$PACKAGE_VERSION is already published; skipping duplicate publish"
+          else
+            echo 'published=false' >> "$GITHUB_OUTPUT"
+          fi
+      - name: Publish to npmjs with trusted publishing
+        if: steps.release.outputs.release_tag != '' && steps.registry.outputs.published != 'true'
+        run: npm publish --access public --loglevel verbose

package/AGENTS.md

@@ -22,20 +22,20 @@ Sempre comece pela **Home** da wiki e siga as categorias abaixo.
 | 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 — criar usuário (UsersTab)](https://github.com/ControleOnline/ui-customers/wiki/Client-Details-Criar-Usuario) | Criação de usuário no detalhe; people em IRI; auth ROLE_HUMAN |
 | [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`
+Cópias versionadas no Git: `docs/technical/Cliente-Vendedor-Vinculo-e-Permissoes.md`, `docs/technical/Client-Details-Criar-Usuario.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.).
+- Dono da tela `ClientDetails` e abas (geral, contatos, documentos, **vendedores**, 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.
+- Gestão administrativa de vendedores e comissões: apenas quando `APP_TYPE=MANAGER`.
+- Fora de `MANAGER` (ex.: CRM): pode identificar o vendedor, sem expor comissão nem CRUD administrativo.
 
 ## Regras específicas
 
@@ -44,7 +44,13 @@ Cópia versionada no Git: `docs/technical/Cliente-Vendedor-Vinculo-e-Permissoes.
 ### 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 |
+| `api-platform-users` | Backend `POST /users` (ROLE_HUMAN) | https://github.com/ControleOnline/api-platform-users/wiki |
 | `app-community` | Home do app e mapa de submódulos | https://github.com/ControleOnline/app-community/wiki |
+
+### Usuários no detalhe de pessoa
+
+- Aba `UsersTab` em `src/react/components/tabs/` (helpers em `usersTabHelpers.js`, modais em `UserFormModal` / `UserApiKeyModal`).
+- Lista geral da empresa: `UsersPage` em `ui-users` (rota Manager `UsersPage` / path `users`).

package/docs/technical/Client-Details-Criar-Usuario.md

@@ -0,0 +1,113 @@
+# Client Details — criar usuário (UsersTab)
+
+Documentação técnica do fluxo de **criação de usuário** na tela **Client Details** (`/client-details`), com foco no contexto `contextKey=employee` e demais contexts que reutilizam a aba Usuários.
+
+Trilha de origem: [app-community#369](https://github.com/ControleOnline/app-community/issues/369).
+
+## Como este módulo se encaixa
+
+| Visão (`APP_TYPE`) | Uso neste fluxo |
+| --- | --- |
+| **MANAGER** | Detalhe administrativo de pessoa/cliente/colaborador; aba **Usuários** permite listar e **criar** usuário vinculado à pessoa |
+| **CRM** / outros | Reutilizam `ClientDetails` conforme rota e `contextKey`; a mesma aba e contrato de API se aplicam quando a tab de usuários está visível |
+
+`contextKey` (query) seleciona o modo do detalhe (`employee`, `client`, `provider`, contatos, etc.). A criação de usuário na aba Usuários **não** depende de um `contextKey` exclusivo: o contrato de payload e autenticação é o mesmo.
+
+## Objetivo
+
+Registrar regras de negócio, contratos de API e modularização do fluxo:
+
+1. listagem de usuários da pessoa no detalhe;
+2. criação de usuário via `POST /users` com autenticação de sessão e vínculo correto à pessoa (IRI);
+3. feedback de sucesso/erro (incluindo falhas de autenticação);
+4. componentes e helpers ≤ 500 linhas, com testes unitários e smoke browser.
+
+## Repositórios afetados
+
+| Módulo | Papel no fluxo |
+| --- | --- |
+| `ui-customers` | Página `ClientDetails`, aba `UsersTab`, helpers e smoke de criação |
+| `api-platform-users` | Recurso `User`, operação `POST /users` (`CreateUserAction`), security `ROLE_HUMAN` |
+| `app-community` | Composição / pin dos submódulos; rota `/client-details` |
+
+## Regras de negócio (UI)
+
+### Entrada
+
+- Rota: `/client-details?clientId=<id>&contextKey=<contexto>` (ex.: `employee`).
+- Aba: **Usuários** (`UsersTab`), ou equivalente quando o detalhe expõe a tab de usuários.
+- Ação: **Adicionar Usuário** → modal com username, senha, confirmação (e timezone quando aplicável).
+
+### Criação — contrato do payload
+
+O frontend **deve** enviar:
+
+| Campo | Formato | Observação |
+| --- | --- | --- |
+| `username` | string | Obrigatório |
+| `password` | string | Obrigatório (política de senha via `ui-common`) |
+| `people` | **IRI** `/people/{id}` | **Não** enviar id numérico nu (`"106218"`). Use `toPeopleIri(client.id \| client['@id'])` |
+| `timezone` | IRI `/timezones/{id}` ou omitido | Opcional |
+
+Helper canônico: `toPeopleIri` em `src/react/components/tabs/usersTabHelpers.js`.
+
+### Autenticação na requisição
+
+- O `POST /users` exige usuário autenticado com papel **`ROLE_HUMAN`** (`securityPostDenormalize` na operação Post do recurso `User`).
+- A camada de API do app deve enviar o token/header de sessão válido (ex.: `API-TOKEN`). Ausência de credencial resulta em falha de auth (historicamente o backend podia responder HTTP 500 com `{"message":"Authentication required"}`; a UI trata 401 e a mensagem “Authentication required” de forma explícita).
+
+### Feedback de erro
+
+`extractErrorMessage` (mesmo helpers):
+
+- HTTP **401** → mensagem orientando novo login;
+- corpo com texto *Authentication required* → mesma mensagem amigável em PT;
+- violações de validação / política de senha → mapeadas via `mapPasswordErrorMessage`.
+
+Após sucesso, o usuário criado entra na listagem local da aba (normalização via `normalizeUserItem`).
+
+## Regras de negócio (API)
+
+| Operação | Segurança | Controller |
+| --- | --- | --- |
+| `POST /users` | `is_granted('ROLE_HUMAN')` (securityPostDenormalize) | `CreateUserAction` → `UserService::createUserFromContent` |
+| `DELETE /users/{id}` | `ROLE_HUMAN` | `DeleteUserAction` |
+| change-api-key / change-password | `ROLE_HUMAN` | controllers dedicados |
+
+O vínculo com a pessoa é feito pelo campo `people` no payload (IRI). Payload com id nu (sem `/people/`) quebra a deserialização/associação e pode se manifestar como erro genérico de autenticação no cliente — por isso o frontend **obrigatoriamente** normaliza para IRI.
+
+## Modularização (UI)
+
+| Arquivo | Papel |
+| --- | --- |
+| `src/react/pages/details.js` | `ClientDetails`, resolução de `contextKey` e tabs |
+| `src/react/components/tabs/UsersTab.js` | Listagem + fluxo create/edit (orquestra store `users`) |
+| `src/react/components/tabs/UsersTabUserModal.js` / `UsersTabApiKeyModal.js` | Modais extraídos |
+| `src/react/components/tabs/usersTabHelpers.js` | `toPeopleIri`, `extractErrorMessage`, `normalizeUserItem`, etc. |
+
+Limite absoluto de linhas do projeto: **≤ 500** por arquivo.
+
+## Testes
+
+| Tipo | Local | Cobertura |
+| --- | --- | --- |
+| Unit | `src/tests/react/components/tabs/usersTabHelpers.test.js` (e `.mjs`) | `toPeopleIri`, `extractErrorMessage` (401 / Authentication required), normalização |
+| Browser smoke | `src/tests/browser/manager/client-details-create-user.spec.js` | `/client-details?...&contextKey=employee&initialTab=users` → Adicionar Usuário → POST com token + people IRI → sucesso na listagem |
+
+## O que este módulo **não** faz
+
+- Não redefine o fluxo de login do usuário recém-criado.
+- Não altera o contrato público de auto-cadastro (outra trilha em `api-platform-people` / auto-cadastro).
+- Não é o enforce de autorização no backend — a UI apenas envia o token de sessão e o IRI correto; o gate real é `ROLE_HUMAN` no `POST /users`.
+
+## Links cruzados
+
+| Destino | URL |
+| --- | --- |
+| Home deste módulo | https://github.com/ControleOnline/ui-customers/wiki |
+| Backend users (Home) | https://github.com/ControleOnline/api-platform-users/wiki |
+| App home | https://github.com/ControleOnline/app-community/wiki |
+| Issue de origem | https://github.com/ControleOnline/app-community/issues/369 |
+| Visões do app | https://github.com/ControleOnline/app-community/blob/master/MODOS_OPERACAO.md |
+
+Cópia versionada no Git: `docs/technical/Client-Details-Criar-Usuario.md`

package/package.json

@@ -1,21 +1,22 @@
 {
   "name": "@controleonline/ui-customers",
-  "version": "1.0.81",
+  "version": "1.0.82",
   "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": "npm run test:supplier-product-flow && npm run test:fiscal-shortcut && npm run test:people-type && npm run test:salesman-tab",
+    "test:people-type": "node --test src/tests/react/components/tabs/peopleType.contract.test.mjs",
     "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"
+    "test:salesman-tab": "node --test src/tests/react/components/tabs/salesmanTab.helpers.test.mjs src/tests/react/components/tabs/salesmanTabHelpers.test.mjs src/tests/react/components/tabs/salesmanTabMedia.no-redeclare.test.mjs"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/controleonline/conline-quasar-ui"
+    "url": "https://github.com/ControleOnline/ui-customers"
   },
   "bugs": "",
   "homepage": "https://www.controleonline.com/devs/plugins",