# ITLab.Template.DevPack

> Pacote NuGet opinionado de infraestrutura para projetos .NET 10 da ITLab. Provê
> primitivos de DDD/CQRS, behaviors de pipeline `Mediator` (martinothamar),
> interceptors EF Core, sistema de autorização policy-based, contratos de identity
> e utilitários transversais — sem wrappers sobre frameworks (ver ADR-001).

Esta pasta (`devpack-docs/`) é shipada **dentro do nupkg** e é a fonte autoritativa de
documentação para a versão exata do DevPack que o projeto consome. Resolve via:

```
{NuGetPackageRoot}/itlab.template.devpack/{version}/devpack-docs/
```

Onde `{version}` é o valor de `<PackageVersion Include="ITLab.Template.DevPack">` em
`Directory.Packages.props` do projeto consumidor, e `{NuGetPackageRoot}` é
tipicamente `~/.nuget/packages` no Linux/macOS ou `%USERPROFILE%\.nuget\packages` no
Windows. Edições locais nesse path são descartadas em qualquer `dotnet restore`.

## Comece aqui

- [CLAUDE.md](CLAUDE.md): convenções operacionais para agentes de IA — namespace map,
  retorno de handlers (`ValueTask<TResponse>`), filosofia "no framework wrappers",
  manutenção obrigatória de README + CHANGELOG ao mexer em `src/`. Leia primeiro.
- [DEVPACK.md](DEVPACK.md): visão de arquitetura, decisões de design por release,
  pontos de extensão por área, convenções globais (XML doc em inglês, permissões
  hierárquicas com pontos, etc.).
- [CHANGELOG.md](CHANGELOG.md): histórico de versões com guias de migração entre
  releases — fonte de verdade para "como API X mudou da versão Y para Z?".

## Decisões arquiteturais (ADRs)

ADRs são snapshots imutáveis. Cada um descreve **um** trade-off em ponto-no-tempo.

- [ADR-001 — No framework wrappers](adrs/001-no-framework-wrappers.md): princípio
  raiz; o DevPack expõe contratos pequenos e composição via DI, não invólucros
  sobre Mediator/EF Core/Serilog/ASP.NET.
- [ADR-002 — Mediator → Cqrs namespace rename](adrs/002-rename-mediator-to-cqrs.md):
  por que `using ITLab.Template.DevPack.Cqrs;` (não `.Mediator;`) é o caminho
  correto para handlers/records; e por que `using Mediator;` é o caminho para o
  `IMediator` injetado.
- [ADR-003 — AuditTimestamp value object](adrs/003-audit-timestamp-value-object.md):
  `(DateTime UtcDateTime, string? LocalTimeZone)` per-evento, anotado `[Owned]`
  para EF auto-mapear; preserva atribuição de usuário (`CreatedBy`/`ModifiedBy`/
  `DeletedBy`); cobre cenário de criação/update/delete em fusos diferentes.
- [ADR-004 — Role-based permission resolution](adrs/004-role-based-permission-resolution.md):
  `IRolePermissionResolver` + `RoleBasedPermissionEvaluator` como caminho default
  para "permissões derivadas de roles"; `ICurrentUser` deliberadamente sem campo
  `Permissions`; `IPermissionEvaluator` como contrato agnóstico.
- [ADR-005 — Identity store & self-issued tokens](adrs/005-identity-store-and-self-issued-tokens.md):
  Identity local + emissão de JWT assimétrico (RSA), JWKS, dual scheme (cookie BFF + Bearer).
- [ADR-006 — Tenant query filter + stamping](adrs/006-multi-tenant-query-filter-and-stamping.md):
  applicator de global query filter + `MultiTenantEntityInterceptor` + `IMultiTenantDbContext`;
  persistência claim-based.
- [ADR-007 — Domain tenant resolution + glue middleware](adrs/007-domain-tenant-resolution.md):
  contributors concretos por host (`DomainTenantResolveContributor`) + `TenantResolutionMiddleware`
  (`UseDevPackTenantResolution`) com cross-check host-vs-token; opt-in via `MultiTenancyOptions`.
- [ADR-008 — Per-tenant settings store + secret protection](adrs/008-per-tenant-settings-store-and-secret-protection.md):
  `ISecretProtector` (Data Protection) + `IPerTenantSettingsStore`; cifragem no store (não interceptor);
  schemes estáticos + validação por-tenant nos eventos como recipe (substrato da auth por-tenant).
- [ADR-009 — Email abstractions in the DevPack](adrs/009-email-abstractions.md):
  contratos universais de email (`IEmailService`, renderer/repositório de template) + options no DevPack;
  concretos (SMTP/SendGrid, renderer HTML, layouts) no consumidor.
- [ADR-010 — Microsoft Entra ID multi-scheme per-tenant](adrs/010-entra-id-multi-scheme-per-tenant.md):
  Entra como terceiro scheme opt-in por tenant (`AddDevPackEntraId`); validação per-tenant via
  `IEntraTenantValidator` + `IPerTenantSettingsStore`; `IEntraGraphClientFactory` interface-only.

## Áreas (uma página por namespace)

Cada README de área documenta os tipos públicos, padrões de uso, anti-padrões e
pontos de extensão. Mesmo conteúdo navegável no source tree do repositório do
DevPack — versão local aqui é o snapshot da release publicada.

### Foundation

- [Abstractions](areas/Abstractions/README.md): contratos centrais
  (`IDateTimeProvider`, `ICacheService`, `IAppOptions`, `IServiceProviderAccessor`,
  `ISecretProtector` + `DataProtectionSecretProtector` / `AddDevPackSecretProtector`)
  + implementações default `UtcDateTimeProvider` (Singleton) e
  `LocalDateTimeProvider` (Scoped, IANA fallback UTC).
- [Domain](areas/Domain/README.md): `Entity`, `AuditedEntity`, `AuditedSoftDeletableEntity`,
  `AuditTimestamp`, `DomainEvent`, `ValueObject`, `SmartEnum<,>`, `EnumDomainTable<>`.
- [Results](areas/Results/README.md): `Result`, `Result<T>`, `Error`, `ErrorType`,
  `ValidationError` — railway-oriented programming.
- [Cqrs](areas/Cqrs/README.md): `ICommand`, `ICommand<T>`, `IQuery<T>`,
  `ICommandHandler<,>`, `IQueryHandler<,>`, `INotificationEvent`. **Use estes
  imports**, não os do namespace `Mediator` raiz, para handlers/records.

### Pipeline & Authorization

- [Behaviors](areas/Behaviors/README.md): `RequestLoggingPipelineBehavior`,
  `ValidationPipelineBehavior`, `AddDevPackBehaviors()`. Pipeline:
  Logging → Validation. (NormalizeDateTimeOffsetBehavior removido em 10.2.0.)
- [Authorization](areas/Authorization/README.md): `IPermissionEvaluator`,
  `IRolePermissionResolver`, `RoleBasedPermissionEvaluator`,
  `[RequiresPermission]`, `AuthorizationBehavior`, `PermissionAuthorizationPolicyProvider`,
  `AddDevPackAuthorization()`, `AddDevPackRoleBasedPermissionEvaluator<T>()`.
  Convenção dual: `RequireAuthorization("X")` no endpoint **+**
  `[RequiresPermission("X")]` no Command/Query quando há regra contextual.

### Identity

- [Identity](areas/Identity/README.md): `ICurrentUser`, `CurrentUser`,
  `AsyncLocalCurrentUserAccessor`, `UserInfo`, `BaseIdentityUser`, `BaseIdentityRole`,
  `EIdentityProvider`, `IdentitySchemas`.
- [Identity/AuthSettings](areas/Identity/AuthSettings/README.md): DTOs de
  configuração de auth por tenant — Microsoft Entra ID (WebApi/SPA/Agent), LDAP,
  default provider.
- [Identity/Settings](areas/Identity/Settings/README.md): `IPerTenantSettingsStore`
  (get/set por-tenant, secrets cifrados via `ISecretProtector`) + recipe de schemes
  estáticos com validação por-tenant nos eventos (substrato da auth por-tenant, 10.7.1).
- [Identity/MultiTenancy](areas/Identity/MultiTenancy/README.md): pipeline
  `ITenantResolver` + `ITenantResolveContributor` (header, claim, route, ...) +
  `ITenantAccessValidator`; resolução por domínio (`DomainTenantResolveContributor`,
  `AddDomainTenantResolver`) + glue `TenantResolutionMiddleware` (opt-in, 10.6.0).

### Infrastructure (EF Core)

- [Infrastructure](areas/Infrastructure/README.md): apontador para sub-namespaces.
- [Infrastructure/EfCore](areas/Infrastructure/EfCore/README.md):
  `DevPackEfCoreInterceptorBuilder`, `AddDevPackEfCoreInterceptors()` — fluent
  builder para registrar interceptors (DevPack + customizados).
- [Infrastructure/EfCore/Interceptors](areas/Infrastructure/EfCore/Interceptors/README.md):
  `AuditableEntityInterceptor` (popula `CreatedAt`/`UpdatedAt` via
  `IServiceProvider` + `CreateScope()`), `SoftDeleteInterceptor`,
  `DispatchDomainEventsInterceptor` (publica via `Mediator.IPublisher`).

### Data

- [Data](areas/Data/README.md): `PaginatedList<T>`, `GroupableList<T>`,
  `Group<T>`, `OneOf<,>`, `QueryFilter` (DSL OData-like), `IRepository<T>` (opt-in,
  use `IAppDbContext` direto por padrão), `IUnitOfWork`, `EOrderDirection`,
  `PaginatedQueryBase<TDto>`.

### Cross-cutting

- [Helpers](areas/Helpers/README.md): `EntityHelper`, `EnumHelper`, `HashHelper`,
  `ObjectHelper`, `PermissionsGenerator` (gera JSON/TS para frontend a partir de
  classe estática hierárquica de permissões), `ReflectionHelper`, `TypeHelper`.
- [Extensions](areas/Extensions/README.md): 22 classes estáticas de extensions
  (`DateTimeOffsetExtensions`, `StringCaseExtensions`, `ResultExtensions`,
  `HttpContextExtensions`, `EnumerableExtensions`, etc.).
- [Guards](areas/Guards/README.md): `Guard.Against.NotEqual(...)`,
  `Guard.Against.MustBeQuarterHourRounded(...)`, `Guard.Against.NotFirstDayOfMonth(...)` — extensions
  Ardalis customizadas. Use `using ITLab.Template.DevPack.Guards;`.
- [Attributes](areas/Attributes/README.md): `AdditionalAttribute`,
  `DisableIdGenerationAttribute`, `ErrorCatalogAttribute`, `NotifyAttribute`.
  (`NormalizeDateTimeOffsetAttribute` removido em 10.2.0.)
- [SensitiveData](areas/SensitiveData/README.md): `[SensitiveData(requiredPermission: ...)]`
  + `SensitiveDataLoggingJsonConverter` para mascaramento condicional de PII em logs.
- [Middleware](areas/Middleware/README.md): `CultureMiddleware`, `NotFoundMiddleware`,
  `UnauthenticatedFallbackMiddleware`.
- [Actions](areas/Actions/README.md): `DisposeAction`, `DisposeAction<T>` — wrapper
  `IDisposable` para cleanup determinístico via delegate.

### Configuration & DTOs

- [AppSettings](areas/AppSettings/README.md): 10 options classes strongly typed
  (`ApplicationOptions`, `JwtOptions`, `LdapOptions`, `MicrosoftEntraIdOptions`,
  `CacheOptions`, `LoggerOptions`, `ScheduledJobsOptions`, `ServiceBusOptions`,
  `SignalROptions`, `ConnectionStrings`).
- [Dtos](areas/Dtos/README.md): `BaseKeyValueDto`, `OptionDto<T>`, `NameValue`,
  `EmailAttachment`, `NotificationRecipientDto`, `ScheduledJobConfiguration`,
  `StorageConfiguration`, `CachedKey`.
- [Enums](areas/Enums/README.md): enums compartilhados — `EAuthenticationType`,
  `ENotificationType`, `EOrderStatus`, `ESenderTool`, `EStorageProvider`, etc.
- [CoreConsts](areas/CoreConsts/README.md): constantes globais — regex, SQL collation,
  MIME types, claim names, header `SensitiveData.RevealHeader`.

### Serialization & Notifications

- [JsonConverters](areas/JsonConverters/README.md): `IgnoreOffsetJsonConverter`,
  `OneOfJsonConverter`, `RoundedDoubleJsonConverter`.
- [Formatters](areas/Formatters/README.md): `FormattedStringValueExtracter` —
  tokenização de templates com extração de valores via `{token}`.
- [Messaging](areas/Messaging/README.md): `EMessageDisposition`,
  `MessageHandlingResult`, `MessagingErrors` — settlement de message broker
  (Service Bus, etc.); sem cliente embutido.
- [Notifications](areas/Notifications/README.md): apontador para sub-namespaces.
- [Notifications/MicrosoftTeams](areas/Notifications/MicrosoftTeams/README.md):
  `AdaptiveCard`, `MicrosoftTeamsMessage`.
- [Notifications/Slack](areas/Notifications/Slack/README.md): `SlackMessage`.

### Misc

- [Exceptions](areas/Exceptions/README.md): `GuardClauseException`.
- [Structs](areas/Structs/README.md): `RoundedDouble`.

## Como agentes devem usar

1. **Antes de criar nova abstração:** consulte a área correspondente nesta lista.
   Probabilidade alta de que o DevPack já tem (`AuditedEntity`, `Result<T>`,
   `IPermissionEvaluator`, etc.).
2. **Antes de adicionar nova dependência NuGet:** consulte [DEVPACK.md](DEVPACK.md)
   seção "Dependências" — pode já estar disponível transitivamente.
3. **Ao migrar de versão:** o [CHANGELOG.md](CHANGELOG.md) é a fonte canônica de
   guias de migração. Não inferir mudanças por diff.
4. **Ao gerar handler/record:** use `using ITLab.Template.DevPack.Cqrs;` para
   contratos (`ICommand`, `IQuery`, `ICommandHandler`); use `using Mediator;`
   apenas para o `IMediator` injetado em endpoints. Ver ADR-002.
5. **Ao trabalhar com auditoria:** entidades estendem `AuditedEntity<TKey>`; campos
   são `CreatedAt`/`UpdatedAt` (`AuditTimestamp` value object), não `DateTimeOffset`.
   Ver ADR-003.