delivery-app-web/AGENTS.md

Model Delivery engineering rules

• Current authorized scope also includes planned delivery dates, a local dashboard/calendar with common-action shortcuts and operational stored-price summaries, delivery editing/cancellation, explicit conflict resolution, editable/archiveable customer profiles with contact details, structured addresses, delivery windows/comments/related records, Synology OIDC sign-in with a configurable group allowlist, a personal greeting, and one local recovery account with guarded SSO settings at /local-admin. Keep dispatch, courier, approval, accounting reports and WhatsApp work out of this slice.
• Hebrew UI and RTL; English source, comments and technical documentation.
• Use pnpm and strict TypeScript. This repository has a flat src/ layout. Repository ownership and shared package release rules are in docs/repositories.md.
• All operational writes commit to IndexedDB with their outbox entry atomically before any network request. Authentication and SSO administration require an online server. Never perform network I/O inside an IndexedDB transaction.
• Never expose MariaDB to browsers. Require server sessions for sync; the authentication foundation remains local/loopback until deployment hardening is completed. Keep each user's device cache separate and pause sync on 401 without losing queued writes.
• Normal authentication uses OIDC Authorization Code + PKCE, state, nonce and signature/issuer/audience checks through openid-client. Provider tokens and client secrets stay encrypted on the API server. Never put them in browser storage or logs. offline_access is optional and does not enable offline API access.
• OIDC group access uses the verified configured claim, exact normalized case-insensitive allowlist matching and a stored last-login snapshot. Reject unmatched users before provisioning or session creation. Keep restriction disabled until an allowlist is configured, keep the local recovery account exempt, and require a fresh SSO login to learn changed provider membership.
• /local-admin is unlisted, authenticated and restricted to loopback requests. Never replace these controls with a secret URL or an unauthenticated bypass. Exactly one password-based account may be bootstrapped using LOCAL_ADMIN_SETUP_TOKEN; no shipped/default credentials. Deny the admin routes at a future public reverse proxy.
• Optional AD lookup enriches display names only after verified OIDC; never use it to bypass sign-in or infer roles. Require configured issuer/domain matching, exact escaped user filters, verified LDAPS, bounded operations and encrypted read credentials. Keep directory settings/tests behind the same local-admin controls. Preserve manual names and use cached names during directory outages.
• Apply DB changes only through checked-in migrations. Do not modify an already applied migration. MariaDB DDL implicitly commits; keep migrations restart-safe.
• Idempotency receipts, entity writes, business-number allocation and change log entries share one server transaction. Hold the sync_state lock until commit so the delta feed cannot miss late commits.
• UUIDs are entity identities. Delivery numbers are server-controlled, monotonically allocated and never reused after commit, even after future cancellation.
• No weight field. Shipment-unit multipliers live in reference data, not hardcoded business logic. Store immutable fixed-point shipment-unit and pricing snapshots on deliveries.
• Require each delivery address to belong to the selected customer, validated locally, by the API and by a composite foreign key.
• No silent conflict resolution. Preserve the local draft and server conflict details. Use version checks for future edits. Synchronized deletions must use tombstones and change-log entries.
• Pull cursors are opaque decimal strings. Never advance them from push receipts. Keep outbox entries until a valid server acknowledgment is durably applied.
• Sync on launch, reconnect, foreground, manual request, and periodically while visible. Do not depend on background sync support.
• Responsive layouts support phones and tablets in both orientations. Use logical CSS properties, 44px touch targets, safe areas and 100dvh.
• Never commit .env, database files or secrets. Avoid logging request bodies and customer data.
• Before delivery: pnpm typecheck, pnpm test, pnpm build; for sync changes also run the isolated MariaDB integration and Playwright offline/reconnect tests (README has setup).
• Do not reset, drop, or truncate working databases to fix tests. Use model_delivery_test.