Pular para o conteúdo principal
Versão: 10.4.1

Changelog

All notable changes to this template are documented in this file.

The format is based on Keep a Changelog, and this template adheres to Semantic Versioning.

[Unreleased]​

Added​

  • Template package (templatepack/). ITLab.Template.Next.Templates nupkg (PackageType=Template) so consumers install from the ITLab.Template feed (dotnet new install ITLab.Template.Next.Templates) instead of cloning. Packs .template.config + src/tests/infra/.github + root files, shipping dotfiles and excluding bin/obj/node_modules/dist and repo-only docs/examples. Validated end-to-end: install from the nupkg → scaffold → 38 backend tests + SPA 8 tests + build green. Publishing pipeline at .azure/template-publish.yml (tag release/template/vX.Y.Z): build + solution tests → pack → scaffold smoke from the packed nupkg (dotnet new install, build, backend + SPA tests) → push to the ITLab.Template feed.

  • Frontend SPA (ADR-007). src/ITLab.Template.Next.Spa: React + Vite + TypeScript + Tailwind v4 + shadcn/ui, served same-origin by the API so the ADR-006 BFF cookie works without CORS — UseStaticFiles + SPA fallback (reserved prefixes /v1, /health, /.well-known, /openapi, /scalar return 404, never HTML). Publish-time integration: the Api csproj builds the SPA (pnpm, override seams for CI) and bundles dist into wwwroot; dev uses the Vite proxy. Typed API client via committed OpenAPI spec + openapi-typescript/openapi-fetch (hermetic codegen); session bootstrap from GET /v1/auth/me with CSRF middleware (X-XSRF-TOKEN) and global 401 handling — no token ever touches JavaScript. UI canon: login (react-hook-form + zod), protected shell with route guard, and Orders as living reference (paginated table, create dialog, approve — role-gated while the API stays the enforcement). Tests: Vitest + Testing Library + MSW (8). dotnet new scaffolds the SPA renamed end-to-end (folder, csproj SpaRoot, brand, titles), excluding node_modules/dist.

  • GET /v1/auth/me — current authenticated user (id, name, roles) projected from ICurrentUser, for SPA session hydration and UI gating; works for both cookie and Bearer schemes.

  • OpenAPI response schemas. Endpoints now declare .Produces<T>(...) (the doc previously had no response schemas — IResult is opaque); /v1/auth/csrf returns a typed CsrfTokenResponse; Asp.Versioning ApiExplorer substitutes the version in paths (/v1/orders, not /v{version}/orders). Benefits Scalar UI and the SPA codegen alike.

  • Phase 3 packaging — dotnet new itlab-fullstack. .template.config/template.json declares the template with sourceName: ITLab.Template.Next, classifications Web/WebAPI/Worker/DDD/CQRS, and sources.modifiers.exclude that keeps examples/, docs/, **/bin/, **/obj/, IDE state and per-dev appsettings.Development.json out of generated projects. Smoke-tested end-to-end (dotnet new itlab-fullstack -n Probe builds Debug + Release clean and passes 20/20 tests against renamed namespaces).

  • Local authentication, dual-scheme (ADR-006, supersedes ADR-003; DevPack bumped to 10.4.0). The template ships with working auth — local ASP.NET Core Identity (AppUser/AppRole over BaseIdentityDbContext, tables in the identity schema without the AspNet prefix) issuing its own asymmetric (RSA) JWTs. Two schemes coexist via a forwarding selector: a BFF HttpOnly session cookie for browsers (/v1/auth/session*, CSRF-protected via BffAntiforgeryMiddleware + /v1/auth/csrf) and Bearer JWT validated through a published JWKS (/.well-known/jwks.json) for mobile (/v1/auth/token*, rotating refresh tokens) and service-to-service (/v1/auth/clients/token, client-credentials). Signing key is ephemeral in Development and a required PEM in production (fail-early). IdentitySeeder seeds canonical roles + an optional admin from Identity:Admin:*. Authorization (RolePermissions + RoleBasedPermissionEvaluator) is unchanged across schemes. External-JWT resource-server (ADR-003) remains as a documented opt-in swap.

  • DB-backed permission resolver. RolePermission entity + DbRolePermissionResolver with IMemoryCache (5 min TTL per role). Seed via RolePermissionConfiguration.HasData (Admin/Operator/Viewer × Orders.*) honored by both relational migrations and EF Core InMemory. Documented in ADR-004.

  • Order concurrency token. byte[] RowVersion mapped via IsRowVersion() in the entity config plus a dedicated migration AddOrderConcurrencyToken. Concurrent updates raise DbUpdateConcurrencyException instead of silently overwriting; integration tests via EF InMemory cannot exercise the race (documented caveat) — cover with Testcontainers.MsSql when it matters.

  • OpenTelemetry observability. AddTemplateObservability helper in Infrastructure ships baseline (resource, HttpClient, Runtime, EF Core ActivitySource, OTLP exporter); Api adds AddAspNetCoreInstrumentation() in its own composition root. Endpoint follows OTel env-var standard (OTEL_EXPORTER_OTLP_ENDPOINT, default http://localhost:4317).

  • Bearer security scheme in OpenAPI. BearerSecuritySchemeTransformer declares the scheme + document-wide requirement so Scalar UI auto-renders the Authorize button.

  • Split health probes. /health/live (no checks — process is alive) and /health/ready (filters checks tagged ready, includes AddDbContextCheck<AppDbContext>). Both anonymous and opted out of rate limiting.

  • Rate limiting. Built-in fixed-window per-IP partition with 1000 req/min default, configurable via RateLimiting:PermitLimit/WindowSeconds. /health/* opts out via .DisableRateLimiting().

  • CORS (opt-in). Registered only when Cors:AllowedOrigins contains at least one entry; defaults allow any method/header + credentials + 10 min preflight cache.

  • API versioning. Asp.Versioning.Http 10.0.0 with URL-segment primary reader (/v{version:apiVersion}/orders) and X-Api-Version header fallback. Default version 1.0, ReportApiVersions enabled. Health probes stay unversioned.

  • Docker + docker-compose. Multi-stage Dockerfile per project (Api/Worker), .dockerignore, docker-compose.yml orchestrating sql, api, worker and otel-collector. BuildKit secret mounts ~/.nuget/NuGet/NuGet.Config so dotnet restore can hit the private feed inside the build.

  • GitHub Actions CI workflow (.github/workflows/ci.yml). Restore (using AZURE_DEVOPS_PAT secret) + build Debug + build Release + tests with TRX logger + XPlat Code Coverage.

  • examples/Customers/ opt-in reference (ADR-005). Domain with Email/Cpf value objects (Cpf delegates to DevPack Guard.Against.InvalidCpf), uniqueness pre-check + unique index, deactivation as state transition. 8-step copy recipe in the per-example README. Not shipped via dotnet new.

  • Architecture Decision Records under docs/adrs/ (5 ADRs covering vertical slices, English-only source, JWT Bearer, DB-backed roles, examples opt-in).

  • appsettings.Development.json.sample as the copy-from reference (.env.sample pattern). Local appsettings.Development.json stays gitignored; the sample carries plausible Authority/Audience values for IdP-less local runs.

  • Setup section in README with prerequisites, primeiro-run sequence, NuGet feed credential setup and Docker/docker-compose recipes.

  • CLAUDE.md as the live contract for AI agents — vertical slices, returns/validation, domain events policy, permissions convention, authentication, observability, rate limiting, CORS, API versioning, EF, tests.

  • LICENSE (ITLab proprietary internal).

Changed​

  • Canon Pedidos → Orders (English-only). All identifiers, methods, events, DTOs, EF table names, migration names, endpoint paths and test class/method names refactored to English. Markdown docs (CLAUDE.md, README, docs/) intentionally remain in Portuguese. Documented in ADR-002.
  • ITLabTemplateNextPermissions → Permissions. Short class identifier so sourceName: ITLab.Template.Next substitution does not need custom symbols at dotnet new time.
  • DevPack 10.2.3 → 10.3.0. Migrate Result/Error to ITLab.Template.DevPack.Core namespace per the 10.3 BREAKING change. Drop four local shims now shipped by the package: ResultHttpExtensions, IdentityContextMiddleware, ScopedDispatchDomainEventsInterceptor and the TestAuthenticationHandler (latter moves to the new ITLab.Template.DevPack.Testing nupkg).
  • Order constructor chains : base(id) (DevPack 10.3 AuditedSoftDeletableEntity<TKey> ctor).
  • OrdersEndpoints uses MapPaginatedGet<TQuery, TDto> for the paginated GET (replaces ~26 LOC of manual query-string binding).
  • Program.cs uses app.UseDevPackIdentityContext() instead of a local middleware to bridge HttpContext.User into AsyncLocalCurrentUserAccessor.
  • IntegrationTestFactory inherits WebApplicationFactoryBase<Program, AppDbContext> from ITLab.Template.DevPack.Testing — body collapses to a single class declaration. Overrides ConfigureAdditionalServices to inject JwtOptions and call EnsureCreated so the HasData seed populates the in-memory database.

Removed​

  • PlaceholderAuthenticationHandler and the #if !DEBUG / #error gate — superseded by JWT Bearer (ADR-003).
  • InMemoryRolePermissionResolver — superseded by DbRolePermissionResolver (ADR-004).
  • Api/Extensions/ResultHttpExtensions.cs, Api/Middleware/IdentityContextMiddleware.cs, Infrastructure/Persistence/Interceptors/ScopedDispatchDomainEventsInterceptor.cs, tests/.../Setup/TestAuthenticationHandler.cs — all canonical in DevPack 10.3.0 now.
  • "Known doc-vs-binary mismatches in DevPack 10.2.3" section from CLAUDE.md — fixed in 10.3.

Phases overview (historical)​

This template went through three phases before its first release:

  • Phase 1 — initial skeleton. Project structure, base configuration, NuGet packages. Pre-this-changelog.
  • Phase 2 — canon Orders + DevPack 10.3 absorption. Vertical-slice canon shipped, English-only refactor applied, JWT Bearer + DB-backed roles + observability + concurrency + Docker + CI all landed under the Unreleased bucket above.
  • Phase 3 — dotnet new packaging. .template.config/template.json shipped, smoke test verified end-to-end. Ready for first tagged release.