1. Índice do documento

Requisito original

O pedido, na íntegra (tradução livre da mensagem do usuário), definia as seguintes regras de negócio:

• O Distrital é responsável por criar e gerenciar os distritos.
• No cadastro do usuário deve existir vínculo com o termo/consultor e com o setor correspondente.
• Cada distrito possui seus próprios setores.
• As lojas devem ser vinculadas a setores.
• Cada consultor pertence a um único setor, alocado no momento do cadastro.
• No cadastro/edição de loja deve ser possível vincular a um setor dentro do distrito atual.
• A divisão dos dados respeita: Distrito → Setor → Lojas / Consultores.
• Consultas e listagens devem trazer apenas dados do distrito/setor ao qual o usuário está vinculado.
• Reaproveitar padrões existentes; não duplicar lógica se já houver estrutura de distrito/setor/loja/usuário aproveitável.
• Vínculos devem ser validados no backend, impedindo loja ou consultor associados a setor de outro distrito.

Análise da estrutura existente

Antes de qualquer código, o backend foi inspecionado para entender o que já existia.

2.1 Hierarquia de papéis (já existente)

2.2 O que já existia sobre "distrito"

Um achado central da análise: não existia entidade Distrito no banco de dados. O único vínculo de "distrito" era o auto-relacionamento users.district_manager_id (um Dermoconsultor aponta para o GerenteDistrital responsável por ele). Além disso, a tabela stores já tinha uma coluna chamada district — mas essa coluna é um texto livre de bairro/endereço, sem nenhuma relação com hierarquia organizacional. Essa distinção foi importante para não confundir os dois conceitos durante a implementação.

2.3 Setor: já existia parcialmente

Em uma sessão anterior já havia sido implementada a entidade Setor (agrupando lojas e dermoconsultores), porém de forma independente da hierarquia de distrito — não havia distrito_id em lugar nenhum, e os arquivos (SetorController, SaveSetorRequest, migration, model) ainda estavam não commitados no repositório (apareciam como ?? no git status). A estrutura de Setor existia, mas faltava exatamente a camada que o pedido descreve como topo da hierarquia — o Distrito.

2.4 Padrões de código reaproveitados

• FormRequest por recurso, com regras condicionais via closures quando dependem do usuário autenticado.
• Policies para autorização por instância, além de um Gate global gerenciar-cadastros.
• API Resources para serialização, com whenLoaded/whenCounted.
• Autenticação JWT própria (não Sanctum/sessão) via JwtService.
• Precedente de 404 em vez de 403 para esconder existência de registros fora do escopo do ator (StoreController::unassign()).

Decisões de arquitetura

3.1 Distrito como entidade nova, aditiva

Como não existia representação de "distrito" como registro de banco, foi criada a tabela e o model Distrito. A decisão consciente foi não substituir district_manager_id por essa nova entidade: o mecanismo de hierarquia gerente→consultor já é usado em várias regras de negócio existentes (transferências, visibilidade de rotas, aprovações). Reescrevê-lo teria um raio de impacto muito maior do que o pedido exige. Em vez disso, o Distrito foi encaixado ao lado: o Distrital ganhou uma coluna distrito_id (qual distrito ele administra), e o Setor ganhou distrito_id (a qual distrito pertence). O district_manager_id continua controlando quem gerencia quem; o distrito_id controla a que distrito cada setor/gerente pertence.

3.2 Hipótese sobre "termo/consultor"

O pedido usa a expressão "termo/consultor". Não existe campo ou tabela "termo" em nenhum lugar do pdv-api ou do pdv-web. A hipótese assumida — e sinalizada ao usuário em vez de implementada silenciosamente — foi tratar "termo/consultor" como sinônimo do Dermoconsultor já existente, vinculado ao distrital via district_manager_id.

3.3 Setor obrigatório, Distrito do gerente opcional

Um Setor sempre pertence a um distrito (distrito_id é NOT NULL com restrictOnDelete()). Já o distrito_id em users é nullable: um Distrital recém-criado ainda não administra nenhum distrito até criar um (ou ser vinculado por um Nacional) — reflete o fluxo real de que o distrito nasce depois do usuário, não antes.

3.4 Quem pode criar o quê

3.5 Por que 404 em vez de 403/422 em alguns pontos

Sempre que um Distrital tenta acessar diretamente (via show/update) um registro de outro distrito, a resposta é 404, não 403 — retornar 403 confirmaria que o registro existe, vazando informação sobre recursos fora do escopo do usuário. Quando o problema está no corpo da requisição (por exemplo, setor_id de outro distrito), a resposta é 422, porque o próprio ator já sabe da tentativa — não há vazamento de informação nova.

Modelo de dados e hierarquia

4.1 Tabelas

Migration: database/migrations/2026_08_30_190000_create_distritos_table.php. O down() desfaz na ordem inversa para respeitar as FKs.

Implementação — arquivos novos

novoapp/Models/Distrito.php

class Distrito extends Model
{
    protected $fillable = ['name', 'status'];
    protected $attributes = ['status' => 'ATIVO'];

    public function setores(): HasMany
    {
        return $this->hasMany(Setor::class);
    }

    /** Gerentes distritais que administram este distrito. */
    public function managers(): HasMany
    {
        return $this->hasMany(User::class);
    }
}

novoapp/Http/Controllers/Api/DistritoController.php

CRUD completo, exceto destroy (distritos não são removidos via API — consistente com o restante do domínio, que usa soft status ATIVO/INATIVO em vez de exclusão física).

public function index(Request $request): AnonymousResourceCollection
{
    $user = $request->user();
    $distritos = Distrito::query()
        ->withCount('setores', 'managers')
        // Distrital só enxerga o próprio distrito.
        ->when($user->isDistrict(), fn ($q) => $q->where('id', $user->distrito_id))
        ->when($request->filled('status'), fn ($q) => $q->where('status', $request->string('status')))
        ->when($request->filled('search'), fn ($q) => $q->where('name', 'like', '%'.$request->string('search').'%'))
        ->orderBy('name')->paginate($request->integer('per_page', 20))->withQueryString();

    return DistritoResource::collection($distritos);
}

/** Distrital que ainda não administra um distrito passa a administrar o que criar. */
public function store(SaveDistritoRequest $request): DistritoResource
{
    $this->authorize('gerenciar-cadastros');
    $user = $request->user();

    if ($user->isDistrict() && $user->distrito_id !== null) {
        throw ValidationException::withMessages(['distrito_id' => 'Você já gerencia um distrito.']);
    }

    $distrito = Distrito::create($request->validated());
    if ($user->isDistrict()) {
        $user->update(['distrito_id' => $distrito->id]);
    }

    return new DistritoResource($distrito);
}

O ponto central desse controller: um Distrital só pode criar um distrito (o primeiro que criar passa a ser o seu), e show/update devolvem 404 para distritos que não são o seu — mesmo padrão de escopo aplicado depois em Setor e Loja.

novoapp/Http/Requests/SaveDistritoRequest.php

Espelha SaveSetorRequest: name obrigatório na criação / opcional na edição, máx. 120 caracteres, único ignorando o próprio registro; status em ATIVO/INATIVO.

novoapp/Http/Resources/DistritoResource.php

Expõe id, name, status, setores_count e managers_count (via whenCounted, populados pelo withCount dos controllers).

completado nesta sessãoEntidade Setor

A entidade Setor já havia sido escrita numa sessão anterior, mas ainda não commitada e sem vínculo com distrito. Nesta sessão ela foi completada com distrito_id e o relacionamento belongsTo(Distrito::class):

class Setor extends Model
{
    protected $table = 'setores';
    protected $fillable = ['distrito_id', 'name', 'status'];
    protected $attributes = ['status' => 'ATIVO'];

    public function distrito(): BelongsTo { return $this->belongsTo(Distrito::class); }
    public function stores(): HasMany { return $this->hasMany(Store::class); }
    public function users(): HasMany { return $this->hasMany(User::class); }
}

SetorController — regra central: Distrital tem o distrito_id forçado (o enviado no payload é ignorado); Nacional precisa informar qual distrito:

public function store(SaveSetorRequest $request): SetorResource
{
    $this->authorize('gerenciar-cadastros');
    $data = $request->validated();
    $user = $request->user();

    if ($user->isDistrict()) {
        if ($user->distrito_id === null) {
            throw ValidationException::withMessages([
                'distrito_id' => 'Você precisa gerenciar um distrito antes de criar setores.',
            ]);
        }
        $data['distrito_id'] = $user->distrito_id; // ignora valor enviado pelo cliente
    } elseif (empty($data['distrito_id'])) {
        throw ValidationException::withMessages(['distrito_id' => 'Informe o distrito do setor.']);
    }

    return new SetorResource(Setor::create($data)->load('distrito'));
}

index() filtra por distrito_id do usuário quando ele é Distrital; show()/update() usam o mesmo abort_unless(..., 404) de escopo; update() remove distrito_id do payload quando o ator é Distrital.

Implementação — arquivos modificados

Resumo do que mudou em cada arquivo já existente, e por quê.

modificadoapp/Models/User.php

• Adicionado distrito_id e setor_id a $fillable.
• Nova relação distrito(): BelongsTo — "distrito que este gerente administra".
• Relação setor(): BelongsTo — setor do consultor.

modificadoapp/Models/Store.php

• setor_id adicionado a $fillable.
• Nova relação setor(): BelongsTo.

modificadoSaveStoreRequest.php · SaveUserRequest.php

Ambos ganharam a mesma regra de validação (closure) para setor_id:

'setor_id' => ['nullable', 'integer', 'exists:setores,id', function ($attribute, $value, $fail) {
    $user = $this->user();
    if ($value && $user?->isDistrict() && Setor::find($value)?->distrito_id !== $user->distrito_id) {
        $fail('Este setor não pertence ao seu distrito.');
    }
}],

SaveUserRequest ganhou também distrito_id (nullable, exists:distritos,id) — usado quando o Nacional cadastra/edita um Distrital diretamente.

modificadoapp/Policies/StorePolicy.php

Antes, qualquer gerente podia ver/editar/atribuir qualquer loja. Agora, um Distrital só pode fazer isso dentro do próprio distrito:

public function view(User $actor, Store $store): bool
{
    if ($actor->role->isManager()) { return $this->withinOwnDistrito($actor, $store); }
    return $store->activeAssignments()->where('user_id', $actor->id)->exists();
}

/** Distrital só administra lojas de setores do próprio distrito. */
private function withinOwnDistrito(User $actor, Store $store): bool
{
    return ! $actor->isDistrict() || $store->setor?->distrito_id === $actor->distrito_id;
}

Nacional não é afetado: isDistrict() é false para ele, logo a checagem sempre retorna true no primeiro termo do ||.

modificadoStoreController.php

• index() restringe lojas às do distrito do Distrital via whereHas('setor', ...).
• Novos filtros de query string: ?setor_id= e ?distrito_id=.
• show/store/update passam a carregar a relação setor.

modificadoUserController.php

• Novos filtros: ?setor_id= e ?distrito_id= (cobre tanto o Distrital que administra aquele distrito quanto o consultor cujo setor pertence a ele).
• Todos os pontos que retornam UserResource passam a carregar setor e distrito.

modificadoStoreResource.php · UserResource.php

Ambos ganharam blocos setor_id / setor (via whenLoaded); UserResource ganhou também distrito_id / distrito.

modificadodatabase/seeders/DemoSeeder.php

Passa a criar um Distrito ("Distrito Fortaleza") antes do usuário Distrital, vincula o Distrital a ele, cria um Setor ("Setor Centro-Aldeota") dentro desse distrito, e vincula o Dermoconsultor e as lojas de exemplo a esse setor — o ambiente de demonstração já nasce com a hierarquia completa preenchida.

modificadoroutes/api.php

// Distritos: nível organizacional acima do setor (Distrito -> Setor -> Lojas/Consultores).
Route::apiResource('distritos', DistritoController::class)->except('destroy')
    ->parameters(['distritos' => 'distrito']);

// Setores: agrupam lojas e dermoconsultores dentro de um distrito.
Route::apiResource('setores', SetorController::class)->except('destroy')
    ->parameters(['setores' => 'setor']);

Camadas de validação (defense in depth)

A regra "garanta que os vínculos sejam validados no backend para evitar que uma loja ou consultor seja associado a um setor de outro distrito" foi implementada em quatro camadas independentes, cada uma cobrindo um ponto de entrada diferente. Mesmo que uma camada seja contornada ou removida por engano no futuro, as outras ainda protegem a invariante.

Melhorias adicionais (segunda rodada)

Após a implementação inicial atender ponto a ponto o pedido original, foi feita uma revisão adicional por iniciativa própria, focada em fechar uma lacuna de integridade de dados (não apenas de autorização) que as camadas 1–3 não cobriam.

8.1 Lacuna encontrada: transferência de consultor não revalidava o setor

UserService::transfer() move um Dermoconsultor de um Distrital para outro. As validações em SaveStoreRequest/SaveUserRequest só entram em ação quando o próprio Distrital está editando; a transferência, porém, é operação exclusiva do Nacional. Antes da correção, era possível transferir um consultor para um gerente cujo distrito não tinha relação nenhuma com o setor_id atual do consultor.

8.2 Correção: guard compartilhado entre create/update/transfer

/** Consultor e gerente distrital precisam pertencer ao mesmo distrito. */
private function guardSetorDistrito(?int $setorId, ?int $managerId): void
{
    if ($setorId === null || $managerId === null) { return; }

    $setorDistritoId = Setor::find($setorId)?->distrito_id;
    $managerDistritoId = User::find($managerId)?->distrito_id;

    if ($setorDistritoId !== null && $managerDistritoId !== null && $setorDistritoId !== $managerDistritoId) {
        throw ValidationException::withMessages([
            'setor_id' => 'O setor informado não pertence ao distrito do gerente distrital.',
        ]);
    }
}

Reutilizado nos três pontos de entrada do serviço de usuários:

• create() — antes de User::create($data).
• update() — antes de aplicar as mudanças, usando o valor novo ou o atual como fallback.
• transfer() — antes de mover o consultor, usando seu setor_id atual contra o distrito_id do gerente de destino.

Um guard irmão, guardDistrito(), também foi adicionado para impedir que distrito_id seja setado em qualquer papel que não seja GerenteDistrital.

8.3 Filtros de consulta por distrito

Adicionado ?distrito_id= em GET /api/stores e GET /api/users, permitindo que um Nacional filtre a listagem por distrito sem precisar descobrir os setor_id daquele distrito manualmente.

Endpoints da API

Testes e verificação

10.1 Suíte automatizada

tests/Feature/Pdv360FlowTest.php ganhou dois novos testes ponta a ponta (via HTTP real, autenticando com JWT emitido por JwtService):

• test_distrito_scopes_setores_and_blocks_cross_district_links() — confirma que o Distrital só lista/vê setores do próprio distrito (404 no alheio); que forçar distrito_id de outro distrito é ignorado; e 422 ao vincular loja/consultor a setor de outro distrito.
• test_transfer_blocks_setor_from_a_different_distrito() — transferência para gerente de outro distrito é bloqueada com 422 em setor_id.

{"tool":"phpunit","result":"passed","tests":17,"passed":17,"assertions":90,"duration_ms":419}

Progressão ao longo da sessão: 15 testes (linha de base) → 16 → 17. Todos verdes em cada etapa.

10.2 Estilo de código

./vendor/bin/pint --dirty --test apontou violações de fully_qualified_strict_types e ordered_imports em seis arquivos. Corrigido com auto-fix; suíte re-executada e 100% verde depois da formatação.

10.3 Verificação manual

Com o servidor local rodando e o banco SQLite resetado (migrate:fresh --seed, seguro por ser um banco de demonstração reproduzível pelo DemoSeeder), foram exercitados via curl: login Nacional/Distrital, escopo de /api/setores e /api/distritos, forçar distrito_id de outro distrito na criação (ignorado), vincular loja a setor de outro distrito (422), acesso direto a setor/distrito fora de escopo (404). Todos os comportamentos bateram com o desenho da Seção 07.

Lacunas conhecidas e próximos passos

• Migração de dados legados: lojas e consultores criados antes desta mudança têm setor_id nulo; hoje só é possível vincular registro a registro pelo PUT existente.
• Exclusão de distrito/setor: propositalmente fora do escopo do CRUD, consistente com o padrão do domínio de usar status em vez de exclusão física.
• Migração de lojas ao transferir consultor: pendência de negócio pré-existente no próprio código — não foi criada nem resolvida nesta sessão, apenas preservada.