# P20 — Associações, parceiros e aderência (condicional)

| Campo | Valor |
|---|---|
| Programa | F7+ — operação, estrutura e conteúdo |
| Status | `planejado` (condicionado a cliente; **D14: implantação posterior**) |
| Depende de | P14, P19 |
| Habilita | — |
| Tamanho | **M** (2–3 sessões) |
| ADRs | ADR-001/002, ADR-017/019, ADR-026/027, ADR-033/035 |

## 1. Objetivo

Implementar os módulos de **associação e parceria** que o corpus Sucesu prova — Associados,
Parceiros Institucionais e Associe-se — apenas para clientes cuja estrutura não é o portal municipal
padrão. É uma fase de **aderência**, não parte do MVP municipal.
**D14:** a implantação fica posterior; o desenho A (perfil + módulos opcionais, sem multi-tenant) é
mantido. Se o escopo for simples, tratar como backlog; se complexo, executar A quando houver cliente.

**Resultado observável:** o cliente associação mantém seus associados e parceiros, recebe leads de
associação com consentimento e publica a lista; o portal municipal não é afetado.

## 2. Gate de produto

- Contrato/cliente cujo domínio é associação/entidade representativa; sem isso, a fase **não inicia**
  (permanece `PODE`).
- `structure_type`/perfil de produto definido; navegação e permissões separadas.
- `Unidade Regional` **não** vira multi-tenant: no V7 single-tenant, no máximo uma tabela de
  referência `unidades_regionais` para classificar associados. Isolamento por tenant exigiria ADR
  própria e não pertence a este programa.
- Nada de `Associados`/`Parceiros` no menu do portal municipal padrão.

## 3. Escopo fechado

### S1 — Associados

- Módulo `Conexoes/Associados` (token `associados`), grupo `Conexoes`.
- Tabelas:
  - `associados`: `id`, `slug` único case-insensitive, `nome` jsonb, `categoria_id` FK,
    `unidade_regional_id` nullable, `descricao` AST, `logo_media_id`, `site` (https validado),
    `email` institucional, `telefone` institucional, `active`, `metadata` jsonb, timestamps.
  - `associado_categorias`: `id`, `slug`, `nome` jsonb, `position`, `active`.
  - `unidades_regionais`: `id`, `nome` jsonb, `uf`, `slug`, `active` (referência, não tenancy).
- Portal lista/filtro por categoria/UF; detalhe; CMS CRUD; sitemap/busca.
- Regras: sem CPF de representante; e-mail/telefone institucionais; logo via Media; slug estável.

### S2 — Parceiros Institucionais + Associe-se

- `Conexoes/Parceiros` (token `parceiros`):
  - `parceiros`: `id`, `nome` jsonb, `logo_media_id`, `url` (https), `descricao` AST,
    `position`, `active`; portal grade/lista; CMS.
- `Conexoes/AssocieSe` (token `associe_se`):
  - `associe_se_leads`: `id`, `nome`, `email`, `instituicao`, `mensagem`, `consent_at`, `status`
    enum (`novo|em_contato|convertido|descartado`), `ip_hash`, timestamps.
  - Portal form com honeypot/time-trap/rate limit; notificação (P9); CMS; retenção; LGPD.
- Regras: lead não vira associado automaticamente; conversão é ação explícita auditada; sem PII em
  log; export com cuidado.

### S3 — Fechamento

- E2E: associado/parceiro/lead; busca/sitemap; 4 locales; axe.
- `make check` 2× + `E2E=1`; cobertura ≥90%; PHPStan max 0.
- Se o cliente não for associação, a fase permanece `PODE` e não é aberta.

## 4. Fora de escopo

- Multi-tenant/regional (ADR própria; V7 é single-tenant).
- Financeiro/mensalidade de associados.
- CRM completo.
- Integração com sistema de associados legado (sem ETL, ADR-042).
- Módulos municipais (P14–P19) — esta fase é aderência.

## 5. Fatias de sessão

| Sessão | Entrega | Prova | Depende |
|---|---|---|---|
| **P20.S1** | Associados + categorias + unidades (referência) | slug; sem PII; logo Media; filtros | P14/P19 |
| **P20.S2** | Parceiros + Associe-se | anti-spam; consentimento; conversão explícita | S1 |
| **P20.S3** | E2E, docs, 2× check | 4 locales; axe; evidência no `kd` | S1–S2 |

## 6. DoD

- [ ] Gate de cliente registrado; portal municipal não afetado.
- [ ] Associados/parceiros com slug, logo Media e contatos institucionais.
- [ ] Lead com consentimento, antiabuso, retenção e conversão auditada.
- [ ] `Unidade Regional` é referência, não tenancy.
- [ ] `make check` 2× + `E2E=1`; cobertura ≥90%; PHPStan max 0.

## Fechamento — ficha de revisão

> **Obrigatório antes de fechar:** criar `_to_revision/P20-associacoes.md` e seguir
> `_to_revision/README.md` + `_to_revision/PROTOCOLO.md` (v2.0). A ficha não é gate de build; é a
> entrada da fila de revisão profunda.

- Cabeçalho: fase, `kd` épico/tasks/slices, âncoras (este arquivo, ADRs e código) e status
  `⬜ pendente` → `🟡 em revisão` → `✅ revisado` / `🔧 com correções`.
- Conteúdo: o que foi implementado, arquivos/superfícies a revisar, checklist D1–D14 aplicável,
  riscos e observações.
- Fechamento: preencher “Notas da revisão” com data/revisor/resultado e achados (`kd write
  --anchor`), atualizar a fila em `_to_revision/README.md` e `_to_revision/_inventario.md`.
- Achado com correção exige teste vermelho→verde; a fase só é `closed` no `kd` com a ficha
  registrada.

## 7. Riscos

| Risco | Mitigação |
|---|---|
| Cliente errado ativar módulos de associação | gate + ativação por ADR-034 |
| Multi-tenant acidental | só referência; ADR separada |
| Lead virar associado sem revisão | conversão explícita + auditoria |
| PII em export/log | allowlist + retenção + teste |
| Logo/URL de terceiro | Media local + link validado |

## 8. Retomada

```bash
kd prime
kd ask "associados parceiros associe-se unidade regional sucesu"
kd task list --ready
```

Ler: `sucesu_analise/05_modulos/Conexoes/{Associados,ParceirosInstitucionais,UnidadeRegional}/**`
→ `sucesu_analise/05_modulos/Institucional/AssocieSe/**` → `MODULOS.md` §1/P20.