docs(openspec): archive completed changes and sync main specs

Archive three completed changes to archive/:
- api-resource-standard (70 tasks, 14 resource classes)
- capacity-expert-mode (68 tasks, expert mode planning grid)
- enhanced-allocation (62 tasks, planning fidelity + reporting)

Sync all delta specs to main specs/:
- api-resource-standard: API response standardization
- capacity-expert-mode: Expert mode toggle, grid, KPIs, batch API
- resource-allocation: Month execution comparison, bulk, untracked
- untracked-allocation: Null team member support
- allocation-indicators: Variance indicators (red/amber/neutral)
- monthly-budget: Explicit project-month planning

All changes verified and tested (157 tests passing).
This commit is contained in:
2026-03-08 19:13:28 -04:00
parent ec15386b52
commit b8262bbcaf
26 changed files with 2949 additions and 0 deletions

View File

@@ -0,0 +1,58 @@
## Why
The Headroom API currently returns raw JSON responses without a standardized wrapper. This violates the architecture specification (docs/headroom-architecture.md, lines 315-393) which mandates Laravel API Resources for consistent JSON structure. This technical debt creates several problems:
1. **Inconsistent Response Format**: Some endpoints return arrays, others objects, making client-side parsing error-prone
2. **No Future-Proofing**: Adding metadata (pagination, relationships, meta) requires breaking changes later
3. **Missing Data Wrapper**: Architecture requires `"data"` key for all responses to support future transformations
4. **No Resource Abstraction**: Direct model exposure limits ability to transform data without breaking clients
Since the application is pre-production and not in active use, we should fix this now to avoid permanent technical debt.
## What Changes
### Breaking Changes
- **BREAKING**: All API responses will be wrapped in `"data"` key
- **BREAKING**: Collections will use Laravel's resource collection format with `"data"` array
- **BREAKING**: Frontend API client must unwrap `response.data` instead of direct access
### New Components
- Create `app/Http/Resources/` directory structure
- Create 11 API Resource classes for consistent transformation
- Create base `BaseResource` with common formatting utilities
### Updated Components
- Update 6 controllers to use API Resources instead of `response()->json()`
- Update 63 backend tests to expect `"data"` wrapper in responses
- Update frontend API client to handle new response format
- Regenerate Scribe API documentation
## Capabilities
### New Capabilities
- `api-resource-standard`: Standardize all API responses using Laravel API Resources with consistent `"data"` wrapper
### Modified Capabilities
- *(none - this is a refactoring change, no functional requirements change)*
## Impact
### Backend (Laravel)
- **Files Created**: 11 new resource classes in `app/Http/Resources/`
- **Files Modified**: 6 controllers in `app/Http/Controllers/Api/`
- **Tests Updated**: 63 feature tests
- **New Tests**: 11+ unit tests for resource classes
### Frontend (SvelteKit)
- **Files Modified**: API client in `src/lib/api/` directory
- **Breaking**: All API calls must access `response.json().data` instead of `response.json()`
### Documentation
- **Regenerated**: Scribe API docs will show new response format
### Dependencies
- No new dependencies required (Laravel's built-in API Resources)
### Performance
- Minimal impact - API Resources add negligible overhead
- Slight improvement: Consistent caching keys can be optimized