diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..956a5f6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,202 @@ +# AGENTS.md - EmailBill Project Guidelines + +Full-stack budget tracking app with .NET 10 backend and Vue 3 frontend. + +## Project Structure + +``` +EmailBill/ +├── Common/ # Shared utilities and abstractions +├── Entity/ # Database entities (FreeSql ORM) +├── Repository/ # Data access layer +├── Service/ # Business logic layer +├── WebApi/ # ASP.NET Core Web API +├── WebApi.Test/ # Backend tests (xUnit) +└── Web/ # Vue 3 frontend (Vite + Vant UI) +``` + +## Build & Test Commands + +### Backend (.NET 10) +```bash +# Build and run +dotnet build EmailBill.sln +dotnet run --project WebApi/WebApi.csproj + +# Run all tests +dotnet test WebApi.Test/WebApi.Test.csproj + +# Run single test class +dotnet test --filter "FullyQualifiedName~BudgetStatsTest" + +# Run single test method +dotnet test --filter "FullyQualifiedName~BudgetStatsTest.GetCategoryStats_月度_Test" + +# Clean +dotnet clean EmailBill.sln +``` + +### Frontend (Vue 3) +```bash +cd Web + +# Setup and dev +pnpm install +pnpm dev + +# Build and preview +pnpm build +pnpm preview + +# Lint and format +pnpm lint # ESLint with auto-fix +pnpm format # Prettier formatting +``` + +## C# Code Style + +**Namespaces & Imports:** +- File-scoped namespaces: `namespace Entity;` +- Global usings in `Common/GlobalUsings.cs` +- Sort using statements alphabetically + +**Naming:** +- Classes/Methods: `PascalCase` +- Interfaces: `IPascalCase` +- Private fields: `_camelCase` +- Parameters/locals: `camelCase` + +**Entities:** +- Inherit from `BaseEntity` +- Use `[Column]` attributes for FreeSql ORM +- IDs via Snowflake: `YitIdHelper.NextId()` +- Use XML docs (`///`) for public APIs +- **Chinese comments for business logic** (per `.github/csharpe.prompt.md`) + +**Best Practices:** +- Use modern C# syntax (records, pattern matching, nullable types) +- Use `IDateTimeProvider` instead of `DateTime.Now` for testability +- Avoid deep nesting, keep code flat and readable +- Reuse utilities from `Common` project + +**Example:** +```csharp +namespace Entity; + +/// +/// 实体基类 +/// +public abstract class BaseEntity +{ + [Column(IsPrimary = true)] + public long Id { get; set; } = YitIdHelper.NextId(); + + public DateTime CreateTime { get; set; } = DateTime.Now; +} +``` + +## Vue/TypeScript Style + +**Component Structure:** +```vue + + + + + +``` + +**Rules:** +- Composition API with `