Merge pull request #25 from bwl21/fix/automatic-groups-grouptype-display-v2

docs: add session documentation and permission fix for automatic groups

Author: bwl21

docs/DEVELOPMENT_SESSION_2025-09-27_Automatic_Groups_Grouptype_Fix.md

@@ -0,0 +1,91 @@
+# Development Session - 2025-09-27
+
+## Session Overview
+
+**Started**: 12:33  
+**Completed**: 12:48  
+**Branch**: `fix/automatic-groups-grouptype-display-v2`  
+**Focus**: Fix automatic groups displaying "Unbekannter Typ" instead of actual group type names
+
+## Major Accomplishments
+
+### Phase 1: Problem Analysis (12:33-12:42)
+
+- **Goal**: Identify why automatic groups showed "Unbekannter Typ" instead of group type names
+- **Result**: Discovered merge conflicts in original branch, created new clean branch
+- **Code Changes**: Created `fix/automatic-groups-grouptype-display-v2` branch
+
+### Phase 2: API Investigation (12:42-12:45)
+
+- **Goal**: Understand the correct API structure for group types and groups
+- **Result**: Found that ChurchTools APIs return `{ data: Array<...> }` structure
+- **Code Changes**: Updated response handling for both group types and groups APIs
+
+### Phase 3: Field Path Discovery (12:45-12:46)
+
+- **Goal**: Locate the correct field containing groupTypeId in group objects
+- **Result**: Discovered groupTypeId is in `group.information.groupTypeId`, not at root level
+- **Code Changes**: Updated field access path with proper fallback chain
+
+### Phase 4: Implementation & Testing (12:46-12:48)
+
+- **Goal**: Implement complete fix and clean up debug code
+- **Result**: Working implementation with proper group type name display
+- **Code Changes**: Removed debug logging, finalized implementation
+
+## Technical Decisions
+
+### Decision: API Response Structure Handling (12:42)
+
+**Context**: ChurchTools client returns different structures than expected  
+**Decision**: Handle both `{ data: Array }` and direct `Array` responses with proper fallbacks  
+**Impact**: Robust API response handling that works with current ChurchTools client
+
+### Decision: Group Type Mapping Strategy (12:43)
+
+**Context**: Need to resolve group type IDs to human-readable names  
+**Decision**: Fetch all group types upfront and create Map<number, string> for efficient lookups  
+**Impact**: Single API call for group types, efficient O(1) lookups during group processing
+
+### Decision: Field Access Priority (12:46)
+
+**Context**: groupTypeId could be in multiple locations within group object  
+**Decision**: Priority chain: `information.groupTypeId` → `domainAttributes.groupTypeId` → `groupTypeId` → 0  
+**Impact**: Robust field access that works with different API response variations
+
+## Next Steps
+
+- [ ] Monitor group type display in production
+- [ ] Consider caching group types separately if performance becomes an issue
+- [ ] Evaluate if similar pattern needed for other ID-to-name mappings
+
+## Lessons Learned
+
+- ChurchTools API responses follow `{ data: Array<...> }` pattern consistently
+- Group data structure has nested `information` object containing core properties
+- Debug logging is essential for understanding complex API response structures
+- Clean branch creation is faster than resolving complex merge conflicts
+- TypeScript interfaces should reflect actual API structure, not assumptions
+
+## Files Modified
+
+- `src/composables/useAutomaticGroups.ts` - Core logic for fetching and mapping group types
+- `src/components/automatic-groups/AutomaticGroupsAdmin.vue` - UI updates for displaying group type names
+
+## Commit
+
+```
+fix: display group type names instead of IDs in automatic groups
+
+- Fetch group types from /group/grouptypes API to create ID-to-name mapping
+- Access groupTypeId from correct field path (group.information.groupTypeId)
+- Update interface to include both groupTypeId (number) and groupTypeName (string)
+- Update admin table to display groupTypeName instead of groupTypeId
+- Add robust error handling for group types API calls
+- Include domainAttributes in groups API call for complete data
+
+Resolves issue where automatic groups showed 'Unbekannter Typ' instead of
+actual group type names like 'Hauskreis', 'Mitarbeiterteam', etc.
+
+Co-authored-by: Ona <no-reply@ona.com>
+```

docs/LESSONS-LEARNED.md

@@ -20,7 +20,25 @@
 
 # 🎓 Lessons Learned 2025-09-27
 
-### 1. Vue Computed Race Conditions
+### 1. ChurchTools API Response Structure Patterns
+
+**Problem**: Inconsistent handling of ChurchTools API responses leading to data access failures
+**Solution**: ChurchTools APIs consistently return `{ data: Array<...>, meta?: ... }` structure, not direct arrays
+**Application**: Always check for `.data` property first, then fallback to direct array access for robustness
+
+### 2. Group Data Structure Navigation
+
+**Problem**: Assuming groupTypeId would be at root level of group objects
+**Solution**: Core group properties are nested in `information` object (e.g., `group.information.groupTypeId`)
+**Application**: Consult TypeScript definitions and use debug logging to understand actual API response structure
+
+### 3. ID-to-Name Mapping Strategy
+
+**Problem**: Displaying numeric IDs instead of human-readable names in UI
+**Solution**: Fetch reference data (like group types) upfront and create efficient Map<ID, Name> lookups
+**Application**: Use this pattern for any entity that needs ID-to-name resolution (group types, statuses, categories)
+
+### 4. Vue Computed Race Conditions
 
 **Problem**: Computed properties can execute before async dependencies are ready
 **Solution**: Always check for null/undefined dependencies in computed properties

src/config/permissions.json

@@ -1,8 +1,8 @@
 {
   "modulePermissions": {
     "automatic-groups": {
-      "module": "churchdb",
-      "permission": "administer groups",
+      "module": "churchgroup",
+      "permission": "view",
       "description": "Zugriff auf automatische Gruppen - benötigt Gruppen-Administration"
     },
     "expiring-appointments": {