# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

### Building
- **Build entire solution**: `dotnet build Centron.sln`
- **Build specific project**: `dotnet build src/centron/Centron.WPF.UI/Centron.WPF.UI.csproj`
- **Build for Release**: `dotnet build Centron.sln -c Release`

### Testing
- **Run all tests**: `dotnet test Centron.sln`
- **Run specific test project**: `dotnet test tests/backend/Centron.Tests.BL/Centron.Tests.BL.csproj`
- **Run integration tests**: `dotnet test tests/Centron.Tests.Integration/Centron.Tests.Integration.csproj`
- **Run end-to-end tests**: `dotnet test tests/Centron.Tests.EndToEnd/Centron.Tests.EndToEnd.csproj`

### Using Centron.Scripts Build System
The project uses a custom build system via Centron.Scripts for complete builds:

```bash
cd scripts/Centron.Scripts
dotnet run -- <target>
```

Available targets:
- `clean` - Clean artifacts and bin/obj directories
- `setup-versioning` - Set up version information
- `build-web-service` - Build the web service components
- `build-centron-net` - Build the WPF client application
- `run-tests` - Execute all test suites
- `create-installers` - Build MSI installers

### Publishing
- **Publish WPF UI**: `dotnet publish src/centron/Centron.WPF.UI/Centron.WPF.UI.csproj -c Release -r win-x64 --self-contained`
- **Publish Web Service**: `dotnet publish src/webservice/Centron.Host.WindowsService/Centron.Host.WindowsService.csproj -c Release -r win-x64 --self-contained`

## Project Architecture

### High-Level Structure
This is a .NET 8 enterprise application with a multi-layered architecture:

```
src/
├── apis/              - External API integrations (FinAPI, GLS, Shipcloud, etc.)
├── backend/           - Core business logic layer
│   ├── Centron.BL/           - Business Logic layer
│   ├── Centron.Common/       - Common utilities and helpers
│   ├── Centron.DAO/          - Data Access Objects (NHibernate)
│   ├── Centron.Entities/     - Domain entities
│   ├── Centron.Gateway/      - External service gateways
│   └── Centron.Interfaces/   - Service interfaces
├── centron/           - WPF client application
│   ├── Centron.WPF.UI/           - Main WPF application
│   └── Centron.WPF.UI.Extension/ - UI extensions
├── shared/            - Shared components and controls
│   ├── Centron.Core/         - Core shared functionality
│   ├── Centron.Controls/     - Custom UI controls
│   └── Centron.Controls.Preview/ - Preview controls
└── webservice/        - Web service components
    ├── Centron.Host/                    - Web service host
    ├── Centron.Host.Console/            - Console host
    ├── Centron.Host.WindowsService/     - Windows service host
    ├── Centron.WebServices.Core/        - Web service core
    └── c-entron.misc.ConnectionManager/ - Connection management
```

### Data Access Pattern
The application uses a dual data access pattern supporting both direct database access and web service communication:

#### WPF UI Architecture (3-layer pattern | ILogic Interface Pattern)
All data operations in the UI must use the ILogic interface accessed through ClassContainer:
- WPF UI modules use a 3-part data access pattern:
    - I{Module}Logic interface - Defines the contract
    - BL{Module}Logic (NHibernate/SQL Server) - Direct database access via NHibernate
    - WS{Module}Logic (REST API) - Web service access via REST API
- Access via ClassContainer.Instance.WithInstance((ILogic logic) => ...).ThrowIfError();
- Connection types controlled by AppModuleController:
    - CentronConnectionType.CentronWebServices ➜ WSLogic
    - CentronConnectionType.SqlServer ➜ BLLogic

```csharp
var result = await ClassContainer
    .Instance
    .WithInstance((IAccountContractsLogic logic) => logic.GetAccountContracts(filter))
    .ThrowIfError();
```

#### Backend Architecture (2-layer pattern)
- Backend uses a 2-layer BL approach for web service implementation:
    - Base BL class (e.g., AccountDeviceBL) - contains core business logic and database access via DAO
    - WebService BL class (e.g., AccountDeviceWebServiceBL) - handles DTO conversion and calls base BL
- WebService BL pattern:
    - Inherits from BaseBL and creates instance of corresponding base BL class
    - Converts DTOs to entities using conversion methods (ConvertAccountDeviceDTOToAccountDevice)
    - Uses ObjectMapper for entity-to-DTO conversion
    - Ensures DTO entities are not connected to NHibernate database context for API security
- API implementation in ICentronRestService and CentronRestService:
    - API methods call WebService BL classes
    - All API operations use DTO entities for data transfer
    - Example: SaveAccountDevice API method → AccountDeviceWebServiceBL.SaveAccountDevice → AccountDeviceBL.SaveAccountDevice

### Technology Stack
- **.NET 8** - Primary framework
- **WPF** - Desktop UI framework
- **NHibernate** with **FluentNHibernate** - ORM for database access
- **DevExpress 24.2.7** - UI controls and components
- **Bullseye** - Build orchestration
- **Entity Framework** - Some components use EF alongside NHibernate

### Connection Types
Modules support different connection types declared in AppModuleController:
- `CentronConnectionType.CentronWebServices` - Uses WSLogic implementation
- `CentronConnectionType.SqlServer` - Uses BLLogic implementation

## Development Guidelines

### Code Style and Standards
- KISS
- DRY
- SOLID
- Clean Architecture

### General Rules
- Write self-explanatory code and only comment when absolutely necessary
- When updating code, always update DocStrings

### Language Requirements
- All user-facing content must be in German (primary market)
- Support for English through localization files
- Use German resource files (LocalizedStrings.resx) and English (LocalizedStrings.en.resx)

### File Encoding
- All C# source files (*.cs) must use UTF-8 with BOM
- All XAML files (*.xaml) must use UTF-8 with BOM

### Naming Conventions
- ILogic interfaces: `I{Module}Logic`
- BL implementations: `BL{Module}Logic`
- WS implementations: `WS{Module}Logic`
- All methods return `Result<T>` or `Task<Result<T>>`

### Code Signing (Optional)
Set environment variables for code signing:
- `CENTRON_BUILD_CODE_SIGNING_CERTIFICATE` - Path to certificate
- `CENTRON_BUILD_CODE_SIGNING_CERTIFICATE_PASSWORD` - Certificate password

## Database
- Uses NHibernate ORM with SQL Server
- Configuration files generated during build process
- Test databases required for end-to-end testing

## Development Processes

### Database Schema Changes

#### Creating Database Scripts
1. **Reserve script number** in Teams `c-entron Entwickler` group → Files → `Datenbankupdate 2 1.xlsx`
2. **Create script class** at `src/backend/Centron.BL/Administration/Scripts/ScriptMethods/Scripts/ScriptMethod{number}.cs`
3. **Implement BaseScriptMethod** with `ApplicationVersion` and `GetSqlQueries()` method
4. **Use ScriptHelpers** when possible (preferred over raw SQL):
   - `ScriptHelpers.AddColumnIfNotExists()`
   - `ScriptHelpers.AddTableIfNotExists()`
   - `ScriptHelpers.AddRightIfNotExists()`
   - `ScriptHelpers.AddIndexIfNotExists()`
   - `ScriptHelpers.AddForeignKeyIfNotExists()`

#### Database Conventions
- **Primary Key**: Every table must have `I3D` [int] IDENTITY(1,1) NOT NULL
- **Foreign Keys**: Must end with `I3D` suffix (e.g., `AccountI3D`)
- **Standard Columns**: Include `CreatedByI3D`, `CreatedDate`, `ChangedByI3D`, `ChangedDate`, `IsDeleted`, `DeletedByI3D`, `DeletedDate`
- **Data Types**: Use `nvarchar` over `varchar`, `datetime2(2)` for timestamps, `bit` for booleans
- **Naming**: New tables/columns use English names (historical German names remain unchanged)

### Settings Management

#### Application Settings
- **Legacy settings**: Stored in `Stammdat` table (read-only, no new additions)
- **New settings**: Use `ApplicationSettings` table exclusively
- **Setting IDs**: Get next available ID from comment in `src/backend/Centron.Interfaces/Administration/Settings/ApplicationSettingID.cs`
- **Descriptions**: Add to `ApplicationSettingDefinitions.cs`

#### Adding New Settings
1. Check next available ID in `ApplicationSettingID.cs`
2. Add enum value with new ID
3. Update "Next Centron Settings ID" comment
4. Add description in `ApplicationSettingDefinitions.cs`
5. Create group setting classes for accessing settings
6. Use `AppSettingsBL.GetSettings()` and `GetSettingsForUpdate()`

### User Rights Management

#### Adding New Rights
1. **Open** `UserRightsConst.cs` to get next I3D
2. **Create script** using `ScriptHelpers.AddRightIfNotExists()`:
   ```csharp
   yield return ScriptHelpers.AddRightIfNotExists(
       UserRightsConst.Sales.Customer.Helpdesk.SHOW_HOURLYSURCHARGERATES,
       UserRightsConst.Sales.Customer.Helpdesk.ID,
       "German display name",
       "German description");
   ```
3. **Add constant** to `UserRightsConst.cs`

### Web Service Development

#### Creating Web Service Methods (Full Stack)
1. **BL Layer**: Create method in `{Entity}BL.cs` returning `Result<T>`
2. **WebServiceBL**: Create `{Entity}WebServiceBL.cs` with DTO↔Entity conversion
3. **RestService**: Add method to `CentronRestService.cs` accepting `Request<T>` and returning `Response<T>`
4. **Interface**: Add method signature to `ICentronRestService.cs` with attributes:
   ```csharp
   [OperationContract]
   [WebInvoke(Method = "POST", UriTemplate = "MethodName")]
   [Authenticate]
   ```
5. **Logic Interfaces**: Create `I{Entity}Logic`, `BL{Entity}Logic`, `WS{Entity}Logic`

#### Request Classes
- Place in `Centron.WebServices.Core/RestRequests/`
- Decorate with `[DataContract]` and `[DataMember]` attributes
- Use for complex parameters instead of multiple individual parameters

### UI Development

#### Creating WPF Modules
1. **AppModuleController**: Implement `ICentronAppModuleController`
2. **View**: Create `UserControl` inheriting from `BaseModule`
3. **ViewModel**: Inherit from `BindableBase`
4. **Ribbon**: Implement `IRibbonControlModule` interface variations
5. **Registration**: Add to `ModuleRegistration.cs` with rights and feature checks

#### Localization Requirements
- **Resource Files**:
  - German (default): `LocalizedStrings.resx`
  - English: `LocalizedStrings.en.resx`
- **XAML Usage**: `{x:Static properties:LocalizedStrings.KeyName}`
- **Code Usage**: Direct access via `LocalizedStrings.KeyName`
- **Key Format**: `{ClassName}_{MethodName}_{Description}`
- **Tool**: Use ResXManager Visual Studio extension

### Accessing Data in Client Code

#### Single Use
```csharp
var result = await ClassContainer.Instance
    .WithInstance((IEntityLogic logic) => logic.GetEntity(id))
    .ThrowIfError();
```

#### Multiple Uses (with proper disposal)
```csharp
public class ViewModel : IDisposable
{
    private readonly IEntityLogic _logic;

    public ViewModel()
    {
        _logic = ClassContainer.Instance.GetInstance<IEntityLogic>();
    }

    public void Dispose()
    {
        ClassContainer.Instance.ReleaseInstance(_logic);
    }
}
```

## Documentation

### Creating Documentation
When adding new documentation to the project:

1. **Choose the right location** within the existing `docs/` structure:
   - `docs/getting-started/` - Beginner guides and introductory material
   - `docs/guides/development/` - Development task guides
   - `docs/guides/database/` - Database-related guides
   - `docs/guides/ui/` - UI development guides
   - `docs/guides/services/` - Web services guides
   - `docs/reference/architecture/` - Architecture specifications
   - `docs/reference/database/` - Database reference documentation
   - `docs/reference/receipts/` - Receipts system documentation
   - `docs/reference/security/` - Security documentation
   - `docs/operations/` - Operational procedures

2. **Name the file appropriately** using kebab-case (e.g., `actionprice-system.md`)

3. **Create the file** with UTF-8 with BOM encoding, using proper Markdown format

4. **Update navigation** in `docs/README.md`:
   - Add a new entry with a link to your documentation file
   - Follow the existing pattern and place in appropriate section

5. **Update the Solution File** (`Centron.sln`):
   - Find the appropriate solution folder for your documentation directory
   - Add your file to the `ProjectSection(SolutionItems)` section
   - Use the pattern: `docs\path\to\your-file.md = docs\path\to\your-file.md`

### Documentation Standards
- Use UTF-8 with BOM encoding for all documentation files
- Start with a `#` heading that clearly describes the content
- Use proper Markdown formatting for headings, lists, code blocks, etc.
- Include links to related documentation when appropriate
- For internal links, use relative paths to other documentation files

## Important Notes
- Project uses custom versioning via Nerdbank.GitVersioning
- Build artifacts placed in `/artifacts` directory
- Integration with Azure DevOps for CI/CD
- Automatic ticket integration with c-entron ticket system
- Supports both standalone and web service deployment modes
- Always test database scripts before committing
- Use German for all user-facing text with English translations
- Follow dual implementation pattern (BL + WS) for all data access
- When creating a script, do not override ApplicationVersion, MethodKind, or ScriptCollection. These are legacy properties.
- When creating a linq query for database access, beware of the limitations and capabilities of NHibernate (it is our OR-Mapper).