accounting-system/AGENTS.md

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

# 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

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