feat: initial project setup
- Add .NET 8 backend with Clean Architecture - Add React + Vite + TypeScript frontend - Implement authentication with JWT - Implement Azure Blob Storage client - Implement OCR integration - Implement supplier matching service - Implement voucher generation - Implement Fortnox provider - Add unit and integration tests - Add Docker Compose configuration
This commit is contained in:
Invoice Master
194
AGENTS.md
Normal file
194
AGENTS.md
Normal file
@@ -0,0 +1,194 @@
|
||||
# Invoice Master - Multi-Accounting System Integration
|
||||
|
||||
Invoice Master - 多会计系统集成平台，支持 Fortnox、Visma、Hogia 等瑞典及北欧会计软件。
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Component | Technology |
|
||||
|-----------|------------|
|
||||
| Backend Framework | .NET 10 + ASP.NET Core |
|
||||
| Database | PostgreSQL + EF Core |
|
||||
| ORM | Entity Framework Core |
|
||||
| API Documentation | Swagger/OpenAPI |
|
||||
| Authentication | JWT Bearer Tokens |
|
||||
| HTTP Client | HttpClient + Polly |
|
||||
| Logging | Serilog + Structured Logging |
|
||||
| Testing | xUnit + Moq + FluentAssertions |
|
||||
| Frontend | React 18 + TypeScript + Vite |
|
||||
|
||||
## Development Environment
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- .NET 10 SDK
|
||||
- Node.js 18+
|
||||
- PostgreSQL 15+
|
||||
- Redis 7+ (optional, for caching)
|
||||
|
||||
### Running the Application
|
||||
|
||||
```bash
|
||||
# Backend
|
||||
cd backend
|
||||
dotnet restore
|
||||
dotnet run --project src/InvoiceMaster.API
|
||||
|
||||
# Frontend
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## Project-Specific Rules
|
||||
|
||||
### .NET Development
|
||||
|
||||
- Use .NET 8 with C# 12 features
|
||||
- Use primary constructors where appropriate
|
||||
- Use `required` properties for mandatory fields
|
||||
- Use `record` types for DTOs and immutable data
|
||||
- Use `IResult` for minimal API responses
|
||||
- Use `ProblemDetails` for error responses
|
||||
- No `Console.WriteLine()` in production - use `ILogger<T>`
|
||||
- Run tests: `dotnet test --verbosity normal`
|
||||
|
||||
### Entity Framework
|
||||
|
||||
- Use Code-First migrations
|
||||
- Use `IQueryable` for database queries
|
||||
- Use eager loading (`Include`, `ThenInclude`) to avoid N+1
|
||||
- Use raw SQL only when necessary with `FromSqlRaw`
|
||||
- Always use parameterized queries
|
||||
- Migrations naming: `Add{FeatureName}To{TableName}`
|
||||
|
||||
### Async/Await Best Practices
|
||||
|
||||
- Use `async`/`await` for all I/O operations
|
||||
- Use `CancellationToken` for cancellable operations
|
||||
- Avoid `async void` - use `async Task` instead
|
||||
- Use `ConfigureAwait(false)` in library code
|
||||
- Name async methods with `Async` suffix
|
||||
|
||||
## Critical Rules
|
||||
|
||||
### Code Organization
|
||||
|
||||
- Many small files over few large files
|
||||
- High cohesion, low coupling
|
||||
- 200-400 lines typical, 800 max per file
|
||||
- Organize by feature/domain, not by type
|
||||
- Use vertical slice architecture for features
|
||||
|
||||
### Code Style
|
||||
|
||||
- No emojis in code, comments, or documentation
|
||||
- Immutability always - never mutate objects or arrays
|
||||
- No `console.log` in production code
|
||||
- Proper error handling with try/catch
|
||||
- Input validation with FluentValidation or Data Annotations
|
||||
- Use `readonly` for fields that don't change after construction
|
||||
|
||||
### Testing
|
||||
|
||||
- TDD: Write tests first
|
||||
- 80% minimum coverage
|
||||
- Unit tests for utilities and services
|
||||
- Integration tests for APIs (use TestServer)
|
||||
- E2E tests for critical flows
|
||||
- Use `IClassFixture` for shared test context
|
||||
- Use `CollectionDefinition` for test collections
|
||||
|
||||
### Security
|
||||
|
||||
- No hardcoded secrets
|
||||
- Environment variables for sensitive data
|
||||
- Validate all user inputs
|
||||
- Use parameterized queries (EF Core does this automatically)
|
||||
- Enable CSRF protection
|
||||
- Use HTTPS redirection in production
|
||||
- Store passwords with bcrypt/Argon2 (use Identity)
|
||||
|
||||
## Environment Variables
|
||||
|
||||
```bash
|
||||
# Required
|
||||
DB_PASSWORD=
|
||||
JWT_SECRET_KEY=
|
||||
|
||||
# Optional (with defaults)
|
||||
DB_HOST=localhost
|
||||
DB_PORT=5432
|
||||
DB_NAME=invoice_master
|
||||
DB_USER=postgres
|
||||
ASPNETCORE_ENVIRONMENT=Development
|
||||
ASPNETCORE_URLS=http://localhost:5000
|
||||
|
||||
# Provider-specific (at least one required)
|
||||
FORTNOX_CLIENT_ID=
|
||||
FORTNOX_CLIENT_SECRET=
|
||||
FORTNOX_REDIRECT_URI=http://localhost:5173/accounting/fortnox/callback
|
||||
|
||||
# OCR API
|
||||
OCR_API_URL=http://localhost:8000/api/v1
|
||||
OCR_API_KEY=
|
||||
|
||||
# Azure Blob Storage
|
||||
AZURE_STORAGE_CONNECTION_STRING=
|
||||
AZURE_STORAGE_CONTAINER=documents
|
||||
```
|
||||
|
||||
## Available Commands
|
||||
|
||||
- `/tdd` - Test-driven development workflow
|
||||
- `/plan` - Create implementation plan
|
||||
- `/code-review` - Review code quality
|
||||
- `/build-fix` - Fix build errors
|
||||
|
||||
## Git Workflow
|
||||
|
||||
- Conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`
|
||||
- Never commit to main directly
|
||||
- PRs require review
|
||||
- All tests must pass before merge
|
||||
- Commit the code for each phase
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
backend/
|
||||
├── src/
|
||||
│ ├── InvoiceMaster.API/ # Web API entry point
|
||||
│ ├── InvoiceMaster.Core/ # Domain models, interfaces
|
||||
│ ├── InvoiceMaster.Application/ # Business logic, services
|
||||
│ ├── InvoiceMaster.Infrastructure/ # EF Core, external clients
|
||||
│ └── InvoiceMaster.Integrations/ # Accounting system providers
|
||||
└── tests/
|
||||
├── InvoiceMaster.UnitTests/
|
||||
├── InvoiceMaster.IntegrationTests/
|
||||
└── InvoiceMaster.ArchitectureTests/
|
||||
```
|
||||
|
||||
## Useful Guides
|
||||
|
||||
- API_DESIGN.md
|
||||
- ARCHITECTURE.md
|
||||
- DATABASE_SCHEMA.md
|
||||
- DEPLOYMENT_GUIDE.md
|
||||
- DEVELOPMENT_PLAN.md
|
||||
- DIRECTORY_STRUCTURE.md
|
||||
|
||||
## Project Memory Rules
|
||||
|
||||
Must proactively invoke the progress-recorder skill to record key information such as important decisions, task changes, completed items, etc., into progress.md.
|
||||
|
||||
Automatically trigger progress-recorder immediately when any of the following are detected:
|
||||
|
||||
Decision-related language such as “decide to use / final choice / will adopt”
|
||||
|
||||
Constraint-related language such as “must / must not / required”
|
||||
|
||||
Completion indicators such as “completed / implemented / fixed”
|
||||
|
||||
New task indicators such as “need to / should / plan to”
|
||||
|
||||
When the Notes/Done entries in progress.md become too numerous (>100 items) and affect readability, they should be archived to progress.archive.md.
|
||||
Reference in New Issue
Block a user