84 lines
4.3 KiB
Markdown
84 lines
4.3 KiB
Markdown
# AGENTS.md
|
|
|
|
> **CRITICAL INSTRUCTION FOR AI AGENTS:** > This project uses a specific hybrid architecture: ASP.NET Core MVC with Quasar Framework (UMD/CDN version).
|
|
> You MUST follow the "Frontend Constraints" section below strictly. Failure to do so will break the HTML parsing.
|
|
|
|
## 1. Project Overview
|
|
* **Type:** Multi-platform Web Application
|
|
* **Backend:** ASP.NET Core MVC (C#)
|
|
* **Frontend:** Quasar Framework (UMD Version) on top of Razor Views
|
|
* **Database:** Entity Framework Core
|
|
* **Real-time:** Native WebSockets (or SignalR, per specific task requirements)
|
|
|
|
## 2. Tech Stack & Architecture
|
|
|
|
### Backend (C# / .NET)
|
|
* **Framework:** ASP.NET Core (Latest Stable)
|
|
* **Pattern:** MVC (Model-View-Controller)
|
|
* **Database:** Entity Framework Core (Code-First or DbFirst usually, check `DbContext`).
|
|
* **Real-time:** WebSockets are used for bi-directional communication.
|
|
* *Agent Note:* If implementing a chat or live feed, prefer `Microsoft.AspNetCore.SignalR` unless raw `System.Net.WebSockets` is explicitly requested.
|
|
|
|
### Frontend (Quasar UMD + Razor)
|
|
* **Library:** Vue.js 3 + Quasar Framework (UMD/CDN).
|
|
* **Integration:**
|
|
* Vue/Quasar is loaded via `<script>` tags in the `_Layout.cshtml` (Layout Page).
|
|
* The Vue app is mounted to a `#q-app` div which wraps the `@RenderBody()`.
|
|
* Razor views (`.cshtml`) contain raw HTML combined with Quasar components (e.g., `<q-btn>`).
|
|
* **NO Build Step:** There is no webpack/vite build step for the frontend. We are using raw JavaScript in `wwwroot/js`.
|
|
|
|
## 3. CRITICAL Frontend Constraints (The "UMD Rule")
|
|
**You must strictly adhere to these rules when generating Razor views or JavaScript:**
|
|
|
|
1. **NO Self-Closing Tags for Components:**
|
|
* The UMD version of Vue runs directly in the DOM (in-DOM templates). Browsers generally do not support self-closing tags for custom elements.
|
|
* ❌ **WRONG:** `<q-input v-model="text" />`
|
|
* ✅ **CORRECT:** `<q-input v-model="text"></q-input>`
|
|
* ✅ **CORRECT:** `<q-btn label="Save"></q-btn>`
|
|
* *Always* use an explicit closing tag for all Quasar components (`<q-card>`, `<q-icon>`, etc.).
|
|
|
|
2. **Kebab-case for Props:**
|
|
* In-DOM templates are case-insensitive. You must use kebab-case for component props.
|
|
* ❌ **WRONG:** `<q-btn flat round icon="menu" @click="toggleLeftDrawer" />` (Mixed issues)
|
|
* ✅ **CORRECT:** `<q-btn flat round icon="menu" @click="toggleLeftDrawer"></q-btn>`
|
|
|
|
3. **PascalCase usage:**
|
|
* Do NOT use PascalCase for component names in the HTML. Use kebab-case.
|
|
* ❌ **WRONG:** `<QBtn label="Click"></QBtn>`
|
|
* ✅ **CORRECT:** `<q-btn label="Click"></q-btn>`
|
|
|
|
## 4. Code Style & Structure
|
|
|
|
### Directory Structure
|
|
* `Controllers/`: C# MVC Controllers.
|
|
* `Views/Shared/_Layout.cshtml`: The master page containing the Quasar/Vue CDN links, the `#q-app` wrapper, and the main `new Vue({ ... })` initialization script.
|
|
* `Views/`: Razor views containing the UI templates.
|
|
* `wwwroot/js/`: Client-side logic.
|
|
* If creating a new page functionality, consider creating a dedicated `.js` file or a `<script>` section at the bottom of the View using `@section Scripts`.
|
|
|
|
### Database (Entity Framework)
|
|
* Use `Async/Await` for all DB operations.
|
|
* Ensure a `DbContext` is injected into controllers.
|
|
* If creating new Entities, update the `DbContext` and suggest a Migration command.
|
|
|
|
### WebSockets
|
|
* WebSocket logic should handle connection, sending, and receiving messages asynchronously.
|
|
* Ensure the `ws://` or `wss://` URI is dynamically constructed based on the `window.location`.
|
|
|
|
## 5. Standard Task Workflows
|
|
|
|
### When asked to "Create a new Page":
|
|
1. Create a Controller Action in C# (e.g., `public IActionResult Index()`).
|
|
2. Create a View (`Index.cshtml`).
|
|
3. In the View, write the HTML using Quasar components. **REMEMBER: `<tag></tag>`, never `<tag/>`.**
|
|
4. If logic is needed, add a `<script>` block that pushes data or methods into the global Vue app instance or a local component definition.
|
|
|
|
### When asked to "Add a Grid/Table":
|
|
1. Use `<q-table>`.
|
|
2. Define the `columns` and `rows` arrays in the JavaScript `data()` section.
|
|
3. Ensure `<q-table></q-table>` is closed properly.
|
|
|
|
## 6. Common Commands
|
|
* **Run App:** `dotnet run` or `dotnet watch run`
|
|
* **Add Package:** `dotnet add package [PackageName]`
|
|
* **Migrations:** `dotnet ef migrations add [Name]` -> `dotnet ef database update` |