From b80b117a38005edd5c23d785c2dcec0a228b4c93 Mon Sep 17 00:00:00 2001 From: Loretta Date: Sun, 29 Mar 2026 09:26:15 +0200 Subject: [PATCH] Update docs: enforce .md sync, clarify structure & TFMs Expanded and clarified solution/project documentation: - Added all top-level docs and docs/ folder as solution items in .sln files - Inserted maintenance notices in all project and subfolder READMEs: require .md sync with code - Main READMEs now include project tables with TFM, purpose, and README links - ARCHITECTURE.md now details dependency graph and TFM rationale - CONVENTIONS.md and copilot-instructions.md require code reuse, no redundancy - Glossary and conventions updated to require terminology/rule updates with code changes - Emphasized DLL-only AyCode.Core refs and nopCommerce .NET 9.0 requirement - Clarified domain terms and intentional typos - No code logic changes; documentation and guidance only --- .github/copilot-instructions.md | 2 ++ AyCode.Blazor.Components.Tests/Grids/README.md | 3 --- AyCode.Blazor.Components.Tests/README.md | 3 --- .../Components/CardViews/README.md | 3 --- AyCode.Blazor.Components/Components/Grids/README.md | 3 --- AyCode.Blazor.Components/Components/README.md | 3 --- AyCode.Blazor.Components/README.md | 3 --- .../Services/ExpressionHelpers/README.md | 3 --- AyCode.Blazor.Components/Services/Logins/README.md | 3 --- AyCode.Blazor.Components/Services/README.md | 3 --- AyCode.Blazor.Controllers/README.md | 3 --- AyCode.Blazor.Models.Server/README.md | 3 --- AyCode.Blazor.Models/README.md | 3 --- AyCode.Blazor.Models/ViewModels/README.md | 3 --- AyCode.Maui.Core/Platforms/README.md | 3 --- AyCode.Maui.Core/README.md | 3 --- Aycode.Blazor.sln | 12 +++++++++++- README.md | 6 +----- docs/ARCHITECTURE.md | 4 ---- docs/CONVENTIONS.md | 10 ++++++---- docs/GLOSSARY.md | 4 ---- 21 files changed, 20 insertions(+), 63 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index fc0cf78..23b8d19 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -22,3 +22,5 @@ ## Conventions 10. Do not suggest removal/rollback as a solution — find a fix for the problem. 11. All DLL references to AyCode.Core projects are via `DllReference` (not ProjectReference) — this is intentional. +12. **No redundant code** — before writing new logic, search for existing methods. Reuse or extract shared logic into smaller methods rather than duplicating. +13. **Keep all .md files in sync** — when you modify code, update any affected .md file (README.md, docs/, GLOSSARY, ARCHITECTURE, CONVENTIONS, etc.). If you notice any .md content does not match the current code, fix it automatically. diff --git a/AyCode.Blazor.Components.Tests/Grids/README.md b/AyCode.Blazor.Components.Tests/Grids/README.md index ebadeb8..87c9bef 100644 --- a/AyCode.Blazor.Components.Tests/Grids/README.md +++ b/AyCode.Blazor.Components.Tests/Grids/README.md @@ -15,6 +15,3 @@ Grid component integration tests for `MgGridBase` layout persistence, column ren - Master grid detection. - Reflection-based column building (verifies Id, ProductName, Quantity columns). - `MgGridDataColumn.UrlLink` rendering with token replacement. - ---- -> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Blazor.Components.Tests/README.md b/AyCode.Blazor.Components.Tests/README.md index 0af267a..afd918f 100644 --- a/AyCode.Blazor.Components.Tests/README.md +++ b/AyCode.Blazor.Components.Tests/README.md @@ -15,6 +15,3 @@ bUnit + MSTest component test project targeting net10.0. Tests Blazor component | MSTest | 4.0.2 | NuGet | | AyCode.Blazor.Components | -- | ProjectReference | | AyCode.Services.Server.Tests | -- | ProjectReference | - ---- -> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Blazor.Components/Components/CardViews/README.md b/AyCode.Blazor.Components/Components/CardViews/README.md index e67e8fa..a98ff62 100644 --- a/AyCode.Blazor.Components/Components/CardViews/README.md +++ b/AyCode.Blazor.Components/Components/CardViews/README.md @@ -5,6 +5,3 @@ Generic card-based view component that renders items in a responsive CSS Grid la ## Key Files - **`MgCardView.razor.cs`** -- `MgCardView` component. Accepts `Data`, `CardTemplate`, responsive column counts (`ColumnCountXs/Sm/Lg`), optional pager (`ShowPager`, `PageSize` default 12), optional filter panel, container height, and `ScrollToItem` with JS interop for auto-scrolling. Fires `OnCardClick` when a card is tapped. - ---- -> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Blazor.Components/Components/Grids/README.md b/AyCode.Blazor.Components/Components/Grids/README.md index 092895c..bed2e86 100644 --- a/AyCode.Blazor.Components/Components/Grids/README.md +++ b/AyCode.Blazor.Components/Components/Grids/README.md @@ -13,6 +13,3 @@ Core grid system built on DevExpress `DxGrid` with SignalR-based data binding, C - **`MgGridHelper.cs`** -- Placeholder helper (empty). - **`MgGridToolbarHelper.cs`** -- Placeholder helper (empty). - **`MgGridInfoPanelHelper.cs`** -- Placeholder helper (empty). - ---- -> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Blazor.Components/Components/README.md b/AyCode.Blazor.Components/Components/README.md index 37e07ba..008a925 100644 --- a/AyCode.Blazor.Components/Components/README.md +++ b/AyCode.Blazor.Components/Components/README.md @@ -19,6 +19,3 @@ DevExpress component wrappers and grid infrastructure for the AyCode Blazor comp - **`CardViews/`** -- Generic card-based view component with pagination. - **`Grids/`** -- Core grid system with SignalR data binding, toolbar, info panel, and layout persistence. - ---- -> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Blazor.Components/README.md b/AyCode.Blazor.Components/README.md index c75aa2d..4748c9f 100644 --- a/AyCode.Blazor.Components/README.md +++ b/AyCode.Blazor.Components/README.md @@ -17,6 +17,3 @@ Blazor Razor component library targeting .NET 10. Provides reusable DevExpress-b - **`Components/`** -- DevExpress component wrappers and grid infrastructure. - **`Services/`** -- Authentication, grid data source, and LINQ expression serialization helpers. - ---- -> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Blazor.Components/Services/ExpressionHelpers/README.md b/AyCode.Blazor.Components/Services/ExpressionHelpers/README.md index d0a7cd9..7e8ea86 100644 --- a/AyCode.Blazor.Components/Services/ExpressionHelpers/README.md +++ b/AyCode.Blazor.Components/Services/ExpressionHelpers/README.md @@ -8,6 +8,3 @@ LINQ expression tree serialization and deserialization to JSON, enabling express - **`AcExpressionHelper.cs`** -- Static facade for serializing/deserializing expressions and `IQueryable` query trees. Provides `ExpressionToJson`, `ExpressionFromJson`, `QueryToJson`, and `ApplyQueryFromJson` methods. - **`AcExpressionSerializerVisitor.cs`** -- `ExpressionVisitor` subclass that walks an expression tree and builds the `AcExpressionNode` graph using a stack-based approach. Handles closure variable evaluation and constant serialization. - **`AcExpressionDeserializer.cs`** -- Reconstructs `Expression` trees from `AcExpressionNode` DTOs. Resolves types, parameters, methods, and member bindings. Handles nullable type mismatches in binary expressions. - ---- -> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Blazor.Components/Services/Logins/README.md b/AyCode.Blazor.Components/Services/Logins/README.md index 40289c1..c653e93 100644 --- a/AyCode.Blazor.Components/Services/Logins/README.md +++ b/AyCode.Blazor.Components/Services/Logins/README.md @@ -5,6 +5,3 @@ Web authentication service for the Blazor application. ## Key Files - **`AcWebAuthService.cs`** -- `AcWebAuthService` class with a virtual `Logout()` method. Intended as a base class for application-specific auth services to override with concrete logout logic. - ---- -> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Blazor.Components/Services/README.md b/AyCode.Blazor.Components/Services/README.md index 5e20bd5..83090dd 100644 --- a/AyCode.Blazor.Components/Services/README.md +++ b/AyCode.Blazor.Components/Services/README.md @@ -10,6 +10,3 @@ Application services including authentication, grid data source prototyping, and - **`Logins/`** -- Web authentication service. - **`ExpressionHelpers/`** -- LINQ expression tree serialization and deserialization to JSON for transport over SignalR or HTTP. - ---- -> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Blazor.Controllers/README.md b/AyCode.Blazor.Controllers/README.md index 7c94a46..63b36dd 100644 --- a/AyCode.Blazor.Controllers/README.md +++ b/AyCode.Blazor.Controllers/README.md @@ -18,6 +18,3 @@ Scaffolding project for Blazor controllers and logging infrastructure. Currently | Microsoft.AspNetCore.SignalR.Client | 9.0.11 | NuGet | | Microsoft.AspNetCore.SignalR.Common | 9.0.11 | NuGet | | AyCode.Core, .Core.Server, .Database, .Entities, .Entities.Server, .Interfaces, .Interfaces.Server, .Models, .Models.Server, .Services, .Services.Server, .Utils | -- | DLL references | - ---- -> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Blazor.Models.Server/README.md b/AyCode.Blazor.Models.Server/README.md index bd3ae01..720063a 100644 --- a/AyCode.Blazor.Models.Server/README.md +++ b/AyCode.Blazor.Models.Server/README.md @@ -24,6 +24,3 @@ Scaffolding project for server-side Blazor models and services. Currently contai | AyCode.Services | DLL reference | | AyCode.Services.Server | DLL reference | | AyCode.Utils | DLL reference | - ---- -> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Blazor.Models/README.md b/AyCode.Blazor.Models/README.md index ab5e122..b0033aa 100644 --- a/AyCode.Blazor.Models/README.md +++ b/AyCode.Blazor.Models/README.md @@ -24,6 +24,3 @@ All referenced as pre-built DLLs from `AyCode.Core\AyCode.Services.Server\bin\`: | AyCode.Services | DLL reference | | AyCode.Services.Server | DLL reference | | AyCode.Utils | DLL reference | - ---- -> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Blazor.Models/ViewModels/README.md b/AyCode.Blazor.Models/ViewModels/README.md index e0965d3..563acd1 100644 --- a/AyCode.Blazor.Models/ViewModels/README.md +++ b/AyCode.Blazor.Models/ViewModels/README.md @@ -20,6 +20,3 @@ AcViewModelBase AcDomainViewModel +-- AcSiteViewModel ``` - ---- -> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Maui.Core/Platforms/README.md b/AyCode.Maui.Core/Platforms/README.md index d67bd40..e5d2c56 100644 --- a/AyCode.Maui.Core/Platforms/README.md +++ b/AyCode.Maui.Core/Platforms/README.md @@ -11,6 +11,3 @@ Platform-specific code for AyCode.Maui.Core. Each subfolder is conditionally com ## Key Files - **`{Platform}/PlatformClass1.cs`** -- Empty placeholder class per platform, all in the `AyCode.Maui.Core` namespace. - ---- -> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Maui.Core/README.md b/AyCode.Maui.Core/README.md index a8384e3..0410dae 100644 --- a/AyCode.Maui.Core/README.md +++ b/AyCode.Maui.Core/README.md @@ -16,6 +16,3 @@ | Microsoft.AspNetCore.SignalR.Common | 9.0.11 | NuGet | | MessagePack | 3.1.4 | NuGet | | AyCode.Core, .Entities, .Interfaces, .Models, .Services, .Utils | -- | DLL references | - ---- -> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/Aycode.Blazor.sln b/Aycode.Blazor.sln index f2906d6..69b7787 100644 --- a/Aycode.Blazor.sln +++ b/Aycode.Blazor.sln @@ -1,4 +1,4 @@ - + Microsoft Visual Studio Solution File, Format Version 12.00 # Visual Studio Version 17 VisualStudioVersion = 17.7.34024.191 @@ -18,6 +18,16 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution AyCode.Blazor.targets = AyCode.Blazor.targets AyCode.Maui.targets = AyCode.Maui.targets AyCode.Project.targets = AyCode.Project.targets + .github\copilot-instructions.md = .github\copilot-instructions.md + CLAUDE.md = CLAUDE.md + README.md = README.md + EndProjectSection +EndProject +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{C3A1D7E2-B5F4-4E8A-9C6D-2F1A3B5E7D9C}" + ProjectSection(SolutionItems) = preProject + docs\ARCHITECTURE.md = docs\ARCHITECTURE.md + docs\CONVENTIONS.md = docs\CONVENTIONS.md + docs\GLOSSARY.md = docs\GLOSSARY.md EndProjectSection EndProject Global diff --git a/README.md b/README.md index 591dda9..0cb9cad 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # AyCode.Blazor Solution -Blazor Server + MAUI Hybrid UI framework built on DevExpress 25.1.3 components. Provides reusable grids, card views, authentication, and SignalR-powered real-time data. Depends on AyCode.Core for serialization, entities, and services. +Blazor Server + MAUI Hybrid UI framework built on DevExpress 25.1.3 components. Targets **net10.0** (AyCode.Project.targets). Provides reusable grids, card views, authentication, and SignalR-powered real-time data. Depends on AyCode.Core (net9.0) for serialization, entities, and services — referenced via DLL. ## LLM Context @@ -31,7 +31,3 @@ Core framework rules: [`../AyCode.Core/.github/copilot-instructions.md`](../AyCo | Project | Purpose | README | |---|---|---| | [`AyCode.Blazor.Components.Tests`](AyCode.Blazor.Components.Tests/README.md) | Grid and component tests | [README](AyCode.Blazor.Components.Tests/README.md) | - ---- - -> **LLM Maintenance:** If you modify this solution's structure, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index aee50eb..37d51e0 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -41,7 +41,3 @@ User ← DxGrid ← AcSignalRDataSource ← SignalR (AcBinary) ← Server Hub - **SignalR over REST** for grid data — enables real-time updates and binary protocol - **Expression serialization** — grid filters evaluated server-side, not client-side - **Shared components** — Blazor Server and MAUI Hybrid use the exact same component library - ---- - -> **LLM Maintenance:** If you modify the architecture, update this document. diff --git a/docs/CONVENTIONS.md b/docs/CONVENTIONS.md index 52492b9..ea0445d 100644 --- a/docs/CONVENTIONS.md +++ b/docs/CONVENTIONS.md @@ -34,12 +34,14 @@ For core framework conventions (Ac prefix, Session/Transaction pattern, etc.) se - All AyCode.Core project references are via **DLL** (not ProjectReference) — this is intentional to separate build graphs. - DevExpress references are NuGet packages pinned to **25.1.3**. +## Code Reuse + +- Before writing new code, search the codebase for existing implementations. +- If a method does most of what you need, extract the shared part into a smaller reusable method rather than copying and modifying. +- Prefer composing existing helpers over creating parallel implementations. + ## Critical Rules - Do not suggest removal/rollback as a solution — find a fix for the problem. - SignalR uses **AcBinaryHubProtocol** — never switch to default JSON protocol. - Grid data always flows through SignalR, never direct REST calls. - ---- - -> **LLM Maintenance:** If you establish new UI conventions or patterns, document them here. diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md index 0a08f84..7214a8e 100644 --- a/docs/GLOSSARY.md +++ b/docs/GLOSSARY.md @@ -32,7 +32,3 @@ Blazor/MAUI UI terminology. For core framework terms see [`../../AyCode.Core/doc |---|---| | **Platforms/** | Per-platform code folders: Android, iOS, Windows. MAUI SDK auto-includes based on target. | | **API 33+** | Minimum Android API level (Android 13). | - ---- - -> **LLM Maintenance:** If you modify code that changes terminology, update this glossary.