docs(domain,data): XML docs completas com CS1591 como erro + gate de cobertura no CI

- Domain: 18 tipos/membros documentados em português; Data: docs
  erradas corrigidas (IEntity truncada, cref enganoso)
- CS1591 reativado como erro nos dois pacotes-núcleo (teste negativo
  validado)
- dotnet.yml: gate de cobertura ratchet em 45% (atual 47,4%) sobre os
  assemblies Codout.*
- ROADMAP: status final das fases

https://claude.ai/code/session_01BnjVoHxcLymD2Mp9RcdG3u

Author: claude

.github/workflows/dotnet.yml

@@ -29,6 +29,26 @@ jobs:
       run: dotnet build --no-restore
     - name: Test
       run: dotnet test --no-build --verbosity normal --collect:"XPlat Code Coverage" --results-directory ./coverage
+    - name: Coverage gate
+      # Ratchet: começa em 45% (cobertura atual ~47%) e deve SUBIR conforme a
+      # suíte crescer — nunca baixar. Falha o CI se a cobertura de linhas dos
+      # assemblies Codout.* cair abaixo do piso.
+      run: |
+        python3 - <<'EOF'
+        import glob, sys, xml.etree.ElementTree as ET
+        THRESHOLD = 45.0
+        hit = total = 0
+        for f in glob.glob('coverage/**/coverage.cobertura.xml', recursive=True):
+            for pkg in ET.parse(f).getroot().iter('package'):
+                if not pkg.get('name', '').startswith(('Codout', 'Softprime')):
+                    continue
+                for line in pkg.iter('line'):
+                    total += 1
+                    hit += int(line.get('hits', '0')) > 0
+        pct = 100 * hit / total if total else 0.0
+        print(f'Cobertura de linhas (Codout.*): {pct:.1f}% (piso: {THRESHOLD}%)')
+        sys.exit(0 if pct >= THRESHOLD else 1)
+        EOF
     - name: Upload coverage
       uses: actions/upload-artifact@v4
       if: always()

Codout.Framework.Data/Codout.Framework.Data.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
 	<PropertyGroup>
 		<Version>6.4.0</Version>
@@ -8,9 +8,14 @@
 		<Description>Interface da Biblioteca de persistência do Framework da Codout</Description>
 		<PackageTags>Codout;Framework;ORM;DAL;Repository;UnitOfWork;Specification;Auditing</PackageTags>
 		<GenerateDocumentationFile>true</GenerateDocumentationFile>
-		<NoWarn>$(NoWarn);CS1591</NoWarn>
 		<LangVersion>latest</LangVersion>
 		<Nullable>enable</Nullable>
 	</PropertyGroup>
 
+	<PropertyGroup>
+		<!-- XML docs completas neste pacote: CS1591 volta a ser erro -->
+		<NoWarn>$(NoWarn.Replace(';CS1591', ''))</NoWarn>
+		<WarningsAsErrors>$(WarningsAsErrors);CS1591</WarningsAsErrors>
+	</PropertyGroup>
+
 </Project>

Codout.Framework.Data/Entity/IEntity'1.cs

@@ -1,12 +1,14 @@
-namespace Codout.Framework.Data.Entity;
+namespace Codout.Framework.Data.Entity;
 
 /// <summary>
-///     This serves as a base interface for <see cref="IEntity{TId}" /> and
+///     Entidade com identificador tipado: estende <see cref="IEntity" /> expondo o
+///     Id de forma covariante (<c>out TId</c>).
 /// </summary>
+/// <typeparam name="TId">Tipo do identificador da entidade.</typeparam>
 public interface IEntity<out TId> : IEntity
 {
     /// <summary>
     ///     Gets the ID which uniquely identifies the entity instance within its type's bounds.
     /// </summary>
     TId Id { get; }
-}
+}

Codout.Framework.Data/Entity/IEntity.cs

@@ -1,10 +1,13 @@
-using System.Collections.Generic;
+using System.Collections.Generic;
 using System.Reflection;
 
 namespace Codout.Framework.Data.Entity;
 
 /// <summary>
-///     This serves as a base interface for <see cref="IEntity{TId}" /> and
+///     Interface base (não genérica) de toda entidade do framework: expõe os membros
+///     de identidade que não dependem do tipo do Id, permitindo que repositórios e
+///     infraestrutura tratem entidades de forma polimórfica. Para acesso tipado ao
+///     Id, use <see cref="IEntity{TId}" />.
 /// </summary>
 public interface IEntity
 {
@@ -23,4 +26,4 @@ public interface IEntity
     ///     objects to be lazily loaded.
     /// </remarks>
     bool IsTransient();
-}
+}

Codout.Framework.Data/Entity/IHasAssignedId.cs

@@ -1,4 +1,4 @@
-namespace Codout.Framework.Data.Entity;
+namespace Codout.Framework.Data.Entity;
 
 /// <summary>
 ///     Defines the public members of a class that supports setting an assigned ID of an object.
@@ -10,9 +10,9 @@ internal interface IHasAssignedId<in TId>
     ///     Sets the assigned ID of an object.
     /// </summary>
     /// <remarks>
-    ///     This is not part of <see cref="Entity" /> since most entities do not have assigned
+    ///     This is not part of <see cref="IEntity{TId}" /> since most entities do not have assigned
     ///     IDs and since business rules will certainly vary as to what constitutes a valid,
     ///     assigned ID for one object but not for another.
     /// </remarks>
     void SetAssignedIdTo(TId assignedId);
-}
+}

Codout.Framework.Domain/Codout.Framework.Domain.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
 	<PropertyGroup>
 		<Version>6.4.0</Version>
@@ -9,6 +9,12 @@
 		<PackageTags>Codout;Framework;Domain;</PackageTags>
 	</PropertyGroup>
 
+	<PropertyGroup>
+		<!-- XML docs completas neste pacote: CS1591 volta a ser erro -->
+		<NoWarn>$(NoWarn.Replace(';CS1591', ''))</NoWarn>
+		<WarningsAsErrors>$(WarningsAsErrors);CS1591</WarningsAsErrors>
+	</PropertyGroup>
+
 	<ItemGroup>
 	</ItemGroup>
 

Codout.Framework.Domain/Entities/ClientGeneratedEntity.cs

@@ -18,6 +18,11 @@ namespace Codout.Framework.Domain.Entities;
 [Serializable]
 public abstract class ClientGeneratedEntity : Entity<Guid?>, IClientGeneratedId
 {
+    /// <summary>
+    ///     Atribui <c>Guid.NewGuid()</c> ao Id quando a instância ainda é transient.
+    ///     Na materialização pelo EF o comportamento é preservado: o Id atribuído
+    ///     aqui é sobrescrito em seguida pelos valores vindos do banco.
+    /// </summary>
     protected ClientGeneratedEntity()
     {
         // Só atribui na criação real. Na materialização do EF a instância ainda é

Codout.Framework.Domain/Entities/Entity.cs

@@ -9,9 +9,16 @@
 namespace Codout.Framework.Domain.Entities;
 
 /// <summary>
+///     Classe base para entidades de domínio com identificador tipado. Implementa
+///     igualdade por Id quando a entidade está persistida e por assinatura de domínio
+///     (propriedades com <see cref="DomainSignatureAttribute" />) quando ainda é
+///     transient, com hash code estável durante o ciclo de vida da instância.
+/// </summary>
+/// <typeparam name="TId">Tipo do identificador da entidade (int, long, Guid, string, etc.).</typeparam>
+/// <remarks>
 ///     For a discussion of this object, see
 ///     http://devlicio.us/blogs/billy_mccafferty/archive/2007/04/25/using-equals-gethashcode-effectively.aspx
-/// </summary>
+/// </remarks>
 [Serializable]
 public abstract class Entity<TId> : ValidatableObject, IEntity<TId>
 {
@@ -61,6 +68,13 @@ public virtual bool IsTransient()
         return Id == null || Id.Equals(default(TId));
     }
 
+    /// <summary>
+    ///     Define explicitamente o Id da entidade (assigned/client-generated id).
+    ///     Use quando a identidade é atribuída pela aplicação (ex.:
+    ///     <see cref="ClientGeneratedEntity" />); em cenários store-generated o Id é
+    ///     preenchido pela infraestrutura de persistência e este método não deve ser chamado.
+    /// </summary>
+    /// <param name="id">Identificador a atribuir à entidade.</param>
     public virtual void SetId(TId id)
     {
         Id = id;

ROADMAP.md

@@ -93,10 +93,13 @@ risco × facilidade, em `tests/<Pacote>.Tests`:
 - [x] Onda 2 concluída (Testcontainers exige Docker no runner — `ubuntu-latest` já tem).
 - [x] Onda 3 concluída.
 - [x] Onda 4 concluída.
-- [ ] Coleta de cobertura com `coverlet.collector` + publicação de relatório
+- [x] Coleta de cobertura com `coverlet.collector` + publicação de relatório
       no CI (artifact ou Codecov + badge no README).
-- [ ] Meta de cobertura: ≥ 70 % nos pacotes core (Data/Domain/Common/EF),
-      ≥ 50 % nos demais.
+- [ ] Meta de cobertura: ≥ 70 % nos pacotes core, ≥ 50 % nos demais.
+      *Status 2026-06-12: 47,4% total com gate ratchet de 45% no CI; EF 73%,
+      Mongo 96%, NH 79%, Multitenancy 99% — pendências principais: Domain
+      (22%), DynamicLinq (28%), Common (44%). Subir o piso junto com a
+      cobertura.*
 
 **Critério de aceite**: todo pacote publicável tem projeto de teste; metas de
 cobertura atingidas e visíveis no CI.
@@ -134,8 +137,8 @@ Tudo no `Directory.Build.props`, exceto onde indicado:
 - [x] `PackageReadmeFile`: criar `README.md` curto por pacote (o que é,
       instalação, exemplo mínimo) e empacotar — hoje 19/20 pacotes têm página
       vazia no NuGet.org.
-- [ ] `Description` e `PackageTags` individualizados em cada csproj.
-- [ ] Publicar os snupkg no fluxo de release (NuGet.org aceita no mesmo
+- [x] `Description` e `PackageTags` individualizados em cada csproj.
+- [x] Publicar os snupkg no fluxo de release (NuGet.org aceita no mesmo
       `dotnet nuget push`).
 - [ ] Republicar pacotes com bump **patch** (mudança só de empacotamento) —
       confirmar com o usuário antes, pois publicar exige tag.
@@ -148,7 +151,7 @@ e símbolos depuráveis (F12 no código do framework a partir de um consumidor).
 - [x] Reescrever a tabela de módulos do README: remover "Zenvia", "DAL",
       "Kendo.DynamicLinq", "DP", "Shared"; incluir Security.*, Storage,
       Storage.Azure, Application, Mcp, Image.Extensions.
-- [ ] Seção "Qual pacote eu instalo?" com cenários comuns (EF + API,
+- [x] Seção "Qual pacote eu instalo?" com cenários comuns (EF + API,
       Mongo, multitenancy, mailer).
 - [x] `GenerateDocumentationFile=true` global (via `Directory.Build.props`)
       e completar XML docs nos tipos públicos de `Domain`, `Common`, `Data`