feat(tags): Add database schema and tags module (v1.3.0 Phase 1)
Implements tag/category system backend following microformats2 p-category specification. Database changes: - Migration 008: Add tags and note_tags tables - Normalized tag storage (case-insensitive lookup, display name preserved) - Indexes for performance New module: - starpunk/tags.py: Tag management functions - normalize_tag: Normalize tag strings - get_or_create_tag: Get or create tag records - add_tags_to_note: Associate tags with notes (replaces existing) - get_note_tags: Retrieve note tags (alphabetically ordered) - get_tag_by_name: Lookup tag by normalized name - get_notes_by_tag: Get all notes with specific tag - parse_tag_input: Parse comma-separated tag input Model updates: - Note.tags property (lazy-loaded, prefer pre-loading in routes) - Note.to_dict() add include_tags parameter CRUD updates: - create_note() accepts tags parameter - update_note() accepts tags parameter (None = no change, [] = remove all) Micropub integration: - Pass tags to create_note() (tags already extracted by extract_tags()) - Return tags in q=source response Per design doc: docs/design/v1.3.0/microformats-tags-design.md Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,332 @@
|
||||
# Implementation Report: Hotfix v1.1.1-rc.2 - Admin Dashboard Route Conflict
|
||||
|
||||
## Metadata
|
||||
- **Date**: 2025-11-25
|
||||
- **Version**: 1.1.1-rc.2
|
||||
- **Type**: Hotfix
|
||||
- **Priority**: CRITICAL
|
||||
- **Implemented By**: Fullstack Developer (AI Agent)
|
||||
- **Design By**: StarPunk Architect
|
||||
|
||||
## Problem Statement
|
||||
|
||||
Production deployment of v1.1.1-rc.1 caused a 500 error at `/admin/metrics-dashboard` endpoint. User reported the issue from production container logs showing:
|
||||
|
||||
```
|
||||
jinja2.exceptions.UndefinedError: 'dict object' has no attribute 'database'
|
||||
At: /app/templates/admin/metrics_dashboard.html line 163
|
||||
```
|
||||
|
||||
### Root Cause Analysis (Updated)
|
||||
|
||||
**Initial Hypothesis**: Route conflict between `/admin/` and `/admin/dashboard` routes.
|
||||
**Status**: Partially correct - route conflict was fixed in initial attempt.
|
||||
|
||||
**Actual Root Cause**: Template/Data Structure Mismatch
|
||||
1. **Template Expects** (line 163 of `metrics_dashboard.html`):
|
||||
```jinja2
|
||||
{{ metrics.database.count|default(0) }}
|
||||
{{ metrics.database.avg|default(0) }}
|
||||
{{ metrics.database.min|default(0) }}
|
||||
{{ metrics.database.max|default(0) }}
|
||||
```
|
||||
|
||||
2. **get_metrics_stats() Returns**:
|
||||
```python
|
||||
{
|
||||
"total_count": 150,
|
||||
"max_size": 1000,
|
||||
"process_id": 12345,
|
||||
"by_type": {
|
||||
"database": {
|
||||
"count": 50,
|
||||
"avg_duration_ms": 12.5,
|
||||
"min_duration_ms": 2.0,
|
||||
"max_duration_ms": 45.0
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **The Mismatch**: Template tries to access `metrics.database.count` but the data structure provides `metrics.by_type.database.count` with different field names (`avg_duration_ms` vs `avg`).
|
||||
|
||||
## Design Documents Referenced
|
||||
- `/docs/decisions/ADR-022-admin-dashboard-route-conflict-hotfix.md` (Initial fix)
|
||||
- `/docs/decisions/ADR-060-production-hotfix-metrics-dashboard.md` (Template data fix)
|
||||
- `/docs/design/hotfix-v1.1.1-rc2-route-conflict.md`
|
||||
- `/docs/design/hotfix-validation-script.md`
|
||||
|
||||
## Implementation Summary
|
||||
|
||||
### Changes Made
|
||||
|
||||
#### 1. File: `/starpunk/routes/admin.py`
|
||||
|
||||
**Lines 218-260 - Data Transformer Function Added:**
|
||||
```python
|
||||
def transform_metrics_for_template(metrics_stats):
|
||||
"""
|
||||
Transform metrics stats to match template structure
|
||||
|
||||
The template expects direct access to metrics.database.count, but
|
||||
get_metrics_stats() returns metrics.by_type.database.count.
|
||||
This function adapts the data structure to match template expectations.
|
||||
|
||||
Args:
|
||||
metrics_stats: Dict from get_metrics_stats() with nested by_type structure
|
||||
|
||||
Returns:
|
||||
Dict with flattened structure matching template expectations
|
||||
|
||||
Per ADR-060: Route Adapter Pattern for template compatibility
|
||||
"""
|
||||
transformed = {}
|
||||
|
||||
# Map by_type to direct access
|
||||
for op_type in ['database', 'http', 'render']:
|
||||
if 'by_type' in metrics_stats and op_type in metrics_stats['by_type']:
|
||||
type_data = metrics_stats['by_type'][op_type]
|
||||
transformed[op_type] = {
|
||||
'count': type_data.get('count', 0),
|
||||
'avg': type_data.get('avg_duration_ms', 0),
|
||||
'min': type_data.get('min_duration_ms', 0),
|
||||
'max': type_data.get('max_duration_ms', 0)
|
||||
}
|
||||
else:
|
||||
# Provide defaults for missing types or when by_type doesn't exist
|
||||
transformed[op_type] = {
|
||||
'count': 0,
|
||||
'avg': 0,
|
||||
'min': 0,
|
||||
'max': 0
|
||||
}
|
||||
|
||||
# Keep other top-level stats
|
||||
transformed['total_count'] = metrics_stats.get('total_count', 0)
|
||||
transformed['max_size'] = metrics_stats.get('max_size', 1000)
|
||||
transformed['process_id'] = metrics_stats.get('process_id', 0)
|
||||
|
||||
return transformed
|
||||
```
|
||||
|
||||
**Line 264 - Route Decorator (from initial fix):**
|
||||
```python
|
||||
@bp.route("/metrics-dashboard") # Changed from "/dashboard"
|
||||
```
|
||||
|
||||
**Lines 302-315 - Transformer Applied in Route Handler:**
|
||||
```python
|
||||
try:
|
||||
raw_metrics = get_metrics_stats()
|
||||
metrics_data = transform_metrics_for_template(raw_metrics)
|
||||
except Exception as e:
|
||||
flash(f"Error loading metrics: {e}", "warning")
|
||||
# Provide safe defaults matching template expectations
|
||||
metrics_data = {
|
||||
'database': {'count': 0, 'avg': 0, 'min': 0, 'max': 0},
|
||||
'http': {'count': 0, 'avg': 0, 'min': 0, 'max': 0},
|
||||
'render': {'count': 0, 'avg': 0, 'min': 0, 'max': 0},
|
||||
'total_count': 0,
|
||||
'max_size': 1000,
|
||||
'process_id': 0
|
||||
}
|
||||
```
|
||||
|
||||
**Lines 286-296 - Defensive Imports (from initial fix):**
|
||||
```python
|
||||
# Defensive imports with graceful degradation for missing modules
|
||||
try:
|
||||
from starpunk.database.pool import get_pool_stats
|
||||
from starpunk.monitoring import get_metrics_stats
|
||||
monitoring_available = True
|
||||
except ImportError:
|
||||
monitoring_available = False
|
||||
# Provide fallback functions that return error messages
|
||||
def get_pool_stats():
|
||||
return {"error": "Database pool monitoring not available"}
|
||||
def get_metrics_stats():
|
||||
return {"error": "Monitoring module not implemented"}
|
||||
```
|
||||
|
||||
#### 2. File: `/starpunk/__init__.py`
|
||||
**Line 272 - Version Update:**
|
||||
```python
|
||||
# FROM:
|
||||
__version__ = "1.1.1"
|
||||
|
||||
# TO:
|
||||
__version__ = "1.1.1-rc.2"
|
||||
```
|
||||
|
||||
#### 3. File: `/CHANGELOG.md`
|
||||
Added hotfix entry documenting the changes and fixes.
|
||||
|
||||
### Route Structure After Fix
|
||||
|
||||
| Path | Function | Purpose | Status |
|
||||
|------|----------|---------|--------|
|
||||
| `/admin/` | `dashboard()` | Notes list | Working |
|
||||
| `/admin/metrics-dashboard` | `metrics_dashboard()` | Metrics viz | Fixed |
|
||||
| `/admin/metrics` | `metrics()` | JSON API | Working |
|
||||
| `/admin/health` | `health_diagnostics()` | Health check | Working |
|
||||
|
||||
## Testing Results
|
||||
|
||||
### Transformer Function Validation
|
||||
Created a dedicated test script to verify the data transformation works correctly:
|
||||
|
||||
**Test Cases:**
|
||||
1. **Full metrics data**: Transform nested `by_type` structure to flat structure
|
||||
2. **Empty metrics**: Handle missing `by_type` gracefully with zero defaults
|
||||
3. **Template expectations**: Verify all required fields accessible
|
||||
|
||||
**Results:**
|
||||
```
|
||||
✓ All template expectations satisfied!
|
||||
✓ Transformer function works correctly!
|
||||
```
|
||||
|
||||
**Data Structure Verification:**
|
||||
- Input: `metrics.by_type.database.count` → Output: `metrics.database.count` ✓
|
||||
- Input: `metrics.by_type.database.avg_duration_ms` → Output: `metrics.database.avg` ✓
|
||||
- Input: `metrics.by_type.database.min_duration_ms` → Output: `metrics.database.min` ✓
|
||||
- Input: `metrics.by_type.database.max_duration_ms` → Output: `metrics.database.max` ✓
|
||||
- Safe defaults provided when data is missing ✓
|
||||
|
||||
### Admin Route Tests (Critical for Hotfix)
|
||||
```bash
|
||||
uv run pytest tests/test_routes_admin.py -v
|
||||
```
|
||||
|
||||
**Results:**
|
||||
- Total: 32 tests
|
||||
- Passed: 32
|
||||
- Failed: 0
|
||||
- Success Rate: 100%
|
||||
|
||||
### Key Test Coverage
|
||||
- Dashboard loads without error
|
||||
- All CRUD operations redirect correctly
|
||||
- Authentication still works
|
||||
- Navigation links functional
|
||||
- No 500 errors in admin routes
|
||||
- Transformer handles empty/missing data gracefully
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
- [x] Route conflict resolved - `/admin/` and `/admin/metrics-dashboard` are distinct
|
||||
- [x] Data transformer function correctly maps nested structure to flat structure
|
||||
- [x] Template expectations met - all required fields accessible
|
||||
- [x] Safe defaults provided for missing/empty metrics data
|
||||
- [x] Field name mapping correct (`avg_duration_ms` → `avg`, etc.)
|
||||
- [x] Defensive imports handle missing monitoring module gracefully
|
||||
- [x] All existing `url_for("admin.dashboard")` calls still work
|
||||
- [x] Notes dashboard at `/admin/` remains unchanged
|
||||
- [x] All admin route tests pass
|
||||
- [x] Version number updated
|
||||
- [x] CHANGELOG updated
|
||||
- [x] No new test failures introduced
|
||||
|
||||
## Files Modified
|
||||
|
||||
1. `/starpunk/routes/admin.py` - Data transformer function, route handler updates, defensive imports
|
||||
2. `/starpunk/__init__.py` - Version bump
|
||||
3. `/CHANGELOG.md` - Hotfix documentation
|
||||
|
||||
## Backward Compatibility
|
||||
|
||||
This hotfix is **fully backward compatible**:
|
||||
|
||||
1. **Existing redirects**: All 8+ locations using `url_for("admin.dashboard")` continue to work correctly, resolving to the notes dashboard at `/admin/`
|
||||
2. **Navigation templates**: Already used correct endpoint names (`admin.dashboard` and `admin.metrics_dashboard`)
|
||||
3. **No breaking changes**: All existing functionality preserved
|
||||
4. **URL structure**: Only the metrics dashboard route changed (from `/admin/dashboard` to `/admin/metrics-dashboard`)
|
||||
|
||||
## Production Impact
|
||||
|
||||
### Before Hotfix
|
||||
- `/admin/metrics-dashboard` returned 500 error
|
||||
- Jinja2 template error: `'dict object' has no attribute 'database'`
|
||||
- Users unable to access metrics dashboard
|
||||
- Template couldn't access metrics data in expected structure
|
||||
|
||||
### After Hotfix
|
||||
- `/admin/` displays notes dashboard correctly
|
||||
- `/admin/metrics-dashboard` loads without error
|
||||
- Data transformer maps `metrics.by_type.database` → `metrics.database`
|
||||
- Field names correctly mapped (`avg_duration_ms` → `avg`, etc.)
|
||||
- Safe defaults provided for missing data
|
||||
- No 500 errors
|
||||
- All redirects work as expected
|
||||
|
||||
## Deployment Notes
|
||||
|
||||
### Deployment Steps
|
||||
1. Merge hotfix branch to main
|
||||
2. Tag as `v1.1.1-rc.2`
|
||||
3. Deploy to production
|
||||
4. Verify `/admin/` and `/admin/metrics-dashboard` both load
|
||||
5. Monitor error logs for any issues
|
||||
|
||||
### Rollback Plan
|
||||
If issues occur:
|
||||
1. Revert to `v1.1.1-rc.1`
|
||||
2. Direct users to `/admin/` instead of `/admin/dashboard`
|
||||
3. Temporarily disable metrics dashboard
|
||||
|
||||
## Deviations from Design
|
||||
|
||||
**Minor deviation in transformer implementation:** The ADR-060 specified the transformer logic structure, which was implemented with a slight optimization:
|
||||
|
||||
- **Specified**: Separate `if 'by_type' in metrics_stats:` block wrapper
|
||||
- **Implemented**: Combined condition in single loop for cleaner code: `if 'by_type' in metrics_stats and op_type in metrics_stats['by_type']:`
|
||||
|
||||
This produces identical behavior with slightly more efficient code. All other aspects followed the design exactly:
|
||||
- ADR-022: Route naming strategy
|
||||
- ADR-060: Data transformer pattern
|
||||
- Design documents: Code changes and defensive imports
|
||||
- Validation script: Testing approach
|
||||
|
||||
## Follow-up Items
|
||||
|
||||
### For v1.2.0
|
||||
1. Implement `starpunk.monitoring` module properly
|
||||
2. Add comprehensive metrics collection
|
||||
3. Consider dashboard consolidation
|
||||
|
||||
### For v2.0.0
|
||||
1. Restructure admin area with sub-blueprints
|
||||
2. Implement consistent URL patterns
|
||||
3. Add dashboard customization options
|
||||
|
||||
## Conclusion
|
||||
|
||||
The hotfix successfully resolves the production 500 error by:
|
||||
1. Eliminating the route conflict through clear path separation (initial fix)
|
||||
2. Adding data transformer function to map metrics structure to template expectations
|
||||
3. Transforming nested `by_type` structure to flat structure expected by template
|
||||
4. Mapping field names correctly (`avg_duration_ms` → `avg`, etc.)
|
||||
5. Providing safe defaults for missing or empty metrics data
|
||||
6. Adding defensive imports to handle missing modules gracefully
|
||||
7. Maintaining full backward compatibility with zero breaking changes
|
||||
|
||||
**Root Cause Resolution:**
|
||||
- Template expected: `metrics.database.count`
|
||||
- Code provided: `metrics.by_type.database.count`
|
||||
- Solution: Route Adapter Pattern transforms data at presentation layer
|
||||
|
||||
All tests pass, including the critical admin route tests. The fix is minimal, focused, and production-ready.
|
||||
|
||||
## Sign-off
|
||||
|
||||
- **Implementation**: Complete
|
||||
- **Testing**: Passed (100% of admin route tests)
|
||||
- **Documentation**: Updated
|
||||
- **Ready for Deployment**: Yes
|
||||
- **Architect Approval**: Pending
|
||||
|
||||
---
|
||||
|
||||
**Branch**: `hotfix/v1.1.1-rc.2-route-conflict`
|
||||
**Commit**: Pending
|
||||
**Status**: Ready for merge and deployment
|
||||
Reference in New Issue
Block a user