Browse Source
- Introduced comprehensive documentation for the role system in a new `docs/ROLES.md` file, covering role types, auto-assignment, product visibility, and menu visibility. - Updated `CLAUDE.md` and `docs/PRD.md` to reference the new roles documentation, enhancing clarity on role management and its implications for users. - Ensured all relevant documentation links are consistent and accessible for better user guidance.main
Bastian Masanek
2 months ago
3 changed files with 529 additions and 0 deletions
@ -0,0 +1,524 @@ |
|||||
|
# Rollen-System Dokumentation |
||||
|
|
||||
|
**Version:** 1.0 |
||||
|
**Letztes Update:** Januar 2025 |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Überblick |
||||
|
|
||||
|
Das Rollen-System von my.experimenta.science ermöglicht es, Produkte und UI-Komponenten basierend auf der aktiven Rolle des Benutzers anzuzeigen oder zu verstecken. Dies ermöglicht rollenspezifische Preise, Produkte und Funktionen. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 1. Rollen-Typen |
||||
|
|
||||
|
### 1.1 Verfügbare Rollen |
||||
|
|
||||
|
| Code | Display Name | Beschreibung | Approval erforderlich | |
||||
|
|------|--------------|--------------|----------------------| |
||||
|
| `private` | Privatperson | Private Nutzung | Nein (auto-assigned) | |
||||
|
| `educator` | Pädagoge | Lehrkräfte und Schulen | Ja (Post-MVP) | |
||||
|
| `company` | Unternehmen | Geschäftskunden | Ja (Post-MVP) | |
||||
|
|
||||
|
### 1.2 TypeScript Type Definition |
||||
|
|
||||
|
```typescript |
||||
|
type RoleCode = 'private' | 'educator' | 'company' |
||||
|
|
||||
|
interface Role { |
||||
|
code: RoleCode // Primary key |
||||
|
displayName: string // "Privatperson", "Pädagoge", "Unternehmen" |
||||
|
description: string |
||||
|
requiresApproval: boolean // false for 'private', true for others |
||||
|
sortOrder: number |
||||
|
active: boolean |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 2. Automatische Rollen-Zuweisung |
||||
|
|
||||
|
### 2.1 Auto-Assignment bei First Login (MVP) |
||||
|
|
||||
|
Alle neuen Benutzer erhalten automatisch die Rolle `private` beim ersten Login: |
||||
|
|
||||
|
```typescript |
||||
|
// server/api/auth/login.post.ts |
||||
|
if (!user) { |
||||
|
// Neuer User - erstelle Profil |
||||
|
const [newUser] = await db.insert(users).values({...}).returning() |
||||
|
|
||||
|
// Auto-assign 'private' role |
||||
|
await assignRoleToUser(newUser.id, 'private', { |
||||
|
adminNotes: 'Auto-assigned on first login', |
||||
|
}) |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
**Wichtig:** |
||||
|
- Status ist immer `approved` (kein Approval-Workflow in MVP) |
||||
|
- Jeder User hat mindestens eine Rolle |
||||
|
- Safety-Check: Existing users ohne Rollen bekommen auch `private` role |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 3. Rollen-basierte Produktsichtbarkeit |
||||
|
|
||||
|
### 3.1 Konzept |
||||
|
|
||||
|
Produkte sind NUR sichtbar, wenn: |
||||
|
1. Das Produkt `product_role_visibility` Einträge hat |
||||
|
2. Der User eine genehmigte (`approved`) Rolle hat, die in `product_role_visibility` vorkommt |
||||
|
|
||||
|
**Opt-in Visibility:** |
||||
|
- Produkt ohne `product_role_visibility` Einträge → Unsichtbar für ALLE |
||||
|
- User ohne genehmigte Rollen → Sieht KEINE Produkte |
||||
|
|
||||
|
### 3.2 Database Schema |
||||
|
|
||||
|
```sql |
||||
|
-- Many-to-Many: Product ↔ Roles |
||||
|
CREATE TABLE product_role_visibility ( |
||||
|
id UUID PRIMARY KEY, |
||||
|
product_id UUID NOT NULL REFERENCES products(id), |
||||
|
role_code TEXT NOT NULL REFERENCES roles(code), |
||||
|
UNIQUE(product_id, role_code) |
||||
|
); |
||||
|
``` |
||||
|
|
||||
|
### 3.3 Automatische Zuordnung (ERP Import) |
||||
|
|
||||
|
Beim Import aus NAV ERP werden Produkte automatisch Rollen zugeordnet: |
||||
|
|
||||
|
```typescript |
||||
|
// server/utils/roles.ts |
||||
|
const categoryRoleMapping = { |
||||
|
'makerspace-annual-pass': ['private', 'educator'], |
||||
|
'annual-pass': ['private'], |
||||
|
'educator-annual-pass': ['educator'], |
||||
|
'company-annual-pass': ['company'] |
||||
|
} |
||||
|
|
||||
|
// server/api/erp/products.post.ts |
||||
|
await assignRolesToProductByCategory(product.id, category) |
||||
|
``` |
||||
|
|
||||
|
### 3.4 API Filtering Pattern |
||||
|
|
||||
|
```typescript |
||||
|
// server/api/products/index.get.ts |
||||
|
export default defineEventHandler(async (event) => { |
||||
|
const { user } = await getUserSession(event) |
||||
|
|
||||
|
// Unauthenticated users see NO products |
||||
|
if (!user) return [] |
||||
|
|
||||
|
// Get visible product IDs for user's roles |
||||
|
const visibleProductIds = await getVisibleProductIdsForUser(user.id) |
||||
|
|
||||
|
// Fetch products with role filter |
||||
|
const products = await db.query.products.findMany({ |
||||
|
where: and( |
||||
|
eq(products.active, true), |
||||
|
inArray(products.id, visibleProductIds) |
||||
|
) |
||||
|
}) |
||||
|
|
||||
|
return products |
||||
|
}) |
||||
|
``` |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 4. Rollen-basierte Menüpunkt-Sichtbarkeit |
||||
|
|
||||
|
### 4.1 Konzept |
||||
|
|
||||
|
Navigation-Tabs können für bestimmte Rollen ein-/ausgeblendet werden: |
||||
|
- `roleVisibility: 'all'` → Sichtbar für alle Rollen |
||||
|
- `roleVisibility: ['educator']` → Nur für Pädagogen |
||||
|
- `roleVisibility: ['educator', 'company']` → Für mehrere Rollen |
||||
|
|
||||
|
### 4.2 Implementation (AreaTabs.vue) |
||||
|
|
||||
|
```typescript |
||||
|
interface ProductArea { |
||||
|
id: string |
||||
|
label: string |
||||
|
icon: any |
||||
|
enabled: boolean |
||||
|
visible: boolean |
||||
|
badge?: string |
||||
|
route: string |
||||
|
roleVisibility?: 'all' | RoleCode[] // NEW |
||||
|
} |
||||
|
|
||||
|
const areas: ProductArea[] = [ |
||||
|
{ id: 'start', roleVisibility: 'all' }, // Alle Rollen |
||||
|
{ id: 'makerspace', roleVisibility: 'all' }, // Alle Rollen |
||||
|
{ id: 'educator', roleVisibility: ['educator'] }, // Nur Pädagogen |
||||
|
{ id: 'experimenta', roleVisibility: 'all' }, // Alle Rollen |
||||
|
] |
||||
|
|
||||
|
const { activeRole } = useActiveRole() |
||||
|
|
||||
|
const visibleAreas = computed(() => { |
||||
|
return areas.filter(area => { |
||||
|
if (!area.visible) return false |
||||
|
if (!area.roleVisibility) return true |
||||
|
if (area.roleVisibility === 'all') return true |
||||
|
return area.roleVisibility.includes(activeRole.value as RoleCode) |
||||
|
}) |
||||
|
}) |
||||
|
``` |
||||
|
|
||||
|
### 4.3 Automatische Updates |
||||
|
|
||||
|
Menüpunkte aktualisieren sich automatisch beim Rollenwechsel: |
||||
|
- ✅ Vue Computed Property reagiert auf `activeRole` Änderungen |
||||
|
- ✅ Keine manuellen Refresh-Calls nötig |
||||
|
- ✅ Sofortige UI-Updates |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 5. Client-Side Composable |
||||
|
|
||||
|
### 5.1 useActiveRole() |
||||
|
|
||||
|
```typescript |
||||
|
// app/composables/useActiveRole.ts |
||||
|
export function useActiveRole() { |
||||
|
const activeRole = useState<string>('activeRole', () => 'private') |
||||
|
const roles = useState<RoleWithStatus[]>('roles', () => []) |
||||
|
|
||||
|
// Fetch current role status from server |
||||
|
async function fetchRoleStatus() { ... } |
||||
|
|
||||
|
// Switch to a different role |
||||
|
async function switchRole(roleCode: string) { |
||||
|
await $fetch('/api/user/active-role', { |
||||
|
method: 'PATCH', |
||||
|
body: { roleCode }, |
||||
|
}) |
||||
|
|
||||
|
activeRole.value = roleCode |
||||
|
|
||||
|
// Auto-refresh product pages |
||||
|
await Promise.all([ |
||||
|
refreshNuxtData('products-list'), |
||||
|
refreshNuxtData('educator-products'), |
||||
|
refreshNuxtData('experimenta-products'), |
||||
|
]) |
||||
|
} |
||||
|
|
||||
|
return { |
||||
|
activeRole, |
||||
|
roles, |
||||
|
approvedRoles: computed(() => roles.value.filter(r => r.hasRole)), |
||||
|
hasMultipleRoles: computed(() => approvedRoles.value.length > 1), |
||||
|
fetchRoleStatus, |
||||
|
switchRole, |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
### 5.2 Auto-Initialization |
||||
|
|
||||
|
Rollen werden automatisch beim Login geladen: |
||||
|
|
||||
|
```typescript |
||||
|
const { loggedIn } = useUserSession() |
||||
|
if (loggedIn.value) { |
||||
|
callOnce('init-roles', () => fetchRoleStatus()) |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 6. Server-Side Utilities |
||||
|
|
||||
|
### 6.1 Wichtige Functions |
||||
|
|
||||
|
```typescript |
||||
|
// server/utils/roles.ts |
||||
|
|
||||
|
// Get user's approved role codes |
||||
|
await getUserApprovedRoleCodes(userId) |
||||
|
// => ['private', 'educator'] |
||||
|
|
||||
|
// Get visible product IDs for user |
||||
|
await getVisibleProductIdsForUser(userId) |
||||
|
// => ['uuid-1', 'uuid-2', ...] |
||||
|
|
||||
|
// Get visible product IDs for specific role |
||||
|
await getVisibleProductIdsForRole(userId, roleCode) |
||||
|
// => ['uuid-1', 'uuid-2', ...] |
||||
|
|
||||
|
// Check if product is visible for user |
||||
|
await isProductVisibleForUser(productId, userId) |
||||
|
// => true/false |
||||
|
|
||||
|
// Assign role to user (MVP: always approved) |
||||
|
await assignRoleToUser(userId, 'private', { |
||||
|
adminNotes: 'Auto-assigned', |
||||
|
}) |
||||
|
|
||||
|
// Auto-assign roles to product by category |
||||
|
await assignRolesToProductByCategory(productId, 'annual-pass') |
||||
|
``` |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 7. Session Management |
||||
|
|
||||
|
### 7.1 Active Role Session |
||||
|
|
||||
|
Die aktive Rolle wird server-side in der Session gespeichert: |
||||
|
|
||||
|
```typescript |
||||
|
// server/utils/role-session.ts |
||||
|
|
||||
|
// Get user's active role (with TTL validation) |
||||
|
const activeRole = await getUserActiveRole(event) |
||||
|
// => 'private' | 'educator' | 'company' |
||||
|
|
||||
|
// Set user's active role in session + DB |
||||
|
await setUserActiveRole(event, userId, 'educator') |
||||
|
|
||||
|
// Validate active role (TTL-based) |
||||
|
const isValid = await validateActiveRole(event, userId) |
||||
|
``` |
||||
|
|
||||
|
**Session TTL:** |
||||
|
- Active role ist 30 Tage gültig |
||||
|
- Nach Ablauf: Fallback auf erste approved role |
||||
|
- Update bei jedem `switchRole()` |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 8. API Endpoints |
||||
|
|
||||
|
### 8.1 Role Management Endpoints |
||||
|
|
||||
|
| Endpoint | Method | Beschreibung | |
||||
|
|----------|--------|--------------| |
||||
|
| `/api/user/role-status` | GET | Aktuellen Role-Status abrufen | |
||||
|
| `/api/user/active-role` | PATCH | Aktive Rolle wechseln | |
||||
|
|
||||
|
#### GET /api/user/role-status |
||||
|
|
||||
|
**Response:** |
||||
|
```json |
||||
|
{ |
||||
|
"activeRoleCode": "private", |
||||
|
"roles": [ |
||||
|
{ |
||||
|
"code": "private", |
||||
|
"displayName": "Privatperson", |
||||
|
"description": "Private Nutzung", |
||||
|
"hasRole": true, |
||||
|
"requiresApproval": false |
||||
|
}, |
||||
|
{ |
||||
|
"code": "educator", |
||||
|
"displayName": "Pädagoge", |
||||
|
"description": "Lehrkräfte und Schulen", |
||||
|
"hasRole": true, |
||||
|
"requiresApproval": true |
||||
|
} |
||||
|
], |
||||
|
"roleChangedByAdmin": false |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
#### PATCH /api/user/active-role |
||||
|
|
||||
|
**Request:** |
||||
|
```json |
||||
|
{ |
||||
|
"roleCode": "educator" |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
**Validation:** |
||||
|
- ✅ User muss eingeloggt sein |
||||
|
- ✅ User muss die Rolle haben (approved status) |
||||
|
- ✅ Rolle muss existieren |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 9. UI Components |
||||
|
|
||||
|
### 9.1 RoleSwitcher Component |
||||
|
|
||||
|
Der RoleSwitcher zeigt die aktive Rolle an und ermöglicht Rollenwechsel: |
||||
|
|
||||
|
```vue |
||||
|
<!-- app/components/navigation/RoleSwitcher.vue --> |
||||
|
<template> |
||||
|
<DropdownMenu> |
||||
|
<DropdownMenuTrigger> |
||||
|
Du kaufst als: {{ activeRoleDisplay }} |
||||
|
</DropdownMenuTrigger> |
||||
|
<DropdownMenuContent> |
||||
|
<DropdownMenuItem |
||||
|
v-for="role in approvedRoles" |
||||
|
@click="switchRole(role.code)" |
||||
|
> |
||||
|
{{ role.displayName }} |
||||
|
</DropdownMenuItem> |
||||
|
</DropdownMenuContent> |
||||
|
</DropdownMenu> |
||||
|
</template> |
||||
|
``` |
||||
|
|
||||
|
**Features:** |
||||
|
- ✅ Zeigt nur approved roles |
||||
|
- ✅ Markiert aktive Rolle mit Checkmark |
||||
|
- ✅ Disabled für roles die User nicht hat |
||||
|
- ✅ Triggert automatische Product-Refresh |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 10. Testing |
||||
|
|
||||
|
### 10.1 Test User Setup |
||||
|
|
||||
|
```typescript |
||||
|
// Test User mit multiple roles |
||||
|
const user = await createTestUser({ |
||||
|
email: 'test@example.com', |
||||
|
roles: ['private', 'educator'] |
||||
|
}) |
||||
|
|
||||
|
// Setze aktive Rolle |
||||
|
await setUserActiveRole(event, user.id, 'educator') |
||||
|
``` |
||||
|
|
||||
|
### 10.2 Test Scenarios |
||||
|
|
||||
|
**Scenario 1: Privatperson Login** |
||||
|
- ✅ User erhält `private` role |
||||
|
- ✅ Sieht nur Produkte mit `private` role |
||||
|
- ✅ Sieht Navigation: Start, Makerspace, experimenta |
||||
|
|
||||
|
**Scenario 2: Pädagoge Login** |
||||
|
- ✅ User hat `private` + `educator` roles |
||||
|
- ✅ Kann zwischen Rollen wechseln |
||||
|
- ✅ Als Pädagoge: Zusätzliche Produkte sichtbar |
||||
|
- ✅ Als Pädagoge: "Bildung" Tab sichtbar |
||||
|
|
||||
|
**Scenario 3: Rollenwechsel** |
||||
|
- ✅ Produktliste aktualisiert sich automatisch |
||||
|
- ✅ Navigation aktualisiert sich automatisch |
||||
|
- ✅ Session + DB werden aktualisiert |
||||
|
- ✅ Product detail page: 404 redirect wenn nicht sichtbar |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 11. MVP Limitations |
||||
|
|
||||
|
### 11.1 Was NICHT implementiert ist (Post-MVP) |
||||
|
|
||||
|
**Approval Workflow:** |
||||
|
- ❌ Keine UI für Rollen-Antrag (Pädagogen/Unternehmen) |
||||
|
- ❌ Kein Admin-Panel für Genehmigung |
||||
|
- ❌ Status bleibt immer `approved` |
||||
|
|
||||
|
**Role Management:** |
||||
|
- ❌ Keine Self-Service Rollen-Verwaltung |
||||
|
- ❌ Keine Admin-Funktionen zum Hinzufügen/Entfernen von Rollen |
||||
|
- ❌ Keine Rollen-History für Admins |
||||
|
|
||||
|
**Advanced Features:** |
||||
|
- ❌ Keine Organisation-Level Rollen (z.B. alle Lehrer einer Schule) |
||||
|
- ❌ Keine zeitlich begrenzte Rollen |
||||
|
- ❌ Keine Rollen-Hierarchien |
||||
|
|
||||
|
### 11.2 Database prepared for Post-MVP |
||||
|
|
||||
|
Trotz MVP Limitations ist die Datenbank bereits vorbereitet: |
||||
|
|
||||
|
```typescript |
||||
|
// user_roles table (prepared but status always 'approved' in MVP) |
||||
|
interface UserRole { |
||||
|
status: 'pending' | 'approved' | 'rejected' | 'revoked' |
||||
|
organizationName?: string // Prepared |
||||
|
requestMessage?: string // Prepared |
||||
|
proofDocument?: string // Prepared |
||||
|
adminNotes?: string // Prepared |
||||
|
statusHistory: StatusHistoryEntry[] // JSONB audit trail |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 12. Best Practices |
||||
|
|
||||
|
### 12.1 Beim Hinzufügen neuer Rollen |
||||
|
|
||||
|
1. **Database:** Füge neue Rolle zu `roles` table hinzu |
||||
|
2. **Type:** Update `RoleCode` type in schema |
||||
|
3. **Mapping:** Update `categoryRoleMapping` in `server/utils/roles.ts` |
||||
|
4. **UI:** Update RoleSwitcher display names |
||||
|
5. **Navigation:** Update `roleVisibility` in AreaTabs.vue |
||||
|
|
||||
|
### 12.2 Beim Hinzufügen neuer Produkte |
||||
|
|
||||
|
1. **Category:** Definiere eine klare Kategorie |
||||
|
2. **Mapping:** Füge Kategorie zu `categoryRoleMapping` hinzu |
||||
|
3. **Visibility:** Produkt wird automatisch Rollen zugeordnet beim Import |
||||
|
|
||||
|
### 12.3 Beim Hinzufügen neuer Navigation-Items |
||||
|
|
||||
|
```typescript |
||||
|
{ |
||||
|
id: 'new-tab', |
||||
|
label: 'Neuer Tab', |
||||
|
roleVisibility: 'all' // oder ['educator', 'company'] |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 13. Troubleshooting |
||||
|
|
||||
|
### Problem: User sieht keine Produkte |
||||
|
|
||||
|
**Prüfen:** |
||||
|
1. Hat User eine approved Rolle? → `getUserApprovedRoleCodes(userId)` |
||||
|
2. Hat Produkt `product_role_visibility` Einträge? |
||||
|
3. Matchen Rolle und Produkt-Visibility? |
||||
|
|
||||
|
### Problem: Menüpunkt erscheint nicht nach Rollenwechsel |
||||
|
|
||||
|
**Prüfen:** |
||||
|
1. Ist `roleVisibility` korrekt gesetzt? |
||||
|
2. Ist `activeRole` korrekt aktualisiert? → Vue DevTools |
||||
|
3. Ist computed property `visibleAreas` reaktiv? |
||||
|
|
||||
|
### Problem: Produkt bleibt sichtbar nach Rollenwechsel |
||||
|
|
||||
|
**Prüfen:** |
||||
|
1. Wurde `refreshNuxtData()` aufgerufen in `switchRole()`? |
||||
|
2. Sind die richtigen keys verwendet? (`products-list`, etc.) |
||||
|
3. Hat API-Endpoint role-based filtering? |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 14. Weitere Dokumentation |
||||
|
|
||||
|
- **Architektur:** `docs/ARCHITECTURE.md` - Database Schema Details |
||||
|
- **PRD:** `docs/PRD.md` - Product Requirements |
||||
|
- **Testing:** `docs/TESTING.md` - Test Credentials & Scenarios |
||||
|
- **Cidaas Integration:** `docs/CIDAAS_INTEGRATION.md` - Auth Flow |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 15. Changelog |
||||
|
|
||||
|
| Version | Datum | Änderung | |
||||
|
|---------|-------|----------| |
||||
|
| 1.0 | Jan 2025 | Initial documentation - MVP implementation | |
||||
Loading…
Reference in new issue