[BE-24] Implement asset history and audit trail — GET /assets/:id/history

[yusuftomilola]

Overview

The asset detail page (frontend/app/(dashboard)/assets/[id]/page.tsx) has a "History" tab that calls GET /assets/:id/history and renders a timeline of all events on the asset. Every create, update, status change, transfer, maintenance event, note, and document upload must be captured.

Context

• Frontend: frontend/lib/api/assets.ts getAssetHistory(id) calls GET /assets/:id/history
• Frontend type: AssetHistoryEvent.action enum in frontend/lib/query/types/asset.ts: CREATED, UPDATED, STATUS_CHANGED, TRANSFERRED, MAINTENANCE, NOTE_ADDED, DOCUMENT_UPLOADED
• History records are write-only — they must never be updated or deleted (immutable audit trail)

Acceptance Criteria

• Create AssetHistory entity: id (UUID), assetId, action (AssetHistoryAction enum), userId (who performed the action), metadata (JSON — stores before/after values or relevant context), createdAt
• Create AssetHistoryAction enum matching the frontend: CREATED, UPDATED, STATUS_CHANGED, TRANSFERRED, MAINTENANCE, NOTE_ADDED, DOCUMENT_UPLOADED
• GET /assets/:id/history returns paginated history records sorted by createdAt DESC, with user firstName and lastName included (JOIN, not N+1)
• Create AssetHistoryService.log(assetId, action, userId, metadata?) as a reusable method called from AssetsService, NotesService, MaintenanceService, DocumentService
• Add @Index() on AssetHistory.assetId and AssetHistory.createdAt

[temitope-007]

@temitope-007 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hi maintainer

Please i'd like to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @temitope-007 to this issue.

[Babigdk]

@Babigdk has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I'd like to work on #897.

I have experience building audit trails and event-history systems in NestJS/TypeORM applications.

For this issue, I will:

• Create the "AssetHistory" entity and "AssetHistoryAction" enum matching frontend requirements.
• Add indexed "assetId" and "createdAt" fields for efficient history queries.
• Implement a reusable "AssetHistoryService.log()" method.
• Integrate history logging into asset, note, maintenance, and document workflows.
• Implement "GET /assets/:id/history" with pagination, newest-first ordering, and joined user information to avoid N+1 queries.
• Add tests to verify logging, pagination, ordering, and immutability.

This will provide a complete audit trail for all asset lifecycle events while keeping the implementation performant and maintainable.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Babigdk to this issue.

[temiport25]

@temiport25 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

can i work on this issue?

ℹ️ Repo Maintainers: To accept this application, review their application or assign @temiport25 to this issue.

[drips-wave]

Congratulations, @temiport25! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @temiport25: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[drips-wave]

This issue has been completed by @temiport25 as part of the Stellar Wave Program's 6th Wave 🥳

😎 @temiport25: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.