rhl-lieferscheine/Docs/SPEC.md

rhl-lieferscheine - Specification

Goals

• Replace the currently used v1 with a more reliable v2 for internal delivery note access.
• Let branch users find and open delivery note PDFs quickly through explorer and search flows.
• Provide controlled cross-branch access and user management for privileged roles.

Target Users

• Primary: branch staff who need to retrieve delivery note PDFs for their own branch.
• Secondary: admin, superadmin, and developer/support users who oversee delivery note operations and manage accounts.

Core Features (as-built)

1. Cookie-based authentication with role-aware access, logout/session handling, and enforced password change when required.
2. Branch/year/month/day explorer flow with breadcrumbs and dedicated empty, loading, error, forbidden, and not-found states.
3. Search with branch scopes, date filters, cursor pagination, recent-search history, and navigation back into explorer context.
4. PDF open/download flow from both explorer and search.
5. Profile page with password-change flow and support contact.
6. User management for privileged roles, including create, edit, delete, search, and temporary password reset.
7. Overview home cards that route users into the main application areas.

Known Limitations

• v2 is not live yet; release and deployment are still largely manual.
• GitLab migration/setup, CI/CD, HTTPS/reverse proxy, MongoDB hardening, and observability are still open work areas.
• There is no separate staging/test server environment yet.
• The production-ready search experience depends on Qsirch being available and configured.

Non-Goals

• A large dashboard with new-document or last-seen behavior.
• Saved searches/bookmarks as a major product feature.
• An in-app PDF viewer.
• Feature expansion without a clear operational need.

Constraints

• The application is internal to a multi-branch company and must enforce branch-level isolation for standard users.
• Each branch currently works with one shared branch account; privileged admin-like roles are individual accounts.
• Delivery note PDFs are scanned externally and deposited onto the NAS folder tree used by the app.
• User-facing UI remains German, while code, tests, and docs remain English.
• URL state is the source of truth for explorer and search navigation.
• Documentation updates happen after successful verification, not before.

Technical Architecture

• Next.js 16 App Router application using route handlers under app/api/*.
• React 19 client shell around protected/public routes.
• MongoDB-backed user model managed through Mongoose.
• Signed JWT session cookie authentication with RBAC checks in the application layer.
• NAS-backed document browsing plus Qsirch-backed indexed search for the target environment.
• Docker Compose runtime with separate local-fixture and server-like NAS mount behavior.

Open Questions

• The exact GitLab project migration and branch/environment automation flow are still TBD.
• The concrete monitoring and alerting stack is still TBD.
• The final production release checklist after HTTPS and CI/CD rollout is still TBD.