funifier-mcp 0.2.26 → 0.2.27

package/datasource-funifier-docs/knowledge/modules/team.md

@@ -1,75 +1,593 @@
-# Team (Equipe)
+# `team`
 
 **Acesso Studio:** `/studio/team`
 **API Endpoint:** `/v3/team`
+**Coleção MongoDB:** `team` (coleções auxiliares: `principal`, `team_player`; coleção legada: `team_challenge`)
 
-## O que é
+> Documentação de engenharia reversa baseada **exclusivamente** no código de `funifier-service` (pacote `com.funifier.engine.team` + `com.funifier.rest.v3.rest.TeamRest`). Reflete o comportamento real do runtime, não a documentação anterior.
 
-Configuração de grupos ou equipes de jogadores. Permite criar grupos fixos (como "Equipe de Vendas") ou equipes dinâmicas, formadas automaticamente com base em critérios como aniversariantes do dia. Equipes permitem competição ou colaboração entre grupos.
+---
 
-## Quando usar
+## 1. Visão Geral
 
-- Quando há competição ou colaboração entre grupos
-- Para organizar jogadores por departamento, região ou função
-- Para criar rankings por equipe
-- Para atribuir desafios coletivos
+O módulo `team` agrupa jogadores em **equipes**. Uma equipe é uma entidade de gamificação de primeira classe: ao ser criada, recebe um registro na coleção `principal` (`type = 1 / TYPE_TEAM`), o que permite que a equipe **participe de desafios, acumule pontos, itens e níveis exatamente como um jogador** — todos os totais da equipe são lançamentos da coleção `achievement` cujo campo `player` é o `_id` da equipe.
 
-## Checklist de Configuração no Studio
+Papel arquitetural:
 
-- [ ] Definir _id da equipe
-- [ ] Definir nome da equipe
-- [ ] Adicionar descrição e imagem/brasão (opcional)
-- [ ] Adicionar membros à equipe
-- [ ] Definir dono da equipe (owner)
+- **Agrupamento de principais.** A equipe é um `Principal` do tipo time. O `_id` da equipe entra no mesmo espaço de identificadores dos jogadores (coleção `principal`), e por isso pode ser alvo de `achievement`, `action_log`, `challenge_progress`, etc.
+- **Membership (vínculo jogador↔equipe).** Existem dois mecanismos mutuamente exclusivos por equipe:
+  - **Manual** — vínculos persistidos na coleção `team_player` (uma linha `TeamLink` por par equipe/jogador), espelhados no array `player.teams[]`.
+  - **Dinâmico (v4)** — a equipe não tem vínculos persistidos; seus membros são **calculados em tempo de execução** rodando um pipeline de aggregation MongoDB (`Team.dynamic`) sobre uma coleção arbitrária.
+- **Desafios de equipe.** Quando um jogador dispara uma ação, `AchievementManager.fireAction` reavalia a mesma ação para **cada equipe manual** do jogador, gerando achievements no nome da equipe (vide §2.5). É assim que uma equipe “ganha” pontos/desafios.
+- **Status agregado.** `GET /v3/team/{id}/status` calcula o extrato de gamificação **da própria equipe** (não a soma dos membros) via `AchievementManager.calculateTeamStatus`.
 
-## API Endpoints
+Problemas que resolve:
 
-### Listar Equipes
-**Método:** GET
-**Endpoint:** `/v3/team`
+- Competição/colaboração entre grupos (rankings por equipe via `crowning`/leaderboard).
+- Organização de jogadores por departamento, região, função (manual) ou por critério calculado, ex.: “aniversariantes do dia”, “jogadores com score > X” (dinâmico).
+- Atribuição de desafios coletivos (`Challenge.teamChallenge = true`).
 
-### Criar Equipe
-**Método:** POST
-**Endpoint:** `/v3/team`
+Relação direta com outros módulos:
 
-**Exemplo de Body:**
+- `player` — `player.teams[]` é a fonte de verdade do membership manual; salvar um player re-sincroniza `team_player` (vide §2.4).
+- `achievement` — `AchievementManager.fireAction` faz a recursão de desafios de equipe; `calculateTeamStatus` lê achievements da equipe.
+- `principal` — toda equipe cria/atualiza um `Principal` espelho.
+- `challenge` — `teamChallenge = true` direciona desafios para principais do tipo time.
+- `crowning` — `findLeadersByPlayerId(teamId)` devolve posições de leaderboard da equipe.
+- `competition` — reaproveita a classe `AutoJoin` (`com.funifier.engine.competition.AutoJoin`) como configuração de equipe dinâmica.
+
+> **Nota de manutenção (no código):** o comentário em `AchievementManager.java:849` indica que a resolução de equipes do jogador está sendo migrada para Node.js (`"...quando o esau implementar no nodejs"`). O módulo Java aqui descrito é o comportamento vigente no `funifier-service`.
+
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Classes envolvidas
+
+| Classe | Arquivo | Papel |
+|---|---|---|
+| `Team` | `engine/team/Team.java` | Entidade/POJO raiz — documento da coleção `team` |
+| `TeamManager` | `engine/team/TeamManager.java` | Manager: CRUD, membership, resolução dinâmica |
+| `TeamDaoMongo` | `engine/team/TeamDaoMongo.java` | Acesso MongoDB via Jongo; cascatas de delete/reset |
+| `TeamLink` | `engine/team/TeamLink.java` | Vínculo jogador↔equipe persistido em `team_player` |
+| `TeamStatus` | `engine/team/TeamStatus.java` | **Código morto** — definido mas nunca instanciado (vide §7) |
+| `AutoJoin` | `engine/competition/AutoJoin.java` | Configuração de equipe dinâmica (`entity` + `aggregate`) |
+| `Principal` | `engine/player/Principal.java` | Espelho da equipe na coleção `principal` (`type = 1`) |
+| `TeamRest` | `rest/v3/rest/TeamRest.java` | Controller REST `/v3/team` |
+
+Não há `TeamService` separado — a lógica de negócio mora inteiramente em `TeamManager`. O acesso ao Mongo é direto via Jongo dentro de `TeamDaoMongo`.
+
+### 2.2 Pipeline de criação — `TeamManager.add(Team)`
+
+Sequência real (`TeamManager.add`, linhas 34-49 → `TeamDaoMongo.add`, linhas 19-27):
+
+```
+[1] Se team.id é null ou vazio  → team.id = Guid.shortTimeMillis()
+[2] Se team.created é null      → team.created = new Date()
+[3] team.updated = new Date()                     (sempre sobrescreve)
+[4] Monta Principal(id=team.id, name=team.name, type=TYPE_TEAM, teamId=team.id, userId=null)
+[5] mongo.add:
+      - team collection      → c.save(team)        (Jongo save = UPSERT por _id)
+      - principal collection → cP.save(principal)   (UPSERT por _id = team.id)
+```
+
+```mermaid
+flowchart LR
+    A["POST /v3/team"] --> B{"id vazio?"}
+    B -- sim --> C["id = Guid.shortTimeMillis()"]
+    B -- nao --> D["mantem id"]
+    C --> E{"created null?"}
+    D --> E
+    E -- sim --> F["created = now"]
+    E -- nao --> G["mantem created"]
+    F --> H["updated = now"]
+    G --> H
+    H --> I["save(team) UPSERT"]
+    I --> J["save(Principal type=TEAM)"]
+```
+
+Observações de comportamento:
+
+- **Não existe operação de update/PATCH.** `POST /v3/team` sempre chama `add`. Como `c.save` é **upsert por `_id`**, reenviar um POST com um `_id` existente faz **substituição total (full replace)** do documento. Se o corpo não trouxer `created`, o `created` é **reescrito com a data atual** (perde-se a data original).
+- A geração de id no manager (`Guid.shortTimeMillis`) torna o fallback de `TeamDaoMongo.add` (`Guid.newShortGuid`, linha 20) um **ramo morto** — quando `mongo.add` roda, o id já foi definido.
+- `add` é **síncrono** e **não dispara triggers nem webhooks** próprios do módulo team. A equipe só entra no fluxo de eventos quando passa a receber achievements (via desafios de equipe).
+
+### 2.3 Fluxo de adição de membro (manual)
+
+`TeamRest.addMember` → `TeamManager.linkUser` (linhas 188-202):
+
+```mermaid
+sequenceDiagram
+    participant C as Cliente
+    participant R as TeamRest.addMember
+    participant TM as TeamManager
+    participant DAO as TeamDaoMongo
+    participant PM as PlayerManager
+    C->>R: GET /v3/team/{id}/member/add/{playerId}
+    R->>TM: isUserOfTeam(playerId, id)?
+    alt ja e membro
+        R-->>C: 200 (no-op)
+    else nao e membro
+        R->>TM: linkUser(team, playerId)
+        TM->>DAO: linkUser -> save TeamLink em team_player
+        TM->>PM: player.teams += teamId; insert(player)
+        Note over PM: insert re-sincroniza team_player a partir de player.teams<br/>e chama updateUserStatus(playerId)
+        R-->>C: 200 {team, player}
+    end
+```
+
+- A resposta é sempre `{ "team": id, "player": playerId }` — **não** retorna a equipe nem a lista de membros.
+- `linkUser` deduplica (`teamIds.remove` seguido de `add`) antes de salvar o player.
+- `POST /v3/team/{id}/member/bulk` (corpo = `["p1","p2",...]`) processa em laço e devolve um status por membro: `DONT_EXIST` (player inexistente), `MEMBER_ADDED`, `ALREADY_MEMBER`.
+
+### 2.4 Re-sincronização `player.teams[]` → `team_player`
+
+Ponto não óbvio: a coleção `team_player` é **derivada de `player.teams[]`** a cada save de player (`PlayerManager`, linhas 309-320):
+
+```
+[1] teamDao.deleteLinksByPlayer(player.id)        → apaga TODOS os TeamLink do jogador
+[2] para cada teamId em player.teams:
+      team = teamDao.findById(teamId)
+      se team != null E team.dynamic == null:
+          teamDao.linkUser(teamId, player.id)      → recria o vínculo
+[3] updateUserStatus(player.id)
+```
+
+Consequências:
+
+- Editar `player.teams[]` (via `PUT/POST /v3/player`) é uma **forma alternativa e equivalente** de gerenciar membership manual.
+- Equipes **dinâmicas são ignoradas** nesse passo (`team.dynamic == null`); um id de equipe dinâmica em `player.teams[]` é **silenciosamente descartado** (não vira `TeamLink`).
+- Um id de equipe **inexistente** em `player.teams[]` também é descartado em silêncio.
+- Como `TeamManager.linkUser`/`removeUsers` chamam `playerManager.insert(player)`, toda mutação de membership manual passa por essa re-sincronização completa + recálculo de status.
+
+### 2.5 Desafios de equipe — recursão em `fireAction`
+
+`AchievementManager.fireAction` (linhas 815-823), após avaliar os desafios do **jogador**:
+
+```
+se principal é PLAYER:
+    teamIds = findTeamIdsByUserId(userId)          // AchievementManager:850 — SOMENTE team_player
+    para cada teamId:
+        fireAction(new ActionLog(actionId, teamId, time, attributes))
+```
+
+Na chamada recursiva, o principal resolvido é a **equipe** (`type = TEAM`), então apenas desafios com `teamChallenge = true` são avaliados, e os achievements resultantes são gravados com `player = teamId`.
+
+```mermaid
+flowchart TB
+    A["Jogador dispara acao"] --> B["fireAction(player)"]
+    B --> C["Avalia desafios do jogador"]
+    C --> D{"principal e PLAYER?"}
+    D -- sim --> E["findTeamIdsByUserId(userId)<br/>SOMENTE team_player (manual)"]
+    E --> F["para cada teamId"]
+    F --> G["fireAction(teamId) recursivo"]
+    G --> H["Avalia desafios teamChallenge=true"]
+    H --> I["addAchievement(player=teamId)"]
+    D -- nao --> Z["fim"]
+```
+
+> **Assimetria crítica (vide §7):** a recursão usa `AchievementManager.findTeamIdsByUserId` (linha 850), que consulta **apenas** `team_player`. Equipes **dinâmicas não entram nessa lista**, logo **membros de equipes dinâmicas nunca disparam desafios de equipe**. Isto difere de `TeamManager.findTeamIdsByUserId` (linha 204), que inclui dinâmicas — e que é o método usado por `GET /v3/player/{id}/team`.
+
+Quando o principal é uma equipe, o passo de “update status” é um **TODO vazio** (`AchievementManager.java:807-809`): **não existe `player_status` materializado para equipes**. O status da equipe é sempre calculado sob demanda.
+
+### 2.6 Resolução de membership — `findUserIdsByTeamId`
+
+```mermaid
+flowchart LR
+    A["findUserIdsByTeamId(teamId)"] --> B["findById(teamId)"]
+    B --> C{"team.dynamic.entity E<br/>team.dynamic.aggregate definidos?"}
+    C -- sim --> D["roda pipeline em dynamic.entity<br/>coleta _id de cada doc"]
+    C -- nao --> E["team_player.distinct(linkId)<br/>where teamId"]
+    D --> F["lista de ids dinamica"]
+    E --> G["lista de ids manual"]
+```
+
+`findDynamicMemberIds` (linhas 318-337): desserializa `dynamic.aggregate` (string JSON) numa lista de estágios, executa `collection(dynamic.entity).aggregate(estágio[0])` encadeando `.and(estágio[i])`, e coleta o campo `_id` de cada resultado. `isDynamicMember` (linhas 339-355) faz o mesmo e anexa um estágio final `{$match:{_id: <user>}}` para testar pertinência de um jogador específico.
+
+### 2.7 Status da equipe — `calculateTeamStatus`
+
+`AchievementManager.calculateTeamStatus(teamId)` (linhas 1086-1129) retorna um objeto **`PlayerStatus`** (não `TeamStatus`), tratando o `teamId` como se fosse um `player`:
+
+| Campo do status | Origem |
+|---|---|
+| `player`, `name`, `image`, `extra` | Copiados do documento `team` |
+| `total_challenges`, `challenges` | `achievement` `type=CHALLENGE` onde `player = teamId` |
+| `total_points`, `point_categories` | `sumTotalPoints(teamId)` / `getTotalPointsGroupedByType(teamId)` |
+| `total_catalog_items`, `catalog_items` | `achievement` `type=CATALOG_ITEM` onde `player = teamId` |
+| `challenge_progress` | `challenge_progress` onde `player = teamId` |
+| `positions` | `crowningManager.findLeadersByPlayerId(teamId)` (envolto em try/catch silencioso) |
+| `time` | `new Date()` |
+
+> O status reflete **as conquistas da própria equipe** (geradas por desafios de equipe), **não** a soma das conquistas individuais dos membros.
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `Team` — documento raiz (coleção `team`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | auto (`Guid.shortTimeMillis()`) | — | Id da equipe. Se ausente/vazio no POST, é gerado. |
+| `name` | String | — | não (recomendado) | Nome de exibição. Copiado para o `Principal`. |
+| `description` | String | — | não | Descrição livre. |
+| `image` | `Image` | — | não | Estrutura `{small, medium, original}`, cada um `{url}`. |
+| `extra` | `Map<String,Object>` | `{}` | não | Atributos arbitrários. Persistido e devolvido. Lido em `calculateTeamStatus`. |
+| `owner` | String | — | não | **Persistido mas nunca lido** em nenhum ponto do código (campo decorativo — vide §7). |
+| `created` | Date | `now` no 1º save | — | Definido por `add` apenas se null; reescrito em re-POST sem `created`. |
+| `updated` | Date | `now` | — | Reescrito em todo `add`/`update`. |
+| `dynamic` | `AutoJoin` | — | não | Configuração de equipe dinâmica (v4). Se presente e válido, a equipe não usa `team_player`. |
+
+**Getters/setters:** a entidade só expõe getters/setters para `id`, `name`, `image`, `description`. Os campos `extra`, `owner`, `created`, `updated`, `dynamic` são **públicos** e mapeados diretamente pelo Jackson.
+
+`@JsonIgnoreProperties(ignoreUnknown = true)` — campos desconhecidos no corpo do POST são **ignorados silenciosamente**.
+
+### 3.2 `AutoJoin` — configuração dinâmica (`Team.dynamic`)
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `entity` | String | Coleção MongoDB onde o pipeline é executado (ex.: `"player"`). |
+| `aggregate` | String | **String JSON** com um array de estágios de aggregation. Deve retornar documentos cujo `_id` é o id do membro (ex.: `[{"$project":{"_id":1}}]`). |
+
+Ambos `entity` e `aggregate` precisam estar **não-nulos** para a equipe ser tratada como dinâmica (`TeamManager:240, 319, 340`). Caso contrário, cai no caminho manual.
+
+### 3.3 `TeamLink` — vínculo manual (coleção `team_player`)
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `_id` | String | `Guid.newShortGuid()` por vínculo. |
+| `teamId` | String | Id da equipe. |
+| `linkId` | String | Id do jogador (membro). |
+
+### 3.4 `Principal` — espelho da equipe (coleção `principal`)
+
+Criado/atualizado a cada `add`. Para equipes: `_id = teamId`, `name = team.name`, `type = 1 (TYPE_TEAM)`, `teamId = teamId`, `userId = null`.
+
+**Enum `Principal.type`:**
+
+| Valor | Constante | Significado |
+|---|---|---|
+| `0` | `TYPE_USER` | Principal é um jogador |
+| `1` | `TYPE_TEAM` | Principal é uma equipe |
+
+### 3.5 `TeamStatus` — subentidade **inativa**
+
+`TeamStatus extends Team` adiciona um booleano `joined`. **Nunca é instanciada** em lugar nenhum do repositório (vide §7). O endpoint de status retorna `PlayerStatus`, não esta classe.
+
+### 3.6 Coleções escritas pelo módulo
+
+| Coleção | Conteúdo | Quem escreve |
+|---|---|---|
+| `team` | Documentos `Team` | `add`/`update` |
+| `principal` | Espelho `Principal` (type=1) | `add`/`update`/`delete` |
+| `team_player` | Vínculos `TeamLink` manuais | `linkUser`/`removeUsers`/sync do player |
+| `team_challenge` | **Legado** — vínculos via `linkChallenge` (`@Deprecated`) | Não usado em fluxo ativo (§7) |
+
+---
+
+## 4. Endpoints
+
+Todos os endpoints exigem `Authorization: Bearer <token>` (`@BeanParam AuthBean`). O tenant é resolvido por `FrontController.getInstance(authBean.getApiKey())` — isolamento por organização (§8).
+
+### `GET /v3/team` — listar/consultar equipes
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Lista paginada de equipes (`findAllPaginated`) |
+| Autenticação | Bearer token |
+| Paginação | Header `Range: items=0-100` (default 0-100); `max_results` default 100 |
+
+**Query params:**
+
+| Param | Tipo | Descrição |
+|---|---|---|
+| `team` | String | Ids separados por vírgula → `{_id:{$in:[...]}}`. |
+| `name` | String | Filtro `{name:{$regex:<name>, $options:'i'}}` (substring, case-insensitive). |
+| `q` | String | **Critério MongoDB cru** injetado diretamente no `$match` (`", " + q`). Ex.: `extra.country:"USA"`. Superfície de injeção (§8). |
+| `fields` | String | Projeção `$project` (campos separados por vírgula). |
+| `orderby` | String | Campo de ordenação (`$sort`). |
+| `reverse` | boolean | `true` → ordem decrescente. |
+| `max_results` | int | Limite (`$limit`); `<=0` vira 100. |
+
+**Comportamento real:** monta um pipeline de aggregation `[$match, ($project), ($sort), ($limit)]`. A resposta é o envelope paginado padrão (`Callback.paginatedCallback`).
+
+### `GET /v3/team/{id}` — obter uma equipe
+
+Retorna o documento `Team` (campos null removidos via `JsonUtil.toJsonRemoveNullFields`). Não embute membros.
+
+### `GET /v3/team/{id}/status` — extrato de gamificação da equipe
+
+Retorna um `PlayerStatus` calculado por `calculateTeamStatus` (§2.7). Reflete as conquistas **da equipe**, não dos membros.
+
+### `POST /v3/team` — criar/substituir equipe
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | `TeamManager.add` (upsert por `_id`) |
+| Full replace ou patch | **Full replace** (não há PATCH). Re-POST com `_id` existente substitui o documento inteiro. |
+| Status | `201 CREATED`; corpo = a equipe (com `_id`/`created`/`updated` preenchidos) |
+
+**Exemplo de request:**
 ```json
 {
   "_id": "sales",
   "name": "Sales",
   "description": "Funifier sales team",
   "image": {
-    "small": {"url": "https://my.funifier.com/images/funny.png"},
-    "medium": {"url": "https://my.funifier.com/images/funny.png"},
-    "original": {"url": "https://my.funifier.com/images/funny.png"}
+    "small": {"url": "https://my.funifier.com/funny.png"},
+    "medium": {"url": "https://my.funifier.com/funny.png"},
+    "original": {"url": "https://my.funifier.com/funny.png"}
   },
-  "extra": { "country": "USA" },
+  "extra": {"country": "USA"},
   "owner": "john"
 }
 ```
 
-### Excluir Equipe
-**Método:** DELETE
-**Endpoint:** `/v3/team/:id`
+### `DELETE /v3/team/{id}` — excluir equipe (cascata)
+
+`TeamManager.delete` (linhas 66-72) → `removeUsers(membros)` → `mongo.delete`:
+- remove `principal {teamId:id}`
+- remove `team {_id:id}`
+- remove `team_player {teamId:id}`
+- executa `reset(id)` (vide abaixo)
+
+Resposta `204 NO_CONTENT`.
+
+### `DELETE /v3/team/{id}/reset` — **reset destrutivo**
+
+`TeamManager.reset` → `TeamDaoMongo.reset` (linhas 37-46) apaga, tratando `id` como id de jogador, **8 coleções**:
+
+| Coleção | Filtro |
+|---|---|
+| `action_log` | `{userId:id}` |
+| `mystery_box_log` | `{player:id}` |
+| `player_status` | `{_id:id}` |
+| `achievement` | `{player:id}` |
+| `challenge_progress` | `{player:id}` |
+| `lottery_ticket` | `{player:id}` |
+| `competition_join` | `{player:id}` |
+| `folder_log` | `{player:id}` |
+
+Resposta `200 OK`.
+
+> **Atenção:** não há validação de que `id` é uma equipe. Se um `id` de **jogador** for passado, os dados de gamificação **desse jogador** são apagados. Vide anti-pattern em §10.
+
+### `GET /v3/team/{id}/member` — listar membros (objetos `Player`)
+
+Resolve ids via `findUserIdsByTeamId` (manual **ou** dinâmico) e carrega cada `Player`. Custo O(n) de `findById` por membro.
+
+### `GET /v3/team/{id}/memberids` — listar ids dos membros
+
+Mesma resolução, devolve apenas a lista de ids.
+
+### `GET /v3/team/{id}/member/add/{playerId}` — adicionar membro
+
+`isUserOfTeam` → se não membro, `linkUser` (§2.3). Resposta `{team, player}`. **Não tem efeito útil em equipes dinâmicas** (membership é calculado; o `TeamLink` criado seria ignorado na resolução dinâmica).
+
+### `POST /v3/team/{id}/member/bulk` — adicionar membros em lote
+
+Corpo: array de ids `["p1","p2"]`. Retorna `{team, members:[{member, status}]}` com `status ∈ {DONT_EXIST, MEMBER_ADDED, ALREADY_MEMBER}`. Status `201 CREATED`.
+
+### `GET /v3/team/{id}/member/remove/{playerId}` — remover membro
+
+`isUserOfTeam` → se membro, `removeUsers([playerId], id)` (remove `TeamLink` + atualiza `player.teams`). Resposta `200 OK`.
+
+### Endpoints de membership no controller de player
+
+São equivalentes funcionais aos de `team` (mesmos métodos de `TeamManager`):
+
+| Método | Endpoint | Ação |
+|---|---|---|
+| GET | `/v3/player/{id}/team` | Lista equipes do jogador (`TeamManager.findTeamIdsByUserId` — **inclui dinâmicas**) |
+| GET | `/v3/player/{id}/team/join/{teamId}` | `linkUser` (entrar) |
+| GET | `/v3/player/{id}/team/unjoin/{teamId}` | `removeUsers` (sair) |
+
+---
+
+## 5. Regras de Negócio
+
+Regras presentes no código e **não** evidentes pelo schema:
+
+- **Membership manual vs dinâmico é exclusivo por equipe.** Se `dynamic.entity` e `dynamic.aggregate` estão definidos, a equipe **ignora** completamente `team_player`; vínculos manuais criados nessa equipe não têm efeito na resolução de membros.
+- **`player.teams[]` é a fonte de verdade do membership manual.** `team_player` é reconstruído a partir dele em todo save de player (§2.4).
+- **Equipe é um principal.** Pontos/desafios/itens da equipe vivem em `achievement` com `player = teamId`. Não há campo agregado de “pontos da equipe” no documento `team`.
+- **Desafios de equipe só alcançam membros manuais** (assimetria de §2.5/§7).
+- **Idempotência de criação:** `POST` é upsert; reenviar com mesmo `_id` substitui o documento (e zera `created` se omitido).
+- **Sem update parcial:** a única forma de “editar” é re-POSTar o objeto completo.
+- **Multi-tenant:** todo acesso é escopado pela `apiKey` do bearer (instância isolada de `ManagerFactory`/conexão Mongo). Não há vazamento entre organizações.
+- **`name` propaga para `principal`:** em `update` (não exposto) e em saves de player, o nome do principal é mantido em sincronia; em `add`, o principal é (re)criado com o nome atual.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Geração de `_id` | `add` com id vazio | `Guid.shortTimeMillis()` | `team._id` |
+| Criação do `Principal` espelho | `add` | Equipe vira principal `type=1` | coleção `principal` |
+| `created`/`updated` automáticos | `add` | Datas preenchidas/reescritas | `team` |
+| Sync `player.teams[]` → `team_player` | save de qualquer player | Reescreve vínculos manuais (ignora dinâmicas) | `team_player` |
+| Recálculo de status do jogador | `linkUser`/`removeUsers` (via `insert`) | `updateUserStatus(playerId)` | `player_status` |
+| Recursão de desafio de equipe | `fireAction` de um jogador | Achievements no nome da equipe (só membros manuais) | `achievement` |
+| Cascata de delete | `DELETE /v3/team/{id}` | Remove principal+team+team_player e roda reset | múltiplas coleções |
+| Reset destrutivo | `DELETE /v3/team/{id}/reset` ou delete | Apaga 8 coleções pelo id | múltiplas coleções |
+
+```mermaid
+flowchart TB
+    A["DELETE /v3/team/{id}"] --> B["findUserIdsByTeamId(id)"]
+    B --> C["removeUsers(membros)<br/>limpa team_player + player.teams"]
+    C --> D["remove principal {teamId:id}"]
+    D --> E["remove team {_id:id}"]
+    E --> F["remove team_player {teamId:id}"]
+    F --> G["reset(id)"]
+    G --> H["apaga 8 colecoes:<br/>action_log, mystery_box_log, player_status,<br/>achievement, challenge_progress,<br/>lottery_ticket, competition_join, folder_log"]
+```
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- CRUD de equipes (criar/substituir via POST, ler, listar paginado, excluir).
+- Membership manual: add/remove individual, add em lote (`bulk`), via endpoints de team **ou** de player.
+- Equipes dinâmicas (membros calculados por pipeline de aggregation).
+- Equipe como principal de gamificação (pontos/desafios/itens/níveis via `achievement`).
+- Desafios de equipe (`Challenge.teamChallenge = true`) para **membros manuais**.
+- Status agregado da equipe (`/status`) e posições de leaderboard.
+- Reset destrutivo e cascata de delete.
+
+### ❌ NÃO Suportado / armadilhas confirmadas no código
+
+- **Update parcial / PUT.** `TeamManager.update` existe (remove+save + atualiza nome do principal) mas **não está ligado a nenhum endpoint** (nenhum chamador no repositório). “Editar” = re-POST full replace.
+- **`TeamStatus` é código morto.** A classe e seu campo `joined` nunca são instanciados (`grep "new TeamStatus"` = 0 ocorrências). O endpoint `/status` devolve `PlayerStatus`.
+- **Campo `owner` é decorativo.** Persistido e devolvido, mas **nenhum código o lê** — não confere permissão, propriedade nem qualquer comportamento.
+- **Desafios de equipe não alcançam membros dinâmicos.** `AchievementManager.findTeamIdsByUserId` (linha 850) consulta só `team_player`; equipes dinâmicas ficam de fora da recursão de `fireAction`.
+- **Sem `player_status` materializado para equipes.** `fireAction` tem `// TODO UPDATE TEAM STATUS` vazio; status só existe sob demanda via `calculateTeamStatus`.
+- **`TeamDaoMongo.findByLikeName` está quebrado:** consulta `{team: {$regex:...}}`, mas o campo correto é `name` — sempre retorna vazio. Método **não usado** por nenhum endpoint.
+- **`Team.equals` usa `==` em String** (`this.id == t.id`) — comparação por referência, não por valor. Não está em caminho crítico, mas é incorreto.
+- **Coleção/fluxo `team_challenge` é legado.** `linkChallenge` é `@Deprecated`; `removeTeamsOfChallenge` filtra `{challengeId:#}` enquanto `TeamLink` só tem `linkId`/`teamId` — o filtro nunca casa. Bloco de métodos comentados em `TeamDaoMongo` (findTeamIdsByUserId, findByUserId, findByChallengeId, isUserInChallengeTeams, isUserOfTeam) foi movido para `TeamManager`.
+- **`findAll`, `findLimited`, `findByLikeName` (variantes não paginadas)** não são chamados por nenhum endpoint — `GET /v3/team` usa exclusivamente `findAllPaginated`.
+- **Sem hooks/triggers/webhooks próprios** do módulo team (criação/edição/exclusão de equipe não dispara eventos). Eventos só surgem indiretamente via achievements de desafio de equipe.
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação:** todos os endpoints exigem `Authorization: Bearer <token>` (`AuthBean`). A `apiKey` extraída do token seleciona a instância de `FrontController`/`ManagerFactory`, isolando dados por **organização/tenant**.
+- **Isolamento multi-tenant:** todas as queries rodam na conexão Mongo do tenant; não há cruzamento entre organizações.
+- **Superfícies de injeção (requerem token válido, normalmente de administração):**
+  - `GET /v3/team?q=...` — o parâmetro `q` é **concatenado cru** no `$match` da aggregation (`TeamManager.java:105`). Um cliente autorizado pode injetar operadores arbitrários do Mongo.
+  - `Team.dynamic.aggregate` — é uma **string JSON de pipeline executada como aggregation** sobre `dynamic.entity` (coleção arbitrária). Quem cria/edita equipes dinâmicas controla um pipeline Mongo arbitrário (`findDynamicMemberIds`/`isDynamicMember`). Não há sanitização nem allowlist de coleções/operadores.
+- **Operações destrutivas sem confirmação:**
+  - `DELETE /v3/team/{id}/reset` apaga 8 coleções **pelo id**, sem checar se o id é de equipe — pode apagar dados de um **jogador** homônimo.
+  - `DELETE /v3/team/{id}` remove a equipe e roda o mesmo reset.
+- **Sem autorização granular por equipe:** o campo `owner` não é verificado; qualquer token com acesso ao endpoint pode editar/excluir qualquer equipe do tenant.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+### Diagnóstico rápido
+
+```http
+GET /v3/team/{id}            # a equipe existe? confira _id, dynamic
+GET /v3/team/{id}/memberids  # quem o runtime considera membro (manual ou dinâmico)
+GET /v3/team/{id}/status     # a equipe acumulou pontos/desafios? (achievements com player=teamId)
+GET /v3/player/{id}/team     # de quais equipes o jogador participa (inclui dinâmicas)
+```
+
+### Queries MongoDB úteis
+
+```js
+// Vínculos manuais de uma equipe
+db.team_player.find({ teamId: "sales" })
+
+// Equipes de um jogador (manual)
+db.team_player.distinct("teamId", { linkId: "john" })
+
+// O principal espelho existe? (necessário para desafios de equipe)
+db.principal.findOne({ _id: "sales", type: 1 })
+
+// Conquistas geradas pela equipe (desafios de equipe)
+db.achievement.find({ player: "sales" })
+
+// Todas as equipes dinâmicas
+db.team.find({ "dynamic.entity": { $exists: true }, "dynamic.aggregate": { $exists: true } })
+```
+
+### Erros comuns e causas
+
+| Sintoma | Causa provável |
+|---|---|
+| Equipe não ganha pontos em desafio de equipe | Equipe é **dinâmica** (recursão de `fireAction` só vê `team_player`); ou `Challenge.teamChallenge` não é `true`; ou falta o `principal` (recriar via re-POST). |
+| `/memberids` vazio numa equipe dinâmica | `dynamic.aggregate` não retorna documentos com `_id`, ou `dynamic.entity` errada, ou JSON do pipeline inválido. |
+| Membro adicionado “some” | Save de player sobrescreveu `player.teams[]` e re-sincronizou `team_player` (§2.4); ou a equipe é dinâmica e o `TeamLink` é ignorado. |
+| `created` mudou após “editar” | Re-POST sem o campo `created` (full replace reescreve a data). |
+| Dados de gamificação de um jogador sumiram | Alguém chamou `DELETE /v3/team/{id}/reset` com um id que coincide com o do jogador. |
+| Filtro por nome não funciona via `findByLikeName` | Método legado quebrado (campo `team` em vez de `name`); use `GET /v3/team?name=...`. |
+
+---
+
+## 10. Exemplos Práticos
+
+### Exemplo mínimo (equipe manual)
+
+```http
+POST /v3/team
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{ "_id": "sales", "name": "Sales" }
+```
+```http
+GET /v3/team/sales/member/add/john     # adiciona "john"
+GET /v3/team/sales/memberids           # => ["john"]
+```
+
+### Exemplo avançado (equipe dinâmica)
+
+Equipe cujos membros são, em tempo real, todos os jogadores com `extra.department == "sales"`:
+
+```http
+POST /v3/team
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "_id": "sales_dynamic",
+  "name": "Sales (dinâmico)",
+  "description": "Todos os jogadores do departamento de vendas",
+  "image": { "small": {"url": "https://cdn/sales.png"} },
+  "extra": { "managedBy": "rule" },
+  "dynamic": {
+    "entity": "player",
+    "aggregate": "[{\"$match\":{\"extra.department\":\"sales\"}},{\"$project\":{\"_id\":1}}]"
+  }
+}
+```
+
+- `GET /v3/team/sales_dynamic/memberids` executa o pipeline e devolve os `_id` casados.
+- **Não** adicione membros manualmente nessa equipe — o vínculo seria ignorado.
+- Lembre-se: membros dinâmicos **não** disparam desafios de equipe (§2.5).
 
-### Adicionar Membro
-**Método:** GET
-**Endpoint:** `/v3/team/:id/member/add/:player`
+### Exemplo de membership via player
+
+```http
+GET /v3/player/john/team/join/sales      # entra na equipe
+GET /v3/player/john/team                 # lista equipes de john (inclui dinâmicas)
+GET /v3/player/john/team/unjoin/sales    # sai
+```
 
-### Remover Membro
-**Método:** GET
-**Endpoint:** `/v3/team/:team_id/member/remove/:player_id`
+### Anti-pattern — `reset` confundido com “limpar membros”
 
-### Listar IDs dos Membros
-**Método:** GET
-**Endpoint:** `/v3/team/:team_id/memberids`
+```http
+# ERRADO: a intenção era "remover todos os membros da equipe"
+DELETE /v3/team/john/reset
+```
+Se `john` for (ou coincidir com) um **id de jogador**, este comando **apaga as conquistas, action_logs, status, tickets e progresso do jogador** em 8 coleções — irreversível. Para esvaziar uma equipe, remova membros individualmente (`/member/remove/{playerId}`) ou exclua a equipe (`DELETE /v3/team/{id}`), ciente de que o delete **também** roda o reset.
+
+### Anti-pattern — “editar” com PATCH mental
+
+```http
+# Não existe PATCH. Isto NÃO atualiza só o nome — substitui o documento inteiro:
+POST /v3/team
+{ "_id": "sales", "name": "Novo Nome" }
+# Resultado: description, image, extra, owner e created (se omitido) são PERDIDOS/reescritos.
+```
+Sempre reenvie o objeto **completo** ao re-POSTar.
 
-### Consultar Status da Equipe
-**Método:** GET
-**Endpoint:** `/v3/team/:id/status`
+---
 
-## Validações e Testes
+## Checklist de Configuração
 
-- [ ] Equipe aparece na lista GET /v3/team
-- [ ] Membros foram adicionados corretamente
-- [ ] Status da equipe reflete pontos e desafios dos membros
+- [ ] `_id` definido (ou aceitar o gerado automaticamente).
+- [ ] `name` preenchido (propaga para o `principal`).
+- [ ] Para desafios de equipe: equipe é **manual** (`team_player`) — equipes **dinâmicas não recebem desafios de equipe**.
+- [ ] Para desafios de equipe: existe `principal` com `type=1` (recriado via POST) e o `Challenge` tem `teamChallenge=true`.
+- [ ] Equipe dinâmica: `dynamic.entity` aponta para coleção existente e `dynamic.aggregate` é JSON válido retornando documentos com `_id`.
+- [ ] **Não** misture membership manual com `dynamic` na mesma equipe (manual é ignorado).
+- [ ] Ao “editar”, reenviar o objeto **completo** (full replace) e incluir `created` se quiser preservá-lo.
+- [ ] **Nunca** use `/{id}/reset` para esvaziar membros — ele apaga dados de gamificação do id (tratado como jogador).
+- [ ] Não dependa de `owner` para autorização — o campo não tem efeito.
+- [ ] `q` em `GET /v3/team` é critério Mongo cru — valide a entrada se exposto a clientes não confiáveis.