[BosuBose132]

Overview

Enhanced the Building Management Equipment backend to support historical status updates, smart-default data retrieval, replacement validation, authenticated user attribution, and consistent equipment status handling.

These changes support the frontend Tool Status Update Form enhancements while improving data integrity, response handling, and test coverage.

Original Task Requirements Supported

The backend changes support the following Tool Status Update Form requirements:

1. Retrieve previous user and usage information for automatic form defaults.
2. Provide historical update details, including the update date, condition/status, and last known user.
3. Save replacement information and validate the replacement reason when required.
4. Return the saved update information needed for accurate submission confirmation.

Related Frontend PR

This is related to frontend PR #5782
The frontend PR implements the corresponding UI enhancements, smart defaults, history summary, validation feedback, and submission confirmation.

Changes Implemented

Equipment Status History

• Extended the BuildingEquipment schema to maintain equipment status-update history.
• Persisted update information including condition/status, update timestamp, last user, usage purpose, replacement requirement, replacement reason, description, and notes.
• Improved equipment response population so the frontend can retrieve historical update information and associated user details.

Validation and Data Integrity

• Implemented server-side validation for equipment status values.
• Added normalization to map supported frontend and legacy status labels to canonical backend values.
• Rejected invalid status values before database updates.
• Added conditional replacement reason validation.
• Ensured replacement reasons are cleared when replacement is not required.
• Preserved compatibility with existing equipment records and supported historical status formats.

Authentication and Submission Handling

• Strengthened update authentication by using the authenticated request identity rather than trusting client-provided user identifiers.
• Improved validation responses for invalid requests.
• Ensured successful responses contain the persisted update information needed by the frontend.
• Refactored status-update pre-validation into a focused helper to reduce controller complexity while preserving behavior and response contracts.

Automated Tests

• Added and expanded backend equipment-controller tests.
• Covered valid and invalid statuses, replacement validation, authenticated user attribution, saved history handling, and API response behavior.
• Verified that invalid requests are rejected appropriately.

Testing Performed

Feature-Specific Tests

• Backend equipment-controller tests: 38 passed.
• Backend ESLint: 0 errors, 4 remaining warnings.
• Controller complexity warning: Resolved.
• Backend Prettier checks: Passed.
• Backend build: Passed (791 files compiled).
• git diff --check: Passed.

Known Upstream Test-Suite Failure

The broader backend pre-commit test selection reports 30 failures in bmMaterialsController.test.js.

To determine whether the feature introduced these failures, I ran equivalent test selections against both the feature branch and a clean origin/development baseline (985e7aec6).

Results on both branches were identical:

• 94 suites executed.
• 93 suites passed, 1 failed.
• 1,697 tests passed, 30 failed, 6 skipped, 2 todo.

The materials-controller suite also passed independently on both branches (84/84 tests).

This confirms that the broader test-selection failure reproduces on the development baseline and is not specific to the equipment feature. The behavior appears related to shared test context, mock isolation, or test execution order. The underlying cause has not yet been fully identified.

No unrelated materials-controller implementation or test files were modified.

The issue may still affect CI and should be tracked independently by backend maintainers.

How to Test

1. Run the HGNRest backend and connect it to the development database.
2. Log in through the frontend using an authorized account.
3. Navigate to the Equipment List and open the Tool/Equipment Status Update Form.
4. Select a valid status, previous user, and usage purpose.
5. Select Yes for replacement and provide a replacement reason.
6. Submit the form and verify that the update is saved successfully.
7. Verify the equipment's status history contains the new update and appropriate authenticated user information.
8. Refresh the frontend and confirm that historical information can be retrieved.
9. Test a missing replacement reason and confirm the request is rejected.
10. Verify that unsupported status values are rejected by backend validation.
11. Confirm successful responses contain the saved update information.

Known Limitations / Reviewer Notes

Status Mapping — Requires Product Approval

Some distinct frontend status options map to the same backend canonical value:

• Stolen/Lost → Out of Order
• End of life → Out of Order
• Returned → Good
• Working well → Good

These mappings maintain compatibility with the existing backend schema but do not preserve all original business meanings.

Project-lead confirmation is required before merge to determine whether the canonical statuses are acceptable or the data model should be extended.

Image Persistence

The current change does not introduce image-storage support. Image handling remains preview-only on the frontend.

Historical Records

Existing historical records are not migrated.

Screenshots / Demo

Screen.Recording.2026-11-05.at.3.54.22.PM.mov

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
94.4% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud