{"owner":"abpframework","repo":"abp","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":[".cursorrules",".github/copilot-instructions.md"],"skills":{".cursorrules":"# ABP Framework – Cursor Rules\n# Scope: ABP Framework repository (abpframework/abp) — for developing ABP itself, not ABP-based applications.\n# Goal: Enforce ABP module architecture best practices (DDD, layering, DB/ORM independence),\n# maintain backward compatibility, ensure extensibility, and align with ABP contribution guidelines.\n\n## Global Defaults\n- Follow existing patterns in this repository first. Before generating new code, search for similar implementations and mirror their structure, naming, and conventions.\n- Prefer minimal, focused diffs. Avoid drive-by refactors and formatting churn.\n- Preserve public APIs. Avoid breaking changes unless explicitly requested and justified.\n- Keep layers clean. Do not introduce forbidden dependencies between packages.\n\n## Module / Package Architecture (Layering)\n- Use a layered module structure with explicit dependencies:\n  - *.Domain.Shared: constants, enums, shared types safe for all layers and 3rd-party clients. MUST NOT contain entities, repositories, domain services, or business objects.\n  - *.Domain: entities/aggregate roots, repository interfaces, domain services.\n  - *.Application.Contracts: application service interfaces and DTOs.\n  - *.Application: application service implementations.\n  - *.EntityFrameworkCore / *.MongoDb: ORM integration packages depend on *.Domain only. MUST NOT depend on other layers.\n  - *.HttpApi: REST controllers. MUST depend ONLY on *.Application.Contracts (NOT *.Application).\n  - *.HttpApi.Client: remote client proxies. MUST depend ONLY on *.Application.Contracts.\n  - *.Web: UI. MUST depend ONLY on *.HttpApi.\n- Enforce dependency direction:\n  - Web -> HttpApi -> Application.Contracts\n  - Application -> Domain + Application.Contracts\n  - Domain -> Domain.Shared\n  - ORM integration -> Domain\n- Do not leak web concerns into application/domain.\n\n## Domain Layer – Entities & Aggregate Roots\n- Define entities in the domain layer.\n- Entities must be valid at creation:\n  - Provide a primary constructor that enforces invariants.\n  - Always include a protected parameterless constructor for ORMs.\n  - Always initialize sub-collections in the primary constructor.\n  - Do NOT generate Guid keys inside constructors; accept `id` and generate using `IGuidGenerator` from the calling code.\n- Make members `virtual` where appropriate (ORM/proxy compatibility).\n- Protect consistency:\n  - Use non-public setters (private/protected/internal) when needed.\n  - Provide meaningful domain methods for state transitions; prefer returning `this` from setters when applicable.\n- Aggregate roots:\n  - Always use a single `Id` property. Do NOT use composite keys.\n  - Prefer `Guid` keys for aggregate roots.\n  - Inherit from `AggregateRoot<TKey>` or audited base classes as required.\n- Aggregate boundaries:\n  - Keep aggregates small. Avoid large sub-collections unless necessary.\n- References:\n  - Reference other aggregate roots by Id only.\n  - Do NOT add navigation properties to other aggregate roots.\n\n## Repositories\n- Define repository interfaces in the domain layer.\n- Create one dedicated repository interface per aggregate root (e.g., `IProductRepository`).\n- Public repository interfaces exposed by modules:\n  - SHOULD inherit from `IBasicRepository<TEntity, TKey>` (or `IReadOnlyRepository<...>` when suitable).\n  - SHOULD NOT expose `IQueryable` in the public contract.\n  - Internal implementations MAY use `IRepository<TEntity, TKey>` and `IQueryable` as needed.\n- Do NOT define repositories for non-aggregate-root entities.\n- Repository method conventions:\n  - All methods async.\n  - Include optional `CancellationToken cancellationToken = default` in every method.\n  - For single-entity returning methods: include `bool includeDetails = true`.\n  - For list returning methods: include `bool includeDetails = false`.\n  - Do NOT return composite projection classes like `UserWithRoles`. Use `includeDetails` for eager-loading.\n  - Avoid projection-only view models from repositories by default; only allow when performance is critical.\n\n## Domain Services\n- Define domain services in the domain layer.\n- Default: do NOT create interfaces for domain services unless necessary (mocking/multiple implementations).\n- Naming: use `*Manager` suffix.\n- Domain service methods:\n  - Focus on operations that enforce domain invariants and business rules.\n  - Query methods are acceptable when they encapsulate domain-specific lookup logic (e.g., normalized lookups, caching, complex resolution). Simple queries belong in repositories.\n  - Define methods that mutate state and enforce domain rules.\n  - Use specific, intention-revealing names (avoid generic `UpdateXAsync`).\n  - Accept valid domain objects as parameters; do NOT accept/return DTOs.\n  - On rule violations, throw `BusinessException` (or custom business exceptions).\n  - Use unique, namespaced error codes suitable for localization (e.g., `IssueTracking:ConcurrentOpenIssueLimit`).\n  - Do NOT depend on authenticated user logic; pass required values from application layer.\n\n## Application Services (Contracts + Implementation)\n### Contracts\n- Define one interface per application service in *.Application.Contracts.\n- Interfaces must inherit from `IApplicationService`.\n- Naming: `I*AppService`.\n- Do NOT accept/return entities. Use DTOs and primitive parameters.\n\n### Method Naming & Shapes\n- All service methods async and end with `Async`.\n- Do not repeat entity names in method names (use `GetAsync`, not `GetProductAsync`).\n- Standard CRUD:\n  - `GetAsync(Guid id)` returns a detailed DTO.\n  - `GetListAsync(QueryDto queryDto)` returns a list of detailed DTOs.\n  - `CreateAsync(CreateDto dto)` returns detailed DTO.\n  - `UpdateAsync(Guid id, UpdateDto dto)` returns detailed DTO (id MUST NOT be inside update DTO).\n  - `DeleteAsync(Guid id)` returns void/Task.\n- `GetListAsync` query DTO:\n  - Filtering/sorting/paging fields optional with defaults.\n  - Enforce a maximum page size for performance.\n\n### DTO Usage\n- Inputs:\n  - Do not include unused properties.\n  - Do NOT share input DTOs between methods.\n  - Do NOT use inheritance between input DTOs (except rare abstract base DTO cases; be very cautious).\n\n### Implementation\n- Application layer must be independent of web.\n- Implement interfaces in *.Application, name `ProductAppService` for `IProductAppService`.\n- Inherit from `ApplicationService`.\n- Make all public methods `virtual`.\n- Avoid private helper methods; prefer `protected virtual` helpers for extensibility.\n- Data access:\n  - Use dedicated repositories (e.g., `IProductRepository`).\n  - Do NOT use generic repositories.\n  - Do NOT put LINQ/SQL queries inside application service methods; repositories perform queries.\n- Entity mutation:\n  - Load required entities from repositories.\n  - Mutate using domain methods.\n  - Call repository `UpdateAsync` after updates (do not assume change tracking).\n- Extra properties:\n  - Use `MapExtraPropertiesTo` or configure object mapper for `MapExtraProperties`.\n- Files:\n  - Do NOT use web types like `IFormFile` or `Stream` in application services.\n  - Controllers handle upload; pass `byte[]` (or similar) to application services.\n- Cross-application-service calls:\n  - Do NOT call other application services within the same module.\n  - For reuse, push logic into domain layer or extract shared helpers carefully.\n  - You MAY call other modules’ application services only via their Application.Contracts.\n\n## DTO Conventions\n- Define DTOs in *.Application.Contracts.\n- Prefer ABP base DTO types (`EntityDto<TKey>`, audited DTOs).\n- For aggregate roots, prefer extensible DTO base types so extra properties can map.\n- DTO properties: public getters/setters.\n- Input DTO validation:\n  - Use data annotations.\n  - Reuse constants from Domain.Shared wherever possible.\n- Avoid logic in DTOs; only implement `IValidatableObject` when necessary.\n- Do NOT use `[Serializable]` attribute (BinaryFormatter is obsolete); ABP uses JSON serialization.\n- Output DTO strategy:\n  - Prefer a Basic DTO and a Detailed DTO; avoid many variants.\n  - Detailed DTOs: include reference details as nested basic DTOs; avoid duplicating raw FK ids unnecessarily.\n\n## EF Core Integration\n- Define a separate DbContext interface + class per module.\n- Do NOT rely on lazy loading; do NOT enable lazy loading.\n- DbContext interface:\n  - Inherit from `IEfCoreDbContext`.\n  - Add `[ConnectionStringName(\"...\")]`.\n  - Expose `DbSet<TEntity>` ONLY for aggregate roots.\n  - Do NOT include setters in the interface.\n- DbContext class:\n  - Inherit `AbpDbContext<TDbContext>`.\n  - Add `[ConnectionStringName(\"...\")]` and implement the interface.\n- Table prefix/schema:\n  - Provide static `TablePrefix` and `Schema` defaulted from constants.\n  - Use short prefixes; `Abp` prefix reserved for ABP core modules.\n  - Default schema should be `null`.\n- Model mapping:\n  - Do NOT configure entities directly inside `OnModelCreating`.\n  - Create `ModelBuilder` extension method `ConfigureX()` and call it.\n  - Call `b.ConfigureByConvention()` for each entity.\n- Repository implementations:\n  - Inherit from `EfCoreRepository<TDbContextInterface, TEntity, TKey>`.\n  - Use DbContext interface as generic parameter.\n  - Pass cancellation tokens using `GetCancellationToken(cancellationToken)`.\n  - Implement `IncludeDetails(include)` extension per aggregate root with sub-collections.\n  - Override `WithDetailsAsync()` where needed.\n\n## MongoDB Integration\n- Define a separate MongoDbContext interface + class per module.\n- MongoDbContext interface:\n  - Inherit from `IAbpMongoDbContext`.\n  - Add `[ConnectionStringName(\"...\")]`.\n  - Expose `IMongoCollection<TEntity>` ONLY for aggregate roots.\n- MongoDbContext class:\n  - Inherit `AbpMongoDbContext` and implement the interface.\n- Collection prefix:\n  - Provide static `CollectionPrefix` defaulted from constants.\n  - Use short prefixes; `Abp` prefix reserved for ABP core modules.\n- Mapping:\n  - Do NOT configure directly inside `CreateModel`.\n  - Create `IMongoModelBuilder` extension method `ConfigureX()` and call it.\n- Repository implementations:\n  - Inherit from `MongoDbRepository<TMongoDbContextInterface, TEntity, TKey>`.\n  - Pass cancellation tokens using `GetCancellationToken(cancellationToken)`.\n  - Ignore `includeDetails` for MongoDB in most cases (documents load sub-collections).\n  - Prefer `GetQueryableAsync()` to ensure ABP data filters are applied.\n\n## ABP Module Classes\n- Every package must have exactly one `AbpModule` class.\n- Naming: `Abp[ModuleName][Layer]Module` (e.g., `AbpIdentityDomainModule`, `AbpIdentityApplicationModule`).\n- Use `[DependsOn(typeof(...))]` to declare module dependencies explicitly.\n- Override `ConfigureServices` for DI registration and configuration.\n- Override `OnApplicationInitialization` sparingly; prefer `ConfigureServices` when possible.\n- Each module must be usable standalone; avoid hidden cross-module coupling.\n\n## Framework Extensibility\n- All public and protected members should be `virtual` for inheritance-based extensibility.\n- Prefer `protected virtual` over `private` for helper methods to allow overriding.\n- Use `[Dependency(ReplaceServices = true)]` patterns for services intended to be replaceable.\n- Provide extension points via interfaces and virtual methods.\n- Document extension points with XML comments explaining intended usage.\n- Consider providing `*Options` classes for configuration-based extensibility.\n\n## Backward Compatibility\n- Do NOT remove or rename public API members without a deprecation cycle.\n- Use `[Obsolete(\"Message. Use X instead.\")]` with clear migration guidance before removal.\n- Maintain binary and source compatibility within major versions.\n- Add new optional parameters with defaults; do not change existing method signatures.\n- When adding new abstract members to base classes, provide default implementations if possible.\n- Prefer adding new interfaces over modifying existing ones.\n\n## Localization Resources\n- Define localization resources in Domain.Shared.\n- Resource class naming: `[ModuleName]Resource` (e.g., `IdentityResource`, `PermissionManagementResource`).\n- JSON files under `/Localization/[ModuleName]/` directory.\n- Use `LocalizableString.Create<TResource>(\"Key\")` for localizable exceptions and messages.\n- All user-facing strings must be localized; no hardcoded English text in code.\n- Error codes should be namespaced: `ModuleName:ErrorCode` (e.g., `Identity:UserNameAlreadyExists`).\n\n## Settings & Features\n- Define settings in `*SettingDefinitionProvider` in Domain.Shared or Domain.\n- Setting names must follow `Abp.[ModuleName].[SettingName]` convention.\n- Define features in `*FeatureDefinitionProvider` in Domain.Shared.\n- Feature names must follow `[ModuleName].[FeatureName]` convention.\n- Use constants for setting/feature names; never hardcode strings.\n\n## Permissions\n- Define permissions in `*PermissionDefinitionProvider` in Application.Contracts.\n- Permission names must follow `[ModuleName].[Permission]` convention.\n- Use constants for permission names (e.g., `IdentityPermissions.Users.Create`).\n- Group related permissions logically.\n\n## Event Bus & Distributed Events\n- Use `ILocalEventBus` for intra-module communication within the same process.\n- Use `IDistributedEventBus` for cross-module or cross-service communication.\n- Define Event Transfer Objects (ETOs) in Domain.Shared for distributed events.\n- ETO naming: `[EntityName][Action]Eto` (e.g., `UserCreatedEto`, `OrderCompletedEto`).\n- Event handlers belong in the Application layer.\n- ETOs should be simple, serializable, and contain only primitive types or nested ETOs.\n\n## Testing\n- Unit tests: `*.Tests` projects for isolated logic testing with mocked dependencies.\n- Integration tests: `*.EntityFrameworkCore.Tests` / `*.MongoDB.Tests` for repository and DB tests.\n- Use `AbpIntegratedTest<TModule>` or `AbpApplicationTestBase<TModule>` base classes.\n- Test modules should use `[DependsOn]` on the module under test.\n- Use `Shouldly` assertions (ABP convention).\n- Test both EF Core and MongoDB implementations when the module supports both.\n- Include tests for permission checks, validation, and edge cases.\n- Name test methods: `MethodName_Scenario_ExpectedResult` or `Should_ExpectedBehavior_When_Condition`.\n\n## Contribution Discipline (PR / Issues / Tests)\n- Before significant changes, align via GitHub issue/discussion.\n- PRs:\n  - Keep changes scoped and reviewable.\n  - Add/update unit/integration tests relevant to the change.\n  - Build and run tests for the impacted area when possible.\n- Localization:\n  - Prefer the `abp translate` workflow for adding missing translations (generate `abp-translation.json`, fill, apply, then PR).\n\n## Review Checklist\n- Layer dependencies respected (no forbidden references).\n- No `IQueryable` or generic repository usage leaking into application/domain.\n- Entities maintain invariants; Guid id generation not inside constructors.\n- Repositories follow async + CancellationToken + includeDetails conventions.\n- No web types in application services.\n- DTOs in contracts, serializable, validated, minimal, no logic.\n- EF/Mongo integration follows context + mapping + repository patterns.\n- Minimal diff; no unnecessary API surface expansion.\n",".github/copilot-instructions.md":"# ABP Framework – GitHub Copilot Instructions\n\n> **Scope**: ABP Framework repository (abpframework/abp) — for developing ABP itself, not ABP-based applications.\n>\n> **Goal**: Enforce ABP module architecture best practices (DDD, layering, DB/ORM independence), maintain backward compatibility, ensure extensibility, and align with ABP contribution guidelines.\n\n---\n\n## Global Defaults\n\n- Follow existing patterns in this repository first. Before generating new code, search for similar implementations and mirror their structure, naming, and conventions.\n- Prefer minimal, focused diffs. Avoid drive-by refactors and formatting churn.\n- Preserve public APIs. Avoid breaking changes unless explicitly requested and justified.\n- Keep layers clean. Do not introduce forbidden dependencies between packages.\n\n---\n\n## Module / Package Architecture (Layering)\n\nUse a layered module structure with explicit dependencies:\n\n| Layer | Purpose | Allowed Dependencies |\n|-------|---------|---------------------|\n| `*.Domain.Shared` | Constants, enums, shared types safe for all layers and 3rd-party clients. MUST NOT contain entities, repositories, domain services, or business objects. | None |\n| `*.Domain` | Entities/aggregate roots, repository interfaces, domain services. | Domain.Shared |\n| `*.Application.Contracts` | Application service interfaces and DTOs. | Domain.Shared |\n| `*.Application` | Application service implementations. | Domain, Application.Contracts |\n| `*.EntityFrameworkCore` / `*.MongoDb` | ORM integration packages. MUST NOT depend on other layers. | Domain only |\n| `*.HttpApi` | REST controllers. MUST depend ONLY on Application.Contracts (NOT Application). | Application.Contracts |\n| `*.HttpApi.Client` | Remote client proxies. MUST depend ONLY on Application.Contracts. | Application.Contracts |\n| `*.Web` | UI layer. MUST depend ONLY on HttpApi. | HttpApi |\n\n### Dependency Direction\n```\nWeb -> HttpApi -> Application.Contracts\nApplication -> Domain + Application.Contracts\nDomain -> Domain.Shared\nORM integration -> Domain\n```\n\nDo not leak web concerns into application/domain.\n\n---\n\n## Domain Layer – Entities & Aggregate Roots\n\n- Define entities in the domain layer.\n- Entities must be valid at creation:\n  - Provide a primary constructor that enforces invariants.\n  - Always include a `protected` parameterless constructor for ORMs.\n  - Always initialize sub-collections in the primary constructor.\n  - Do NOT generate Guid keys inside constructors; accept `id` and generate using `IGuidGenerator` from the calling code.\n- Make members `virtual` where appropriate (ORM/proxy compatibility).\n- Protect consistency:\n  - Use non-public setters (`private`/`protected`/`internal`) when needed.\n  - Provide meaningful domain methods for state transitions.\n\n### Aggregate Roots\n- Always use a single `Id` property. Do NOT use composite keys.\n- Prefer `Guid` keys for aggregate roots.\n- Inherit from `AggregateRoot<TKey>` or audited base classes as required.\n- Keep aggregates small. Avoid large sub-collections unless necessary.\n\n### References\n- Reference other aggregate roots by Id only.\n- Do NOT add navigation properties to other aggregate roots.\n\n---\n\n## Repositories\n\n- Define repository interfaces in the domain layer.\n- Create one dedicated repository interface per aggregate root (e.g., `IProductRepository`).\n- Public repository interfaces exposed by modules:\n  - SHOULD inherit from `IBasicRepository<TEntity, TKey>` (or `IReadOnlyRepository<...>` when suitable).\n  - SHOULD NOT expose `IQueryable` in the public contract.\n  - Internal implementations MAY use `IRepository<TEntity, TKey>` and `IQueryable` as needed.\n- Do NOT define repositories for non-aggregate-root entities.\n\n### Method Conventions\n- All methods async.\n- Include optional `CancellationToken cancellationToken = default` in every method.\n- For single-entity returning methods: include `bool includeDetails = true`.\n- For list returning methods: include `bool includeDetails = false`.\n- Do NOT return composite projection classes like `UserWithRoles`. Use `includeDetails` for eager-loading.\n- Avoid projection-only view models from repositories by default; only allow when performance is critical.\n\n---\n\n## Domain Services\n\n- Define domain services in the domain layer.\n- Default: do NOT create interfaces for domain services unless necessary (mocking/multiple implementations).\n- Naming: use `*Manager` suffix.\n\n### Method Guidelines\n- Focus on operations that enforce domain invariants and business rules.\n- Query methods are acceptable when they encapsulate domain-specific lookup logic (e.g., normalized lookups, caching, complex resolution). Simple queries belong in repositories.\n- Define methods that mutate state and enforce domain rules.\n- Use specific, intention-revealing names (avoid generic `UpdateXAsync`).\n- Accept valid domain objects as parameters; do NOT accept/return DTOs.\n- On rule violations, throw `BusinessException` (or custom business exceptions).\n- Use unique, namespaced error codes suitable for localization (e.g., `IssueTracking:ConcurrentOpenIssueLimit`).\n- Do NOT depend on authenticated user logic; pass required values from application layer.\n\n---\n\n## Application Services\n\n### Contracts\n- Define one interface per application service in `*.Application.Contracts`.\n- Interfaces must inherit from `IApplicationService`.\n- Naming: `I*AppService`.\n- Do NOT accept/return entities. Use DTOs and primitive parameters.\n\n### Method Naming & Shapes\n- All service methods async and end with `Async`.\n- Do not repeat entity names in method names (use `GetAsync`, not `GetProductAsync`).\n\n**Standard CRUD:**\n```csharp\nTask<ProductDto> GetAsync(Guid id);\nTask<PagedResultDto<ProductDto>> GetListAsync(GetProductListInput input);\nTask<ProductDto> CreateAsync(CreateProductInput input);\nTask<ProductDto> UpdateAsync(Guid id, UpdateProductInput input);  // id NOT inside DTO\nTask DeleteAsync(Guid id);\n```\n\n### DTO Usage (Inputs)\n- Do not include unused properties.\n- Do NOT share input DTOs between methods.\n- Do NOT use inheritance between input DTOs (except rare abstract base DTO cases; be very cautious).\n\n### Implementation\n- Application layer must be independent of web.\n- Implement interfaces in `*.Application`, name `ProductAppService` for `IProductAppService`.\n- Inherit from `ApplicationService`.\n- Make all public methods `virtual`.\n- Avoid private helper methods; prefer `protected virtual` helpers for extensibility.\n\n### Data Access\n- Use dedicated repositories (e.g., `IProductRepository`).\n- Do NOT put LINQ/SQL queries inside application service methods; repositories perform queries.\n\n### Entity Mutation\n- Load required entities from repositories.\n- Mutate using domain methods.\n- Call repository `UpdateAsync` after updates (do not assume change tracking).\n\n### Files\n- Do NOT use web types like `IFormFile` or `Stream` in application services.\n- Controllers handle upload; pass `byte[]` (or similar) to application services.\n\n### Cross-Service Calls\n- Do NOT call other application services within the same module.\n- For reuse, push logic into domain layer or extract shared helpers carefully.\n- You MAY call other modules' application services only via their Application.Contracts.\n\n---\n\n## DTO Conventions\n\n- Define DTOs in `*.Application.Contracts`.\n- Prefer ABP base DTO types (`EntityDto<TKey>`, audited DTOs).\n- For aggregate roots, prefer extensible DTO base types so extra properties can map.\n- DTO properties: public getters/setters.\n\n### Input DTO Validation\n- Use data annotations.\n- Reuse constants from Domain.Shared wherever possible.\n\n### General Rules\n- Avoid logic in DTOs; only implement `IValidatableObject` when necessary.\n- Do NOT use `[Serializable]` attribute (BinaryFormatter is obsolete); ABP uses JSON serialization.\n\n### Output DTO Strategy\n- Prefer a Basic DTO and a Detailed DTO; avoid many variants.\n- Detailed DTOs: include reference details as nested basic DTOs; avoid duplicating raw FK ids unnecessarily.\n\n---\n\n## EF Core Integration\n\n- Define a separate DbContext interface + class per module.\n- Do NOT rely on lazy loading; do NOT enable lazy loading.\n\n### DbContext Interface\n```csharp\n[ConnectionStringName(\"ModuleName\")]\npublic interface IModuleNameDbContext : IEfCoreDbContext\n{\n    DbSet<Product> Products { get; }  // No setters, aggregate roots only\n}\n```\n\n### DbContext Class\n```csharp\n[ConnectionStringName(\"ModuleName\")]\npublic class ModuleNameDbContext : AbpDbContext<ModuleNameDbContext>, IModuleNameDbContext\n{\n    public static string TablePrefix { get; set; } = ModuleNameConsts.DefaultDbTablePrefix;\n    public static string? Schema { get; set; } = ModuleNameConsts.DefaultDbSchema;\n    \n    public DbSet<Product> Products { get; set; }\n}\n```\n\n### Table Prefix/Schema\n- Provide static `TablePrefix` and `Schema` defaulted from constants.\n- Use short prefixes; `Abp` prefix reserved for ABP core modules.\n- Default schema should be `null`.\n\n### Model Mapping\n- Do NOT configure entities directly inside `OnModelCreating`.\n- Create `ModelBuilder` extension method `ConfigureX()` and call it.\n- Call `b.ConfigureByConvention()` for each entity.\n\n### Repository Implementations\n- Inherit from `EfCoreRepository<TDbContextInterface, TEntity, TKey>`.\n- Use DbContext interface as generic parameter.\n- Pass cancellation tokens using `GetCancellationToken(cancellationToken)`.\n- Implement `IncludeDetails(include)` extension per aggregate root with sub-collections.\n- Override `WithDetailsAsync()` where needed.\n\n---\n\n## MongoDB Integration\n\n- Define a separate MongoDbContext interface + class per module.\n\n### MongoDbContext Interface\n```csharp\n[ConnectionStringName(\"ModuleName\")]\npublic interface IModuleNameMongoDbContext : IAbpMongoDbContext\n{\n    IMongoCollection<Product> Products { get; }  // Aggregate roots only\n}\n```\n\n### MongoDbContext Class\n```csharp\npublic class ModuleNameMongoDbContext : AbpMongoDbContext, IModuleNameMongoDbContext\n{\n    public static string CollectionPrefix { get; set; } = ModuleNameConsts.DefaultDbTablePrefix;\n}\n```\n\n### Mapping\n- Do NOT configure directly inside `CreateModel`.\n- Create `IMongoModelBuilder` extension method `ConfigureX()` and call it.\n\n### Repository Implementations\n- Inherit from `MongoDbRepository<TMongoDbContextInterface, TEntity, TKey>`.\n- Pass cancellation tokens using `GetCancellationToken(cancellationToken)`.\n- Ignore `includeDetails` for MongoDB in most cases (documents load sub-collections).\n- Prefer `GetQueryableAsync()` to ensure ABP data filters are applied.\n\n---\n\n## ABP Module Classes\n\n- Every package must have exactly one `AbpModule` class.\n- Naming: `Abp[ModuleName][Layer]Module` (e.g., `AbpIdentityDomainModule`, `AbpIdentityApplicationModule`).\n- Use `[DependsOn(typeof(...))]` to declare module dependencies explicitly.\n- Override `ConfigureServices` for DI registration and configuration.\n- Override `OnApplicationInitialization` sparingly; prefer `ConfigureServices` when possible.\n- Each module must be usable standalone; avoid hidden cross-module coupling.\n\n---\n\n## Framework Extensibility\n\n- All public and protected members should be `virtual` for inheritance-based extensibility.\n- Prefer `protected virtual` over `private` for helper methods to allow overriding.\n- Use `[Dependency(ReplaceServices = true)]` patterns for services intended to be replaceable.\n- Provide extension points via interfaces and virtual methods.\n- Document extension points with XML comments explaining intended usage.\n- Consider providing `*Options` classes for configuration-based extensibility.\n\n---\n\n## Backward Compatibility\n\n- Do NOT remove or rename public API members without a deprecation cycle.\n- Use `[Obsolete(\"Message. Use X instead.\")]` with clear migration guidance before removal.\n- Maintain binary and source compatibility within major versions.\n- Add new optional parameters with defaults; do not change existing method signatures.\n- When adding new abstract members to base classes, provide default implementations if possible.\n- Prefer adding new interfaces over modifying existing ones.\n\n---\n\n## Localization Resources\n\n- Define localization resources in Domain.Shared.\n- Resource class naming: `[ModuleName]Resource` (e.g., `IdentityResource`, `PermissionManagementResource`).\n- JSON files under `/Localization/[ModuleName]/` directory.\n- Use `LocalizableString.Create<TResource>(\"Key\")` for localizable exceptions and messages.\n- All user-facing strings must be localized; no hardcoded English text in code.\n- Error codes should be namespaced: `ModuleName:ErrorCode` (e.g., `Identity:UserNameAlreadyExists`).\n\n---\n\n## Settings & Features\n\n- Define settings in `*SettingDefinitionProvider` in Domain.Shared or Domain.\n- Setting names must follow `Abp.[ModuleName].[SettingName]` convention.\n- Define features in `*FeatureDefinitionProvider` in Domain.Shared.\n- Feature names must follow `[ModuleName].[FeatureName]` convention.\n- Use constants for setting/feature names; never hardcode strings.\n\n---\n\n## Permissions\n\n- Define permissions in `*PermissionDefinitionProvider` in Application.Contracts.\n- Permission names must follow `[ModuleName].[Permission]` convention.\n- Use constants for permission names (e.g., `IdentityPermissions.Users.Create`).\n- Group related permissions logically.\n\n---\n\n## Event Bus & Distributed Events\n\n- Use `ILocalEventBus` for intra-module communication within the same process.\n- Use `IDistributedEventBus` for cross-module or cross-service communication.\n- Define Event Transfer Objects (ETOs) in Domain.Shared for distributed events.\n- ETO naming: `[EntityName][Action]Eto` (e.g., `UserCreatedEto`, `OrderCompletedEto`).\n- Event handlers belong in the Application layer.\n- ETOs should be simple, serializable, and contain only primitive types or nested ETOs.\n\n---\n\n## Testing\n\n- Unit tests: `*.Tests` projects for isolated logic testing with mocked dependencies.\n- Integration tests: `*.EntityFrameworkCore.Tests` / `*.MongoDB.Tests` for repository and DB tests.\n- Use `AbpIntegratedTest<TModule>` or `AbpApplicationTestBase<TModule>` base classes.\n- Test modules should use `[DependsOn]` on the module under test.\n- Use `Shouldly` assertions (ABP convention).\n- Test both EF Core and MongoDB implementations when the module supports both.\n- Include tests for permission checks, validation, and edge cases.\n- Name test methods: `MethodName_Scenario_ExpectedResult` or `Should_ExpectedBehavior_When_Condition`.\n\n---\n\n## Contribution Discipline (PR / Issues / Tests)\n\n- Before significant changes, align via GitHub issue/discussion.\n\n### PRs\n- Keep changes scoped and reviewable.\n- Add/update unit/integration tests relevant to the change.\n- Build and run tests for the impacted area when possible.\n\n### Localization\n- Prefer the `abp translate` workflow for adding missing translations (generate `abp-translation.json`, fill, apply, then PR).\n\n---\n\n## Review Checklist\n\n- [ ] Layer dependencies respected (no forbidden references).\n- [ ] No `IQueryable` leaking into public repository contracts.\n- [ ] Entities maintain invariants; Guid id generation not inside constructors.\n- [ ] Repositories follow async + CancellationToken + includeDetails conventions.\n- [ ] No web types in application services.\n- [ ] DTOs in contracts, validated, minimal, no logic.\n- [ ] EF/Mongo integration follows context + mapping + repository patterns.\n- [ ] Public members are `virtual` for extensibility.\n- [ ] Backward compatibility maintained; no breaking changes without deprecation.\n- [ ] Minimal diff; no unnecessary API surface expansion.\n"},"files":{".cursorrules":"# ABP Framework – Cursor Rules\n# Scope: ABP Framework repository (abpframework/abp) — for developing ABP itself, not ABP-based applications.\n# Goal: Enforce ABP module architecture best practices (DDD, layering, DB/ORM independence),\n# maintain backward compatibility, ensure extensibility, and align with ABP contribution guidelines.\n\n## Global Defaults\n- Follow existing patterns in this repository first. Before generating new code, search for similar implementations and mirror their structure, naming, and conventions.\n- Prefer minimal, focused diffs. Avoid drive-by refactors and formatting churn.\n- Preserve public APIs. Avoid breaking changes unless explicitly requested and justified.\n- Keep layers clean. Do not introduce forbidden dependencies between packages.\n\n## Module / Package Architecture (Layering)\n- Use a layered module structure with explicit dependencies:\n  - *.Domain.Shared: constants, enums, shared types safe for all layers and 3rd-party clients. MUST NOT contain entities, repositories, domain services, or business objects.\n  - *.Domain: entities/aggregate roots, repository interfaces, domain services.\n  - *.Application.Contracts: application service interfaces and DTOs.\n  - *.Application: application service implementations.\n  - *.EntityFrameworkCore / *.MongoDb: ORM integration packages depend on *.Domain only. MUST NOT depend on other layers.\n  - *.HttpApi: REST controllers. MUST depend ONLY on *.Application.Contracts (NOT *.Application).\n  - *.HttpApi.Client: remote client proxies. MUST depend ONLY on *.Application.Contracts.\n  - *.Web: UI. MUST depend ONLY on *.HttpApi.\n- Enforce dependency direction:\n  - Web -> HttpApi -> Application.Contracts\n  - Application -> Domain + Application.Contracts\n  - Domain -> Domain.Shared\n  - ORM integration -> Domain\n- Do not leak web concerns into application/domain.\n\n## Domain Layer – Entities & Aggregate Roots\n- Define entities in the domain layer.\n- Entities must be valid at creation:\n  - Provide a primary constructor that enforces invariants.\n  - Always include a protected parameterless constructor for ORMs.\n  - Always initialize sub-collections in the primary constructor.\n  - Do NOT generate Guid keys inside constructors; accept `id` and generate using `IGuidGenerator` from the calling code.\n- Make members `virtual` where appropriate (ORM/proxy compatibility).\n- Protect consistency:\n  - Use non-public setters (private/protected/internal) when needed.\n  - Provide meaningful domain methods for state transitions; prefer returning `this` from setters when applicable.\n- Aggregate roots:\n  - Always use a single `Id` property. Do NOT use composite keys.\n  - Prefer `Guid` keys for aggregate roots.\n  - Inherit from `AggregateRoot<TKey>` or audited base classes as required.\n- Aggregate boundaries:\n  - Keep aggregates small. Avoid large sub-collections unless necessary.\n- References:\n  - Reference other aggregate roots by Id only.\n  - Do NOT add navigation properties to other aggregate roots.\n\n## Repositories\n- Define repository interfaces in the domain layer.\n- Create one dedicated repository interface per aggregate root (e.g., `IProductRepository`).\n- Public repository interfaces exposed by modules:\n  - SHOULD inherit from `IBasicRepository<TEntity, TKey>` (or `IReadOnlyRepository<...>` when suitable).\n  - SHOULD NOT expose `IQueryable` in the public contract.\n  - Internal implementations MAY use `IRepository<TEntity, TKey>` and `IQueryable` as needed.\n- Do NOT define repositories for non-aggregate-root entities.\n- Repository method conventions:\n  - All methods async.\n  - Include optional `CancellationToken cancellationToken = default` in every method.\n  - For single-entity returning methods: include `bool includeDetails = true`.\n  - For list returning methods: include `bool includeDetails = false`.\n  - Do NOT return composite projection classes like `UserWithRoles`. Use `includeDetails` for eager-loading.\n  - Avoid projection-only view models from repositories by default; only allow when performance is critical.\n\n## Domain Services\n- Define domain services in the domain layer.\n- Default: do NOT create interfaces for domain services unless necessary (mocking/multiple implementations).\n- Naming: use `*Manager` suffix.\n- Domain service methods:\n  - Focus on operations that enforce domain invariants and business rules.\n  - Query methods are acceptable when they encapsulate domain-specific lookup logic (e.g., normalized lookups, caching, complex resolution). Simple queries belong in repositories.\n  - Define methods that mutate state and enforce domain rules.\n  - Use specific, intention-revealing names (avoid generic `UpdateXAsync`).\n  - Accept valid domain objects as parameters; do NOT accept/return DTOs.\n  - On rule violations, throw `BusinessException` (or custom business exceptions).\n  - Use unique, namespaced error codes suitable for localization (e.g., `IssueTracking:ConcurrentOpenIssueLimit`).\n  - Do NOT depend on authenticated user logic; pass required values from application layer.\n\n## Application Services (Contracts + Implementation)\n### Contracts\n- Define one interface per application service in *.Application.Contracts.\n- Interfaces must inherit from `IApplicationService`.\n- Naming: `I*AppService`.\n- Do NOT accept/return entities. Use DTOs and primitive parameters.\n\n### Method Naming & Shapes\n- All service methods async and end with `Async`.\n- Do not repeat entity names in method names (use `GetAsync`, not `GetProductAsync`).\n- Standard CRUD:\n  - `GetAsync(Guid id)` returns a detailed DTO.\n  - `GetListAsync(QueryDto queryDto)` returns a list of detailed DTOs.\n  - `CreateAsync(CreateDto dto)` returns detailed DTO.\n  - `UpdateAsync(Guid id, UpdateDto dto)` returns detailed DTO (id MUST NOT be inside update DTO).\n  - `DeleteAsync(Guid id)` returns void/Task.\n- `GetListAsync` query DTO:\n  - Filtering/sorting/paging fields optional with defaults.\n  - Enforce a maximum page size for performance.\n\n### DTO Usage\n- Inputs:\n  - Do not include unused properties.\n  - Do NOT share input DTOs between methods.\n  - Do NOT use inheritance between input DTOs (except rare abstract base DTO cases; be very cautious).\n\n### Implementation\n- Application layer must be independent of web.\n- Implement interfaces in *.Application, name `ProductAppService` for `IProductAppService`.\n- Inherit from `ApplicationService`.\n- Make all public methods `virtual`.\n- Avoid private helper methods; prefer `protected virtual` helpers for extensibility.\n- Data access:\n  - Use dedicated repositories (e.g., `IProductRepository`).\n  - Do NOT use generic repositories.\n  - Do NOT put LINQ/SQL queries inside application service methods; repositories perform queries.\n- Entity mutation:\n  - Load required entities from repositories.\n  - Mutate using domain methods.\n  - Call repository `UpdateAsync` after updates (do not assume change tracking).\n- Extra properties:\n  - Use `MapExtraPropertiesTo` or configure object mapper for `MapExtraProperties`.\n- Files:\n  - Do NOT use web types like `IFormFile` or `Stream` in application services.\n  - Controllers handle upload; pass `byte[]` (or similar) to application services.\n- Cross-application-service calls:\n  - Do NOT call other application services within the same module.\n  - For reuse, push logic into domain layer or extract shared helpers carefully.\n  - You MAY call other modules’ application services only via their Application.Contracts.\n\n## DTO Conventions\n- Define DTOs in *.Application.Contracts.\n- Prefer ABP base DTO types (`EntityDto<TKey>`, audited DTOs).\n- For aggregate roots, prefer extensible DTO base types so extra properties can map.\n- DTO properties: public getters/setters.\n- Input DTO validation:\n  - Use data annotations.\n  - Reuse constants from Domain.Shared wherever possible.\n- Avoid logic in DTOs; only implement `IValidatableObject` when necessary.\n- Do NOT use `[Serializable]` attribute (BinaryFormatter is obsolete); ABP uses JSON serialization.\n- Output DTO strategy:\n  - Prefer a Basic DTO and a Detailed DTO; avoid many variants.\n  - Detailed DTOs: include reference details as nested basic DTOs; avoid duplicating raw FK ids unnecessarily.\n\n## EF Core Integration\n- Define a separate DbContext interface + class per module.\n- Do NOT rely on lazy loading; do NOT enable lazy loading.\n- DbContext interface:\n  - Inherit from `IEfCoreDbContext`.\n  - Add `[ConnectionStringName(\"...\")]`.\n  - Expose `DbSet<TEntity>` ONLY for aggregate roots.\n  - Do NOT include setters in the interface.\n- DbContext class:\n  - Inherit `AbpDbContext<TDbContext>`.\n  - Add `[ConnectionStringName(\"...\")]` and implement the interface.\n- Table prefix/schema:\n  - Provide static `TablePrefix` and `Schema` defaulted from constants.\n  - Use short prefixes; `Abp` prefix reserved for ABP core modules.\n  - Default schema should be `null`.\n- Model mapping:\n  - Do NOT configure entities directly inside `OnModelCreating`.\n  - Create `ModelBuilder` extension method `ConfigureX()` and call it.\n  - Call `b.ConfigureByConvention()` for each entity.\n- Repository implementations:\n  - Inherit from `EfCoreRepository<TDbContextInterface, TEntity, TKey>`.\n  - Use DbContext interface as generic parameter.\n  - Pass cancellation tokens using `GetCancellationToken(cancellationToken)`.\n  - Implement `IncludeDetails(include)` extension per aggregate root with sub-collections.\n  - Override `WithDetailsAsync()` where needed.\n\n## MongoDB Integration\n- Define a separate MongoDbContext interface + class per module.\n- MongoDbContext interface:\n  - Inherit from `IAbpMongoDbContext`.\n  - Add `[ConnectionStringName(\"...\")]`.\n  - Expose `IMongoCollection<TEntity>` ONLY for aggregate roots.\n- MongoDbContext class:\n  - Inherit `AbpMongoDbContext` and implement the interface.\n- Collection prefix:\n  - Provide static `CollectionPrefix` defaulted from constants.\n  - Use short prefixes; `Abp` prefix reserved for ABP core modules.\n- Mapping:\n  - Do NOT configure directly inside `CreateModel`.\n  - Create `IMongoModelBuilder` extension method `ConfigureX()` and call it.\n- Repository implementations:\n  - Inherit from `MongoDbRepository<TMongoDbContextInterface, TEntity, TKey>`.\n  - Pass cancellation tokens using `GetCancellationToken(cancellationToken)`.\n  - Ignore `includeDetails` for MongoDB in most cases (documents load sub-collections).\n  - Prefer `GetQueryableAsync()` to ensure ABP data filters are applied.\n\n## ABP Module Classes\n- Every package must have exactly one `AbpModule` class.\n- Naming: `Abp[ModuleName][Layer]Module` (e.g., `AbpIdentityDomainModule`, `AbpIdentityApplicationModule`).\n- Use `[DependsOn(typeof(...))]` to declare module dependencies explicitly.\n- Override `ConfigureServices` for DI registration and configuration.\n- Override `OnApplicationInitialization` sparingly; prefer `ConfigureServices` when possible.\n- Each module must be usable standalone; avoid hidden cross-module coupling.\n\n## Framework Extensibility\n- All public and protected members should be `virtual` for inheritance-based extensibility.\n- Prefer `protected virtual` over `private` for helper methods to allow overriding.\n- Use `[Dependency(ReplaceServices = true)]` patterns for services intended to be replaceable.\n- Provide extension points via interfaces and virtual methods.\n- Document extension points with XML comments explaining intended usage.\n- Consider providing `*Options` classes for configuration-based extensibility.\n\n## Backward Compatibility\n- Do NOT remove or rename public API members without a deprecation cycle.\n- Use `[Obsolete(\"Message. Use X instead.\")]` with clear migration guidance before removal.\n- Maintain binary and source compatibility within major versions.\n- Add new optional parameters with defaults; do not change existing method signatures.\n- When adding new abstract members to base classes, provide default implementations if possible.\n- Prefer adding new interfaces over modifying existing ones.\n\n## Localization Resources\n- Define localization resources in Domain.Shared.\n- Resource class naming: `[ModuleName]Resource` (e.g., `IdentityResource`, `PermissionManagementResource`).\n- JSON files under `/Localization/[ModuleName]/` directory.\n- Use `LocalizableString.Create<TResource>(\"Key\")` for localizable exceptions and messages.\n- All user-facing strings must be localized; no hardcoded English text in code.\n- Error codes should be namespaced: `ModuleName:ErrorCode` (e.g., `Identity:UserNameAlreadyExists`).\n\n## Settings & Features\n- Define settings in `*SettingDefinitionProvider` in Domain.Shared or Domain.\n- Setting names must follow `Abp.[ModuleName].[SettingName]` convention.\n- Define features in `*FeatureDefinitionProvider` in Domain.Shared.\n- Feature names must follow `[ModuleName].[FeatureName]` convention.\n- Use constants for setting/feature names; never hardcode strings.\n\n## Permissions\n- Define permissions in `*PermissionDefinitionProvider` in Application.Contracts.\n- Permission names must follow `[ModuleName].[Permission]` convention.\n- Use constants for permission names (e.g., `IdentityPermissions.Users.Create`).\n- Group related permissions logically.\n\n## Event Bus & Distributed Events\n- Use `ILocalEventBus` for intra-module communication within the same process.\n- Use `IDistributedEventBus` for cross-module or cross-service communication.\n- Define Event Transfer Objects (ETOs) in Domain.Shared for distributed events.\n- ETO naming: `[EntityName][Action]Eto` (e.g., `UserCreatedEto`, `OrderCompletedEto`).\n- Event handlers belong in the Application layer.\n- ETOs should be simple, serializable, and contain only primitive types or nested ETOs.\n\n## Testing\n- Unit tests: `*.Tests` projects for isolated logic testing with mocked dependencies.\n- Integration tests: `*.EntityFrameworkCore.Tests` / `*.MongoDB.Tests` for repository and DB tests.\n- Use `AbpIntegratedTest<TModule>` or `AbpApplicationTestBase<TModule>` base classes.\n- Test modules should use `[DependsOn]` on the module under test.\n- Use `Shouldly` assertions (ABP convention).\n- Test both EF Core and MongoDB implementations when the module supports both.\n- Include tests for permission checks, validation, and edge cases.\n- Name test methods: `MethodName_Scenario_ExpectedResult` or `Should_ExpectedBehavior_When_Condition`.\n\n## Contribution Discipline (PR / Issues / Tests)\n- Before significant changes, align via GitHub issue/discussion.\n- PRs:\n  - Keep changes scoped and reviewable.\n  - Add/update unit/integration tests relevant to the change.\n  - Build and run tests for the impacted area when possible.\n- Localization:\n  - Prefer the `abp translate` workflow for adding missing translations (generate `abp-translation.json`, fill, apply, then PR).\n\n## Review Checklist\n- Layer dependencies respected (no forbidden references).\n- No `IQueryable` or generic repository usage leaking into application/domain.\n- Entities maintain invariants; Guid id generation not inside constructors.\n- Repositories follow async + CancellationToken + includeDetails conventions.\n- No web types in application services.\n- DTOs in contracts, serializable, validated, minimal, no logic.\n- EF/Mongo integration follows context + mapping + repository patterns.\n- Minimal diff; no unnecessary API surface expansion.\n",".github/copilot-instructions.md":"# ABP Framework – GitHub Copilot Instructions\n\n> **Scope**: ABP Framework repository (abpframework/abp) — for developing ABP itself, not ABP-based applications.\n>\n> **Goal**: Enforce ABP module architecture best practices (DDD, layering, DB/ORM independence), maintain backward compatibility, ensure extensibility, and align with ABP contribution guidelines.\n\n---\n\n## Global Defaults\n\n- Follow existing patterns in this repository first. Before generating new code, search for similar implementations and mirror their structure, naming, and conventions.\n- Prefer minimal, focused diffs. Avoid drive-by refactors and formatting churn.\n- Preserve public APIs. Avoid breaking changes unless explicitly requested and justified.\n- Keep layers clean. Do not introduce forbidden dependencies between packages.\n\n---\n\n## Module / Package Architecture (Layering)\n\nUse a layered module structure with explicit dependencies:\n\n| Layer | Purpose | Allowed Dependencies |\n|-------|---------|---------------------|\n| `*.Domain.Shared` | Constants, enums, shared types safe for all layers and 3rd-party clients. MUST NOT contain entities, repositories, domain services, or business objects. | None |\n| `*.Domain` | Entities/aggregate roots, repository interfaces, domain services. | Domain.Shared |\n| `*.Application.Contracts` | Application service interfaces and DTOs. | Domain.Shared |\n| `*.Application` | Application service implementations. | Domain, Application.Contracts |\n| `*.EntityFrameworkCore` / `*.MongoDb` | ORM integration packages. MUST NOT depend on other layers. | Domain only |\n| `*.HttpApi` | REST controllers. MUST depend ONLY on Application.Contracts (NOT Application). | Application.Contracts |\n| `*.HttpApi.Client` | Remote client proxies. MUST depend ONLY on Application.Contracts. | Application.Contracts |\n| `*.Web` | UI layer. MUST depend ONLY on HttpApi. | HttpApi |\n\n### Dependency Direction\n```\nWeb -> HttpApi -> Application.Contracts\nApplication -> Domain + Application.Contracts\nDomain -> Domain.Shared\nORM integration -> Domain\n```\n\nDo not leak web concerns into application/domain.\n\n---\n\n## Domain Layer – Entities & Aggregate Roots\n\n- Define entities in the domain layer.\n- Entities must be valid at creation:\n  - Provide a primary constructor that enforces invariants.\n  - Always include a `protected` parameterless constructor for ORMs.\n  - Always initialize sub-collections in the primary constructor.\n  - Do NOT generate Guid keys inside constructors; accept `id` and generate using `IGuidGenerator` from the calling code.\n- Make members `virtual` where appropriate (ORM/proxy compatibility).\n- Protect consistency:\n  - Use non-public setters (`private`/`protected`/`internal`) when needed.\n  - Provide meaningful domain methods for state transitions.\n\n### Aggregate Roots\n- Always use a single `Id` property. Do NOT use composite keys.\n- Prefer `Guid` keys for aggregate roots.\n- Inherit from `AggregateRoot<TKey>` or audited base classes as required.\n- Keep aggregates small. Avoid large sub-collections unless necessary.\n\n### References\n- Reference other aggregate roots by Id only.\n- Do NOT add navigation properties to other aggregate roots.\n\n---\n\n## Repositories\n\n- Define repository interfaces in the domain layer.\n- Create one dedicated repository interface per aggregate root (e.g., `IProductRepository`).\n- Public repository interfaces exposed by modules:\n  - SHOULD inherit from `IBasicRepository<TEntity, TKey>` (or `IReadOnlyRepository<...>` when suitable).\n  - SHOULD NOT expose `IQueryable` in the public contract.\n  - Internal implementations MAY use `IRepository<TEntity, TKey>` and `IQueryable` as needed.\n- Do NOT define repositories for non-aggregate-root entities.\n\n### Method Conventions\n- All methods async.\n- Include optional `CancellationToken cancellationToken = default` in every method.\n- For single-entity returning methods: include `bool includeDetails = true`.\n- For list returning methods: include `bool includeDetails = false`.\n- Do NOT return composite projection classes like `UserWithRoles`. Use `includeDetails` for eager-loading.\n- Avoid projection-only view models from repositories by default; only allow when performance is critical.\n\n---\n\n## Domain Services\n\n- Define domain services in the domain layer.\n- Default: do NOT create interfaces for domain services unless necessary (mocking/multiple implementations).\n- Naming: use `*Manager` suffix.\n\n### Method Guidelines\n- Focus on operations that enforce domain invariants and business rules.\n- Query methods are acceptable when they encapsulate domain-specific lookup logic (e.g., normalized lookups, caching, complex resolution). Simple queries belong in repositories.\n- Define methods that mutate state and enforce domain rules.\n- Use specific, intention-revealing names (avoid generic `UpdateXAsync`).\n- Accept valid domain objects as parameters; do NOT accept/return DTOs.\n- On rule violations, throw `BusinessException` (or custom business exceptions).\n- Use unique, namespaced error codes suitable for localization (e.g., `IssueTracking:ConcurrentOpenIssueLimit`).\n- Do NOT depend on authenticated user logic; pass required values from application layer.\n\n---\n\n## Application Services\n\n### Contracts\n- Define one interface per application service in `*.Application.Contracts`.\n- Interfaces must inherit from `IApplicationService`.\n- Naming: `I*AppService`.\n- Do NOT accept/return entities. Use DTOs and primitive parameters.\n\n### Method Naming & Shapes\n- All service methods async and end with `Async`.\n- Do not repeat entity names in method names (use `GetAsync`, not `GetProductAsync`).\n\n**Standard CRUD:**\n```csharp\nTask<ProductDto> GetAsync(Guid id);\nTask<PagedResultDto<ProductDto>> GetListAsync(GetProductListInput input);\nTask<ProductDto> CreateAsync(CreateProductInput input);\nTask<ProductDto> UpdateAsync(Guid id, UpdateProductInput input);  // id NOT inside DTO\nTask DeleteAsync(Guid id);\n```\n\n### DTO Usage (Inputs)\n- Do not include unused properties.\n- Do NOT share input DTOs between methods.\n- Do NOT use inheritance between input DTOs (except rare abstract base DTO cases; be very cautious).\n\n### Implementation\n- Application layer must be independent of web.\n- Implement interfaces in `*.Application`, name `ProductAppService` for `IProductAppService`.\n- Inherit from `ApplicationService`.\n- Make all public methods `virtual`.\n- Avoid private helper methods; prefer `protected virtual` helpers for extensibility.\n\n### Data Access\n- Use dedicated repositories (e.g., `IProductRepository`).\n- Do NOT put LINQ/SQL queries inside application service methods; repositories perform queries.\n\n### Entity Mutation\n- Load required entities from repositories.\n- Mutate using domain methods.\n- Call repository `UpdateAsync` after updates (do not assume change tracking).\n\n### Files\n- Do NOT use web types like `IFormFile` or `Stream` in application services.\n- Controllers handle upload; pass `byte[]` (or similar) to application services.\n\n### Cross-Service Calls\n- Do NOT call other application services within the same module.\n- For reuse, push logic into domain layer or extract shared helpers carefully.\n- You MAY call other modules' application services only via their Application.Contracts.\n\n---\n\n## DTO Conventions\n\n- Define DTOs in `*.Application.Contracts`.\n- Prefer ABP base DTO types (`EntityDto<TKey>`, audited DTOs).\n- For aggregate roots, prefer extensible DTO base types so extra properties can map.\n- DTO properties: public getters/setters.\n\n### Input DTO Validation\n- Use data annotations.\n- Reuse constants from Domain.Shared wherever possible.\n\n### General Rules\n- Avoid logic in DTOs; only implement `IValidatableObject` when necessary.\n- Do NOT use `[Serializable]` attribute (BinaryFormatter is obsolete); ABP uses JSON serialization.\n\n### Output DTO Strategy\n- Prefer a Basic DTO and a Detailed DTO; avoid many variants.\n- Detailed DTOs: include reference details as nested basic DTOs; avoid duplicating raw FK ids unnecessarily.\n\n---\n\n## EF Core Integration\n\n- Define a separate DbContext interface + class per module.\n- Do NOT rely on lazy loading; do NOT enable lazy loading.\n\n### DbContext Interface\n```csharp\n[ConnectionStringName(\"ModuleName\")]\npublic interface IModuleNameDbContext : IEfCoreDbContext\n{\n    DbSet<Product> Products { get; }  // No setters, aggregate roots only\n}\n```\n\n### DbContext Class\n```csharp\n[ConnectionStringName(\"ModuleName\")]\npublic class ModuleNameDbContext : AbpDbContext<ModuleNameDbContext>, IModuleNameDbContext\n{\n    public static string TablePrefix { get; set; } = ModuleNameConsts.DefaultDbTablePrefix;\n    public static string? Schema { get; set; } = ModuleNameConsts.DefaultDbSchema;\n    \n    public DbSet<Product> Products { get; set; }\n}\n```\n\n### Table Prefix/Schema\n- Provide static `TablePrefix` and `Schema` defaulted from constants.\n- Use short prefixes; `Abp` prefix reserved for ABP core modules.\n- Default schema should be `null`.\n\n### Model Mapping\n- Do NOT configure entities directly inside `OnModelCreating`.\n- Create `ModelBuilder` extension method `ConfigureX()` and call it.\n- Call `b.ConfigureByConvention()` for each entity.\n\n### Repository Implementations\n- Inherit from `EfCoreRepository<TDbContextInterface, TEntity, TKey>`.\n- Use DbContext interface as generic parameter.\n- Pass cancellation tokens using `GetCancellationToken(cancellationToken)`.\n- Implement `IncludeDetails(include)` extension per aggregate root with sub-collections.\n- Override `WithDetailsAsync()` where needed.\n\n---\n\n## MongoDB Integration\n\n- Define a separate MongoDbContext interface + class per module.\n\n### MongoDbContext Interface\n```csharp\n[ConnectionStringName(\"ModuleName\")]\npublic interface IModuleNameMongoDbContext : IAbpMongoDbContext\n{\n    IMongoCollection<Product> Products { get; }  // Aggregate roots only\n}\n```\n\n### MongoDbContext Class\n```csharp\npublic class ModuleNameMongoDbContext : AbpMongoDbContext, IModuleNameMongoDbContext\n{\n    public static string CollectionPrefix { get; set; } = ModuleNameConsts.DefaultDbTablePrefix;\n}\n```\n\n### Mapping\n- Do NOT configure directly inside `CreateModel`.\n- Create `IMongoModelBuilder` extension method `ConfigureX()` and call it.\n\n### Repository Implementations\n- Inherit from `MongoDbRepository<TMongoDbContextInterface, TEntity, TKey>`.\n- Pass cancellation tokens using `GetCancellationToken(cancellationToken)`.\n- Ignore `includeDetails` for MongoDB in most cases (documents load sub-collections).\n- Prefer `GetQueryableAsync()` to ensure ABP data filters are applied.\n\n---\n\n## ABP Module Classes\n\n- Every package must have exactly one `AbpModule` class.\n- Naming: `Abp[ModuleName][Layer]Module` (e.g., `AbpIdentityDomainModule`, `AbpIdentityApplicationModule`).\n- Use `[DependsOn(typeof(...))]` to declare module dependencies explicitly.\n- Override `ConfigureServices` for DI registration and configuration.\n- Override `OnApplicationInitialization` sparingly; prefer `ConfigureServices` when possible.\n- Each module must be usable standalone; avoid hidden cross-module coupling.\n\n---\n\n## Framework Extensibility\n\n- All public and protected members should be `virtual` for inheritance-based extensibility.\n- Prefer `protected virtual` over `private` for helper methods to allow overriding.\n- Use `[Dependency(ReplaceServices = true)]` patterns for services intended to be replaceable.\n- Provide extension points via interfaces and virtual methods.\n- Document extension points with XML comments explaining intended usage.\n- Consider providing `*Options` classes for configuration-based extensibility.\n\n---\n\n## Backward Compatibility\n\n- Do NOT remove or rename public API members without a deprecation cycle.\n- Use `[Obsolete(\"Message. Use X instead.\")]` with clear migration guidance before removal.\n- Maintain binary and source compatibility within major versions.\n- Add new optional parameters with defaults; do not change existing method signatures.\n- When adding new abstract members to base classes, provide default implementations if possible.\n- Prefer adding new interfaces over modifying existing ones.\n\n---\n\n## Localization Resources\n\n- Define localization resources in Domain.Shared.\n- Resource class naming: `[ModuleName]Resource` (e.g., `IdentityResource`, `PermissionManagementResource`).\n- JSON files under `/Localization/[ModuleName]/` directory.\n- Use `LocalizableString.Create<TResource>(\"Key\")` for localizable exceptions and messages.\n- All user-facing strings must be localized; no hardcoded English text in code.\n- Error codes should be namespaced: `ModuleName:ErrorCode` (e.g., `Identity:UserNameAlreadyExists`).\n\n---\n\n## Settings & Features\n\n- Define settings in `*SettingDefinitionProvider` in Domain.Shared or Domain.\n- Setting names must follow `Abp.[ModuleName].[SettingName]` convention.\n- Define features in `*FeatureDefinitionProvider` in Domain.Shared.\n- Feature names must follow `[ModuleName].[FeatureName]` convention.\n- Use constants for setting/feature names; never hardcode strings.\n\n---\n\n## Permissions\n\n- Define permissions in `*PermissionDefinitionProvider` in Application.Contracts.\n- Permission names must follow `[ModuleName].[Permission]` convention.\n- Use constants for permission names (e.g., `IdentityPermissions.Users.Create`).\n- Group related permissions logically.\n\n---\n\n## Event Bus & Distributed Events\n\n- Use `ILocalEventBus` for intra-module communication within the same process.\n- Use `IDistributedEventBus` for cross-module or cross-service communication.\n- Define Event Transfer Objects (ETOs) in Domain.Shared for distributed events.\n- ETO naming: `[EntityName][Action]Eto` (e.g., `UserCreatedEto`, `OrderCompletedEto`).\n- Event handlers belong in the Application layer.\n- ETOs should be simple, serializable, and contain only primitive types or nested ETOs.\n\n---\n\n## Testing\n\n- Unit tests: `*.Tests` projects for isolated logic testing with mocked dependencies.\n- Integration tests: `*.EntityFrameworkCore.Tests` / `*.MongoDB.Tests` for repository and DB tests.\n- Use `AbpIntegratedTest<TModule>` or `AbpApplicationTestBase<TModule>` base classes.\n- Test modules should use `[DependsOn]` on the module under test.\n- Use `Shouldly` assertions (ABP convention).\n- Test both EF Core and MongoDB implementations when the module supports both.\n- Include tests for permission checks, validation, and edge cases.\n- Name test methods: `MethodName_Scenario_ExpectedResult` or `Should_ExpectedBehavior_When_Condition`.\n\n---\n\n## Contribution Discipline (PR / Issues / Tests)\n\n- Before significant changes, align via GitHub issue/discussion.\n\n### PRs\n- Keep changes scoped and reviewable.\n- Add/update unit/integration tests relevant to the change.\n- Build and run tests for the impacted area when possible.\n\n### Localization\n- Prefer the `abp translate` workflow for adding missing translations (generate `abp-translation.json`, fill, apply, then PR).\n\n---\n\n## Review Checklist\n\n- [ ] Layer dependencies respected (no forbidden references).\n- [ ] No `IQueryable` leaking into public repository contracts.\n- [ ] Entities maintain invariants; Guid id generation not inside constructors.\n- [ ] Repositories follow async + CancellationToken + includeDetails conventions.\n- [ ] No web types in application services.\n- [ ] DTOs in contracts, validated, minimal, no logic.\n- [ ] EF/Mongo integration follows context + mapping + repository patterns.\n- [ ] Public members are `virtual` for extensibility.\n- [ ] Backward compatibility maintained; no breaking changes without deprecation.\n- [ ] Minimal diff; no unnecessary API surface expansion.\n"},"items":[{"name":".cursorrules","path":".cursorrules","title":".cursorrules","content":"# ABP Framework – Cursor Rules\n# Scope: ABP Framework repository (abpframework/abp) — for developing ABP itself, not ABP-based applications.\n# Goal: Enforce ABP module architecture best practices (DDD, layering, DB/ORM independence),\n# maintain backward compatibility, ensure extensibility, and align with ABP contribution guidelines.\n\n## Global Defaults\n- Follow existing patterns in this repository first. Before generating new code, search for similar implementations and mirror their structure, naming, and conventions.\n- Prefer minimal, focused diffs. Avoid drive-by refactors and formatting churn.\n- Preserve public APIs. Avoid breaking changes unless explicitly requested and justified.\n- Keep layers clean. Do not introduce forbidden dependencies between packages.\n\n## Module / Package Architecture (Layering)\n- Use a layered module structure with explicit dependencies:\n  - *.Domain.Shared: constants, enums, shared types safe for all layers and 3rd-party clients. MUST NOT contain entities, repositories, domain services, or business objects.\n  - *.Domain: entities/aggregate roots, repository interfaces, domain services.\n  - *.Application.Contracts: application service interfaces and DTOs.\n  - *.Application: application service implementations.\n  - *.EntityFrameworkCore / *.MongoDb: ORM integration packages depend on *.Domain only. MUST NOT depend on other layers.\n  - *.HttpApi: REST controllers. MUST depend ONLY on *.Application.Contracts (NOT *.Application).\n  - *.HttpApi.Client: remote client proxies. MUST depend ONLY on *.Application.Contracts.\n  - *.Web: UI. MUST depend ONLY on *.HttpApi.\n- Enforce dependency direction:\n  - Web -> HttpApi -> Application.Contracts\n  - Application -> Domain + Application.Contracts\n  - Domain -> Domain.Shared\n  - ORM integration -> Domain\n- Do not leak web concerns into application/domain.\n\n## Domain Layer – Entities & Aggregate Roots\n- Define entities in the domain layer.\n- Entities must be valid at creation:\n  - Provide a primary constructor that enforces invariants.\n  - Always include a protected parameterless constructor for ORMs.\n  - Always initialize sub-collections in the primary constructor.\n  - Do NOT generate Guid keys inside constructors; accept `id` and generate using `IGuidGenerator` from the calling code.\n- Make members `virtual` where appropriate (ORM/proxy compatibility).\n- Protect consistency:\n  - Use non-public setters (private/protected/internal) when needed.\n  - Provide meaningful domain methods for state transitions; prefer returning `this` from setters when applicable.\n- Aggregate roots:\n  - Always use a single `Id` property. Do NOT use composite keys.\n  - Prefer `Guid` keys for aggregate roots.\n  - Inherit from `AggregateRoot<TKey>` or audited base classes as required.\n- Aggregate boundaries:\n  - Keep aggregates small. Avoid large sub-collections unless necessary.\n- References:\n  - Reference other aggregate roots by Id only.\n  - Do NOT add navigation properties to other aggregate roots.\n\n## Repositories\n- Define repository interfaces in the domain layer.\n- Create one dedicated repository interface per aggregate root (e.g., `IProductRepository`).\n- Public repository interfaces exposed by modules:\n  - SHOULD inherit from `IBasicRepository<TEntity, TKey>` (or `IReadOnlyRepository<...>` when suitable).\n  - SHOULD NOT expose `IQueryable` in the public contract.\n  - Internal implementations MAY use `IRepository<TEntity, TKey>` and `IQueryable` as needed.\n- Do NOT define repositories for non-aggregate-root entities.\n- Repository method conventions:\n  - All methods async.\n  - Include optional `CancellationToken cancellationToken = default` in every method.\n  - For single-entity returning methods: include `bool includeDetails = true`.\n  - For list returning methods: include `bool includeDetails = false`.\n  - Do NOT return composite projection classes like `UserWithRoles`. Use `includeDetails` for eager-loading.\n  - Avoid projection-only view models from repositories by default; only allow when performance is critical.\n\n## Domain Services\n- Define domain services in the domain layer.\n- Default: do NOT create interfaces for domain services unless necessary (mocking/multiple implementations).\n- Naming: use `*Manager` suffix.\n- Domain service methods:\n  - Focus on operations that enforce domain invariants and business rules.\n  - Query methods are acceptable when they encapsulate domain-specific lookup logic (e.g., normalized lookups, caching, complex resolution). Simple queries belong in repositories.\n  - Define methods that mutate state and enforce domain rules.\n  - Use specific, intention-revealing names (avoid generic `UpdateXAsync`).\n  - Accept valid domain objects as parameters; do NOT accept/return DTOs.\n  - On rule violations, throw `BusinessException` (or custom business exceptions).\n  - Use unique, namespaced error codes suitable for localization (e.g., `IssueTracking:ConcurrentOpenIssueLimit`).\n  - Do NOT depend on authenticated user logic; pass required values from application layer.\n\n## Application Services (Contracts + Implementation)\n### Contracts\n- Define one interface per application service in *.Application.Contracts.\n- Interfaces must inherit from `IApplicationService`.\n- Naming: `I*AppService`.\n- Do NOT accept/return entities. Use DTOs and primitive parameters.\n\n### Method Naming & Shapes\n- All service methods async and end with `Async`.\n- Do not repeat entity names in method names (use `GetAsync`, not `GetProductAsync`).\n- Standard CRUD:\n  - `GetAsync(Guid id)` returns a detailed DTO.\n  - `GetListAsync(QueryDto queryDto)` returns a list of detailed DTOs.\n  - `CreateAsync(CreateDto dto)` returns detailed DTO.\n  - `UpdateAsync(Guid id, UpdateDto dto)` returns detailed DTO (id MUST NOT be inside update DTO).\n  - `DeleteAsync(Guid id)` returns void/Task.\n- `GetListAsync` query DTO:\n  - Filtering/sorting/paging fields optional with defaults.\n  - Enforce a maximum page size for performance.\n\n### DTO Usage\n- Inputs:\n  - Do not include unused properties.\n  - Do NOT share input DTOs between methods.\n  - Do NOT use inheritance between input DTOs (except rare abstract base DTO cases; be very cautious).\n\n### Implementation\n- Application layer must be independent of web.\n- Implement interfaces in *.Application, name `ProductAppService` for `IProductAppService`.\n- Inherit from `ApplicationService`.\n- Make all public methods `virtual`.\n- Avoid private helper methods; prefer `protected virtual` helpers for extensibility.\n- Data access:\n  - Use dedicated repositories (e.g., `IProductRepository`).\n  - Do NOT use generic repositories.\n  - Do NOT put LINQ/SQL queries inside application service methods; repositories perform queries.\n- Entity mutation:\n  - Load required entities from repositories.\n  - Mutate using domain methods.\n  - Call repository `UpdateAsync` after updates (do not assume change tracking).\n- Extra properties:\n  - Use `MapExtraPropertiesTo` or configure object mapper for `MapExtraProperties`.\n- Files:\n  - Do NOT use web types like `IFormFile` or `Stream` in application services.\n  - Controllers handle upload; pass `byte[]` (or similar) to application services.\n- Cross-application-service calls:\n  - Do NOT call other application services within the same module.\n  - For reuse, push logic into domain layer or extract shared helpers carefully.\n  - You MAY call other modules’ application services only via their Application.Contracts.\n\n## DTO Conventions\n- Define DTOs in *.Application.Contracts.\n- Prefer ABP base DTO types (`EntityDto<TKey>`, audited DTOs).\n- For aggregate roots, prefer extensible DTO base types so extra properties can map.\n- DTO properties: public getters/setters.\n- Input DTO validation:\n  - Use data annotations.\n  - Reuse constants from Domain.Shared wherever possible.\n- Avoid logic in DTOs; only implement `IValidatableObject` when necessary.\n- Do NOT use `[Serializable]` attribute (BinaryFormatter is obsolete); ABP uses JSON serialization.\n- Output DTO strategy:\n  - Prefer a Basic DTO and a Detailed DTO; avoid many variants.\n  - Detailed DTOs: include reference details as nested basic DTOs; avoid duplicating raw FK ids unnecessarily.\n\n## EF Core Integration\n- Define a separate DbContext interface + class per module.\n- Do NOT rely on lazy loading; do NOT enable lazy loading.\n- DbContext interface:\n  - Inherit from `IEfCoreDbContext`.\n  - Add `[ConnectionStringName(\"...\")]`.\n  - Expose `DbSet<TEntity>` ONLY for aggregate roots.\n  - Do NOT include setters in the interface.\n- DbContext class:\n  - Inherit `AbpDbContext<TDbContext>`.\n  - Add `[ConnectionStringName(\"...\")]` and implement the interface.\n- Table prefix/schema:\n  - Provide static `TablePrefix` and `Schema` defaulted from constants.\n  - Use short prefixes; `Abp` prefix reserved for ABP core modules.\n  - Default schema should be `null`.\n- Model mapping:\n  - Do NOT configure entities directly inside `OnModelCreating`.\n  - Create `ModelBuilder` extension method `ConfigureX()` and call it.\n  - Call `b.ConfigureByConvention()` for each entity.\n- Repository implementations:\n  - Inherit from `EfCoreRepository<TDbContextInterface, TEntity, TKey>`.\n  - Use DbContext interface as generic parameter.\n  - Pass cancellation tokens using `GetCancellationToken(cancellationToken)`.\n  - Implement `IncludeDetails(include)` extension per aggregate root with sub-collections.\n  - Override `WithDetailsAsync()` where needed.\n\n## MongoDB Integration\n- Define a separate MongoDbContext interface + class per module.\n- MongoDbContext interface:\n  - Inherit from `IAbpMongoDbContext`.\n  - Add `[ConnectionStringName(\"...\")]`.\n  - Expose `IMongoCollection<TEntity>` ONLY for aggregate roots.\n- MongoDbContext class:\n  - Inherit `AbpMongoDbContext` and implement the interface.\n- Collection prefix:\n  - Provide static `CollectionPrefix` defaulted from constants.\n  - Use short prefixes; `Abp` prefix reserved for ABP core modules.\n- Mapping:\n  - Do NOT configure directly inside `CreateModel`.\n  - Create `IMongoModelBuilder` extension method `ConfigureX()` and call it.\n- Repository implementations:\n  - Inherit from `MongoDbRepository<TMongoDbContextInterface, TEntity, TKey>`.\n  - Pass cancellation tokens using `GetCancellationToken(cancellationToken)`.\n  - Ignore `includeDetails` for MongoDB in most cases (documents load sub-collections).\n  - Prefer `GetQueryableAsync()` to ensure ABP data filters are applied.\n\n## ABP Module Classes\n- Every package must have exactly one `AbpModule` class.\n- Naming: `Abp[ModuleName][Layer]Module` (e.g., `AbpIdentityDomainModule`, `AbpIdentityApplicationModule`).\n- Use `[DependsOn(typeof(...))]` to declare module dependencies explicitly.\n- Override `ConfigureServices` for DI registration and configuration.\n- Override `OnApplicationInitialization` sparingly; prefer `ConfigureServices` when possible.\n- Each module must be usable standalone; avoid hidden cross-module coupling.\n\n## Framework Extensibility\n- All public and protected members should be `virtual` for inheritance-based extensibility.\n- Prefer `protected virtual` over `private` for helper methods to allow overriding.\n- Use `[Dependency(ReplaceServices = true)]` patterns for services intended to be replaceable.\n- Provide extension points via interfaces and virtual methods.\n- Document extension points with XML comments explaining intended usage.\n- Consider providing `*Options` classes for configuration-based extensibility.\n\n## Backward Compatibility\n- Do NOT remove or rename public API members without a deprecation cycle.\n- Use `[Obsolete(\"Message. Use X instead.\")]` with clear migration guidance before removal.\n- Maintain binary and source compatibility within major versions.\n- Add new optional parameters with defaults; do not change existing method signatures.\n- When adding new abstract members to base classes, provide default implementations if possible.\n- Prefer adding new interfaces over modifying existing ones.\n\n## Localization Resources\n- Define localization resources in Domain.Shared.\n- Resource class naming: `[ModuleName]Resource` (e.g., `IdentityResource`, `PermissionManagementResource`).\n- JSON files under `/Localization/[ModuleName]/` directory.\n- Use `LocalizableString.Create<TResource>(\"Key\")` for localizable exceptions and messages.\n- All user-facing strings must be localized; no hardcoded English text in code.\n- Error codes should be namespaced: `ModuleName:ErrorCode` (e.g., `Identity:UserNameAlreadyExists`).\n\n## Settings & Features\n- Define settings in `*SettingDefinitionProvider` in Domain.Shared or Domain.\n- Setting names must follow `Abp.[ModuleName].[SettingName]` convention.\n- Define features in `*FeatureDefinitionProvider` in Domain.Shared.\n- Feature names must follow `[ModuleName].[FeatureName]` convention.\n- Use constants for setting/feature names; never hardcode strings.\n\n## Permissions\n- Define permissions in `*PermissionDefinitionProvider` in Application.Contracts.\n- Permission names must follow `[ModuleName].[Permission]` convention.\n- Use constants for permission names (e.g., `IdentityPermissions.Users.Create`).\n- Group related permissions logically.\n\n## Event Bus & Distributed Events\n- Use `ILocalEventBus` for intra-module communication within the same process.\n- Use `IDistributedEventBus` for cross-module or cross-service communication.\n- Define Event Transfer Objects (ETOs) in Domain.Shared for distributed events.\n- ETO naming: `[EntityName][Action]Eto` (e.g., `UserCreatedEto`, `OrderCompletedEto`).\n- Event handlers belong in the Application layer.\n- ETOs should be simple, serializable, and contain only primitive types or nested ETOs.\n\n## Testing\n- Unit tests: `*.Tests` projects for isolated logic testing with mocked dependencies.\n- Integration tests: `*.EntityFrameworkCore.Tests` / `*.MongoDB.Tests` for repository and DB tests.\n- Use `AbpIntegratedTest<TModule>` or `AbpApplicationTestBase<TModule>` base classes.\n- Test modules should use `[DependsOn]` on the module under test.\n- Use `Shouldly` assertions (ABP convention).\n- Test both EF Core and MongoDB implementations when the module supports both.\n- Include tests for permission checks, validation, and edge cases.\n- Name test methods: `MethodName_Scenario_ExpectedResult` or `Should_ExpectedBehavior_When_Condition`.\n\n## Contribution Discipline (PR / Issues / Tests)\n- Before significant changes, align via GitHub issue/discussion.\n- PRs:\n  - Keep changes scoped and reviewable.\n  - Add/update unit/integration tests relevant to the change.\n  - Build and run tests for the impacted area when possible.\n- Localization:\n  - Prefer the `abp translate` workflow for adding missing translations (generate `abp-translation.json`, fill, apply, then PR).\n\n## Review Checklist\n- Layer dependencies respected (no forbidden references).\n- No `IQueryable` or generic repository usage leaking into application/domain.\n- Entities maintain invariants; Guid id generation not inside constructors.\n- Repositories follow async + CancellationToken + includeDetails conventions.\n- No web types in application services.\n- DTOs in contracts, serializable, validated, minimal, no logic.\n- EF/Mongo integration follows context + mapping + repository patterns.\n- Minimal diff; no unnecessary API surface expansion.\n","category":"root","tokens":3805},{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","title":"copilot-instructions.md","content":"# ABP Framework – GitHub Copilot Instructions\n\n> **Scope**: ABP Framework repository (abpframework/abp) — for developing ABP itself, not ABP-based applications.\n>\n> **Goal**: Enforce ABP module architecture best practices (DDD, layering, DB/ORM independence), maintain backward compatibility, ensure extensibility, and align with ABP contribution guidelines.\n\n---\n\n## Global Defaults\n\n- Follow existing patterns in this repository first. Before generating new code, search for similar implementations and mirror their structure, naming, and conventions.\n- Prefer minimal, focused diffs. Avoid drive-by refactors and formatting churn.\n- Preserve public APIs. Avoid breaking changes unless explicitly requested and justified.\n- Keep layers clean. Do not introduce forbidden dependencies between packages.\n\n---\n\n## Module / Package Architecture (Layering)\n\nUse a layered module structure with explicit dependencies:\n\n| Layer | Purpose | Allowed Dependencies |\n|-------|---------|---------------------|\n| `*.Domain.Shared` | Constants, enums, shared types safe for all layers and 3rd-party clients. MUST NOT contain entities, repositories, domain services, or business objects. | None |\n| `*.Domain` | Entities/aggregate roots, repository interfaces, domain services. | Domain.Shared |\n| `*.Application.Contracts` | Application service interfaces and DTOs. | Domain.Shared |\n| `*.Application` | Application service implementations. | Domain, Application.Contracts |\n| `*.EntityFrameworkCore` / `*.MongoDb` | ORM integration packages. MUST NOT depend on other layers. | Domain only |\n| `*.HttpApi` | REST controllers. MUST depend ONLY on Application.Contracts (NOT Application). | Application.Contracts |\n| `*.HttpApi.Client` | Remote client proxies. MUST depend ONLY on Application.Contracts. | Application.Contracts |\n| `*.Web` | UI layer. MUST depend ONLY on HttpApi. | HttpApi |\n\n### Dependency Direction\n```\nWeb -> HttpApi -> Application.Contracts\nApplication -> Domain + Application.Contracts\nDomain -> Domain.Shared\nORM integration -> Domain\n```\n\nDo not leak web concerns into application/domain.\n\n---\n\n## Domain Layer – Entities & Aggregate Roots\n\n- Define entities in the domain layer.\n- Entities must be valid at creation:\n  - Provide a primary constructor that enforces invariants.\n  - Always include a `protected` parameterless constructor for ORMs.\n  - Always initialize sub-collections in the primary constructor.\n  - Do NOT generate Guid keys inside constructors; accept `id` and generate using `IGuidGenerator` from the calling code.\n- Make members `virtual` where appropriate (ORM/proxy compatibility).\n- Protect consistency:\n  - Use non-public setters (`private`/`protected`/`internal`) when needed.\n  - Provide meaningful domain methods for state transitions.\n\n### Aggregate Roots\n- Always use a single `Id` property. Do NOT use composite keys.\n- Prefer `Guid` keys for aggregate roots.\n- Inherit from `AggregateRoot<TKey>` or audited base classes as required.\n- Keep aggregates small. Avoid large sub-collections unless necessary.\n\n### References\n- Reference other aggregate roots by Id only.\n- Do NOT add navigation properties to other aggregate roots.\n\n---\n\n## Repositories\n\n- Define repository interfaces in the domain layer.\n- Create one dedicated repository interface per aggregate root (e.g., `IProductRepository`).\n- Public repository interfaces exposed by modules:\n  - SHOULD inherit from `IBasicRepository<TEntity, TKey>` (or `IReadOnlyRepository<...>` when suitable).\n  - SHOULD NOT expose `IQueryable` in the public contract.\n  - Internal implementations MAY use `IRepository<TEntity, TKey>` and `IQueryable` as needed.\n- Do NOT define repositories for non-aggregate-root entities.\n\n### Method Conventions\n- All methods async.\n- Include optional `CancellationToken cancellationToken = default` in every method.\n- For single-entity returning methods: include `bool includeDetails = true`.\n- For list returning methods: include `bool includeDetails = false`.\n- Do NOT return composite projection classes like `UserWithRoles`. Use `includeDetails` for eager-loading.\n- Avoid projection-only view models from repositories by default; only allow when performance is critical.\n\n---\n\n## Domain Services\n\n- Define domain services in the domain layer.\n- Default: do NOT create interfaces for domain services unless necessary (mocking/multiple implementations).\n- Naming: use `*Manager` suffix.\n\n### Method Guidelines\n- Focus on operations that enforce domain invariants and business rules.\n- Query methods are acceptable when they encapsulate domain-specific lookup logic (e.g., normalized lookups, caching, complex resolution). Simple queries belong in repositories.\n- Define methods that mutate state and enforce domain rules.\n- Use specific, intention-revealing names (avoid generic `UpdateXAsync`).\n- Accept valid domain objects as parameters; do NOT accept/return DTOs.\n- On rule violations, throw `BusinessException` (or custom business exceptions).\n- Use unique, namespaced error codes suitable for localization (e.g., `IssueTracking:ConcurrentOpenIssueLimit`).\n- Do NOT depend on authenticated user logic; pass required values from application layer.\n\n---\n\n## Application Services\n\n### Contracts\n- Define one interface per application service in `*.Application.Contracts`.\n- Interfaces must inherit from `IApplicationService`.\n- Naming: `I*AppService`.\n- Do NOT accept/return entities. Use DTOs and primitive parameters.\n\n### Method Naming & Shapes\n- All service methods async and end with `Async`.\n- Do not repeat entity names in method names (use `GetAsync`, not `GetProductAsync`).\n\n**Standard CRUD:**\n```csharp\nTask<ProductDto> GetAsync(Guid id);\nTask<PagedResultDto<ProductDto>> GetListAsync(GetProductListInput input);\nTask<ProductDto> CreateAsync(CreateProductInput input);\nTask<ProductDto> UpdateAsync(Guid id, UpdateProductInput input);  // id NOT inside DTO\nTask DeleteAsync(Guid id);\n```\n\n### DTO Usage (Inputs)\n- Do not include unused properties.\n- Do NOT share input DTOs between methods.\n- Do NOT use inheritance between input DTOs (except rare abstract base DTO cases; be very cautious).\n\n### Implementation\n- Application layer must be independent of web.\n- Implement interfaces in `*.Application`, name `ProductAppService` for `IProductAppService`.\n- Inherit from `ApplicationService`.\n- Make all public methods `virtual`.\n- Avoid private helper methods; prefer `protected virtual` helpers for extensibility.\n\n### Data Access\n- Use dedicated repositories (e.g., `IProductRepository`).\n- Do NOT put LINQ/SQL queries inside application service methods; repositories perform queries.\n\n### Entity Mutation\n- Load required entities from repositories.\n- Mutate using domain methods.\n- Call repository `UpdateAsync` after updates (do not assume change tracking).\n\n### Files\n- Do NOT use web types like `IFormFile` or `Stream` in application services.\n- Controllers handle upload; pass `byte[]` (or similar) to application services.\n\n### Cross-Service Calls\n- Do NOT call other application services within the same module.\n- For reuse, push logic into domain layer or extract shared helpers carefully.\n- You MAY call other modules' application services only via their Application.Contracts.\n\n---\n\n## DTO Conventions\n\n- Define DTOs in `*.Application.Contracts`.\n- Prefer ABP base DTO types (`EntityDto<TKey>`, audited DTOs).\n- For aggregate roots, prefer extensible DTO base types so extra properties can map.\n- DTO properties: public getters/setters.\n\n### Input DTO Validation\n- Use data annotations.\n- Reuse constants from Domain.Shared wherever possible.\n\n### General Rules\n- Avoid logic in DTOs; only implement `IValidatableObject` when necessary.\n- Do NOT use `[Serializable]` attribute (BinaryFormatter is obsolete); ABP uses JSON serialization.\n\n### Output DTO Strategy\n- Prefer a Basic DTO and a Detailed DTO; avoid many variants.\n- Detailed DTOs: include reference details as nested basic DTOs; avoid duplicating raw FK ids unnecessarily.\n\n---\n\n## EF Core Integration\n\n- Define a separate DbContext interface + class per module.\n- Do NOT rely on lazy loading; do NOT enable lazy loading.\n\n### DbContext Interface\n```csharp\n[ConnectionStringName(\"ModuleName\")]\npublic interface IModuleNameDbContext : IEfCoreDbContext\n{\n    DbSet<Product> Products { get; }  // No setters, aggregate roots only\n}\n```\n\n### DbContext Class\n```csharp\n[ConnectionStringName(\"ModuleName\")]\npublic class ModuleNameDbContext : AbpDbContext<ModuleNameDbContext>, IModuleNameDbContext\n{\n    public static string TablePrefix { get; set; } = ModuleNameConsts.DefaultDbTablePrefix;\n    public static string? Schema { get; set; } = ModuleNameConsts.DefaultDbSchema;\n    \n    public DbSet<Product> Products { get; set; }\n}\n```\n\n### Table Prefix/Schema\n- Provide static `TablePrefix` and `Schema` defaulted from constants.\n- Use short prefixes; `Abp` prefix reserved for ABP core modules.\n- Default schema should be `null`.\n\n### Model Mapping\n- Do NOT configure entities directly inside `OnModelCreating`.\n- Create `ModelBuilder` extension method `ConfigureX()` and call it.\n- Call `b.ConfigureByConvention()` for each entity.\n\n### Repository Implementations\n- Inherit from `EfCoreRepository<TDbContextInterface, TEntity, TKey>`.\n- Use DbContext interface as generic parameter.\n- Pass cancellation tokens using `GetCancellationToken(cancellationToken)`.\n- Implement `IncludeDetails(include)` extension per aggregate root with sub-collections.\n- Override `WithDetailsAsync()` where needed.\n\n---\n\n## MongoDB Integration\n\n- Define a separate MongoDbContext interface + class per module.\n\n### MongoDbContext Interface\n```csharp\n[ConnectionStringName(\"ModuleName\")]\npublic interface IModuleNameMongoDbContext : IAbpMongoDbContext\n{\n    IMongoCollection<Product> Products { get; }  // Aggregate roots only\n}\n```\n\n### MongoDbContext Class\n```csharp\npublic class ModuleNameMongoDbContext : AbpMongoDbContext, IModuleNameMongoDbContext\n{\n    public static string CollectionPrefix { get; set; } = ModuleNameConsts.DefaultDbTablePrefix;\n}\n```\n\n### Mapping\n- Do NOT configure directly inside `CreateModel`.\n- Create `IMongoModelBuilder` extension method `ConfigureX()` and call it.\n\n### Repository Implementations\n- Inherit from `MongoDbRepository<TMongoDbContextInterface, TEntity, TKey>`.\n- Pass cancellation tokens using `GetCancellationToken(cancellationToken)`.\n- Ignore `includeDetails` for MongoDB in most cases (documents load sub-collections).\n- Prefer `GetQueryableAsync()` to ensure ABP data filters are applied.\n\n---\n\n## ABP Module Classes\n\n- Every package must have exactly one `AbpModule` class.\n- Naming: `Abp[ModuleName][Layer]Module` (e.g., `AbpIdentityDomainModule`, `AbpIdentityApplicationModule`).\n- Use `[DependsOn(typeof(...))]` to declare module dependencies explicitly.\n- Override `ConfigureServices` for DI registration and configuration.\n- Override `OnApplicationInitialization` sparingly; prefer `ConfigureServices` when possible.\n- Each module must be usable standalone; avoid hidden cross-module coupling.\n\n---\n\n## Framework Extensibility\n\n- All public and protected members should be `virtual` for inheritance-based extensibility.\n- Prefer `protected virtual` over `private` for helper methods to allow overriding.\n- Use `[Dependency(ReplaceServices = true)]` patterns for services intended to be replaceable.\n- Provide extension points via interfaces and virtual methods.\n- Document extension points with XML comments explaining intended usage.\n- Consider providing `*Options` classes for configuration-based extensibility.\n\n---\n\n## Backward Compatibility\n\n- Do NOT remove or rename public API members without a deprecation cycle.\n- Use `[Obsolete(\"Message. Use X instead.\")]` with clear migration guidance before removal.\n- Maintain binary and source compatibility within major versions.\n- Add new optional parameters with defaults; do not change existing method signatures.\n- When adding new abstract members to base classes, provide default implementations if possible.\n- Prefer adding new interfaces over modifying existing ones.\n\n---\n\n## Localization Resources\n\n- Define localization resources in Domain.Shared.\n- Resource class naming: `[ModuleName]Resource` (e.g., `IdentityResource`, `PermissionManagementResource`).\n- JSON files under `/Localization/[ModuleName]/` directory.\n- Use `LocalizableString.Create<TResource>(\"Key\")` for localizable exceptions and messages.\n- All user-facing strings must be localized; no hardcoded English text in code.\n- Error codes should be namespaced: `ModuleName:ErrorCode` (e.g., `Identity:UserNameAlreadyExists`).\n\n---\n\n## Settings & Features\n\n- Define settings in `*SettingDefinitionProvider` in Domain.Shared or Domain.\n- Setting names must follow `Abp.[ModuleName].[SettingName]` convention.\n- Define features in `*FeatureDefinitionProvider` in Domain.Shared.\n- Feature names must follow `[ModuleName].[FeatureName]` convention.\n- Use constants for setting/feature names; never hardcode strings.\n\n---\n\n## Permissions\n\n- Define permissions in `*PermissionDefinitionProvider` in Application.Contracts.\n- Permission names must follow `[ModuleName].[Permission]` convention.\n- Use constants for permission names (e.g., `IdentityPermissions.Users.Create`).\n- Group related permissions logically.\n\n---\n\n## Event Bus & Distributed Events\n\n- Use `ILocalEventBus` for intra-module communication within the same process.\n- Use `IDistributedEventBus` for cross-module or cross-service communication.\n- Define Event Transfer Objects (ETOs) in Domain.Shared for distributed events.\n- ETO naming: `[EntityName][Action]Eto` (e.g., `UserCreatedEto`, `OrderCompletedEto`).\n- Event handlers belong in the Application layer.\n- ETOs should be simple, serializable, and contain only primitive types or nested ETOs.\n\n---\n\n## Testing\n\n- Unit tests: `*.Tests` projects for isolated logic testing with mocked dependencies.\n- Integration tests: `*.EntityFrameworkCore.Tests` / `*.MongoDB.Tests` for repository and DB tests.\n- Use `AbpIntegratedTest<TModule>` or `AbpApplicationTestBase<TModule>` base classes.\n- Test modules should use `[DependsOn]` on the module under test.\n- Use `Shouldly` assertions (ABP convention).\n- Test both EF Core and MongoDB implementations when the module supports both.\n- Include tests for permission checks, validation, and edge cases.\n- Name test methods: `MethodName_Scenario_ExpectedResult` or `Should_ExpectedBehavior_When_Condition`.\n\n---\n\n## Contribution Discipline (PR / Issues / Tests)\n\n- Before significant changes, align via GitHub issue/discussion.\n\n### PRs\n- Keep changes scoped and reviewable.\n- Add/update unit/integration tests relevant to the change.\n- Build and run tests for the impacted area when possible.\n\n### Localization\n- Prefer the `abp translate` workflow for adding missing translations (generate `abp-translation.json`, fill, apply, then PR).\n\n---\n\n## Review Checklist\n\n- [ ] Layer dependencies respected (no forbidden references).\n- [ ] No `IQueryable` leaking into public repository contracts.\n- [ ] Entities maintain invariants; Guid id generation not inside constructors.\n- [ ] Repositories follow async + CancellationToken + includeDetails conventions.\n- [ ] No web types in application services.\n- [ ] DTOs in contracts, validated, minimal, no logic.\n- [ ] EF/Mongo integration follows context + mapping + repository patterns.\n- [ ] Public members are `virtual` for extensibility.\n- [ ] Backward compatibility maintained; no breaking changes without deprecation.\n- [ ] Minimal diff; no unnecessary API surface expansion.\n","category":".github","tokens":3884}]}