Fase 14: Governança Comunitária e Sistema de Votação
Duração: 3 semanas (21 dias úteis)
Prioridade: 🔴 CRÍTICA (Essencial para soberania territorial)
Depende de: Nenhuma (pode ser feito em paralelo)
Estimativa Total: 120 horas
Status: ✅ Implementado
🎯 Objetivo
Implementar sistema de governança comunitária que permite:
- Usuários definirem interesses que personalizam o que veem no feed
- Moderação dinâmica definida pela comunidade através de votações
- Sistema de votação para decisões coletivas (priorização de temas, regras, caracterização do território)
- Associação ao perfil (interesses, participação em votações, contribuições)
Princípios:
- ✅ Feed cronológico permanece (não manipula, apenas filtra)
- ✅ Decisões coletivas através de votações
- ✅ Moderadores têm acesso privilegiado, mas comunidade participa
- ✅ Territórios têm autonomia real
📋 Contexto e Requisitos
Estado Atual (pós-implementação)
- ✅ Feed cronológico territorial implementado
- ✅ Sistema de moderação básico (reports, bloqueios)
- ✅ Feature flags por território
- ✅ Interesses do usuário e feed filtrado (opcional,
filterByInterests) - ✅ Sistema de votação comunitária (5 tipos, visibilidade)
- ✅ Moderação dinâmica (regras aplicadas em posts e items)
- ✅ Caracterização do território (tags) e histórico no perfil
Requisitos Funcionais
1. Sistema de Interesses do Usuário
- ✅ Usuário pode definir interesses (tags/categorias)
- ✅ Interesses aparecem no perfil
- ✅ Feed pode ser filtrado por interesses (opcional)
- ✅ Exemplos: "Meio Ambiente", "Eventos", "Marketplace", "Saúde", "Educação", "Cultura"
2. Moderação Dinâmica Comunitária
- ✅ Ferramenta para definir o que é permitido/não permitido no território
- ✅ Moderadores têm acesso privilegiado
- ✅ Usuários podem propor regras
- ✅ Regras podem ser votadas pela comunidade
- ✅ Categorias:
- Tipos de conteúdo permitidos
- Palavras/temas proibidos
- Regras de comportamento
- Política de marketplace
- Política de eventos
3. Sistema de Votação
- ✅ Votações para decisões comunitárias
- ✅ Tipos de votações:
- Priorização de temas (quais aparecem mais no feed)
- Regras de moderação (o que é permitido/não permitido)
- Caracterização do território (tags que descrevem)
- Feature flags territoriais (quais funcionalidades estão ativas)
- Políticas comunitárias (regras de convivência)
- ✅ Votações podem ser:
- Abertas (todos os membros)
- Apenas residents
- Apenas curadores/moderadores
- ✅ Resultados influenciam configuração do território
4. Associação ao Perfil
- ✅ Interesses do usuário aparecem no perfil
- ✅ Histórico de participação em votações
- ✅ Contribuições para moderação comunitária
- ✅ Reputação comunitária (opcional, baseada em contribuições)
📋 Tarefas Detalhadas
Semana 15: Sistema de Interesses
15.1 Modelo de Domínio - Interesses
Estimativa: 8 horas (1 dia)
Status: ✅ Implementado
Tarefas:
- Criar modelo
UserInterest:-
Id,UserId,InterestTag(string) -
CreatedAtUtc - Validação: tag não vazia, máx. 50 caracteres
-
- Criar enum ou lista de interesses predefinidos (opcional):
- "Meio Ambiente", "Eventos", "Marketplace", "Saúde", "Educação", "Cultura", "Esportes", "Arte", "Música", "Tecnologia"
- Criar
IUserInterestRepository - Implementar repositórios (Postgres, InMemory)
- Criar migration
Arquivos a Criar:
backend/Arah.Domain/Users/UserInterest.csbackend/Arah.Application/Interfaces/IUserInterestRepository.csbackend/Arah.Infrastructure/Postgres/PostgresUserInterestRepository.csbackend/Arah.Infrastructure/InMemory/InMemoryUserInterestRepository.csbackend/Arah.Infrastructure/Postgres/Migrations/YYYYMMDDHHMMSS_AddUserInterests.cs
Critérios de Sucesso:
- ✅ Modelo criado
- ✅ Repositórios implementados
- ✅ Migration aplicada
15.2 Serviço de Interesses
Estimativa: 12 horas (1.5 dias)
Status: ✅ Implementado
Tarefas:
- Criar
UserInterestService:-
AddInterestAsync(Guid userId, string interestTag) -
RemoveInterestAsync(Guid userId, string interestTag) -
ListInterestsAsync(Guid userId) -
ListUsersByInterestAsync(string interestTag, Guid territoryId)
-
- Validações:
- Tag não vazia, máx. 50 caracteres
- Máx. 10 interesses por usuário
- Normalização de tags (trim, lowercase)
- Testes unitários
Arquivos a Criar:
backend/Arah.Application/Services/UserInterestService.csbackend/Arah.Tests/Application/UserInterestServiceTests.cs
Critérios de Sucesso:
- ✅ Serviço implementado
- ✅ Validações funcionando
- ✅ Testes passando
15.3 Controller e Integração com Perfil
Estimativa: 12 horas (1.5 dias)
Status: ✅ Implementado
Tarefas:
- Criar
UserInterestsController:-
GET /api/v1/users/me/interests(listar interesses) -
POST /api/v1/users/me/interests(adicionar interesse) -
DELETE /api/v1/users/me/interests/{tag}(remover interesse)
-
- Atualizar
UserProfileResponse:- Adicionar campo
Interests(IReadOnlyList)
- Adicionar campo
- Atualizar
UserProfileService:- Incluir interesses ao buscar perfil
- Validação (FluentValidation)
- Testes de integração (em
GovernanceIntegrationTests)
Arquivos a Criar:
backend/Arah.Api/Controllers/UserInterestsController.csbackend/Arah.Api/Contracts/Users/AddInterestRequest.csbackend/Arah.Api/Validators/AddInterestRequestValidator.csbackend/Arah.Tests/Api/GovernanceIntegrationTests.cs(cobre interesses)
Arquivos a Modificar:
backend/Arah.Api/Contracts/Users/UserProfileResponse.csbackend/Arah.Application/Services/UserProfileService.cs
Critérios de Sucesso:
- ✅ Endpoints funcionando
- ✅ Interesses aparecem no perfil
- ✅ Testes passando
Semana 16: Sistema de Votação
16.1 Modelo de Domínio - Votação
Estimativa: 12 horas (1.5 dias)
Status: ✅ Implementado
Tarefas:
- Criar enum
VotingType:-
ThemePrioritization(priorização de temas) -
ModerationRule(regra de moderação) -
TerritoryCharacterization(caracterização do território) -
FeatureFlag(feature flag territorial) -
CommunityPolicy(política comunitária)
-
- Criar enum
VotingStatus:-
Draft,Open,Closed,Approved,Rejected
-
- Criar enum
VotingVisibility:-
AllMembers,ResidentsOnly,CuratorsOnly
-
- Criar modelo
Voting:-
Id,TerritoryId,CreatedByUserId -
Type(VotingType) -
Title,Description -
Options(lista de opções de voto) -
Visibility(VotingVisibility) -
Status(VotingStatus) -
StartsAtUtc,EndsAtUtc -
CreatedAtUtc,UpdatedAtUtc
-
- Criar modelo
Vote:-
Id,VotingId,UserId -
SelectedOption(string) -
CreatedAtUtc
-
- Criar repositórios
- Criar migrations
Arquivos a Criar:
backend/Arah.Domain/Governance/Voting.csbackend/Arah.Domain/Governance/Vote.csbackend/Arah.Domain/Governance/VotingType.csbackend/Arah.Domain/Governance/VotingStatus.csbackend/Arah.Domain/Governance/VotingVisibility.csbackend/Arah.Application/Interfaces/IVotingRepository.csbackend/Arah.Application/Interfaces/IVoteRepository.csbackend/Arah.Infrastructure/Postgres/PostgresVotingRepository.csbackend/Arah.Infrastructure/Postgres/PostgresVoteRepository.csbackend/Arah.Infrastructure/Postgres/Migrations/YYYYMMDDHHMMSS_AddVotingSystem.cs
Critérios de Sucesso:
- ✅ Modelos criados
- ✅ Repositórios implementados
- ✅ Migrations aplicadas
16.2 Serviço de Votação
Estimativa: 20 horas (2.5 dias)
Status: ✅ Implementado
Tarefas:
- Criar
VotingService:-
CreateVotingAsync(...) -
ListVotingsAsync(...) -
GetVotingAsync(...) -
VoteAsync(...) -
CloseVotingAsync(...)(apenas criador ou curador) -
GetResultsAsync(...)(contagem de votos)
-
- Validações:
- Apenas residents/curadores podem criar votações (depende do tipo)
- Usuário só pode votar uma vez
- Votação deve estar aberta
- Usuário deve ter permissão (visibility)
- Opção selecionada deve existir
- Aplicação de resultados:
- Se
ThemePrioritization: atualizar ordem de temas no feed (opcional) - Se
ModerationRule: criar/atualizar regra de moderação - Se
TerritoryCharacterization: adicionar tags ao território - Se
FeatureFlag: habilitar/desabilitar feature flag - Se
CommunityPolicy: criar política comunitária
- Se
- Testes unitários
Arquivos a Criar:
backend/Arah.Application/Services/VotingService.csbackend/Arah.Tests/Application/VotingServiceTests.cs
Critérios de Sucesso:
- ✅ Serviço implementado
- ✅ Validações funcionando
- ✅ Aplicação de resultados funcionando
- ✅ Testes passando
16.3 Controller de Votação
Estimativa: 12 horas (1.5 dias)
Status: ✅ Implementado
Tarefas:
- Criar
VotingsController:-
POST /api/v1/territories/{territoryId}/votings(criar votação) -
GET /api/v1/territories/{territoryId}/votings(listar votações) -
GET /api/v1/territories/{territoryId}/votings/{id}(obter votação) -
POST /api/v1/territories/{territoryId}/votings/{id}/vote(votar) -
POST /api/v1/territories/{territoryId}/votings/{id}/close(fechar votação) -
GET /api/v1/territories/{territoryId}/votings/{id}/results(resultados)
-
- Criar requests/responses (Governance contracts)
- Validação (FluentValidation)
- Testes de integração (em
GovernanceIntegrationTests)
Arquivos a Criar:
backend/Arah.Api/Controllers/VotingsController.csbackend/Arah.Api/Contracts/Governance/CreateVotingRequest.csbackend/Arah.Api/Contracts/Governance/VotingResponse.csbackend/Arah.Api/Contracts/Governance/VoteRequest.csbackend/Arah.Api/Contracts/Governance/VotingResultsResponse.csbackend/Arah.Api/Validators/CreateVotingRequestValidator.csbackend/Arah.Tests/Api/GovernanceIntegrationTests.cs(cobre votação)
Critérios de Sucesso:
- ✅ Endpoints funcionando
- ✅ Validações funcionando
- ✅ Testes passando
Semana 17: Moderação Dinâmica e Feed Filtrado
17.1 Moderação Dinâmica Comunitária
Estimativa: 20 horas (2.5 dias)
Status: ✅ Implementado
Tarefas:
- Criar modelo
TerritoryModerationRule:-
Id,TerritoryId,CreatedByVotingId?(nullable, se criado por votação) -
RuleType(ContentType, ProhibitedWords, Behavior, MarketplacePolicy, EventPolicy) -
Rule(JSON com configuração da regra) -
IsActive(bool) -
CreatedAtUtc,UpdatedAtUtc
-
- Criar
ITerritoryModerationRuleRepository - Implementar repositórios
- Criar
TerritoryModerationService:-
CreateRuleAsync(...) -
ListRulesAsync(...) -
ApplyRulesAsync(Post post)(verificar se post viola regras) -
ApplyRulesAsync(StoreItem item)(verificar se item viola regras)
-
- Integração com
PostCreationService:- Verificar regras antes de criar post
- Retornar erro se violar regra
- Integração com
StoreItemService:- Verificar regras antes de criar item
- Criar migration
- Testes unitários
Arquivos a Criar:
backend/Arah.Domain/Governance/TerritoryModerationRule.csbackend/Arah.Domain/Governance/RuleType.csbackend/Arah.Application/Interfaces/ITerritoryModerationRuleRepository.csbackend/Arah.Infrastructure/Postgres/PostgresTerritoryModerationRuleRepository.csbackend/Arah.Application/Services/TerritoryModerationService.csbackend/Arah.Infrastructure/Postgres/Migrations/YYYYMMDDHHMMSS_AddModerationRules.cs
Arquivos a Modificar:
backend/Arah.Application/Services/PostCreationService.csbackend/Arah.Application/Services/StoreItemService.cs
Critérios de Sucesso:
- ✅ Regras de moderação funcionando
- ✅ Aplicação de regras funcionando
- ✅ Integração com criação de conteúdo funcionando
- ✅ Testes passando
17.2 Feed Filtrado por Interesses
Estimativa: 16 horas (2 dias)
Status: ✅ Implementado
Tarefas:
- Criar
InterestFilterService:-
FilterFeedByInterestsAsync(posts, userId, territoryId)— filtra por correspondência título/conteúdo com interesses (tags explícitas em posts: ver Fase 14.5) - Opcional: manter feed completo disponível
-
- Atualizar
FeedController:- Adicionar query parameter
filterByInterests(bool, default: false) - Se
true: aplicar filtro de interesses - Se
false: retornar feed completo (cronológico)
- Adicionar query parameter
- Atualizar
FeedService:- Aceitar parâmetro
filterByInterests - Chamar
InterestFilterServicese necessário
- Aceitar parâmetro
- Importante: Feed cronológico permanece como padrão, filtro é opcional
- Teste de integração dedicado para
filterByInterests=true→ Fase 14.5
Arquivos a Criar:
backend/Arah.Application/Services/InterestFilterService.csbackend/Arah.Tests/Application/InterestFilterServiceTests.cs
Arquivos a Modificar:
backend/Arah.Api/Controllers/FeedController.csbackend/Arah.Application/Services/FeedService.csbackend/Arah.Tests/Api/— teste dedicado em Fase 14.5
Critérios de Sucesso:
- ✅ Filtro de interesses funcionando
- ✅ Feed completo continua disponível
- ✅ Feed cronológico mantido como padrão
- ✅ Testes passando
17.3 Caracterização do Território
Estimativa: 12 horas (1.5 dias)
Status: ✅ Implementado
Tarefas:
- Criar modelo
TerritoryCharacterization:-
TerritoryId,Tags(IReadOnlyList) -
UpdatedAtUtc - Tags podem ser definidas por votações
-
- Criar
ITerritoryCharacterizationRepository - Implementar repositórios
- Criar
TerritoryCharacterizationService:-
UpdateCharacterizationAsync(...) -
GetCharacterizationAsync(...)
-
- Integração com
VotingService:- Se votação
TerritoryCharacterizationaprovada: atualizar caracterização
- Se votação
- Atualizar
TerritoryResponse:- Adicionar campo
Tags(caracterização)
- Adicionar campo
- Criar migration
- Testes
Arquivos a Criar:
backend/Arah.Domain/Territories/TerritoryCharacterization.csbackend/Arah.Application/Interfaces/ITerritoryCharacterizationRepository.csbackend/Arah.Infrastructure/Postgres/PostgresTerritoryCharacterizationRepository.csbackend/Arah.Application/Services/TerritoryCharacterizationService.csbackend/Arah.Infrastructure/Postgres/Migrations/YYYYMMDDHHMMSS_AddTerritoryCharacterization.cs
Arquivos a Modificar:
backend/Arah.Api/Contracts/Territories/TerritoryResponse.csbackend/Arah.Application/Services/VotingService.cs
Critérios de Sucesso:
- ✅ Caracterização funcionando
- ✅ Integração com votações funcionando
- ✅ Tags aparecem no território
- ✅ Testes passando
17.4 Histórico de Participação no Perfil
Estimativa: 8 horas (1 dia)
Status: ✅ Implementado
Tarefas:
-
UserProfileGovernanceResponse(separado):VotingHistory,ModerationContributions - Endpoint
GET /api/v1/users/me/profile/governance(histórico completo) - Buscar histórico de votações e contribuições para moderação
- Testes
Arquivos a Modificar:
backend/Arah.Api/Contracts/Users/UserProfileResponse.csbackend/Arah.Application/Services/UserProfileService.csbackend/Arah.Api/Controllers/UserProfileController.cs
Critérios de Sucesso:
- ✅ Histórico aparecendo no perfil
- ✅ Contribuições aparecendo no perfil
- ✅ Testes passando
17.5 Testes e Documentação
Estimativa: 12 horas (1.5 dias)
Status: ✅ Implementado (itens pendentes → Fase 14.5)
Tarefas:
- Testes de integração:
GovernanceIntegrationTests(interesses, votação) - Testes de integração dedicados: feed filtrado, moderação, caracterização → Fase 14.5
- Testes de performance (votações com muitos votos) → Fase 14.5
- Testes de segurança (permissões) reforçados → Fase 14.5
- Documentação técnica:
-
docs/GOVERNANCE_SYSTEM.md -
docs/VOTING_SYSTEM.md -
docs/COMMUNITY_MODERATION.md
-
- Atualizar
docs/CHANGELOG.md - Verificar/atualizar Swagger → Fase 14.5
Arquivos:
-
backend/Arah.Tests/Api/GovernanceIntegrationTests.cs -
docs/GOVERNANCE_SYSTEM.md,VOTING_SYSTEM.md,COMMUNITY_MODERATION.md
Critérios de Sucesso:
- ✅ Testes passando
- ✅ Cobertura >85% (validar)
- ✅ Documentação completa
📊 Resumo da Fase 14
| Tarefa | Estimativa | Status | Prioridade |
|---|---|---|---|
| Modelo de Domínio - Interesses | 8h | ✅ Implementado | 🔴 Crítica |
| Serviço de Interesses | 12h | ✅ Implementado | 🔴 Crítica |
| Controller e Integração com Perfil | 12h | ✅ Implementado | 🔴 Crítica |
| Modelo de Domínio - Votação | 12h | ✅ Implementado | 🔴 Crítica |
| Serviço de Votação | 20h | ✅ Implementado | 🔴 Crítica |
| Controller de Votação | 12h | ✅ Implementado | 🔴 Crítica |
| Moderação Dinâmica Comunitária | 20h | ✅ Implementado | 🔴 Crítica |
| Feed Filtrado por Interesses | 16h | ✅ Implementado | 🔴 Crítica |
| Caracterização do Território | 12h | ✅ Implementado | 🟡 Importante |
| Histórico de Participação no Perfil | 8h | ✅ Implementado | 🟡 Importante |
| Testes e Documentação | 12h | ✅ Implementado | 🟡 Importante |
| Total | 120h (21 dias) |
Itens pendentes (testes dedicados, performance, segurança, Swagger) → ver Fase 14.5.
14.X Configuração Avançada de Notificações
Estimativa: 24 horas (3 dias)
Status: ⏳ Pendente
Prioridade: 🟡 Média
Contexto: UserPreferences já permite configuração de notificações por usuário, mas tipos de notificações e canais disponíveis são fixos no código. Esta tarefa permite configuração de tipos, canais e templates por território ou globalmente.
Tarefas:
- Criar modelo de domínio
NotificationConfig:-
Id,TerritoryId(nullable para config global) -
NotificationTypes(JSON, array de tipos disponíveis) -
Channels(JSON, array de canais: Email, Push, InApp, SMS) -
Templates(JSON, dicionário de templates por tipo) -
DefaultChannels(JSON, canais padrão por tipo) -
Enabled(bool) -
CreatedAtUtc,UpdatedAtUtc
-
- Criar
INotificationConfigRepositorye implementações (Postgres, InMemory) - Criar
NotificationConfigService:-
GetConfigAsync(Guid? territoryId, CancellationToken)→ busca config territorial ou global -
CreateOrUpdateConfigAsync(NotificationConfig, CancellationToken) -
GetAvailableTypesAsync(Guid? territoryId, CancellationToken) -
GetTemplatesAsync(Guid? territoryId, string notificationType, CancellationToken)
-
- Estender
NotificationService:- Usar
NotificationConfigao enviar notificações - Aplicar templates configurados
- Respeitar canais disponíveis
- Usar
- Criar
NotificationConfigController:-
GET /api/v1/territories/{territoryId}/notification-config(Curator) -
PUT /api/v1/territories/{territoryId}/notification-config(Curator) -
GET /api/v1/admin/notification-config(global, SystemAdmin) -
PUT /api/v1/admin/notification-config(global, SystemAdmin)
-
- Interface administrativa (DevPortal):
- Seção para configuração de notificações
- Editor de templates (opcional)
- Visualização de canais disponíveis
- Testes de integração
- Documentação
Arquivos a Criar:
backend/Arah.Domain/Notifications/NotificationConfig.csbackend/Arah.Application/Interfaces/Notifications/INotificationConfigRepository.csbackend/Arah.Application/Services/Notifications/NotificationConfigService.csbackend/Arah.Api/Controllers/NotificationConfigController.csbackend/Arah.Infrastructure/Postgres/PostgresNotificationConfigRepository.csbackend/Arah.Infrastructure/InMemory/InMemoryNotificationConfigRepository.csbackend/Arah.Tests/Api/NotificationConfigIntegrationTests.cs
Arquivos a Modificar:
backend/Arah.Application/Services/NotificationService.cs(ou equivalente)backend/Arah.Infrastructure/InMemory/InMemoryDataStore.csbackend/Arah.Api/Extensions/ServiceCollectionExtensions.csbackend/Arah.Api/wwwroot/devportal/index.html
Critérios de Sucesso:
- ✅ Tipos de notificação configuráveis
- ✅ Canais configuráveis por tipo
- ✅ Templates configuráveis
- ✅ Interface administrativa disponível
- ✅ Testes passando
- ✅ Documentação atualizada
Referência: Consulte FASE10_CONFIG_FLEXIBILIZACAO_AVALIACAO.md para contexto completo.
✅ Critérios de Sucesso da Fase 14
Funcionalidades
- ✅ Sistema de interesses funcionando
- ✅ Sistema de votação funcionando
- ✅ Moderação dinâmica funcionando
- ✅ Feed filtrado por interesses funcionando (opcional)
- ✅ Caracterização do território funcionando
- ✅ Histórico de participação no perfil funcionando
Qualidade
- ✅ Cobertura de testes >85%
- ✅ Testes de integração passando
- ✅ Performance adequada (votações com muitos votos)
- ✅ Segurança validada (permissões)
- Considerar Testcontainers + PostgreSQL para testes de integração (votações, interesses) com banco real (estratégia na Fase 19; TESTCONTAINERS_POSTGRES_IMPACTO).
Documentação
- ✅ Documentação técnica completa
- ✅ Changelog atualizado
- ✅ Swagger atualizado
🔗 Dependências
- Nenhuma: Pode ser feito em paralelo com outras fases
📝 Notas de Implementação
Princípios de Governança
Feed Cronológico Preservado:
- ✅ Feed completo (cronológico) é o padrão
- ✅ Filtro por interesses é opcional (usuário escolhe)
- ✅ Não manipula ordem, apenas filtra conteúdo
- ✅ Respeita cronologia territorial
Votações Comunitárias:
- ✅ Transparência total (todos veem resultados)
- ✅ Decisões coletivas (não apenas moderadores)
- ✅ Resultados aplicados automaticamente (se aprovados)
- ✅ Histórico de votações preservado
Moderação Dinâmica:
- ✅ Regras definidas pela comunidade
- ✅ Moderadores têm acesso privilegiado, mas comunidade participa
- ✅ Regras aplicadas automaticamente
- ✅ Transparência nas regras
Exemplos de Votações
Priorização de Temas:
- Opções: "Meio Ambiente", "Eventos", "Marketplace", "Saúde"
- Resultado: Ordem de prioridade (não altera feed cronológico, apenas destaca)
Regra de Moderação:
- Proposta: "Proibir posts sobre política partidária"
- Opções: "Aprovar", "Rejeitar"
- Resultado: Se aprovado, regra é criada e aplicada
Caracterização do Território:
- Opções: "Rural", "Urbano", "Praia", "Montanha", "Floresta"
- Resultado: Tags adicionadas ao território
Status: ✅ FASE 14 IMPLEMENTADA
Depende de: Nenhuma
Crítico para: Soberania Territorial e Governança Comunitária
Itens faltantes: Ver Fase 14.5