FP-25: Layer Photo Documentation

[steilerDev]

As a homeowner, I want to upload photos to surface layers so that I can document what's inside each wall, ceiling, and floor with visual evidence per construction layer.

Parent Epic: #752 (EPIC-16: Floor Plans & Utility Tracking)
Priority: Must Have
Phase: 3 — Layers & Cross-Sections

Acceptance Criteria

• 1. The existing photos table (from EPIC-13) supports entity_type = 'surface_layer' with entity_id referencing the surface layer
• 2. POST /api/floor-plans/layers/:layerId/photos uploads a photo and associates it with the surface layer
• 3. GET /api/floor-plans/layers/:layerId/photos returns all photos for a surface layer, ordered by creation date
• 4. DELETE /api/floor-plans/layers/:layerId/photos/:photoId removes a photo from a surface layer
• 5. The layer detail view and wall cross-section view display a photo gallery section for each layer
• 6. Photos can be viewed in a lightbox overlay (full-size) by clicking a thumbnail
• 7. Photos support captions (optional text description entered at upload time or edited later)
• 8. PATCH /api/floor-plans/layers/:layerId/photos/:photoId updates the photo caption
• 9. Deleting a surface layer cascades to delete its associated photos (both database records and stored files)
• 10. The photo gallery is responsive: grid layout on desktop, horizontal scroll on mobile
• 11. Photo upload supports drag-and-drop and click-to-browse (reusing the upload pattern from EPIC-13 diary photos)
• 12. Maximum 20 photos per surface layer; validation error returned if exceeded

Notes

• Dependencies: FP-10 (FP-10: Surface Layers Backend #762) — surface layers backend must exist; EPIC-13 — photos table and upload infrastructure
• Reuses the existing polymorphic photos table with entity_type + entity_id pattern from EPIC-13
• This story was added during spec review — the original spec deferred photos but the user confirmed photo documentation per layer is core to the value proposition
• The same photo upload/storage mechanism from diary entries is reused, minimizing new infrastructure

[steilerDev]

Closing — epic deferred. Will be re-opened if/when EPIC-16 is picked up.