Patrick Plate
161 lines
5.5 KiB
Markdown
161 lines
5.5 KiB
Markdown
# CannaManage Frontend — Walkthrough
|
|
|
|
**Sprint 4 Delivery | 2026-06-12 | Commit: fe6e96d**
|
|
|
|
---
|
|
|
|
## 🚀 How to Run
|
|
|
|
```bash
|
|
cd cannamanage-frontend
|
|
pnpm install # first time only
|
|
pnpm dev # starts on http://localhost:3000
|
|
```
|
|
|
|
Note: A mock backend on port 8080 is needed for auth to not timeout. Quick mock:
|
|
```bash
|
|
node -e "require('http').createServer((req,res)=>{res.writeHead(401,{'Content-Type':'application/json'});res.end(JSON.stringify({error:'mock'}))}).listen(8080,()=>console.log('Mock on 8080'))"
|
|
```
|
|
|
|
Or run the real backend: `cd cannamanage-api && mvn spring-boot:run`
|
|
|
|
---
|
|
|
|
## 🗺️ Page Map
|
|
|
|
### Admin Dashboard (requires login)
|
|
|
|
| Route | Feature | Key Elements |
|
|
|-------|---------|-------------|
|
|
| `/login` | Admin login | Email + password, error states, i18n |
|
|
| `/dashboard` | Club overview | 4 KPI cards, stock chart, recent distributions table, quick actions |
|
|
| `/members` | Member list | TanStack Table with search, sort, pagination, status badges |
|
|
| `/members/new` | Add member | Form with Zod validation, age ≥18 check |
|
|
| `/members/[id]` | Edit member | Pre-filled form, under-21 warning |
|
|
| `/distributions` | Distribution history | Filter by date/member, lock icons (immutable), today summary |
|
|
| `/distributions/new` | Record distribution | 4-step form: member → quota check → batch+amount → confirm |
|
|
| `/stock` | Batch management | Bar chart, summary cards, table with recall button |
|
|
| `/stock/new` | Add batch | Strain selector, THC/CBD, supplier, harvest date |
|
|
| `/reports` | Compliance reports | 3 report cards (monthly/member/recall), download + preview |
|
|
|
|
### Member Portal (separate layout)
|
|
|
|
| Route | Feature | Key Elements |
|
|
|-------|---------|-------------|
|
|
| `/portal-login` | Member login | Simplified login for members |
|
|
| `/portal/dashboard` | Quota overview | Radial SVG progress rings (daily/monthly), color-coded |
|
|
| `/portal/history` | My distributions | Table/cards with month filter, lock icons |
|
|
| `/portal/profile` | Profile & settings | Personal info (read-only), password change, language/theme prefs |
|
|
|
|
---
|
|
|
|
## 🎨 Theme System
|
|
|
|
- **Dark mode** (default): `#0D1117` bg, `#2ECC71` green accent
|
|
- **Light mode**: `#FAFBFC` bg, `#1B7A3D` darker green accent
|
|
- Toggle: click the sun/moon icon in the header
|
|
- Persists via localStorage (next-themes)
|
|
|
|
---
|
|
|
|
## 🌐 Language (i18n)
|
|
|
|
- Default: German (de)
|
|
- Also available: English (en)
|
|
- All UI strings come from `messages/de.json` / `messages/en.json`
|
|
- Switching: planned for settings page (currently hardcoded to `de`)
|
|
|
|
---
|
|
|
|
## 🔒 Auth Flow
|
|
|
|
1. User navigates to any protected route
|
|
2. Middleware checks NextAuth session
|
|
3. No session → redirect to `/login`
|
|
4. Login form → POST to backend `/api/v1/auth/login`
|
|
5. Success → NextAuth creates encrypted session cookie
|
|
6. Client never sees the raw JWT (server-side only)
|
|
7. Token refresh happens transparently in the `jwt` callback
|
|
|
|
---
|
|
|
|
## 📊 Key Business Features
|
|
|
|
### Real-time Quota Check (Distribution Form)
|
|
- Step 2 shows remaining daily (25g) and monthly (50g/30g) quota
|
|
- Color-coded: green (<50%), amber (50-80%), red (>80%)
|
|
- Blocks if member is suspended/expelled
|
|
- Shows under-21 reduced limit (30g/month)
|
|
|
|
### Immutable Audit Trail
|
|
- Every distribution row shows a 🔒 lock icon
|
|
- No edit/delete buttons on past distributions
|
|
- Reports include "audit-trail compliant" badge
|
|
|
|
### Batch Recall
|
|
- One-click recall with confirmation dialog
|
|
- Recalled batches disappear from distribution form
|
|
- Recall report captures affected distributions
|
|
|
|
---
|
|
|
|
## 🧪 Testing
|
|
|
|
```bash
|
|
# Run E2E tests (requires dev server running)
|
|
pnpm exec playwright test
|
|
|
|
# Run type check
|
|
pnpm exec tsc --noEmit
|
|
|
|
# Run build (production validation)
|
|
pnpm build
|
|
```
|
|
|
|
---
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
cannamanage-frontend/
|
|
├── src/
|
|
│ ├── app/
|
|
│ │ ├── (auth)/login/ # Admin login
|
|
│ │ ├── (dashboard-layout)/ # Admin pages (sidebar layout)
|
|
│ │ │ ├── dashboard/
|
|
│ │ │ ├── members/
|
|
│ │ │ ├── distributions/
|
|
│ │ │ ├── stock/
|
|
│ │ │ └── reports/
|
|
│ │ ├── (portal)/ # Member portal (top-nav layout)
|
|
│ │ │ ├── portal-login/
|
|
│ │ │ └── portal/
|
|
│ │ │ ├── dashboard/
|
|
│ │ │ ├── history/
|
|
│ │ │ └── profile/
|
|
│ │ └── api/auth/ # NextAuth route handler
|
|
│ ├── components/
|
|
│ │ ├── ui/ # shadcn/ui components
|
|
│ │ ├── portal/ # Portal-specific components
|
|
│ │ └── auth/ # Auth components
|
|
│ ├── data/mock/ # Mock data (replace with API calls)
|
|
│ ├── lib/auth.ts # NextAuth configuration
|
|
│ ├── hooks/ # Custom React hooks
|
|
│ └── types/ # TypeScript interfaces
|
|
├── messages/de.json # German translations
|
|
├── messages/en.json # English translations
|
|
├── e2e/ # Playwright tests
|
|
├── Dockerfile # Multi-stage production build
|
|
└── docker-compose.yml # Dev environment (in repo root)
|
|
```
|
|
|
|
---
|
|
|
|
## ⏭️ What's Next (Sprint 5)
|
|
|
|
1. Wire frontend to real backend API (replace mock data with fetch calls)
|
|
2. Staff management UI (invite, permissions editor)
|
|
3. DSGVO consent management
|
|
4. WebSocket notifications (real-time quota updates)
|
|
5. Full E2E test suite with backend running
|