Files
fs 53ccd212d5 docs(agents): encode list-export convention as GR-UI-EXPORT guard
Make the core-primitive-end-to-end rule for Grid.js list exports binding
instead of advisory — so future consumers (and reviewers) cannot quietly
drift back into inline fputcsv / hand-rolled headers / bespoke click
listeners / lurl() for query-carrying URLs.

- CLAUDE.md: new UI Patterns bullet + two "Never Do This" entries
  spelling out the server/view/client contract in one place.
- .agents/checks/guard-catalog.json: new GR-UI-EXPORT entry describing
  the end-to-end requirement (exportRequireGetRequest + exportCapLimit +
  exportSendCsv + ExportColumn + shared filter-schema + dropdown partial
  + endpointUrl() + initListExport).
- .agents/checks/guard-enforcement-map.json: wire the new guard to
  tests/Architecture/ListExportContractTest.php as the automated
  evidence source.
- .agents/checks/guard-checklist.md & .agents/prompts/reviewer-code.md:
  add GR-UI-EXPORT so the Code Reviewer prompt and the checklist flag
  violations alongside GR-UI-LIST.
- tests/Architecture/ListExportContractFiles: registry of every list
  export (currently helpdesk-domains, admin/users, audit/system-audit).
  Adding a new list = one entry, contract test covers the rest.
- tests/Architecture/ListExportContractTest: six checks per registered
  entry — endpoint uses the primitive, no hand-rolled output, data and
  export share the same filter-schema, template includes the dropdown
  partial and uses endpointUrl(), page module imports and invokes
  initListExport, and the shared dropdown partial stays zero-config.
- pages/admin/users/export().php: align with the new contract by
  switching from ad-hoc requestInput()->queryAll() reads to
  gridParseFiltersFromSchemaFile(__DIR__ . '/filter-schema.php'), same
  as the data endpoint — eliminates the last place Grid and export
  could disagree on what "the current filter" means.

Gates: PHPUnit 1900 OK (+6 contract checks), PHPStan 0 errors.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-21 22:50:43 +02:00

97 lines
4.2 KiB
PHP

<?php
use MintyPHP\Http\Request;
use MintyPHP\Http\SessionStoreInterface;
use MintyPHP\Router;
use MintyPHP\Service\Access\UserAuthorizationPolicy;
use MintyPHP\Service\Export\ExportColumn;
use MintyPHP\Support\Guard;
Guard::requireLogin();
exportRequireGetRequest();
$session = app(SessionStoreInterface::class)->all();
$authorizationService = app(\MintyPHP\Service\Access\AuthorizationService::class);
$decision = $authorizationService->authorize(UserAuthorizationPolicy::ABILITY_ADMIN_USERS_VIEW, [
'actor_user_id' => (int) ($session['user']['id'] ?? 0),
]);
if (!$decision->isAllowed()) {
if (Request::wantsJson()) {
http_response_code($decision->status());
Router::json(['error' => $decision->error()]);
return;
}
Router::redirect('error/forbidden?url=' . urlencode(Request::pathWithQuery()));
return;
}
$request = requestInput();
$currentUserId = (int) ($session['user']['id'] ?? 0);
$filters = gridParseFiltersFromSchemaFile(__DIR__ . '/filter-schema.php');
$filters['limit'] = exportCapLimit($request->query('limit'), 5000);
$filters['offset'] = 0;
$result = app(\MintyPHP\Service\User\UserAccountService::class)->listPaged([
'limit' => $filters['limit'],
'offset' => $filters['offset'],
'search' => $filters['search'],
'order' => $filters['order'],
'dir' => $filters['dir'],
'active' => $filters['active'],
'created_from' => $filters['created_from'],
'created_to' => $filters['created_to'],
'tenant' => $filters['tenant'],
'roles' => $filters['roles'],
'departments' => $filters['departments'],
'email_verified' => $filters['email_verified'],
'login_status' => $filters['login_status'],
'tenantUserId' => $currentUserId,
]);
$joinLabels = static function (mixed $value): string {
if (is_array($value)) {
return implode(' | ', array_map('strval', $value));
}
if (is_string($value)) {
$trimmed = trim($value);
if ($trimmed === '') {
return '';
}
return str_replace('||', ' | ', $trimmed);
}
return '';
};
$formatTimestamp = static function (mixed $value): string {
if ($value === null || $value === '') {
return '';
}
return (string) dt($value, 'Y-m-d H:i:s');
};
$columns = [
new ExportColumn('id', static fn (array $r): string => (string) ($r['id'] ?? '')),
new ExportColumn('uuid', static fn (array $r): string => (string) ($r['uuid'] ?? '')),
new ExportColumn('first_name', static fn (array $r): string => (string) ($r['first_name'] ?? '')),
new ExportColumn('last_name', static fn (array $r): string => (string) ($r['last_name'] ?? '')),
new ExportColumn('email', static fn (array $r): string => (string) ($r['email'] ?? '')),
new ExportColumn('phone', static fn (array $r): string => (string) ($r['phone'] ?? ''), allowSignedNumeric: true),
new ExportColumn('mobile', static fn (array $r): string => (string) ($r['mobile'] ?? ''), allowSignedNumeric: true),
new ExportColumn('short_dial', static fn (array $r): string => (string) ($r['short_dial'] ?? ''), allowSignedNumeric: true),
new ExportColumn('locale', static fn (array $r): string => (string) ($r['locale'] ?? '')),
new ExportColumn('theme', static fn (array $r): string => (string) ($r['theme'] ?? '')),
new ExportColumn('active', static fn (array $r): int => (int) ($r['active'] ?? 0)),
new ExportColumn('tenants', static fn (array $r): string => $joinLabels($r['tenant_labels'] ?? [])),
new ExportColumn('departments', static fn (array $r): string => $joinLabels($r['department_labels'] ?? [])),
new ExportColumn('roles', static fn (array $r): string => $joinLabels($r['role_labels'] ?? [])),
new ExportColumn('created_by', static fn (array $r): string => (string) ($r['created_by'] ?? '')),
new ExportColumn('modified_by', static fn (array $r): string => (string) ($r['modified_by'] ?? '')),
new ExportColumn('created', static fn (array $r): string => $formatTimestamp($r['created'] ?? '')),
new ExportColumn('modified', static fn (array $r): string => $formatTimestamp($r['modified'] ?? '')),
];
$filename = 'users-' . date('Ymd-His') . '.csv';
exportSendCsv($filename, $result['rows'] ?? [], $columns, exportResolveFlavor($request));