Component: Loop Backend Labels: bms, backend, database, phase-1 Description: Create Laravel migrations for 5 BMS tables: bms_connections, bms_equipment_mappings, bms_activity_logs, bms_unmapped_points, bms_message_queue.
Acceptance Criteria:
- All 5 tables created with proper columns, indexes, and foreign keys
- event_type enum includes: message_received, connection_established, connection_lost, error, config_changed, unmapped_point, validation_failed
- mqtt_password_encrypted (TEXT) and mqtt_password_hash (VARCHAR nullable) fields in bms_connections
- Follows existing Loop migration patterns
- Migrations run successfully on dev database
Reference: BMS_UI_INTEGRATION_PLAN.md Section 7
Component: Loop Backend Labels: bms, backend, nestjs, phase-1 Description: Create BMS Integration module in loop-backend-version-2/apps/core/src/modules/bms-integration/ following existing module patterns.
Acceptance Criteria:
- Module structure created: bms-integration.module.ts, controller, service
- Module registered in app.module.ts
- Follows existing module patterns (qr-code, equipment-readings)
- Module compiles without errors
Reference: BMS_UI_INTEGRATION_PLAN.md Section 6
Component: Loop Backend Labels: bms, backend, typeorm, phase-1 Description: Create TypeORM entities for BMS tables with proper relationships and synchronize: false.
Acceptance Criteria:
- 5 entities created: BmsConnection, BmsEquipmentMapping, BmsActivityLog, BmsUnmappedPoint, BmsMessageQueue
- All entities use synchronize: false
- Proper relationships defined (ManyToOne, OneToMany)
- Entities include mqtt_password_encrypted and mqtt_password_hash (nullable)
- Foreign keys to Buildings, Equipments, Users
Reference: BMS_UI_INTEGRATION_PLAN.md Section 6.5
Component: Loop Backend Labels: bms, backend, security, phase-1 Description: Implement JWT authentication and role-based access control for BMS module following auth module patterns.
Acceptance Criteria:
- JwtAuthGuard applied to all BMS endpoints
- RBAC implemented: Admin/Manager can create/edit, Owner/Consultant view-only
- Admin-only endpoints for credential viewing/regeneration
- Follows existing auth patterns from auth.controller.ts
Reference: BMS_UI_INTEGRATION_PLAN.md Section 1.2, 6.3
Component: Loop Backend Labels: bms, backend, typeorm, phase-1 Description: Register BMS entities in global TypeORM configuration to avoid EntityMetadataNotFoundError.
Acceptance Criteria:
- All 5 BMS entities added to apps/core/src/database/db.provider.ts EntitiesList
- Application starts without entity metadata errors
- Entities accessible across modules
Reference: BMS_UI_INTEGRATION_PLAN.md Section 6
Component: Loop Frontend Labels: bms, frontend, ui, phase-2 Description: Add BMS Integration tab to Building Edit page with empty state and connected state layouts.
Acceptance Criteria:
- New tab "BMS Integration" in Building Edit page
- Empty state: "No BMS Connection" with "+ Connect BMS" button
- Connected state: Status card with connection details
- Tab only visible to Admin/Manager roles
- Responsive design (mobile/tablet/desktop)
Reference: BMS_UI_INTEGRATION_PLAN.md Section 2
Component: Loop Frontend Labels: bms, frontend, ui, modal, phase-2 Description: Create 2-step wizard modal for connecting a BMS system.
Acceptance Criteria:
- Step 1: BMS type selection (Schneider/WebCTRL radio buttons)
- Step 2: Protocol selection (MQTT TLS/WebSocket)
- Auto-generates credentials display
- Modal follows CoreUI patterns
- Form validation
- Works with mocked data
Reference: BMS_UI_INTEGRATION_PLAN.md Section 3
Component: Loop Frontend Labels: bms, frontend, ui, modal, security, phase-2 Description: Create credentials modal for viewing/copying MQTT connection details.
Acceptance Criteria:
- Shows both TLS (8883) and WSS (443) endpoints
- Displays client_id, username, password, topic
- Copy-to-clipboard buttons for each field
- Password reveal/hide toggle
- Admin-only access (hidden for other roles)
- Regenerate credentials button with confirmation
Reference: BMS_UI_INTEGRATION_PLAN.md Section 4.1, 8.2
Component: Loop Frontend Labels: bms, frontend, ui, modal, phase-2 Description: Create modal for mapping BMS points to Loop equipment.
Acceptance Criteria:
- Table showing existing mappings (point_id, equipment, status, last_reading)
- "Unmapped BMS Points" section with detected points
- Add mapping form (select equipment, enter point_id)
- Edit/delete mapping actions
- Works with mocked data
Reference: BMS_UI_INTEGRATION_PLAN.md Section 4.2
Component: Loop Frontend Labels: bms, frontend, ui, modal, phase-2 Description: Create modal for viewing BMS connection activity logs.
Acceptance Criteria:
- Filterable list (event_type, severity, date range)
- Event types: message_received, connection_established, connection_lost, error, config_changed, unmapped_point, validation_failed
- Severity badges (info/warning/error)
- Pagination
- Works with mocked data
Reference: BMS_UI_INTEGRATION_PLAN.md Section 4.3
Component: Loop Frontend Labels: bms, frontend, mocking, phase-2 Description: Create mock data service layer with fixtures for UI-first development.
Acceptance Criteria:
- src/mocks/bms/ folder with fixtures (connection, credentials, mappings, unmapped-points, activity, stats)
- bmsService.js with REACT_APP_MOCK_BMS toggle
- Scenario switching support (?bmsScenario=error)
- Mock functions for all API methods
- Fixtures cover: none, active, error states
Reference: BMS_UI_INTEGRATION_PLAN.md Section 13
Component: Infrastructure Labels: bms, infrastructure, mqtt, aks, phase-3 Description: Deploy Mosquitto MQTT broker to AKS loop-dev namespace.
Acceptance Criteria:
- Mosquitto deployment in loop-dev namespace
- ConfigMap for mosquitto.conf
- Resource limits: 100m CPU, 128Mi memory (dev)
- Single replica for dev
- Broker accessible within cluster
Reference: BMS_UI_INTEGRATION_PLAN.md Section 11
Component: Infrastructure Labels: bms, infrastructure, mqtt, networking, phase-3 Description: Expose Mosquitto broker via TLS (8883) and WebSocket (443) endpoints.
Acceptance Criteria:
- LoadBalancer service for port 8883 (native MQTT over TLS)
- Ingress for WSS at wss://mqtt.loop.l7energy.com/mqtt (port 443)
- Ingress proxy-read-timeout: 3600s for long-lived connections
- Both endpoints accessible from external networks
- DNS configured: mqtt.loop.l7energy.com
Reference: BMS_UI_INTEGRATION_PLAN.md Section 11.2
Component: Infrastructure Labels: bms, infrastructure, security, certificates, phase-3 Description: Configure cert-manager for TLS certificates and Azure Key Vault for secrets.
Acceptance Criteria:
- cert-manager installed with Let's Encrypt
- TLS certificate for mqtt.loop.l7energy.com
- Key Vault CSI driver configured
- Encryption key for mqtt_password_encrypted stored in Key Vault
- Certificates auto-renew
Reference: BMS_UI_INTEGRATION_PLAN.md Section 11.6, 8.3
Component: Infrastructure Labels: bms, infrastructure, mqtt, security, phase-3 Description: Configure MQTT topic ACLs and environment separation (loop-dev vs loop).
Acceptance Criteria:
- Topic namespace: loop-dev/buildings/{id}/readings (dev)
- Topic namespace: loop/buildings/{id}/readings (prod)
- ACLs restrict each connection to its building's topic only
- Username/password authentication configured
- Test connection can publish/subscribe to assigned topic only
Reference: BMS_UI_INTEGRATION_PLAN.md Section 8.4, 9.1
Component: Loop Backend Labels: bms, backend, api, phase-4 Description: Implement REST API endpoints for BMS connection management.
Acceptance Criteria:
- GET /api/buildings/{id}/bms-connection
- POST /api/buildings/{id}/bms-connection (auto-generates credentials)
- PUT /api/buildings/{id}/bms-connection
- DELETE /api/buildings/{id}/bms-connection
- PATCH /api/buildings/{id}/bms-connection/status
- POST /api/buildings/{id}/bms-connection/regenerate-credentials (Admin only)
- Swagger documentation
- RBAC enforced
Reference: BMS_UI_INTEGRATION_PLAN.md Section 12.1
Component: Loop Backend Labels: bms, backend, api, phase-4 Description: Implement REST API endpoints for equipment mapping management.
Acceptance Criteria:
- GET /api/buildings/{id}/bms-connection/mappings
- POST /api/buildings/{id}/bms-connection/mappings
- PUT /api/bms-equipment-mappings/{id}
- DELETE /api/bms-equipment-mappings/{id}
- GET /api/buildings/{id}/bms-connection/unmapped-points
- Swagger documentation
- RBAC enforced
Reference: BMS_UI_INTEGRATION_PLAN.md Section 12.2
Component: Loop Backend Labels: bms, backend, api, phase-4 Description: Implement REST API endpoints for activity logs and connection statistics.
Acceptance Criteria:
- GET /api/buildings/{id}/bms-connection/activity (with filters)
- GET /api/buildings/{id}/bms-connection/stats
- POST /api/buildings/{id}/bms-connection/test
- Pagination for activity logs
- Stats include: messages_today, last_message_at, uptime, error_count_24h
- Swagger documentation
Reference: BMS_UI_INTEGRATION_PLAN.md Section 12.3
Component: Loop Backend Labels: bms, backend, mqtt, processor, phase-4 Description: Create MQTT subscriber service to ingest messages from broker and process readings.
Acceptance Criteria:
- MQTT client connects to broker with credentials
- Subscribes to loop-dev/buildings/+/readings topic
- Parses message payload (point_id, value, unit, timestamp)
- Validates message contract
- Logs unmapped points to bms_unmapped_points table
- Logs activity to bms_activity_logs
- Error handling and retry logic
Reference: BMS_UI_INTEGRATION_PLAN.md Section 9
Component: Loop Backend Labels: bms, backend, readings, bucketing, phase-4 Description: Implement 30-minute bucketing for BMS readings with idempotency.
Acceptance Criteria:
- Bucket timestamp to 30-min intervals using UTC epoch-flooring
- Upsert to equipment_readings table with (equipment_id, reading_date, source='bms')
- Add source column to equipment_readings if not exists
- Later messages for same bucket overwrite earlier values
- Timezone: bucketing in UTC, display in building local time
- Unit tests for bucketing function
Reference: BMS_UI_INTEGRATION_PLAN.md Section 10
Component: Loop Backend Labels: bms, backend, security, encryption, phase-4 Description: Implement AES-256 encryption/decryption for MQTT passwords using Azure Key Vault.
Acceptance Criteria:
- Encryption service using AES-256
- Encryption key retrieved from Azure Key Vault
- Encrypt password on connection creation
- Decrypt password for Admin credential viewing
- Optional bcrypt hash generation for broker auth
- Unit tests for encryption/decryption
Reference: BMS_UI_INTEGRATION_PLAN.md Section 7.1, 8.3
Component: Loop Frontend Labels: bms, frontend, integration, phase-5 Description: Replace mock data service with real API calls to backend.
Acceptance Criteria:
- Set REACT_APP_MOCK_BMS=false
- All API calls work with real backend
- Error handling for API failures
- Loading states during API calls
- Toast notifications for success/error
- No console errors
Reference: BMS_UI_INTEGRATION_PLAN.md Section 14.2
Component: Testing Labels: bms, testing, playwright, e2e, phase-5 Description: Create Playwright E2E tests for BMS integration workflows.
Acceptance Criteria:
- Test: Complete setup wizard flow (connect BMS)
- Test: View credentials (Admin only)
- Test: Create equipment mapping
- Test: View activity logs
- Test: Delete BMS connection
- Tests use MSW for mocked backend
- Tests pass in CI/CD pipeline
Reference: BMS_UI_INTEGRATION_PLAN.md Section 19.3
Component: Testing Labels: bms, testing, integration, mqtt, phase-5 Description: Create integration tests that publish test MQTT messages and verify processing.
Acceptance Criteria:
- Test MQTT client publishes to loop-dev/buildings/{id}/readings
- Verify message logged in bms_activity_logs
- Verify reading bucketed and stored in equipment_readings
- Verify unmapped points detected and logged
- Test error scenarios (invalid payload, auth failure)
- Tests run in dev environment
Reference: BMS_UI_INTEGRATION_PLAN.md Section 19.2
Component: Documentation Labels: bms, documentation, phase-5 Description: Create user and technical documentation for BMS integration.
Acceptance Criteria:
- User guide: BMS setup wizard walkthrough
- User guide: Schneider EcoStruxure configuration instructions
- User guide: WebCTRL configuration instructions
- User guide: Troubleshooting guide
- Technical docs: API endpoint reference
- Technical docs: MQTT topic structure and message format
- Technical docs: Database schema documentation
Reference: BMS_UI_INTEGRATION_PLAN.md Section 20
- Total Stories: 25
- Phase 1 (Backend Foundation): 5 stories
- Phase 2 (UI with Mocks): 6 stories
- Phase 3 (MQTT Infrastructure): 4 stories
- Phase 4 (Backend API): 6 stories
- Phase 5 (Integration & Testing): 4 stories
All stories link to Epic L7E-342