# 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.