# CLAUDE.md — Helpdesk Module

Self-contained MintyPHP module. Namespace: `MintyPHP\Module\Helpdesk\*`. All changes stay inside `modules/helpdesk/` — never touch core templates or global layout.

After any manifest change (new route, permission, slot): `docker compose exec php php bin/console module:sync`

---

## Architecture

```
lib/Module/Helpdesk/
  HelpdeskAuthorizationPolicy.php   — all ability/permission constants + authorize()
  HelpdeskContainerRegistrar.php    — all DI bindings (add new services here)
  Handler/                          — scheduled job handlers
  Providers/HelpdeskLayoutProvider.php  — resolves can_* flags for sidebar nav
  Repository/                       — SQL only, no HTTP
  Service/                          — business logic, no HTML
pages/helpdesk/                     — actions (*.php) + views (*.phtml)
templates/
  aside-helpdesk-panel.phtml        — sidebar navigation
  helpdesk-ticket-detail.phtml      — shared ticket detail body
i18n/default_de.json + default_en.json  — 551 keys each, always add both
migrations/                         — 011 SQL files applied via module:migrate
tests/Module/Helpdesk/Service/      — 20 test files, happy path + edge case required
web/css/helpdesk.css
web/js/                             — 16 JS files, components + page scripts
```

---

## Page File Naming

| URL | Action file | View file |
|-----|-------------|-----------|
| `helpdesk/team` | `pages/helpdesk/team/index().php` | `team/index(default).phtml` |
| `helpdesk/handovers/edit/{id}` | `pages/helpdesk/handovers/edit($id).php` | `handovers/edit(default).phtml` |
| `helpdesk/dashboard` | `pages/helpdesk/dashboard/index().php` | `dashboard/index(default).phtml` |
| data endpoint | `pages/helpdesk/foo-data().php` | — |
| drawer fragment | `pages/helpdesk/foo-fragment($id).php` | `foo-fragment(none).phtml` |

**View structure pattern** (always):
```php
<div class="app-details-container">
  <section>
    <?php
    $titlebar = ['title' => t('Page title')];
    require templatePath('partials/app-details-titlebar.phtml');
    ?>
    <!-- content -->
  </section>
</div>
```

---

## Permissions (10 total)

All constants in `HelpdeskAuthorizationPolicy`:

| Constant | Permission key |
|----------|---------------|
| `ABILITY_ACCESS` | `helpdesk.access` — base access, customer search + detail views |
| `ABILITY_SETTINGS_MANAGE` | `helpdesk.settings.manage` |
| `ABILITY_TEAM_WORKLOAD` | `helpdesk.team-workload.view` |
| `ABILITY_RISK_RADAR` | `helpdesk.risk-radar.view` |
| `ABILITY_SOFTWARE_PRODUCTS_MANAGE` | `helpdesk.software-products.manage` |
| `ABILITY_HANDOVERS_VIEW` | `helpdesk.handovers.view` |
| `ABILITY_HANDOVERS_CREATE` | `helpdesk.handovers.create` |
| `ABILITY_HANDOVERS_MANAGE` | `helpdesk.handovers.manage` |
| `ABILITY_UPDATES_VIEW` | `helpdesk.updates.view` |
| `ABILITY_UPDATES_MANAGE` | `helpdesk.updates.manage` |

New pages reuse existing permissions — no new permission keys without product decision.

**Action file boilerplate:**
```php
Guard::requireLogin();
Guard::requireAbilityOrForbidden(HelpdeskAuthorizationPolicy::ABILITY_ACCESS);
$session = app(SessionStoreInterface::class)->all();
$tenantId = (int) ($session['current_tenant']['id'] ?? 0);
```

---

## Services & Repositories

**Gateways (external BC API):**
- `BcODataGateway` — OData V4 queries (customers, domains, tickets, contacts)
- `BcSoapGateway` — SOAP (ticket communication feed, file downloads)

**Core services:**
- `EffectiveHelpdeskSettingsService` — resolves BC config per tenant (global + override)
- `HelpdeskOAuthTokenService` — OAuth2 token acquisition + cache
- `DebitorSearchService` — debtor search by name/number
- `DebitorDetailService` — debtor master data + contacts + tickets
- `DomainDetailService` — domain/contract data + handover/update enrichment
- `DomainListService` — domain list with security level enrichment
- `HandoverService` — handover protocol CRUD + status transitions
- `HandoverRevisionService` — revision snapshots for audit trail
- `UpdateService` — software update tracking + assignment
- `SoftwareProductService` — product catalog + handover schema
- `SoftwareProductSyncService` — BC sync (scheduled daily 02:00 CET)
- `RiskRadarService` — risk scoring engine (5 dimensions, 0–100 score)
- `DomainSecurityLevelService` — security level get/set (niedrig/normal/hoch/kritisch)
- `SystemRecommendationEngine` — rule-based recommendation engine (no constructor)

**Repositories:**
- `HandoverRepository` — insert, findById, listPaged, updateFieldValues, updateStatus, deleteByIds, findByDomainNo, transactions
- `UpdateRepository` — insert, findByTicketNo, findByDomainNo, findAllByTenant, updateAssignment
- `SoftwareProductRepository` — upsertByCode, listPaged, updateHandoverSchema, softDeleteNotInCodes
- `HandoverRevisionRepository` — insert, getLatestRevisionNumber, listByHandover
- `DomainSecurityLevelRepository` — findByTenantAndDomainNo, listLevelsByDomainNos, upsert
- `HelpdeskTenantSettingsRepository` — findByTenantId, upsert, deleteByTenantId
- `HelpdeskTokenRepository` — findValidToken, storeToken, deleteByTenantId (encrypted)

New service → register in `HelpdeskContainerRegistrar::register()` + add `@api` annotation if called from pages.

---

## Sidebar Navigation

**`HelpdeskLayoutProvider`** resolves these flags → passed as `$layoutNav['helpdesk.nav']`:

`can_view_dashboard`, `can_manage_settings`, `can_view_team`, `can_view_risk_radar`,
`can_manage_software_products`, `can_view_handovers`, `can_create_handovers`,
`can_manage_handovers`, `can_view_updates`

**`aside-helpdesk-panel.phtml`** — 5 collapsible groups:
1. **Overview** (`bi-speedometer2`) — Dashboard
2. **Lookup** (`bi-search`) — Customers, Domains
3. **Monitoring** (`bi-bar-chart-line`) — Team workload, Risk radar
4. **Operations** (`bi-clipboard-check`) — Handovers, Updates
5. **Administration** (`bi-sliders`) — Software products, Settings

Adding a nav item = 3 steps: (1) add `can_*` flag to `HelpdeskLayoutProvider`, (2) add `$dashboardActive = navActive(...)` + item to group in `aside-helpdesk-panel.phtml`, (3) add condition to `$customersActive` override if needed.

---

## DB Schema (relevant tables)

| Table | Key columns |
|-------|-------------|
| `helpdesk_handovers` | id, tenant_id, status (draft/in_progress/completed/archived), debitor_no, domain_no |
| `helpdesk_handover_revisions` | handover_id, revision_number, snapshot_json |
| `helpdesk_updates` | id, tenant_id, status (open/assigned/done/resolved/closed), ticket_no, domain_no |
| `helpdesk_software_products` | code, name, handover_schema_json |
| `helpdesk_domain_security_levels` | tenant_id, domain_no, level, note |
| `helpdesk_tenant_settings` | tenant_id, encrypted BC connection overrides |
| `helpdesk_oauth_token_cache` | tenant_id, token (encrypted), expires_at |

Tenant scope enforced on every query — always pass `$tenantId` to repository methods.

---

## Tests

Location: `tests/Module/Helpdesk/Service/`
Pattern: `->method('foo')->willReturn([...])` — no `->with()` (PHPUnit 12 incompatible with PHPStan).
Every new/changed Service or Gateway needs happy path + at least one edge case test.

Run: `docker compose exec php vendor/bin/phpunit modules/helpdesk/tests/`

---

## JS Components

Registered via `data-app-component="<name>"` on the container div:
- `helpdesk-detail` — customer search detail
- `helpdesk-domain-detail` — domain detail
- `helpdesk-ticket` — ticket view
- `helpdesk-team` — team workload
- `helpdesk-risk-radar` — risk radar
- `helpdesk-settings` — settings config
- `helpdesk-communication` — ticket communication feed
- `helpdesk-handover-domain-select` — domain picker in handover wizard
- `helpdesk-handover-schema-editor` — handover schema JSON editor

CSS class prefix: `helpdesk-` for module-specific styles in `web/css/helpdesk.css`.