Plataforma-de-desarrolladores/AGENTS.md

# AGENTS.md

## Project identity

This project is **Plataforma de Desarrolladores Agua Hillo**.

It is an **ASP.NET WebForms** application using **C#** and **.NET Framework 4.8 or 4.8.1**.

Do **not** convert this project to:

- ASP.NET Core
- Razor Pages
- MVC Core
- Blazor
- Minimal APIs
- Angular-only app
- Web API-only app

ASP.NET WebForms must stay on .NET Framework. If a command, package, or template requires ASP.NET Core, do not use it for this project.

---

## Main goal

Create a clean WebForms starter project from zero, keeping the same Metronic visual style and only the necessary bundle methods used by the master page and login page.

The project must use a contract/service structure so pages, master page, login, menu, user session, and future modules do not connect directly to database classes.

Target architecture:

```text
ASPX / Master Page / User Controls
    ↓
Contracts
    ↓
Services
    ↓
Repositories / SQL helpers
    ↓
Database
```

---

## Language rules

- All new code must be **C#**.
- Do not add VB.NET files.
- Do not add `.vb` files to the active project.
- Old VB files may exist only as migration reference files using `.vb.txt`.
- Do not use VB comment syntax in C# files.
- Do not use JavaScript/CSS/Powershell comments as C# comments.

---

## Command rules

When giving commands for this project:

- Prefer **PowerShell**, **Developer PowerShell**, or **Visual Studio Package Manager Console** commands.
- Commands must be written in **one line**.
- Do not use PowerShell line continuation with backticks.
- Do not suggest `dotnet new webforms` because WebForms is not supported by the .NET CLI as an ASP.NET Core project.
- If a WebForms project must be created from command line, use Visual Studio/MSBuild-compatible project files or create the project through Visual Studio using **ASP.NET Web Application (.NET Framework)**.
- Target framework must be `.NET Framework 4.8` or `.NET Framework 4.8.1`.

Recommended project creation path:

```powershell
mkdir "C:\Proyectos\Agua de hermosillo\Plataforma de Desarrolladores"
```

```powershell
cd "C:\Proyectos\Agua de hermosillo\Plataforma de Desarrolladores"
```

Then create/open the WebForms project in Visual Studio 2022 as:

```text
ASP.NET Web Application (.NET Framework) → Web Forms → C# → .NET Framework 4.8/4.8.1
```

---

## Project folder rules

Use this base structure:

```text
SIG.Web/
  AppCode/
    Infrastructure/
    Sql/
    Repositories/
    Security/
    Utilities/
    Contracts/
    Models/
    Services/
  Styles/
  Scripts/
  Metronic/
  Site.master
  Site.master.cs
  Login.aspx
  Login.aspx.cs
  Inicio.aspx
  Inicio.aspx.cs
  BundleConfig.cs
  Global.asax
  Global.asax.cs
  Web.config
```

Rules:

- Do not place database access directly inside `.aspx.cs`, `.ascx.cs`, or `Site.master.cs`.
- Database-related helpers go under `App_Code/Sql` or a clearly named SQL/data folder.
- Business access goes through `Contracts` and `Services`.
- If the project file needs explicit compilation entries, include C# files recursively, for example `App_Code\**\*.cs`, but avoid duplicate compile entries that include the same file twice.

---

## Asset folder rules

The following folders are legacy visual dependencies and must be copied as complete folders:

```text
Styles/
Scripts/
Metronic/
```

Do not replace Metronic with Bootstrap-only layout.
Do not upgrade Metronic unless the user explicitly asks.
Do not remove old scripts just because they look unused; only remove references from bundles when they are not used by the master/login flow.

---

## Bundle rules

The project must implement only the bundle methods needed by the current `Site.master` and login page.

Do not bring every old bundle method from the legacy project.
Do not add unused bundle groups just because they existed before.
Do not add duplicate bundle keys.
Do not add empty bundle methods.

Allowed current bundle keys are the ones actually rendered by master/login, especially:

```text
~/bundles/modernizr
~/bundles/scripts
~/bundles/highcharts
~/Metronic/assets/global/scripts/JSV1
~/Metronic/assets/global/css/cssV1
```

WebForms/AjaxControlToolkit support bundles are allowed only when referenced by `ScriptManager` or required by WebForms controls:

```text
~/bundles/jquery
~/bundles/WebFormsJs
~/bundles/MsAjaxJs
~/Content/AjaxControlToolkit/Styles/Bundle
```

Rules:

- If `Site.master` or `Login.aspx` does not render a bundle, do not add it.
- If a bundle exists only for old pages not migrated yet, leave it out until the page needs it.
- Prefer preserving original asset paths from `Styles`, `Scripts`, and `Metronic`.
- Use `CssRewriteUrlTransform` for CSS bundles that reference fonts, images, or relative URLs.
- Do not register CSS/JS from server controls when the style/script is global; use `BundleConfig` and the master page.

---

## WebForms page rules

All normal `.aspx` pages must use `Site.master`, except the login page.

Normal pages:

- Must include `MasterPageFile="~/Site.master"`.
- Must not include `<html>`, `<head>`, `<body>`, or `<form>`.
- Must use `<asp:Content>` controls.
- Should inherit from `ClsPaginaBase` or the current C# page base class.
- Must not connect directly to SQL classes.
- Must call contracts/services for data, authentication, permissions, catalogs, menus, and user context.

Public registration exception:

- `Pages/Security/RegistroCliente.aspx`, `RegistroPendiente.aspx` and `VerificarCorreo.aspx` may be standalone public pages with their own `form runat="server"`.
- `RegistroCliente.aspx` keeps its two-step draft in encrypted ViewState and persists only after all client/company validations pass.
- All persistence continues through contracts/services/repositories and stored procedures.

Login page:

- Is the only page allowed to have its own full HTML structure.
- May inherit from `System.Web.UI.Page` or its own login base class.
- Must not inherit from `ClsPaginaBase` if that base class requires an authenticated session.
- Must use `IAuthContract` or the current auth contract.
- Must create a dummy session until real authentication is implemented.
- Must not hardcode real database login logic in `Login.aspx.cs`.

Important naming rule:

- Do not create both `Login.aspx` and `LogIn.aspx`.
- If the starter already uses `LogIn.aspx`, keep that name and keep `Web.config` consistent.
- If creating from scratch, prefer `Login.aspx`, but update `Web.config`, redirects, and links consistently.

---

## Master page rules

`Site.master` owns the main HTML structure.

Rules:

- `Site.master` owns the only main `<form runat="server">`.
- `Site.master` must keep the Metronic layout structure.
- Keep the sidebar/header/page-content structure similar to the original Metronic project.
- Do not restore the hidden search box from the old header.
- Keep the actions button if it exists in the selected master layout.
- Do not hardcode real user/menu database logic inside `Site.master.cs`.
- User data must come from a contract/service.
- Menu data must come from a contract/service.
- Breadcrumb/title/layout data must come from a contract/service when dynamic.
- Do not use `<title id="Titulo" runat="server">`.
- Prefer `<title><%: Page.Title %></title>`.
- If a generated starter currently uses a title literal, replace it with `Page.Title` unless there is a specific reason to keep the literal.

Current preferred contracts:

```text
IAuthContract
IUserSessionContract
IMenuContract
IMasterPageContract
```

If old names such as `IUserContextProvider` or `IMenuProvider` exist, migrate them to the current contract naming or create adapters. Do not keep two competing naming systems.

---

## ContentPlaceHolder rules

`Site.master` must use short placeholder IDs.

Preferred final placeholder IDs:

```text
H = page-specific head/CSS content
C = main page content
J = page-specific JavaScript
```

Example in `Site.master`:

```aspx
<asp:ContentPlaceHolder ID="H" runat="server" />
<asp:ContentPlaceHolder ID="C" runat="server" />
<asp:ContentPlaceHolder ID="J" runat="server" />
```

Example in a normal page:

```aspx
<asp:Content ID="ContentHead" ContentPlaceHolderID="H" runat="server">
</asp:Content>

<asp:Content ID="ContentMain" ContentPlaceHolderID="C" runat="server">
</asp:Content>

<asp:Content ID="ContentScripts" ContentPlaceHolderID="J" runat="server">
</asp:Content>
```

If the generated starter currently has `HeadContent`, `MainContent`, or `ScriptsContent`, rename them to `H`, `C`, and `J` before adding more pages.

Do not mix placeholder naming systems in the same project.

---

## Login and session rules

Authentication must go through a contract.

Required flow:

```text
Login.aspx.cs
  ↓
IAuthContract
  ↓
DummyAuthContract now, real AuthService later
  ↓
IUserSessionContract
  ↓
Session user
```

Initial login may be dummy.

Dummy session user should be safe and clearly fake, for example:

```text
UserId: 15
CompanyId: 1
RoleId: 1
RoleName: Administrador
CompanyName: Empresa Demo
DisplayName: Usuario Demo
```

Rules:

- Dummy login may accept any non-empty username and password during starter setup.
- Mark dummy authentication clearly in code comments.
- Do not mix real SQL authentication with dummy authentication in the same class.
- When real login is implemented, create a new service such as `SqlAuthContract` or `AuthService`.
- Do not store passwords in session.
- Do not log raw passwords.
- Use Forms Authentication if staying with classic WebForms auth.

---

## Contract rules

Contracts belong in `/Contracts`.

Current minimum contracts:

```text
Contracts/IAuthContract.cs
Contracts/IUserSessionContract.cs
Contracts/IMenuContract.cs
Contracts/IMasterPageContract.cs
```

Suggested future contracts:

```text
Contracts/IPermissionContract.cs
Contracts/INotificationContract.cs
Contracts/ICatalogSearchContract.cs
Contracts/IAuditContract.cs
Contracts/ICurrentCompanyContract.cs
```

Rules:

- Pages call contracts, not SQL classes.
- Master page calls contracts, not SQL classes.
- Login calls contracts, not SQL classes.
- Contracts must return models, DTOs, or result objects, not raw `DataTable` unless migrating legacy code.
- If legacy `DataTable` is required, isolate it behind a contract and document why.

---

## Service rules

Services belong in `/Services`.

Current starter services may include:

```text
Services/ContractRegistry.cs
Services/DummyAuthContract.cs
Services/UserSessionContract.cs
Services/DummyMenuContract.cs
Services/MasterPageContract.cs
```

Rules:

- `ContractRegistry` may be used as a simple manual dependency resolver for WebForms.
- Do not introduce a complex dependency injection framework unless required.
- Services may depend on SQL helpers/repositories.
- `.aspx.cs` files should be thin and delegate work to services.
- Keep dummy services separate from SQL-backed services.

---

## Model rules

Models belong in `/Models`.

Current starter models may include:

```text
Models/AppUser.cs
Models/LoginResult.cs
Models/MenuItemModel.cs
Models/MasterLayoutModel.cs
Models/BreadcrumbItem.cs
```

Rules:

- Use models to move data between contracts and WebForms pages.
- Do not pass anonymous objects across layers.
- Do not expose SQL connection classes or `SqlDataReader` from services to pages.
- Keep models simple and serializable when possible.

---

## Database and SQL structure rules

All database connection structure must be centralized under `App_Code/Sql` or an equivalent SQL/data folder.

Current starter SQL structure:

```text
App_Code/Sql/ConnectionNames.cs
App_Code/Sql/IConnectionStringProvider.cs
App_Code/Sql/WebConfigConnectionStringProvider.cs
App_Code/Sql/SqlConnectionFactory.cs
App_Code/Sql/SqlQueryExecutor.cs
```

Rules:

- Define connection names in one place.
- Read connection strings from `Web.config`.
- Do not hardcode connection strings in pages, master, controls, or services.
- Do not create `SqlConnection` directly in `.aspx.cs`.
- Do not create `SqlCommand` directly in `.aspx.cs`.
- Use repositories or SQL executor classes behind contracts.
- All application database reads and writes must use stored procedures; inline SQL in C# is prohibited.
- Mandatory: read and follow `AGENTS_STORED_PROCEDURES.md` for naming, output parameters, TRY/CATCH, logging, transactions, and logical deletion.
- Mandatory: read and follow `AGENTS_DATA_READER_MAPPING.md` for object, list, `DataTable`, and `JArray` result mapping.
- Mandatory: read and follow `AGENTS_DATABASE_ERROR_LOGGING.md` for safe parameter logging and reproducible stored-procedure calls.
- Mandatory: read and follow `AGENTS_PAGE_STRUCTURE.md` for the `Pages/Modulo/` location of all new WebForms pages.
- Mandatory: read and follow `AGENTS_WEBFORMS_PARTIAL_POSTBACKS.md` for the single master form, ScriptManager ownership, UpdatePanel usage, and partial-postback rules.
- Mandatory: read and follow `AGENTS_JAVASCRIPT_INITIALIZATION.md` for per-element initialization flags, global event guards, and idempotent control setup after partial postbacks.
- Keep stored procedure names centralized.
- Repositories must use `CommandType.StoredProcedure` and parameterized inputs/outputs.
- Never concatenate raw user input into SQL.

Recommended Web.config connection string pattern:

```xml
<connectionStrings>
  <add name="DefaultConnection" connectionString="..." providerName="System.Data.SqlClient" />
  <add name="SecurityConnection" connectionString="..." providerName="System.Data.SqlClient" />
  <add name="ReportingConnection" connectionString="..." providerName="System.Data.SqlClient" />
</connectionStrings>
```

---

## Base page rules

Normal pages should inherit from a C# base page.

Preferred base class:

```text
App_Code/Infrastructure/ClsPaginaBase.cs
```

If the starter currently has `WebFormsPageBase.cs`, either:

- rename it to `ClsPaginaBase.cs`, or
- keep `WebFormsPageBase` and update this AGENTS.md/project rules consistently.

Do not keep both base classes doing the same job.

Base page responsibilities:

- Validate authenticated session.
- Expose current user from `IUserSessionContract`.
- Provide helper methods for messages, redirects, and permissions.
- Avoid database access.
- Avoid page-specific business logic.

---

## Global.asax rules

`Global.asax` / `Global.asax.cs` should:

- Register bundles through `BundleConfig.RegisterBundles(BundleTable.Bundles)`.
- Configure basic application startup.
- Avoid business logic.
- Avoid direct database startup queries unless absolutely required.

If OWIN is not used, prevent startup errors by adding this to `Web.config`:

```xml
<add key="owin:AutomaticAppStartup" value="false" />
```

Do not add OWIN packages unless the project actually needs OWIN.

---

## Web.config rules

`Web.config` must stay compatible with ASP.NET WebForms on .NET Framework 4.8/4.8.1.

Rules:

- Use Forms Authentication unless a different auth system is explicitly requested.
- Allow anonymous access only to the login page and required static assets.
- Do not add ASP.NET Core middleware settings.
- Do not add unsupported `.NET Core` config sections.
- Do not add CodeDom provider entries unless the matching NuGet package is installed.
- If this error appears: `No se pudo ubicar el tipo de proveedor CodeDom Microsoft.CodeDom.Providers.DotNetCompilerPlatform...`, either install the exact package version or remove/fix the `system.codedom` section.
- Keep MIME mappings for fonts such as `.woff` and `.woff2` when Metronic requires them.

---

## OWIN rule

If the application shows this error:

```text
No assembly found containing an OwinStartupAttribute
```

And the project does not use OWIN, add this in `appSettings`:

```xml
<add key="owin:AutomaticAppStartup" value="false" />
```

Do not create an empty OWIN startup class just to silence the error unless OWIN is actually required.

---

## Site.master rendering rules

The master page should render bundles and scripts in this general order:

Inside `<head>`:

```aspx
<%: Scripts.Render("~/bundles/modernizr") %>
<%: Styles.Render("~/Content/AjaxControlToolkit/Styles/Bundle") %>
<%: Styles.Render("~/Metronic/assets/global/css/cssV1") %>
<asp:ContentPlaceHolder ID="H" runat="server" />
```

Inside `<form>` near the top:

```aspx
<asp:ScriptManager ID="TSM" runat="server" />
<%: Scripts.Render("~/bundles/scripts") %>
```

Before closing `</form>`:

```aspx
<%: Scripts.Render("~/Metronic/assets/global/scripts/JSV1") %>
<%: Scripts.Render("~/bundles/highcharts") %>
<asp:ContentPlaceHolder ID="J" runat="server" />
```

Rules:

- Do not render the same script twice.
- Do not render JQuery twice.
- Keep `ScriptManager` if AjaxControlToolkit, UpdatePanel, or WebForms AJAX is used.
- Keep `TSM_AsyncPostBackError` only if implemented in code-behind.
- Remove or implement any event handler referenced by markup.

---

## Header/menu rules

The master header must preserve the selected Metronic layout.

Rules:

- Keep user dropdown.
- Keep logout option.
- Keep actions button when present.
- Do not restore the hidden/old search box from legacy header.
- Sidebar menu must be built from `IMenuContract`.
- Do not build the menu from SQL inside `Site.master.cs`.
- Menu items should use `MenuItemModel` or an equivalent model.
- Encode text output when generating HTML menu strings.

---

## Page title and breadcrumb rules

Page title and breadcrumb should be handled consistently.

Rules:

- Use `Page.Title` for the browser title.
- Use a master/layout model for visible page title and breadcrumb.
- Do not hardcode global breadcrumb logic in every page.
- Normal pages may set page title in `Page_Load` or via properties.

Preferred model:

```text
MasterLayoutModel
  PageTitle
  Breadcrumbs
  CurrentUser
  MenuItems
```

---

## Security rules

- Do not store passwords in code, comments, Web.config examples, or session.
- Do not expose real connection strings in committed files.
- Use dummy values in examples.
- Use parameterized SQL.
- Validate uploaded files by extension, MIME type, and size when uploads are later added.
- Avoid writing raw exception details to the user in production.
- Keep `customErrors mode="Off"` only for local development.

---

## Error handling rules

- Handle null session user cleanly and redirect to login.
- Handle failed login with a friendly message.
- Handle async postback errors through `ScriptManager.AsyncPostBackError` only if the handler exists.
- Avoid infinite loading states in JavaScript controls.
- For AJAX/server search controls, use client and server timeouts.
- Recommended default search timeout: about 20 to 30 seconds unless the user asks otherwise.

---

## JavaScript and CSS rules

- Global scripts/styles must be registered in `BundleConfig` and rendered by master.
- Page-specific scripts go in placeholder `J`.
- Page-specific CSS/head content goes in placeholder `H`.
- Do not inline large JavaScript blocks in `.aspx` unless page-specific and small.
- Do not remove existing custom legacy files unless the user asks.
- Fix null `addEventListener` errors by checking that the element exists before attaching events.
- Avoid blocking Ctrl+V unless a specific feature requires it.

---

## User control rules

If server controls are migrated:

- Prefer C# classes under `App_Code/SigControls` when creating reusable server controls.
- Do not mix WebForms `.ascx` user controls with App_Code server-control classes unless there is a clear reason.
- Do not register global CSS/JS from the control when master bundles already include them.
- Controls should expose properties/events and avoid direct SQL access.
- Controls should call contracts/services when they need data.

---

## PDF viewer migration rules

If the PDF viewer is added to this project later:

- Implement it in C#.
- Prefer `App_Code/SigControls` for server controls.
- Do not add VB files.
- Do not use `/* */` comments in VB reference files; VB references must remain `.vb.txt` only.
- Keep global PDF viewer CSS/JS references in bundles.
- Do not register duplicate resources from the control and master at the same time.
- Session or temp-folder PDF storage must be explicit and centralized.

---

## Home page rules

Use only one active home page convention.

Allowed options:

```text
Default.aspx
Inicio.aspx
```

Rules:

- Do not keep both as competing entry pages.
- If using `Inicio.aspx`, redirect `Default.aspx` to `Inicio.aspx` or update Forms Authentication default URL.
- If using `Default.aspx`, keep Web.config and menu links pointing to `Default.aspx`.
- The home page must use `Site.master`.

---

## File delivery rules for this project

When generating a single downloadable file:

- If the file is `.js` or `.css` and it is not inside a ZIP, append `.txt` to the filename.
- Example: `custom.js.txt`, `styles.css.txt`.
- If the file is inside a ZIP, keep the real extension `.js` or `.css`.
- For project-level delivery, prefer ZIP files.

---

## What not to add yet

Do not add the following until the user explicitly asks:

- Real SQL login implementation
- Full permission system
- Notifications
- Web Push
- PDF viewer
- BuscadorCatalogo
- DropdownGrid
- PorcentajeBox
- Angular
- APIs
- Background jobs
- OWIN
- Entity Framework
- Dependency injection framework
- New Metronic version

The starter must stay small and focused: commands, master page, login, contracts, dummy user session, bundle structure, copied assets, and centralized SQL foundation.

---

## Current implementation checklist

When modifying or regenerating the project, verify:

- [ ] Project targets .NET Framework 4.8 or 4.8.1.
- [ ] All new code is C#.
- [ ] No active `.vb` files were added.
- [ ] `Styles`, `Scripts`, and `Metronic` were copied as-is.
- [ ] `BundleConfig.cs` contains only bundles rendered by master/login or required by WebForms AJAX.
- [ ] `Site.master` owns the only main form.
- [ ] Normal pages use `Site.master`.
- [ ] Normal pages do not contain full HTML structure.
- [ ] Login is the only standalone full HTML page.
- [ ] User/session data comes from `IUserSessionContract`.
- [ ] Login uses `IAuthContract`.
- [ ] Menu comes from `IMenuContract`.
- [ ] Master layout data comes from `IMasterPageContract`.
- [ ] SQL connection helpers are centralized under `App_Code/Sql`.
- [ ] Pages do not directly instantiate SQL connections.
- [ ] Placeholder IDs are `H`, `C`, and `J`.
- [ ] No hidden old search box was restored.
- [ ] Actions button is preserved when present in the selected layout.
- [ ] `Web.config` login URL matches the actual login page filename.
- [ ] No duplicate `Login.aspx` / `LogIn.aspx` pages exist.
- [ ] No OWIN startup error exists, or OWIN automatic startup is disabled.
- [ ] No missing CodeDom provider error exists.

---

## Preferred next evolution

After the starter works, the safest growth path is:

1. Replace dummy login with SQL-backed `IAuthContract`.
2. Replace dummy menu with SQL-backed `IMenuContract`.
3. Add permission contract.
4. Add base page authorization checks.
5. Add reusable controls one by one.
6. Add catalog search and UI helpers.
7. Add PDF viewer only after the base shell is stable.

Keep every new feature behind contracts so the WebForms UI remains thin and easier to migrate later if needed.