132 lines
8.4 KiB
Markdown
132 lines
8.4 KiB
Markdown
---
|
|
phase: 07-dkv-fleet-module
|
|
plan: 05
|
|
subsystem: dkv-frontend
|
|
tags: [dkv, nextjs, react, frontend, crud, tdd, api-client, i18n]
|
|
dependency_graph:
|
|
requires: [DkvController REST surface (07-04), dkvFleet i18n namespace (07-04), CalendarSourceForm pattern (05-02)]
|
|
provides: [dkv-api.ts typed client, DkvFleetPage (Surface A), InboxConfigForm (Surface B Tab 1), VehicleTable + CsvImportButton (Surface B Tab 2)]
|
|
affects:
|
|
- apps/web/src/lib/dkv-api.ts
|
|
- apps/web/src/app/(portal)/modules/dkv-fleet/page.tsx
|
|
- apps/web/src/app/(portal)/modules/dkv-fleet/components/StatusBadge.tsx
|
|
- apps/web/src/app/(portal)/modules/dkv-fleet/components/InvoiceHistoryTable.tsx
|
|
- apps/web/src/app/(portal)/modules/dkv-fleet/components/ExportFileList.tsx
|
|
- apps/web/src/app/(portal)/modules/dkv-fleet/settings/page.tsx
|
|
- apps/web/src/app/(portal)/modules/dkv-fleet/settings/components/InboxConfigForm.tsx
|
|
- apps/web/src/app/(portal)/modules/dkv-fleet/settings/components/VehicleTable.tsx
|
|
- apps/web/src/app/(portal)/modules/dkv-fleet/settings/components/CsvImportButton.tsx
|
|
- apps/web/src/app/(portal)/modules/dkv-fleet/settings/components/VehicleTable.test.tsx
|
|
- apps/web/src/app/(portal)/modules/dkv-fleet/vehicles/page.tsx
|
|
tech_stack:
|
|
added: []
|
|
patterns:
|
|
- "refreshKey lift: page.tsx increments refreshKey on checkNow success; InvoiceHistoryTable reruns useEffect"
|
|
- "onItemsLoaded callback: InvoiceHistoryTable notifies parent of loaded items; parent passes to ExportFileList"
|
|
- "T-07-12 password-blank-on-load: fetchConfig returns hasPassword boolean only; password field always blank; sent only when user types"
|
|
- "T-07-13 exportFileUrl: pure helper using encodeURIComponent; no client-built raw paths"
|
|
- "T-07-14 XSS: all backend strings via React text nodes; title attribute for badge tooltips (no dangerouslySetInnerHTML)"
|
|
- "T-07-15 CsvImportButton: accept=.csv, replace mode requires explicit destructive confirm before importVehiclesCsv"
|
|
- "TDD RED/GREEN: VehicleTable.test.tsx committed before VehicleTable.tsx; bug fixed (mockResolvedValueOnce vs mockResolvedValue)"
|
|
key_files:
|
|
created:
|
|
- apps/web/src/lib/dkv-api.ts
|
|
- apps/web/src/app/(portal)/modules/dkv-fleet/page.tsx
|
|
- apps/web/src/app/(portal)/modules/dkv-fleet/components/StatusBadge.tsx
|
|
- apps/web/src/app/(portal)/modules/dkv-fleet/components/InvoiceHistoryTable.tsx
|
|
- apps/web/src/app/(portal)/modules/dkv-fleet/components/ExportFileList.tsx
|
|
- apps/web/src/app/(portal)/modules/dkv-fleet/settings/page.tsx
|
|
- apps/web/src/app/(portal)/modules/dkv-fleet/settings/components/InboxConfigForm.tsx
|
|
- apps/web/src/app/(portal)/modules/dkv-fleet/settings/components/VehicleTable.tsx
|
|
- apps/web/src/app/(portal)/modules/dkv-fleet/settings/components/CsvImportButton.tsx
|
|
- apps/web/src/app/(portal)/modules/dkv-fleet/settings/components/VehicleTable.test.tsx
|
|
- apps/web/src/app/(portal)/modules/dkv-fleet/vehicles/page.tsx
|
|
modified: []
|
|
decisions:
|
|
- "InvoiceHistoryTable refetch: refreshKey prop (number) incremented by parent on checkNow success — triggers useEffect re-run; simpler than ref/callback"
|
|
- "ExportFileList data: derives filenames from history items via onItemsLoaded callback from InvoiceHistoryTable; avoids second fetch"
|
|
- "Password blank on load: configToForm() always sets password=''; placeholder shows bullet dots as UX hint; T-07-12 compliant"
|
|
- "VehicleTable test mock fix: mockResolvedValueOnce for initial load (Hans Müller), mockResolvedValue for refetch (Max Mustermann)"
|
|
- "CsvImportButton replace confirm: inline two-step (click Importieren → show confirm block → click Ersetzen) not a full modal; per UI-SPEC"
|
|
- "Vehicles route split: settings/page.tsx has tab bar; Fahrzeuge tab is a <Link> to /modules/dkv-fleet/vehicles (own route); VehicleTable imported from settings/components/"
|
|
metrics:
|
|
duration: 8min
|
|
completed: "2026-06-26T22:41:27Z"
|
|
tasks: 3
|
|
files_created: 11
|
|
files_modified: 0
|
|
---
|
|
|
|
# Phase 07 Plan 05: DKV Fleet Module Frontend — Summary
|
|
|
|
Typed fetch client (dkv-api.ts) and all three UI surfaces delivered: Surface A (module main page with history table + export list + "Jetzt prüfen" trigger), Surface B Tab 1 (InboxConfigForm with show/hide password and Active toggle), and Surface B Tab 2 (VehicleTable CRUD with CsvImportButton merge/replace). All STRIDE threat mitigations from the plan are implemented. VehicleTable covered by 5 passing Vitest tests (TDD RED→GREEN).
|
|
|
|
## Tasks Completed
|
|
|
|
| Task | Name | Commit | Key Files |
|
|
|------|------|--------|-----------|
|
|
| 1 | dkv-api client + StatusBadge + Surface A main page | 2fe7bca | dkv-api.ts, page.tsx, StatusBadge, InvoiceHistoryTable, ExportFileList |
|
|
| 2 | Settings page + InboxConfigForm (Surface B Tab 1) | 45e9a35 | settings/page.tsx, InboxConfigForm.tsx |
|
|
| 3 (RED) | VehicleTable failing tests | c739d27 | VehicleTable.test.tsx |
|
|
| 3 (GREEN) | VehicleTable + CsvImportButton + vehicles/page | 4d81b8b | VehicleTable.tsx, CsvImportButton.tsx, vehicles/page.tsx |
|
|
|
|
## Architecture Notes
|
|
|
|
### InvoiceHistoryTable Refetch Mechanism
|
|
|
|
The page holds a `refreshKey` state (number). After a successful `checkNow()` call, the page increments `refreshKey` by 1. InvoiceHistoryTable receives `refreshKey` as a prop and includes it in its `useEffect` dependency array — this triggers a fresh `fetchHistory()` call.
|
|
|
|
Additionally, InvoiceHistoryTable accepts an `onItemsLoaded(items)` callback. After each fetch, it calls this with the loaded items. The page stores these items in `historyItems` state and passes them to `ExportFileList`, which derives the 10 most recent unique export filenames from them. This avoids a second network request for export files.
|
|
|
|
### Password Blank on Load (T-07-12)
|
|
|
|
`configToForm()` always maps the server response to `password: ''` — the password field is never pre-filled. The server only returns `hasPassword: boolean`. The password field shows `placeholder="••••••••"` as a UX hint when `hasPassword` is true (inferred from the config). The password is only included in the `saveConfig` payload when `form.password !== ''`.
|
|
|
|
### TDD Gate Compliance
|
|
|
|
- RED commit: `c739d27` (VehicleTable.test.tsx only, fails with import error)
|
|
- GREEN commit: `4d81b8b` (VehicleTable.tsx + CsvImportButton.tsx + fix)
|
|
- Tests: 5 passed ✓
|
|
|
|
## Deviations from Plan
|
|
|
|
### Auto-fixed Issues
|
|
|
|
**1. [Rule 1 - Bug] VehicleTable test: mockResolvedValue sequencing bug**
|
|
- **Found during:** Task 3 GREEN phase (first test run)
|
|
- **Issue:** The edit-row test called `mockFetchVehicles.mockResolvedValue([Hans])` then immediately `mockFetchVehicles.mockResolvedValue([Max])`. The second call overwrote the first, making the initial component mount return Max Mustermann instead of Hans Müller. `waitFor(() => getByText('Hans Müller'))` timed out.
|
|
- **Fix:** Changed the first `mockResolvedValue` to `mockResolvedValueOnce` so the initial mount uses Hans Müller; subsequent calls (refetch after update) use the Max Mustermann value.
|
|
- **Files modified:** VehicleTable.test.tsx
|
|
- **Commit:** 4d81b8b (included in GREEN task commit)
|
|
|
|
## Verification Results
|
|
|
|
- `pnpm --filter @tessera/web exec tsc --noEmit -p tsconfig.json` exits 0: PASS
|
|
- `pnpm --filter @tessera/web test -- --run VehicleTable`: 5/5 passed
|
|
- `grep -q "credentials: 'include'"` dkv-api.ts: PASS
|
|
- `grep -q "check-now"` dkv-api.ts: PASS
|
|
- `grep -q "useTranslations('dkvFleet')"` page.tsx: PASS
|
|
- `grep -q "role=\"switch\""` InboxConfigForm.tsx: PASS
|
|
- `grep -q "vi.mock"` VehicleTable.test.tsx: PASS
|
|
- All 11 files present on disk: PASS
|
|
|
|
## Known Stubs
|
|
|
|
None. All API client functions are fully wired to real `/dkv/*` endpoints (Plan 04). All UI interactions call the corresponding dkv-api functions. The module is fully operable once the backend containers are running.
|
|
|
|
## Threat Flags
|
|
|
|
None. All T-07-12 to T-07-15 mitigations from the plan's threat register are implemented:
|
|
- T-07-12: Password blank-on-load in configToForm(); hasPassword-only interface field
|
|
- T-07-13: exportFileUrl() + encodeURIComponent; no client-built paths
|
|
- T-07-14: All backend strings via React text nodes; StatusBadge uses title attribute
|
|
- T-07-15: accept=".csv" on hidden file input; replace requires explicit two-step confirm
|
|
|
|
## TDD Gate Compliance
|
|
|
|
- RED gate commit: c739d27 ✓ (test(07-05): add failing VehicleTable tests)
|
|
- GREEN gate commit: 4d81b8b ✓ (feat(07-05): VehicleTable + CsvImportButton + vehicles page)
|
|
- All tests pass: 5/5 ✓
|
|
|
|
## Self-Check: PASSED
|