# c-entron.NET

> ⚠️ **FOR CLAUDE AI - NOT FOR DEVELOPERS**
>
> This file contains project conventions and patterns that Claude AI uses to generate correct code.
> **Developers**: See [.claude/README.md](.claude/README.md) for user documentation.

> **v2.1.0** | 2025-01-20 | ERP for German SMBs | C# .NET 8 | WPF + REST API

## Stack
**Core**: C# 12, .NET 8 | **Frontend**: WPF + Blazor Server, DevExpress 24.2.7 (WPF & Blazor), MVVM | **Backend**: ASP.NET Core 8, SQL Server 2019+, NHibernate 5.x, JWT auth | **Real-Time**: SignalR | **Build**: Azure DevOps, Centron.Scripts, WiX MSI | **Test**: NUnit

## Structure
```
src/
├── apis/          - External integrations (FinAPI, GLS, Shipcloud, ITscope, etc.)
├── backend/       - BL, DAO, Entities, Interfaces, EDI
├── centron/       - WPF UI (Desktop)
├── CentronNexus/  - Blazor Server (Web Portal)
├── shared/        - Core, Controls
└── webservice/    - REST API, Hosts
tests/ - BL, DAO, Integration, E2E
.claude/ - agents/, commands/, hooks/, settings.json
```

**Key Files**: `src/centron/Centron.WPF.UI/App.xaml.cs` (WPF), `src/webservice/Centron.Host.WindowsService/Program.cs` (Service), `Centron.sln`, `version.json`

## Naming
- **C# Classes**: `PascalCase`, Interfaces: `IPascalCase`, Methods: `PascalCase`, Private: `_camelCase`, Local: `camelCase`
- **DB Tables**: `PascalCase` English (new), Keep German (legacy), PK: `I3D` (int IDENTITY), FK: `{Table}I3D`
- **Standard Columns**: `CreatedByI3D`, `CreatedDate`, `ChangedByI3D`, `ChangedDate`, `IsDeleted`, `DeletedByI3D`, `DeletedDate`
- **BL Pattern**: `I{Module}Logic`, `BL{Module}Logic`, `WS{Module}Logic`, `{Entity}BL`, `{Entity}WebServiceBL`

## Critical Patterns

### Result Pattern (MANDATORY)
```csharp
public Result<T> Method() {
    try {
        var data = _dao.Get<T>(id);
        return data == null ? Result.Error<T>("Not found") : Result.Success(data);
    } catch (Exception ex) { return Result.Error<T>(ex); }
}
```

### UI Data Access (MANDATORY)
```csharp
// Single use
var result = await ClassContainer.Instance
    .WithInstance((IEntityLogic logic) => logic.GetEntity(id))
    .ThrowIfError();

// Multiple uses (IDisposable)
private readonly IEntityLogic _logic;
public ViewModel() { _logic = ClassContainer.Instance.GetInstance<IEntityLogic>(); }
public void Dispose() { ClassContainer.Instance.ReleaseInstance(_logic); }
```

### Architecture
**WPF UI** → `I{Module}Logic` (ClassContainer) → `BL{Module}Logic` (SQL) OR `WS{Module}Logic` (REST)
**REST API** → `CentronRestService` → `{Entity}WebServiceBL` (DTO conversion) → `{Entity}BL` (Business Logic) → DAO → NHibernate → SQL Server

Connection types: `CentronConnectionType.SqlServer` (BLLogic) | `CentronConnectionType.CentronWebServices` (WSLogic)

## Database Conventions (MUST FOLLOW)
- **PK**: `I3D` [int] IDENTITY(1,1) NOT NULL (auto-created by `ScriptHelpers.AddTableIfNotExists()`)
- **FK**: End with `I3D` suffix (e.g., `AccountI3D`)
- **Standard Columns**: CreatedByI3D, CreatedDate, ChangedByI3D, ChangedDate, IsDeleted, DeletedByI3D, DeletedDate (all REQUIRED)
- **Types**: `nvarchar` (NOT varchar), `datetime2(2)`, `bit`, `decimal(18,2)` for currency
- **Naming**: English PascalCase (new), Keep German (legacy), `dbo` schema

### Creating Database Scripts
1. Reserve number in Teams: `c-entron Entwickler` → Files → `Datenbankupdate 2 1.xlsx`
2. Create: `src/backend/Centron.BL/Administration/Scripts/ScriptMethods/Scripts/ScriptMethod{number}.cs`
3. Implement `BaseScriptMethod` with `GetSqlQueries()`
4. Use `ScriptHelpers.*` (AddTableIfNotExists, AddColumnIfNotExists, AddRightIfNotExists, etc.)
5. **Convert to UTF-8 with BOM** (C# files require BOM)

## Localization (REQUIRED)
- **Primary**: German (`LocalizedStrings.resx`) | **Secondary**: English (`LocalizedStrings.en.resx`)
- **Code**: `LocalizedStrings.KeyName` | **XAML**: `{x:Static properties:LocalizedStrings.KeyName}`
- **Key Format**: `{ClassName}_{Method}_{Description}`

## File Encoding (CRITICAL)
- **UTF-8 WITH BOM**: `*.cs`, `*.xaml` (MANDATORY)
- **UTF-8 NO BOM**: `*.md`, `*.json`, `*.xml`, `*.config`

**PowerShell Conversion**:
```powershell
$file = 'path\to\file.cs'
$content = [System.IO.File]::ReadAllText($file)
$utf8BOM = New-Object System.Text.UTF8Encoding($true)
[System.IO.File]::WriteAllText($file, $content, $utf8BOM)
```

## NHibernate Performance
- Use `.Fetch()` for eager loading (prevent N+1)
- Always filter: `.Where(x => !x.IsDeleted)`
- Use `Future()` for multiple collections
- Avoid lazy loading in loops

```csharp
// Good
var accounts = session.Query<Account>()
    .Where(x => !x.IsDeleted)
    .Fetch(x => x.AccountType)
    .Fetch(x => x.PriceList)
    .ToList();
```

## Development Processes

### Settings Management
- **Legacy**: `Stammdat` table (read-only)
- **New**: `ApplicationSettings` table ONLY
- Get next ID from `src/backend/Centron.Interfaces/Administration/Settings/ApplicationSettingID.cs`
- Add description to `ApplicationSettingDefinitions.cs`

### User Rights
1. Get next I3D from `UserRightsConst.cs`
2. Create script: `ScriptHelpers.AddRightIfNotExists(id, parentId, "German name", "German desc")`
3. Add constant to `UserRightsConst.cs`

### Web Service (Full Stack)
1. **BL**: `{Entity}BL.cs` returning `Result<T>`
2. **WebServiceBL**: `{Entity}WebServiceBL.cs` with DTO↔Entity conversion
3. **RestService**: Add to `CentronRestService.cs` (`Request<T>` → `Response<T>`)
4. **Interface**: `ICentronRestService.cs` with `[OperationContract]`, `[WebInvoke(Method="POST", UriTemplate="...")]`, `[Authenticate]`
5. **Logic**: `I{Entity}Logic`, `BL{Entity}Logic`, `WS{Entity}Logic`

### WPF Module
1. **Controller**: Implement `ICentronAppModuleController`
2. **View**: `UserControl` inheriting `BaseModule`
3. **ViewModel**: Inherit `BindableBase`
4. **Ribbon**: Implement `IRibbonControlModule` variations
5. **Registration**: Add to `ModuleRegistration.cs` with rights checks
6. **Theme**: Prefer DevExpress controls over WPF standard

## Agent Usage (MANDATORY)

### Project Agents (.claude/agents/)
- **primary-development**: ALL development tasks (orchestrator)
- **database-script-creator**: Database schema changes → generates ScriptMethod*.cs
- **webservice-developer**: Full-stack web service implementation
- **ui-module-creator**: WPF modules with MVVM + DevExpress
- **centron-nexus-developer**: Blazor Server, Razor components, SignalR, DevExpress Blazor
- **external-api-integrator**: Third-party API integrations (FinAPI, GLS, Shipcloud, etc.)
- **edi-specialist**: EDI processing (OpenTrans, EDIFACT, supplier integrations)
- **nhibernate-query-reviewer**: Query optimization, N+1 detection
- **localization-checker**: German/English verification
- **bookkeeping-export-expert**: DATEV, Abacus, SAP exports
- **test-engineer**: Test generation
- **code-reviewer**: Code quality/security
- **refactoring-specialist**: Code cleanup
- **debugger**: Bug diagnosis
- **architect**: System design
- **documentation-writer**: Docs
- **security-analyst**: Security reviews

### MANDATORY Agent Usage
- New features → **primary-development**
- DB schema → **database-script-creator**
- Web service → **webservice-developer**
- WPF module → **ui-module-creator**
- CentronNexus/Blazor → **centron-nexus-developer**
- External API → **external-api-integrator**
- EDI integration → **edi-specialist**
- Complex queries → **nhibernate-query-reviewer**
- UI text → **localization-checker**

## Commands
```bash
dotnet build Centron.sln                 # Build
dotnet test Centron.sln                  # Test all
cd scripts/Centron.Scripts && dotnet run # Build orchestration
```

**Targets**: clean, setup-versioning, build-web-service, build-centron-net, run-tests, create-installers

## Slash Commands
`/test`, `/review`, `/optimize`, `/implement`, `/explain`, `/analyze`, `/adr`, `/scaffold`

## MCP Servers
**serena**: Semantic search, symbol manipulation | **context7**: Library docs | **fetch**: Web content | **sequential-thinking**: Problem decomposition | **memory**: Knowledge graph | **playwright**: Browser automation | **windows-mcp**: Windows interaction

## Claude Instructions

### Tooling Decision (REQUIRED at task start)
```
🎯 Tooling Strategy Decision

Task Analysis: [Brief description]

Tooling Decisions:
- Agents: [name] / Not using - Reason: [justification]
- Slash Commands: [/command] / Not using - Reason: [justification]
- MCP Servers: [server:tool] / Not using - Reason: [justification]
- Approach: [strategy]
```

**When NOT to use agents**: Single file read, simple edit, 1-2 tool calls

### Task Summary (REQUIRED at end)
```
📊 Task Completion Summary

What Was Done: [description]

Features Involved:
- Agents: [list or None - justification]
- Slash Commands: [list or None - justification]
- MCP Servers: [list or None - justification]
- Core Tools: [Read, Write, Edit, Glob, Grep, Bash, etc.]
- Files Modified: [list or None]
- Performance: [Parallel ops, extended thinking, or N/A]

Efficiency Notes: [observations]
```

### Checklist
✅ Provide tooling decisions at task start
✅ Use `Result<T>` pattern
✅ Follow ILogic interface pattern
✅ German localization for UI text
✅ UTF-8 with BOM for C#/XAML
✅ DB conventions (I3D, FK, tracking columns)
✅ Run tests before commits
✅ Reference ticket numbers
✅ Use parallel tool calls
✅ Leverage agents/slash commands/MCP servers

## Common Tasks
1. **DB Table**: database-script-creator → ScriptMethod*.cs with conventions
2. **Web Service**: webservice-developer → BL → WebServiceBL → REST → Logic
3. **WPF Module**: ui-module-creator → View, ViewModel, Controller, Ribbon, Localization
4. **Query Optimization**: nhibernate-query-reviewer → N+1, indexes, soft delete

## Critical Files
- `src/centron/Centron.WPF.UI/App.xaml.cs` - WPF entry
- `src/backend/Centron.BL/` - Business logic
- `src/backend/Centron.DAO/` - Data access
- `src/webservice/Centron.WebServices.Core/RestService/CentronRestService.cs` - REST API
- `src/backend/Centron.Interfaces/` - Service interfaces

## Git
**Branch**: `master` (main) | **Types**: `feature/*`, `bugfix/*`, `hotfix/*`
**Commits**: `feat(module):`, `fix(module):`, `refactor(module):`, `docs:` + optional `(Ticket #12345)`