u
This commit is contained in:
seb
536
AGENTS.md
Normal file
536
AGENTS.md
Normal file
@@ -0,0 +1,536 @@
|
||||
# AGENTS.md — Dashfront Developer & Agent Guide
|
||||
|
||||
> **Audience**: AI Coding Agents & Pair-Programmers working on `dashfront`.
|
||||
> **Workspace**: `/home/seb/src/dashfront`
|
||||
> **Last Updated**: 2026-09-21
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [System Overview & Ecosystem Map](#1-system-overview--ecosystem-map)
|
||||
2. [Technology Stack & Key Libraries](#2-technology-stack--key-libraries)
|
||||
3. [Directory Layout](#3-directory-layout)
|
||||
4. [State Management Conventions](#4-state-management-conventions)
|
||||
5. [Backend Communication & Authentication Rules](#5-backend-communication--authentication-rules)
|
||||
6. [Route & Navigation Architecture](#6-route--navigation-architecture)
|
||||
7. [Developer Workflows & Commands](#7-developer-workflows--commands)
|
||||
8. [Critical Agent Rules & Common Pitfalls](#8-critical-agent-rules--common-pitfalls)
|
||||
9. [Deep Dive: The Automats (`react-automat`)](#9-deep-dive-the-automats-react-automat)
|
||||
10. [Deep Dive: Redux Toolkit Architecture](#10-deep-dive-redux-toolkit-architecture)
|
||||
11. [`dashgui` Component Library Integration](#11-dashgui-component-library-integration)
|
||||
12. [Application Views & Route Hierarchy](#12-application-views--route-hierarchy)
|
||||
13. [Media, Images & Document Pipelines](#13-media-images--document-pipelines)
|
||||
14. [Real-time SSE Signals & Invalidation](#14-real-time-sse-signals--invalidation)
|
||||
15. [Developer Tooling & Debugging](#15-developer-tooling--debugging)
|
||||
16. [Agent Cheatsheet & Code Recipes](#16-agent-cheatsheet--code-recipes)
|
||||
|
||||
---
|
||||
|
||||
## 1. System Overview & Ecosystem Map
|
||||
|
||||
`dashfront` is the React web client and Progressive Web App (PWA) for the Dash ERP/POS system. It is part of a multi-repository workspace under `/home/seb/src/`:
|
||||
|
||||
```
|
||||
/home/seb/src/
|
||||
├── dashfront/ # THIS REPO: Vite + React 19 web/PWA client (port 4209 HTTP, 4308 HTTPS)
|
||||
├── dashback/ # Backend Express REST/SSE API server (port 4208)
|
||||
├── dashdbschema/ # LibDashStore (MSSQL data layer, migrations, schema graph, API docs)
|
||||
├── dashgui/ # Reusable custom UI component library (file:../dashgui)
|
||||
└── automat/ # react-automat state management library (file:../automat or npm)
|
||||
```
|
||||
|
||||
### End-to-End Data & Execution Flow
|
||||
|
||||
```yaml
|
||||
# Machine-readable execution flow:
|
||||
flow:
|
||||
- step: 1_client
|
||||
component: dashfront
|
||||
runtime: React 19 (PureComponent & Function Components)
|
||||
state_layers:
|
||||
automats: [artikelAutomat, deliveryEditorAutomat, authAutomat, supplierAutomat, navigationAutomat, userSettingsAutomat]
|
||||
redux_slices: [company, category, brand, unit, posterminal]
|
||||
transport: src/api (http(), ApiClient)
|
||||
egress:
|
||||
protocol: HTTP (fetch with credentials: "include") & SSE (/api/events)
|
||||
proxy: Vite dev server (/api -> http://localhost:4208)
|
||||
target: dashback
|
||||
|
||||
- step: 2_api_gateway
|
||||
component: dashback
|
||||
runtime: Express 5 API server (src/api/routes/*)
|
||||
security:
|
||||
auth_middleware: Cookie auth middleware (validates JWT in HTTP-only "token" cookie)
|
||||
context_injection:
|
||||
user_auth_id: req.user.googleAuthId
|
||||
tenant_company_id: req.selectedCompanyId
|
||||
events: Dispatches real-time SSE mutation events to subscribed clients via /api/events
|
||||
egress:
|
||||
interface: In-process method calls (store.<namespace>.<method>())
|
||||
target: dashdbschema
|
||||
|
||||
- step: 3_data_layer
|
||||
component: dashdbschema
|
||||
runtime: LibDashStore (src/store/*)
|
||||
storage: MSSQL connection pool, migrations, and SQL transactions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Technology Stack & Key Libraries
|
||||
|
||||
| Technology | Version / Spec | Notes |
|
||||
|---|---|---|
|
||||
| **Build & Dev** | Vite 8 (`type: module`) | Dev server on `4209`, HTTPS on `4308`, proxies `/api` → `http://localhost:4208` |
|
||||
| **Framework** | React 19 (`react`, `react-dom`) | Uses `PureComponent` (with Automats & dashgui) and modern function components |
|
||||
| **Routing** | `react-router-dom` v7 | Configured in [src/appRouter.jsx](file:///home/seb/src/dashfront/src/appRouter.jsx) with HMR router preservation |
|
||||
| **UI & Theming** | MUI 9 (`@mui/material`, Emotion) | Custom theme in `src/theme/`, base background `#c5ddd8` in `src/colors.js` |
|
||||
| **Shared GUI** | `dashgui` (`file:../dashgui`) | `PanelTile`, `RecordList`, `Tile`, `SingleLineTextEdit`, `ElevatedPill` |
|
||||
| **State Management** | `react-automat` + Redux Toolkit | Automats for reactive domain models; Redux for category tree & session bootstrap |
|
||||
| **Notifications** | `notistack` | `useSnackbar()` / `<SnackbarProvider>` in [src/main.jsx](file:///home/seb/src/dashfront/src/main.jsx) |
|
||||
| **Media & Images** | `@jsquash/avif`, `@jsquash/resize`, `thumbhash` | Client-side AVIF encoding and instant thumbnail hash generation |
|
||||
| **Documents** | `pdfconvert-wasm` | In-browser PDF processing for supplier delivery invoices & receipts |
|
||||
| **Drag & Drop** | `@shopify/draggable`, `sortablejs` | Category re-ordering, article assignments, nested tree nodes |
|
||||
|
||||
---
|
||||
|
||||
## 3. Directory Layout
|
||||
|
||||
```
|
||||
src/
|
||||
├── api/ # Backend communication layer
|
||||
│ ├── index.js # Canonical API module exports (article, category, delivery, etc.)
|
||||
│ ├── ApiClient.js # Object-oriented API client (this.article, this.delivery, etc.)
|
||||
│ ├── StorageManager.js # Client-side cache / local storage management
|
||||
│ └── storageManagerContext.js # React context provider for StorageManager
|
||||
├── automats/ # react-automat stores with fine-grained subscriptions
|
||||
│ ├── artikelAutomat.js # Article cache, deduplicated loads, and reactive single-article state
|
||||
│ ├── authAutomat.js # Authentication state, company list, company selection
|
||||
│ ├── deliveryEditorAutomat.js # Multi-line delivery receipt / invoice editor & draft state
|
||||
│ ├── navigationAutomat.js # Remembers active paths (last delivery path, last article SKU)
|
||||
│ ├── supplierAutomat.js # Supplier list and supplier-article catalogs
|
||||
│ ├── userSettingsAutomat.js # User preferences (viewer positions, layout settings)
|
||||
│ └── index.js # Barrel exports for all automats and helper selectors
|
||||
├── components/ # Shared UI components
|
||||
│ ├── AppShell.jsx # Main application frame (top bar, sidebar, nav buttons)
|
||||
│ ├── SectionLayout.jsx # Secondary navigation header for sections (/artikel, /lieferung...)
|
||||
│ ├── AuthBootstrap.jsx # Session bootstrapper, Google One Tap, company setup gate
|
||||
│ ├── LoginPage.jsx # Google One Tap / credentials login interface
|
||||
│ ├── UserMenu.jsx # User avatar, company switcher dropdown, logout action
|
||||
│ ├── BackendError.jsx # Graceful error banner for backend communication failures
|
||||
│ ├── article/ # Article tiles, editors, dialogs, photos, price tiers
|
||||
│ ├── category/ # Category navigation, dialogs, and picker components
|
||||
│ ├── manifest/ # Manifest / delivery line inspection widgets
|
||||
│ ├── settings/ # Terminal, unit, and brand settings dialogs
|
||||
│ └── tiles/ # Tile components extending dashgui base Tile
|
||||
├── devtools/ # Dev-only debug tools
|
||||
│ └── AutomatInspector.jsx # Docked overlay inspecting all registered window.__AUTOMATS__
|
||||
├── pages/ # Top-level view routes
|
||||
│ ├── artikel/ # Article index, category browser, warehouse, SKU detail editor
|
||||
│ ├── lieferung/ # Delivery list, new delivery editor, supplier manager, edit page
|
||||
│ ├── auftrag/ # Quotes (Angebote) and orders (Bestellungen)
|
||||
│ ├── kunde/ # Customer list, new customer, customer groups, edit page
|
||||
│ └── infos/ # System and company information page
|
||||
├── store/ # Redux Toolkit store (legacy & tree slice)
|
||||
│ ├── index.js # configureStore with dev logger & listener middleware
|
||||
│ ├── authSlice.js # Redux auth state (session bootstrap, company selection)
|
||||
│ ├── companySlice.js # Redux company details (tax rates, rootCategoryId)
|
||||
│ ├── categorySlice.js # Redux category tree, breadcrumbs, category articles
|
||||
│ ├── brandSlice.js # Redux brand list and lookup
|
||||
│ ├── posterminalSlice.js # Redux POS terminals configuration
|
||||
│ └── unitSlice.js # Redux unit of measure definitions
|
||||
├── theme/ # MUI theme definitions (light/dark palette, typography, components)
|
||||
├── utils/ # Helpers (apiShape.js, number formatters, notify.js, etc.)
|
||||
├── appRouter.jsx # react-router-dom route definitions
|
||||
├── nav.js # Navigation items (NAV_ITEMS, SUB_NAV, badges, active path matchers)
|
||||
├── colors.js # Shared color constants (MAIN_BACKGROUND)
|
||||
├── main.jsx # React root mount, providers, dev SW unregistration
|
||||
└── App.jsx # Main router provider wrapper
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. State Management Conventions
|
||||
|
||||
In `dashfront`, two state management solutions coexist harmoniously:
|
||||
|
||||
### A. `react-automat` (Recommended for Domain Models & Frequent Updates)
|
||||
- **Skill reference**: Read [.agents/skills/automat/SKILL.md](file:///home/seb/src/dashfront/.agents/skills/automat/SKILL.md).
|
||||
- Lives outside the React lifecycle in module scope (`src/automats/*.js`).
|
||||
- Designed for React `PureComponent` to bypass unnecessary React reconciliations.
|
||||
- **Pattern**:
|
||||
```jsx
|
||||
import { PureComponent } from 'react';
|
||||
import { artikelAutomat, createArticleSelector, getArticle } from '../automats';
|
||||
|
||||
class ArticleView extends PureComponent {
|
||||
constructor(props) {
|
||||
super(props);
|
||||
// 1. Synchronous read in constructor — zero blank flash!
|
||||
this.state = {
|
||||
article: getArticle(props.sku),
|
||||
};
|
||||
}
|
||||
|
||||
componentDidMount() {
|
||||
// 2. Subscribe with fine-grained selector
|
||||
this.unsub = artikelAutomat.subscribe(this, (state) => ({
|
||||
article: createArticleSelector(this.props.sku)(state),
|
||||
}));
|
||||
}
|
||||
|
||||
componentWillUnmount() {
|
||||
// 3. Always unsubscribe
|
||||
this.unsub?.();
|
||||
}
|
||||
|
||||
render() {
|
||||
const { article } = this.state;
|
||||
if (!article) return <div>Lädt...</div>;
|
||||
return <div>{article.name}</div>;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### B. Redux Toolkit (`src/store/`)
|
||||
- Used for static/relational trees: `company`, hierarchical `category` tree, `brand`, `posterminal`, and `unit`.
|
||||
- Uses `connect(mapStateToProps, mapDispatchToProps)` to connect to `PureComponent` classes or functional hooks where appropriate.
|
||||
- Coordinated via `createListenerMiddleware`: when `authAutomat` emits an auth change (`auth/sessionEstablished` or `auth/companyChanged`), listeners automatically dispatch loads for company info, brands, POS terminals, and units.
|
||||
|
||||
---
|
||||
|
||||
## 5. Backend Communication & Authentication Rules
|
||||
|
||||
### Authentication & Cookies
|
||||
1. **HTTP-only cookie**: The session token is stored in an HTTP-only cookie (`token`).
|
||||
2. **`credentials: 'include'`**: Every `fetch` request MUST set `credentials: 'include'`. The `http()` helper in [src/api/index.js](file:///home/seb/src/dashfront/src/api/index.js) does this automatically.
|
||||
3. **Never pass `googleAuthId`**: The frontend NEVER passes `googleAuthId` in request bodies or query parameters. The backend middleware extracts the authenticated user directly from the cookie session!
|
||||
4. **Session Company**: Multi-tenancy is scoped to the user's selected company. When a user switches companies (`PUT /api/auth/selected-company`), the backend updates the cookie session. All subsequent calls operate on that company.
|
||||
|
||||
### API Entry Point
|
||||
Import API namespaces from `src/api`:
|
||||
```js
|
||||
import { article, category, delivery, supplier, entity, company } from '../api';
|
||||
|
||||
// Examples:
|
||||
const { article: data } = await article.getBySku('SKU-1001');
|
||||
const { deliveries } = await delivery.list();
|
||||
const { suppliers } = await supplier.list();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Route & Navigation Architecture
|
||||
|
||||
- Main navigation sections are defined in [src/nav.js](file:///home/seb/src/dashfront/src/nav.js):
|
||||
- `/artikel` — Articles overview, SKU editor, Warehouse stock
|
||||
- `/kategorien/*` — Drag-and-drop category tree
|
||||
- `/lieferung` — Inbound deliveries, New delivery editor, Suppliers
|
||||
- `/auftrag` — Quotes (`/auftrag`) and Orders (`/auftrag/bestellung`)
|
||||
- `/kunde` — Customers, Customer groups
|
||||
- `/infos` — System settings & company info
|
||||
- **Router Singleton**:
|
||||
- Defined in [src/appRouter.jsx](file:///home/seb/src/dashfront/src/appRouter.jsx).
|
||||
- Preserved across Vite HMR via `import.meta.hot.data.router` to prevent mid-session resets when hot-reloading code.
|
||||
- **Dynamic Badges**:
|
||||
- `DeliveryNavIcon` and `DeliveryNeuIcon` in `src/nav.js` subscribe to `deliveryEditorAutomat` to show live uncommitted draft line badges in real time.
|
||||
|
||||
---
|
||||
|
||||
## 7. Developer Workflows & Commands
|
||||
|
||||
Run commands from the repository root `/home/seb/src/dashfront`:
|
||||
|
||||
```bash
|
||||
# Start Vite development server (proxies /api -> http://localhost:4208)
|
||||
npm run dev
|
||||
|
||||
# Start development server with local HTTPS (uses certs/key.pem and certs/cert.pem)
|
||||
npm run dev:https
|
||||
|
||||
# Run full PWA production build + preview (to test service worker / offline caching)
|
||||
npm run dev:pwa
|
||||
|
||||
# Generate local self-signed TLS certificates
|
||||
npm run cert
|
||||
|
||||
# Production build
|
||||
npm run build
|
||||
|
||||
# Preview production build
|
||||
npm run preview
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> When testing camera-based barcode scanning or Progressive Web App features on mobile devices or local network IP addresses, start the server using `npm run dev:https`. Web browsers require a secure context (HTTPS) to grant access to media devices and service workers.
|
||||
|
||||
---
|
||||
|
||||
## 8. Critical Agent Rules & Common Pitfalls
|
||||
|
||||
1. **Do not create dummy/mock backends**: `dashback` runs locally at `http://localhost:4208`. All `/api/*` routes are handled by it.
|
||||
2. **Keep `dashgui` links working**: `dashgui` is imported via `file:../dashgui`. Vite has deduplication configured (`dedupe: ['react', 'react-dom', ...]` in `vite.config.js`) to avoid dual-instance React conflicts.
|
||||
3. **Article Deletion Restriction**: An article CANNOT be deleted if it has child variants (`is_father: 1` or `childCount > 0`). The backend returns HTTP 400.
|
||||
4. **Prices and Multipliers**:
|
||||
- Article prices are tiered by `minmultiplier` and `customergroup_id`.
|
||||
- Prices sent to the backend are net prices (`net`).
|
||||
5. **Binary / Image Handling**:
|
||||
- Image uploads convert source images into AVIF variants client-side.
|
||||
- Frontend components use `thumbhash` for instant blur placeholders while loading full images via `/api/image/{fullHash}` or `/api/thumb/{fullHash}`.
|
||||
6. **No Hooks in PureComponents**: Never call React hooks (`useState`, `useSelector`, `useEffect`) inside `PureComponent` classes. Automats and `connect()` provide direct reactive subscription without hooks.
|
||||
7. **Always Unsubscribe**: Every `automat.subscribe(this, ...)` in `componentDidMount()` must have its cleanup callback called in `componentWillUnmount()`.
|
||||
|
||||
---
|
||||
|
||||
## 9. Deep Dive: The Automats (`react-automat`)
|
||||
|
||||
All domain Automats are located in [src/automats/](file:///home/seb/src/dashfront/src/automats/). Each automat exposes an observable state container with explicit action methods:
|
||||
|
||||
### 1. `artikelAutomat` ([src/automats/artikelAutomat.js](file:///home/seb/src/dashfront/src/automats/artikelAutomat.js))
|
||||
- **Role**: Cache and reactive distributor for article detail payloads (`GET /api/article/:sku`).
|
||||
- **Inflight Deduplication**: Uses an internal `Map<string, Promise<object>>` so concurrent UI tiles or navigation transitions requesting the same SKU share a single HTTP call.
|
||||
- **Key Actions**:
|
||||
- `loadArticle(sku)`: Fetches if missing, resolves immediately if cached.
|
||||
- `reloadArticle(sku)`: Silently re-fetches to update cache (used on SSE mutation events).
|
||||
- `setArticle(article)`: Updates cache after mutation responses.
|
||||
- `setArticleName(sku, name)`: Optimistic immediate rename.
|
||||
- `clearArticle(sku)` / `clear()`: Invalidates cache.
|
||||
- **Helper Selectors**: `getArticle(sku)`, `hasArticle(sku)`, `createArticleSelector(sku)`, `selectArticle(sku)`.
|
||||
|
||||
### 2. `authAutomat` ([src/automats/authAutomat.js](file:///home/seb/src/dashfront/src/automats/authAutomat.js))
|
||||
- **Role**: Manages user authentication lifecycle and multi-tenant company selection.
|
||||
- **State**: `{ user: AuthUser | null, googleClientId: string | null, status: 'loading' | 'anon' | 'authed' }`.
|
||||
- **Bridge to Redux**: Calls `emit(action)` registered via `setAuthEventDispatcher(store.dispatch)`. Emits:
|
||||
- `auth/sessionEstablished`
|
||||
- `auth/companyChanged`
|
||||
- `auth/loggedOut`
|
||||
- **Actions**: `bootstrapSession(session)`, `switchCompany(companyId)`, `logout()`.
|
||||
|
||||
### 3. `deliveryEditorAutomat` ([src/automats/deliveryEditorAutomat.js](file:///home/seb/src/dashfront/src/automats/deliveryEditorAutomat.js))
|
||||
- **Role**: State engine for the multi-line inbound delivery receiver and invoice reconciler ([src/pages/lieferung/neu.jsx](file:///home/seb/src/dashfront/src/pages/lieferung/neu.jsx)).
|
||||
- **Features**:
|
||||
- Line items editor (`lines`, `createEmptyLineitem`).
|
||||
- Supplier article auto-matching via `buildSupplierArticlesMap(articles)` indexing by supplier SKU, internal SKU, and EANs.
|
||||
- PDF/Receipt attachments parsing with OCR integration.
|
||||
- Reactive draft indicators (provides draft counts for badges in `src/nav.js`).
|
||||
|
||||
### 4. `supplierAutomat` ([src/automats/supplierAutomat.js](file:///home/seb/src/dashfront/src/automats/supplierAutomat.js))
|
||||
- **Role**: Caches supplier directory list and maps articles to their corresponding supplier catalogs (`GET /api/supplier`).
|
||||
|
||||
### 5. `navigationAutomat` ([src/automats/navigationAutomat.js](file:///home/seb/src/dashfront/src/automats/navigationAutomat.js))
|
||||
- **Role**: Remembers last active subpaths and last visited article SKU. When a user navigates between the main sidebar sections (e.g. from `/lieferung` to `/artikel` and back), it restores the exact active SKU or delivery document instead of resetting to the root list.
|
||||
|
||||
### 6. `userSettingsAutomat` ([src/automats/userSettingsAutomat.js](file:///home/seb/src/dashfront/src/automats/userSettingsAutomat.js))
|
||||
- **Role**: Stores client-side user layout preferences such as viewer panel coordinates and drawer positions.
|
||||
|
||||
---
|
||||
|
||||
## 10. Deep Dive: Redux Toolkit Architecture
|
||||
|
||||
Redux Toolkit manages static, relational, and configuration data in [src/store/](file:///home/seb/src/dashfront/src/store/):
|
||||
|
||||
### Slices
|
||||
1. **`categorySlice`**: Hierarchical category tree structure, category breadcrumbs, article-category memberships, category reordering (`moveCategory`, `reorderCategories`).
|
||||
2. **`companySlice`**: Active company configuration, tax rates (standard, reduced), root category ID, company legal details.
|
||||
3. **`brandSlice`**: Catalog brands and manufacturer list.
|
||||
4. **`posterminalSlice`**: Registered point-of-sale hardware terminals.
|
||||
5. **`unitSlice`**: Allowed units of measure (Stück, kg, Liter, etc.).
|
||||
|
||||
### Automatic Bootstrap with Listener Middleware
|
||||
In [src/store/index.js](file:///home/seb/src/dashfront/src/store/index.js), `createListenerMiddleware` coordinates data loading automatically when auth events fire:
|
||||
```js
|
||||
companyLoadListener(listenerMiddleware);
|
||||
unitLoadListener(listenerMiddleware);
|
||||
brandLoadListener(listenerMiddleware);
|
||||
posterminalLoadListener(listenerMiddleware);
|
||||
```
|
||||
When `auth/sessionEstablished` or `auth/companyChanged` occurs, these listeners trigger thunks to reload company tax settings, brands, units, and POS terminals without boilerplate in React views.
|
||||
|
||||
### Redux Dev Logger
|
||||
In development mode (`import.meta.env.DEV`), `reduxDevLogger` intercepts actions from `auth/`, `company/`, `category/`, `brand/`, `posterminal/`, and `unit/`, logging structured before/after counts to the browser console.
|
||||
|
||||
---
|
||||
|
||||
## 11. `dashgui` Component Library Integration
|
||||
|
||||
`dashgui` is a shared, high-performance UI library linked from `file:../dashgui`:
|
||||
|
||||
### Core Components
|
||||
- **`PanelTile`**: Structured card container featuring standard header styling, action slots, collapsible state, and clean borders.
|
||||
- **`RecordList`**: High-performance list component optimized for large dataset rendering with custom row click, hover, and selection handlers.
|
||||
- **`Tile`**: Base container element for building responsive dashboard grids.
|
||||
- **`SingleLineTextEdit`**: Inline editable text field with debounced autosave, blur commit, and escape rollback.
|
||||
- **`ElevatedPill`**: Compact visual badges for status, tags, and category chips.
|
||||
|
||||
### React 19 & Deduplication Warning
|
||||
Because `dashgui` is symlinked from `../dashgui`, it has its own `node_modules`. To prevent duplicate React, Emotion, or MUI instances from causing runtime context errors (`Cannot read properties of null (reading 'useContext')`), [vite.config.js](file:///home/seb/src/dashfront/vite.config.js) enforces `dedupe`:
|
||||
```js
|
||||
resolve: {
|
||||
dedupe: [
|
||||
'react', 'react-dom', 'react/jsx-runtime', 'react/jsx-dev-runtime',
|
||||
'react-router', 'react-router-dom', '@emotion/react', '@emotion/styled',
|
||||
'@mui/material', '@mui/icons-material'
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. Application Views & Route Hierarchy
|
||||
|
||||
The application routing is defined in [src/appRouter.jsx](file:///home/seb/src/dashfront/src/appRouter.jsx) and styled with [src/components/AppShell.jsx](file:///home/seb/src/dashfront/src/components/AppShell.jsx):
|
||||
|
||||
```
|
||||
/
|
||||
├── /artikel
|
||||
│ ├── index → ArtikelUebersichtPage (Search & filter grid)
|
||||
│ ├── /kategorien/* → ArtikelKategorienPage (Interactive category tree)
|
||||
│ ├── /lager → ArtikelLagerPage (Warehouse stock overview)
|
||||
│ └── /:sku/:tab? → ArtikelSkuPage (SKU detail: info, photos, prices, suppliers, warehouse)
|
||||
├── /lieferung
|
||||
│ ├── index → LieferungListePage (Inbound delivery list)
|
||||
│ ├── /neu → LieferungNeuPage (Receipt editor & OCR reconciliation)
|
||||
│ ├── /lieferanten → LieferungLieferantenPage (Supplier directory)
|
||||
│ └── /:deliveryId → LieferungEditPage (Delivery inspection & editing)
|
||||
├── /auftrag
|
||||
│ ├── index → AuftragAngebotPage (Quotes / Angebote)
|
||||
│ ├── /neu → AuftragAngebotNeuPage (Create quote)
|
||||
│ ├── /:quoteId → AuftragAngebotEditPage (Edit quote)
|
||||
│ ├── /bestellung → AuftragBestellungPage (Orders / Bestellungen)
|
||||
│ ├── /bestellung/neu → AuftragBestellungNeuPage (Create order)
|
||||
│ └── /bestellung/:id → AuftragBestellungEditPage (Edit order)
|
||||
├── /kunde
|
||||
│ ├── index → KundeListePage (Customer directory)
|
||||
│ ├── /neu → KundeNeuPage (Create customer)
|
||||
│ ├── /gruppen → KundeGruppenPage (Customer groups & price tiers)
|
||||
│ └── /:entityId → KundeEditPage (Customer profile & address editor)
|
||||
└── /infos → InfosPage (Company information & POS setup)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 13. Media, Images & Document Pipelines
|
||||
|
||||
### Client-Side AVIF Conversion
|
||||
To minimize backend CPU usage and reduce bandwidth:
|
||||
- When a user selects or drops an article photo, the frontend processes the image in-browser using `@jsquash/avif` and `@jsquash/resize`.
|
||||
- Images are scaled to target variant dimensions and compressed into AVIF format before transmission to `/api/article/:sku/photo`.
|
||||
|
||||
### ThumbHash Placeholders
|
||||
- For instant visual feedback without layout shift, article photos generate a 25-byte binary hash using `thumbhash`.
|
||||
- [src/components/article/ThumbHashImage.jsx](file:///home/seb/src/dashfront/src/components/article/ThumbHashImage.jsx) renders the blur preview instantly while the full image loads asynchronously from `/api/thumb/{hash}` or `/api/image/{hash}`.
|
||||
|
||||
### PDF & Document Ingestion
|
||||
- [src/pages/lieferung/neu.jsx](file:///home/seb/src/dashfront/src/pages/lieferung/neu.jsx) utilizes `pdfconvert-wasm` to process supplier PDF delivery notes and invoices directly inside the browser.
|
||||
- Extracted pages are rendered to canvas, displayed for line-by-line inspection, and passed to OCR recognition to populate delivery line items.
|
||||
|
||||
---
|
||||
|
||||
## 14. Real-time SSE Signals & Invalidation
|
||||
|
||||
The frontend connects to the backend Server-Sent Events stream at `/api/events`:
|
||||
- **Architecture**: When mutations occur on `dashback` (whether triggered by this client, another terminal, or the POS), SSE events are broadcast with payload information (e.g. `{ type: 'article-update', sku: '1001' }`).
|
||||
- **Reactive Cache Refresh**:
|
||||
- `artikelAutomat.actions.reloadArticle(sku)` re-fetches the updated article silently, updating subscribers without flicker.
|
||||
- Category updates trigger Redux category slice refreshes.
|
||||
- Delivery and order updates trigger automatic list reloads.
|
||||
|
||||
---
|
||||
|
||||
## 15. Developer Tooling & Debugging
|
||||
|
||||
### AutomatInspector ([src/devtools/AutomatInspector.jsx](file:///home/seb/src/dashfront/src/devtools/AutomatInspector.jsx))
|
||||
- Docked overlay on the right side of the screen, active only in development mode (`import.meta.env.DEV`).
|
||||
- Auto-discovers all running automats registered in `window.__AUTOMATS__`.
|
||||
- Allows developers and agents to:
|
||||
- Inspect full state JSON trees in real time.
|
||||
- View subscriber counts and registered actions.
|
||||
- Trigger actions and test state changes without code modifications.
|
||||
|
||||
### Vite API Proxy Logging
|
||||
[vite.config.js](file:///home/seb/src/dashfront/vite.config.js) includes automatic proxy logging for all `/api` requests and responses. HTTP method, path, request payloads, response statuses, and timing are formatted directly in the Vite terminal.
|
||||
|
||||
### TLS / HTTPS Development
|
||||
For testing hardware barcode scanners, camera video feeds, and PWA offline modes:
|
||||
```bash
|
||||
npm run cert # Generates local certs in ./certs/
|
||||
npm run dev:https # Runs Vite HTTPS server on port 4308
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 16. Agent Cheatsheet & Code Recipes
|
||||
|
||||
### Recipe 1: Consuming an Automat in a React PureComponent
|
||||
```jsx
|
||||
import { PureComponent } from 'react';
|
||||
import { artikelAutomat, createArticleSelector, getArticle } from '../automats';
|
||||
|
||||
export class ArticleTitle extends PureComponent {
|
||||
constructor(props) {
|
||||
super(props);
|
||||
// 1. Read synchronously to avoid blank flash
|
||||
this.state = {
|
||||
article: getArticle(props.sku),
|
||||
};
|
||||
}
|
||||
|
||||
componentDidMount() {
|
||||
// 2. Subscribe with fine-grained selector
|
||||
this.unsub = artikelAutomat.subscribe(this, (state) => ({
|
||||
article: createArticleSelector(this.props.sku)(state),
|
||||
}));
|
||||
}
|
||||
|
||||
componentDidUpdate(prevProps) {
|
||||
// 3. Handle prop changes cleanly
|
||||
if (prevProps.sku !== this.props.sku) {
|
||||
this.setState({ article: getArticle(this.props.sku) });
|
||||
this.unsub?.();
|
||||
this.unsub = artikelAutomat.subscribe(this, (state) => ({
|
||||
article: createArticleSelector(this.props.sku)(state),
|
||||
}));
|
||||
}
|
||||
}
|
||||
|
||||
componentWillUnmount() {
|
||||
// 4. Always cleanup
|
||||
this.unsub?.();
|
||||
}
|
||||
|
||||
render() {
|
||||
const { article } = this.state;
|
||||
return <h1>{article?.name ?? 'Lädt...'}</h1>;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Recipe 2: Calling the API and Notifying Errors
|
||||
```jsx
|
||||
import { article } from '../api';
|
||||
import { enqueueSnackbar } from 'notistack';
|
||||
import { notifyError } from '../utils/notify';
|
||||
import { artikelAutomat } from '../automats';
|
||||
|
||||
async function handleSavePrice(sku, netPrice) {
|
||||
try {
|
||||
const res = await article.updatePrice(sku, { net: netPrice });
|
||||
artikelAutomat.actions.setArticle(res.article);
|
||||
enqueueSnackbar('Preis erfolgreich aktualisiert', { variant: 'success' });
|
||||
} catch (err) {
|
||||
notifyError(err);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Recipe 3: Calculating Gross Prices with Company Tax Rates
|
||||
```jsx
|
||||
// Prices in the database and API are NET prices.
|
||||
// Gross prices shown to end users must apply company tax rates from Redux companySlice:
|
||||
export function calculateGrossPrice(netPrice, taxRatePercent) {
|
||||
const net = Number(netPrice) || 0;
|
||||
const rate = Number(taxRatePercent) || 0;
|
||||
return Math.round(net * (1 + rate / 100) * 100) / 100;
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user