gpw_next/AGENTS.md

GPW_NEXT Agent Instructions

Architecture Overview

• Multi-Project Structure: The solution consists of several interconnected projects.
• Smart10 Module:
  • GPW.CORE.Smart10: The ASP.NET Core Server project. Hosts API Controllers and implements Server-side logic.
  • GPW.CORE.Smart10.Client: The Blazor WebAssembly project. Contains UI components and client-side services that consume APIs.
• Data Layer:
  • GPW.CORE.Data: Contains EF Core models (DbModels), GPWContext, and the GPWController which acts as a data access layer.
  • GPW.CORE.Dto: Contains Data Transfer Objects used for communication between Client and Server to avoid direct dependency on EF Core models.
• Services Pattern:
  • Client-side: Services implement interfaces (e.g., ITimbraturesService) and use HttpClient to call REST endpoints.
  • Server-side (Prerendering): To support Blazor Web App prerendering, implement the same interfaces in the Server project using a "Server-side" implementation that calls CoreSmartDataService directly instead of via HTTP.

Development Workflows

Implementing New Features (Smart10 Example)

1. DTO: Define the required data structure in GPW.CORE.Dto.
2. Server Data Access: Ensure CoreSmartDataService (in GPW.CORE.Smart10.Data) or GPWController (in GPW.CORE.Data) has the necessary business logic.
3. API Controller: Add an endpoint in GPW.CORE.Smart10\Controllers to expose the data via REST.
4. Client Interface: Add the method signature to the interface in GPW.CORE.Smart10.Client\Services.
5. Client Implementation: Implement the service in GPW.CORE.Smart10.Client\Services using HttpClient.
6. Server Implementation (Prerendering Support): Create a server-side implementation of the interface in GPW.CORE.Smart10\Services that calls CoreSmartDataService directly.
7. Dependency Injection:
   • Client: Register the HttpClient-based service in GPW.CORE.Smart10.Client\Program.cs.
   • Server: Register the direct-access service in GPW.CORE.Smart10\Program.cs.

Testing & Verification

• UI Testing: Use the Test...razor pages in the Client project to validate end-to-end flows (Insert, Update, Delete, Search).
• Manual Check: For UI changes, verify the interaction between @bind and event handlers (use @bind:after for .NET 7+).

Key Constraints & Gotchas

• NLog: Do not add NLog.Web.AspNetCore to the Client project; it is incompatible with the WASM runtime.
• UID Logic: Many entities use a calculated UID (e.g., IdxDipendente_DataOra_Ora) for RESTful operations (like DELETE /api/resource/{uid}) instead of passing entire objects.
• Prerendering: Always provide a server-side implementation of client-side services to avoid InvalidOperationException during the initial page load.
• Namespace Integrity: Be careful with namespaces when moving logic between GPW.CORE.Smart10 (Server) and GPW.CORE.Smart10.Client (Client).