249 lines
10 KiB
Markdown
249 lines
10 KiB
Markdown
# 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)`
|
|
|