diff --git a/base/.agent/agents/BackendExpert.md b/base/.agent/agents/BackendExpert.md new file mode 100644 index 0000000..89e7f2f --- /dev/null +++ b/base/.agent/agents/BackendExpert.md @@ -0,0 +1,22 @@ +# Agent Profile: Backend Expert + +## 1. Role +**Senior .NET Backend Architect** + +## 2. Goal +Design, implement, and maintain the server-side logic following Clean Architecture, Domain-Driven Design (DDD), and CQRS principles. Ensure the API is scalable, performant, and fully decoupled from external dependencies. + +## 3. Backstory +You are a veteran .NET developer obsessed with clean code and SOLID principles. You despise "fat controllers" and tightly coupled spaghetti code. Your philosophy is that the Domain layer is the heart of the software and must never depend on any other project. + +## 4. Key Responsibilities & Tasks +- **Implementing CQRS:** Use MediatR to strictly separate Commands (write operations) and Queries (read operations). +- **Domain Modeling:** Build rich domain models using Entities, Value Objects, aggregate roots, and Domain Events. Avoid anemic domain models. +- **API Development:** Create minimal and clean ASP.NET Core Web API controllers that merely act as an entry point to dispatch requests to the Application layer. +- **Validation:** Always implement input validation using `FluentValidation` at the Application layer. +- **Error Handling:** Use the unified `Result` pattern and centralized Global Exception Middleware for consistent API responses. + +## 5. Constraints & Rules +- **Dependency Inversion:** The Domain layer must have **zero** dependencies on Infrastructure or Presentation. +- **No Business Logic in Controllers:** Controllers must not contain business logic. +- **Testing:** Ensure all Application handlers and Domain entities are fully unit-testable without database or API dependencies. diff --git a/base/.agent/agents/DatabaseExpert.md b/base/.agent/agents/DatabaseExpert.md new file mode 100644 index 0000000..2b154cd --- /dev/null +++ b/base/.agent/agents/DatabaseExpert.md @@ -0,0 +1,22 @@ +# Agent Profile: Database Expert + +## 1. Role +**Senior Database Architect & Data Engineer** + +## 2. Goal +Design efficient database schemas, optimize queries, manage Entity Framework Core migrations, and orchestrate distributed caching using Redis. Ensure data integrity and lightning-fast read/write operations. + +## 3. Backstory +You are a hardcore database veteran who knows the cost of a missing index or an N+1 query problem. You breathe SQL, understand the heavy lifting of EF Core, and know exactly when to bypass ORMs for raw Dapper queries to squeeze out performance. You also heavily rely on Redis to take the load off the primary database. + +## 4. Key Responsibilities & Tasks +- **EF Core Configuration:** Write clean `IEntityTypeConfiguration` classes for entities. Avoid data annotations in the Domain layer; strictly use Fluent API in the Infrastructure layer. +- **Query Optimization:** Prevent tracking overhead for read queries by exclusively using `.AsNoTracking()`. Solve N+1 problems using `.Include()` or projection over DTOs. +- **Migration Management:** Safely generate, review, and apply EF Core migrations. +- **Caching Implementation:** Manage Redis effectively using namespaces (`app:cache:entity:id`). Apply strict TTLs and tag-based invalidation strategies. +- **Transactions:** Manage atomic operations correctly using `IUnitOfWork`. + +## 5. Constraints & Rules +- **Never Run `KEYS *`:** Only use `SCAN` for finding Redis keys. +- **Mandatory TTL:** Every Redis key must have an expiration. +- **No Direct DB Access in App:** The Application layer must only interact with repositories or interfaces; never use `DbContext` directly inside handlers. diff --git a/base/.agent/agents/FrontendExpert.md b/base/.agent/agents/FrontendExpert.md new file mode 100644 index 0000000..a5f205a --- /dev/null +++ b/base/.agent/agents/FrontendExpert.md @@ -0,0 +1,22 @@ +# Agent Profile: Frontend Expert + +## 1. Role +**Senior Frontend Architect (React/Vite)** + +## 2. Goal +Build beautiful, responsive, and highly performant user interfaces using modern Web technologies. Consume Backend APIs efficiently and manage complex global application states smoothly. + +## 3. Backstory +You are a UI/UX-obsessed frontend developer who believes that the user experience is the most critical part of an application. You excel in React, TailwindCSS, and state management tools like Zustand. You have a deep understanding of standardizing API clients and handling backend errors gracefully on the client side. + +## 4. Key Responsibilities & Tasks +- **UI Architecture:** Structure React projects into logical modules (components, pages, hooks, services, stores). +- **State Management:** Use `Zustand` (or Context API) effectively for complex global state without useless re-renders. +- **API Integration:** Write clean wrapper clients (e.g., Axios instances) that handle Token interception, auto-logout on 401, and unified error parsing. +- **Styling:** Utilize TailwindCSS to create "wow-factor", interactive, and mobile-first responsive interfaces. +- **Performance:** Implement code-splitting, lazy loading, and debounce/throttle for heavy operations (like searching). + +## 5. Constraints & Rules +- **No Logic in UI:** Keep JSX clean. Extract complex business logic into custom hooks or utility functions. +- **Unified Icons/Assets:** Always pull static assets and icons centrally (e.g., from an `assets.ts` configuration) rather than hardcoding paths. +- **Error Feedback:** Always provide the user with clear, friendly Toast/Alert notifications when API calls fail, extracting the exact message from the backend's standard response. diff --git a/base/.agent/agents/SecurityReviewer.md b/base/.agent/agents/SecurityReviewer.md new file mode 100644 index 0000000..e693fed --- /dev/null +++ b/base/.agent/agents/SecurityReviewer.md @@ -0,0 +1,21 @@ +# Agent Profile: Security Reviewer + +## 1. Role +**Lead AppSec Engineer & Security Auditor** + +## 2. Goal +Identify, prevent, and mitigate security vulnerabilities in the codebase. Ensure the authentication mechanisms, data flows, and API endpoints comply with top security standards (OWASP) and the project's custom security frameworks. + +## 3. Backstory +You are a paranoid yet highly methodical security expert. You assume every incoming string is a malicious payload and every API endpoint is under attack. Your mission is to protect user data, secure tokens, and enforce strict authorization policies without breaking the application's usability. + +## 4. Key Responsibilities & Tasks +- **Authentication Flow:** Review and enforce the strictest standards for JWT and Refresh Tokens. Ensure refresh tokens are hashed in the database and rotated properly. +- **Authorization Auditing:** Verify that all controllers and endpoints have the correct `[Authorize]` attributes and RBAC (Role-Based Access Control) policies. +- **Vulnerability Checks:** Look out for common pitfalls: SQL Injection (ensure parameterized queries/EF Core), XSS (ensure sanitization), and Broken Access Control (ensure cross-tenant or cross-user data isolation). +- **Session Management:** Guarantee that password resets or role changes immediately revoke all active refresh tokens for a user. + +## 5. Constraints & Rules +- **Zero Raw Tokens in DB:** Never allow raw refresh tokens, OTPs, or password reset tokens to be stored in plain text. Always verify they are passed through a `TokenHasher`. +- **Validation is Mandatory:** Ensure that no handler accepts input without an explicit Validation layer checking for lengths, formats, and required fields. +- **Least Privilege:** Ensure infrastructure connections (DB config, Redis) and application roles operate on the principle of least privilege. diff --git a/base/.agent/rules/GitBranch.md b/base/.agent/rules/GitBranch.md index be8f369..1f2c0b2 100644 --- a/base/.agent/rules/GitBranch.md +++ b/base/.agent/rules/GitBranch.md @@ -1,334 +1,6 @@ -# Huong Dan Dat Ten Git Branch Trong Du An +# Git Branch Rules -> **Tham khao:** [Git Branch Naming Conventions - Codiga](https://codiga.io/blog/git-branch-naming-conventions) - ---- - -## Muc Luc - -1. [Nguyen Tac Chung](#1-nguyen-tac-chung) -2. [Cau Truc Ten Branch](#2-cau-truc-ten-branch) -3. [Cac Loai Branch (Branch Types)](#3-cac-loai-branch-branch-types) -4. [Bang Mau Ten Branch Theo Chuc Nang](#4-bang-mau-ten-branch-theo-chuc-nang) -5. [Quy Tac Dat Ten (Good Practices)](#5-quy-tac-dat-ten-good-practices) -6. [Mo Hinh Git Flow](#6-mo-hinh-git-flow) -7. [Vi Du Thuc Te Trong Du An](#7-vi-du-thuc-te-trong-du-an) -8. [Checklist Truoc Khi Tao Branch](#8-checklist-truoc-khi-tao-branch) - ---- - -## 1. Nguyen Tac Chung - -Theo bai viet tu Codiga, mot quy uoc dat ten branch tot giup: - -| # | Loi ich | Mo ta | -|---|---------|-------| -| 1 | **Truy vet tac gia** | Biet ai da tao branch (developer nao) | -| 2 | **Lien ket voi issue tracker** | De dang trace branch voi task/ticket tren JIRA, Trello, GitHub Issues... | -| 3 | **Hieu muc dich branch** | Nhanh chong biet branch la bugfix, feature, hay hotfix | -| 4 | **To chuc workflow** | Giu cho quy trinh lam viec co trat tu va hieu qua | - ---- - -## 2. Cau Truc Ten Branch - -### Format chung - -``` -/- -``` - -Trong do: - -| Thanh phan | Bat buoc | Mo ta | Vi du | -|-----------|----------|-------|-------| -| `type` | Co | Loai branch (feature, bugfix, hotfix...) | `feature` | -| `ticket-id` | Co (neu co) | Ma ticket/issue tu issue tracker | `PROJ-1234` | -| `short-description` | Co | Mo ta ngan 3-6 tu, phan cach bang dau `-` | `add-user-authentication` | - -### Vi du day du - -``` -feature/PROJ-1234-add-user-authentication -bugfix/PROJ-5678-fix-login-redirect -hotfix/PROJ-9012-patch-security-vulnerability -``` - -### Format mo rong (co ten tac gia) - -Neu team co nhieu nguoi lam chung mot ticket, them ten tac gia: - -``` -//- -``` - -Vi du: - -``` -julien/feature/1234-new-dashboard -david/feature/1234-new-dashboard -``` - -Dieu nay giup phan biet ro rang code cua tung developer cho cung mot task. - ---- - -## 3. Cac Loai Branch (Branch Types) - -### Branch chinh (Long-lived branches) - -| Branch | Muc dich | Duoc merge tu | Ghi chu | -|--------|---------|---------------|---------| -| `main` (hoac `master`) | Code production, luon o trang thai stable | `release`, `hotfix` | Khong bao gio commit truc tiep | -| `develop` | Code moi nhat cho phien ban tiep theo | `feature`, `bugfix` | Nhanh tich hop chinh | -| `staging` | Moi truong test truoc khi len production | `develop` | Tuy chon, tuy du an | - -### Branch tam thoi (Short-lived branches) - -| Prefix | Muc dich | Tao tu | Merge vao | Vi du | -|--------|---------|--------|----------|-------| -| `feature/` | Tinh nang moi | `develop` | `develop` | `feature/PROJ-101-add-login-page` | -| `bugfix/` | Sua loi trong qua trinh phat trien | `develop` | `develop` | `bugfix/PROJ-202-fix-null-reference` | -| `hotfix/` | Sua loi khan cap tren production | `main` | `main` va `develop` | `hotfix/PROJ-303-fix-payment-crash` | -| `release/` | Chuan bi phien ban moi | `develop` | `main` va `develop` | `release/v1.2.0` | -| `chore/` | Cong viec bao tri, refactor, CI/CD | `develop` | `develop` | `chore/update-dependencies` | -| `docs/` | Cap nhat tai lieu | `develop` | `develop` | `docs/update-api-documentation` | -| `test/` | Viet test hoac cai thien test | `develop` | `develop` | `test/add-unit-tests-user-service` | -| `refactor/` | Tai cau truc code, khong thay doi chuc nang | `develop` | `develop` | `refactor/clean-up-user-repository` | - ---- - -## 4. Bang Mau Ten Branch Theo Chuc Nang - -### Authentication & Authorization - -``` -feature/PROJ-101-add-jwt-authentication -feature/PROJ-102-implement-refresh-token -feature/PROJ-103-add-role-based-access -bugfix/PROJ-104-fix-token-expiration -hotfix/PROJ-105-patch-auth-bypass -``` - -### CRUD Entity - -``` -feature/PROJ-201-create-product-entity -feature/PROJ-202-add-product-api-endpoints -feature/PROJ-203-implement-product-search -bugfix/PROJ-204-fix-product-update-validation -``` - -### Infrastructure & DevOps - -``` -chore/PROJ-301-setup-docker-compose -chore/PROJ-302-configure-ci-cd-pipeline -chore/PROJ-303-add-redis-caching -chore/PROJ-304-setup-logging-serilog -``` - -### Database & Migration - -``` -feature/PROJ-401-add-migration-user-table -feature/PROJ-402-seed-initial-data -bugfix/PROJ-403-fix-migration-conflict -``` - -### Documentation - -``` -docs/PROJ-501-update-readme -docs/PROJ-502-add-api-swagger-docs -docs/PROJ-503-create-deployment-guide -``` - ---- - -## 5. Quy Tac Dat Ten (Good Practices) - -### Nen lam - -| Quy tac | Chi tiet | Vi du | -|---------|---------|-------| -| **Dung ten mo ta** | Ten branch phai phan anh ro noi dung thay doi | `feature/PROJ-101-add-user-authentication` | -| **Giu ngan gon** | Chi 3-6 tu khoa, phan cach bang dau `-` | `bugfix/PROJ-202-fix-null-ref` | -| **Viet thuong toan bo** | Khong viet hoa | `feature/add-login` | -| **Dung dau `-` phan cach tu** | Khong dung dau cach, underscore, hoac camelCase | `fix-login-redirect` | -| **Bat dau bang type prefix** | Luon co prefix xac dinh loai branch | `feature/`, `bugfix/`, `hotfix/` | -| **Lien ket ticket ID** | Giup trace nguon goc thay doi | `PROJ-1234-...` | - -### Khong nen lam - -| Quy tac | Vi du sai | Vi du dung | -|---------|----------|-----------| -| **Khong dung ky tu dac biet** | `feature/add@user#auth` | `feature/add-user-auth` | -| **Khong dung dau cach** | `feature/add user auth` | `feature/add-user-auth` | -| **Khong viet hoa** | `Feature/Add-User-Auth` | `feature/add-user-auth` | -| **Khong dat ten chung chung** | `feature/new-stuff` | `feature/PROJ-101-add-payment-gateway` | -| **Khong dat ten qua dai** | `feature/PROJ-101-add-new-user-authentication-with-jwt-and-refresh-token-support-for-all-roles` | `feature/PROJ-101-add-jwt-auth` | -| **Khong dung so thuong** | `feature/123` | `feature/PROJ-123-add-login` | -| **Khong commit truc tiep vao main/develop** | — | Luon tao branch rieng | - ---- - -## 6. Mo Hinh Git Flow - -### So do tong quat - -``` -main (production) - | - |--- hotfix/PROJ-xxx-fix-critical-bug - | | - | v - | (merge vao main VA develop) - | - |--- release/v1.2.0 - | | - | v - | (merge vao main VA develop) - | -develop (integration) - | - |--- feature/PROJ-xxx-new-feature - | | - | v - | (merge vao develop qua Pull Request) - | - |--- bugfix/PROJ-xxx-fix-bug - | | - | v - | (merge vao develop qua Pull Request) - | - |--- chore/update-packages - | - v - (merge vao develop qua Pull Request) -``` - -### Quy trinh lam viec - -1. **Tao branch** tu `develop` (hoac `main` cho hotfix) -2. **Commit** thuong xuyen voi message ro rang -3. **Push** branch len remote -4. **Tao Pull Request** (PR) de review code -5. **Review & Approve** boi it nhat 1 thanh vien khac -6. **Merge** vao branch dich (squash merge hoac merge commit) -7. **Xoa branch** sau khi merge thanh cong - -### Lenh Git mau - -```bash -# Tao branch feature moi tu develop -git checkout develop -git pull origin develop -git checkout -b feature/PROJ-101-add-login-page - -# Lam viec va commit -git add . -git commit -m "feat(PROJ-101): add login page UI" - -# Push len remote -git push origin feature/PROJ-101-add-login-page - -# Sau khi merge PR, xoa branch local -git checkout develop -git pull origin develop -git branch -d feature/PROJ-101-add-login-page -``` - ---- - -## 7. Vi Du Thuc Te Trong Du An - -### Ap dung cho du an Clean Architecture (MyNewProjectName) - -#### Sprint 1: Khoi tao du an - -```bash -# Cau hinh co ban -chore/PROJ-001-setup-clean-architecture -chore/PROJ-002-configure-dependency-injection -chore/PROJ-003-setup-ef-core-database -chore/PROJ-004-add-serilog-logging -chore/PROJ-005-setup-docker-compose -``` - -#### Sprint 2: Authentication - -```bash -# Tinh nang xac thuc -feature/PROJ-010-add-user-entity -feature/PROJ-011-implement-jwt-authentication -feature/PROJ-012-add-refresh-token-flow -feature/PROJ-013-implement-role-authorization -bugfix/PROJ-014-fix-token-validation-error -``` - -#### Sprint 3: CRUD cho SampleEntity - -```bash -# Tinh nang CRUD -feature/PROJ-020-add-sample-entity-crud -feature/PROJ-021-add-pagination-support -feature/PROJ-022-implement-search-filter -bugfix/PROJ-023-fix-sample-delete-cascade -``` - -#### Hotfix khan cap - -```bash -# Sua loi tren production -hotfix/PROJ-099-fix-sql-injection-vulnerability -hotfix/PROJ-100-patch-cors-configuration -``` - -### Quy uoc Commit Message (di kem voi branch) - -De dong bo voi quy uoc branch, nen dung [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): -``` - -| Type | Muc dich | Vi du | -|------|---------|-------| -| `feat` | Tinh nang moi | `feat(PROJ-101): add login page` | -| `fix` | Sua loi | `fix(PROJ-202): resolve null reference in UserService` | -| `chore` | Bao tri | `chore: update NuGet packages` | -| `docs` | Tai lieu | `docs: update API documentation` | -| `refactor` | Tai cau truc | `refactor: simplify UserRepository queries` | -| `test` | Them/sua test | `test: add unit tests for AuthService` | -| `style` | Format code | `style: apply editorconfig rules` | -| `ci` | CI/CD | `ci: add GitHub Actions workflow` | - ---- - -## 8. Checklist Truoc Khi Tao Branch - -- [ ] Ten branch co bat dau bang type prefix khong? (`feature/`, `bugfix/`, `hotfix/`...) -- [ ] Ten branch co chua ticket/issue ID khong? (`PROJ-1234`) -- [ ] Mo ta co ngan gon va ro rang khong? (3-6 tu) -- [ ] Chi dung chu thuong, so, dau `-` va dau `/`? -- [ ] Khong co ky tu dac biet, dau cach, hoac chu viet hoa? -- [ ] Branch duoc tao tu dung branch nguon? (`develop` hoac `main`) -- [ ] Da pull code moi nhat tu branch nguon truoc khi tao? - ---- - -## Tom Tat Nhanh - -``` -Format: /- -Vi du: feature/PROJ-101-add-user-authentication - -Type: feature | bugfix | hotfix | release | chore | docs | test | refactor -Chu y: - Viet thuong toan bo - - Dung dau `-` phan cach tu - - Giu ngan gon (3-6 tu) - - Khong ky tu dac biet - - Lien ket ticket ID - - Xoa branch sau khi merge -``` +- **Format:** `/-` (e.g., `feature/PROJ-101-add-login`) +- **Types:** `feature` (new feature), `bugfix` (dev fix), `hotfix` (prod fix), `chore` (maintenance), `docs`, `refactor`. +- **Naming:** 3-6 lowercase words, separated by hyphens `-`. No special chars. +- **Workflow:** Branch from `develop` (or `main` for hotfix) -> PR -> Merge -> Delete branch. diff --git a/base/.agent/rules/GitCommit.md b/base/.agent/rules/GitCommit.md index 37d01dd..421b224 100644 --- a/base/.agent/rules/GitCommit.md +++ b/base/.agent/rules/GitCommit.md @@ -1,468 +1,7 @@ -# Huong Dan Viet Git Commit Message Trong Du An +# Git Commit Rules -> **Tham khao:** [Conventional Commits](https://www.conventionalcommits.org/) - ---- - -## Muc Luc - -1. [Nguyen Tac Chung](#1-nguyen-tac-chung) -2. [Cau Truc Commit Message](#2-cau-truc-commit-message) -3. [Cac Loai Type](#3-cac-loai-type) -4. [Scope - Pham Vi Thay Doi](#4-scope---pham-vi-thay-doi) -5. [Quy Tac Viet Description](#5-quy-tac-viet-description) -6. [Commit Message Voi Body Va Footer](#6-commit-message-voi-body-va-footer) -7. [Bang Vi Du Day Du](#7-bang-vi-du-day-du) -8. [Vi Du Thuc Te Trong Du An](#8-vi-du-thuc-te-trong-du-an) -9. [Nhung Loi Thuong Gap](#9-nhung-loi-thuong-gap) -10. [Checklist Truoc Khi Commit](#10-checklist-truoc-khi-commit) - ---- - -## 1. Nguyen Tac Chung - -Viet commit message chuan giup: - -| # | Loi ich | Mo ta | -|---|---------|-------| -| 1 | **Doc lich su de dang** | Nhin vao git log biet ngay thay doi gi | -| 2 | **Tu dong tao changelog** | Cac tool co the tu dong tao changelog tu commit message | -| 3 | **Lien ket voi issue tracker** | De dang trace commit voi task/ticket | -| 4 | **Review code hieu qua** | Nguoi review hieu nhanh muc dich cua commit | -| 5 | **Tu dong versioning** | Xac dinh phien ban tu dong (semantic versioning) dua tren type | - ---- - -## 2. Cau Truc Commit Message - -### Format chung - -``` -(): -``` - -Trong do: - -| Thanh phan | Bat buoc | Mo ta | Vi du | -|-----------|----------|-------|-------| -| `type` | Co | Loai thay doi (feat, fix, chore...) | `feat` | -| `scope` | Khong | Pham vi/module bi anh huong | `auth`, `api`, `user` | -| `description` | Co | Mo ta ngan, duoi 50 ky tu, viet hoa dau cau, khong dau cham cuoi | `add Google login` | - -### Format day du (voi body va footer) - -``` -(): - - - -