Summary

We need a fresh implementation of the asset audit feature on a new branch. Keep two artifacts from copilot/fix-1991—the Prisma AuditSession schema/migration and the reusable audit drawer foundation (app/components/scanner/drawer/uses/audit-location-drawer.tsx)—and rebuild everything else against the refined workflow described below.

Background

• Issue Feat: Location/Kit Audit System #1991 exposed major gaps in our audit experience.
• The current branch diverged from Shelf standards; we’re restarting while salvaging the DB schema and drawer groundwork.
• The 16 Sep 2025 discussion between Nikolay and Carlos defined the end-to-end requirements (flexible audits, multi-auditor tracking, authoritative outputs).

Goals

• Launch audits directly from filtered selections in the advanced asset index.
• Support multi-auditor collaboration with per-scan attribution and metadata.
• Provide real-time visibility into expected/found/missing/unexpected assets.
• Deliver authoritative in-app summaries and downloadable PDF reports.
• Capture reliable evidence (QR scans) with optional metadata attachments.
• Ensure audits don’t block other workflows (partial progress is OK).

Scope

1. Audit Session Management

• Add a new bulk action to the asset index (“Actions → Start Audit”) that opens a dialog form.
• Form should let users name the audit, add a description, choose assignees, and confirm the selected assets; extend the Prisma model/migration accordingly.
• On submit, create a new audit tied to the chosen assets and launch the new audit drawer.
• Drawer should preload the assets in the session, marking them “scanned” as QR hits come in.
• Reuse the drawer patterns from audit-location-drawer.tsx, adapting BaseDrawer/ConfigurableDrawer as needed (allow preloaded rows, per-asset states, status chips).
• Allow adding assets to existing audits and assigning multiple auditors.
• Preserve partial progress, resume/cancel audits without blocking other flows.

2. Audit Experience

• Introduce an “Audits” page in the sidebar (just below Reminders).
• All organization roles can view audits, but base/self-service roles see only audits assigned to them and cannot create new ones.
• Support multi-auditor attribution (record which user scanned each item, with timestamps).
• Surface real-time counts for expected/found/missing/unexpected; keep the unexpected items visible but non-blocking.
• Provide a clean audit detail view plus actions to add metadata, upload optional photos, etc.

3. Reporting & Outputs

• Create an in-app summary screen highlighting expected vs. unexpected scans.
• Generate PDFs that mirror the summary (sections for expected/found/missing/unexpected).
• Include metadata (scan location, device, optional photo evidence) in both views.
• Make the PDF download accessible from the audit detail page/drawer.

4. Notifications & Follow-Up

• Trigger email notifications for key events (audit created/assigned/completed, discrepancies).
• Document how we’ll evolve toward in-app notifications later.

5. Database & Domain Work

• Retain the existing AuditSession schema and migration from copilot/fix-1991, then extend it for:
  • audit name/description
  • per-asset audit entries (status, auditor, timestamps, metadata, optional photo reference)
  • assignments (audit ↔ user)
• Model relationships to assets, assigned users, and captured evidence.

6. Tech & Testing

• Build on a fresh branch; manually port only the AuditSession migration and drawer base logic.
• Document new APIs, drawer props, and workflow states.
• Cover service-layer logic, drawer behavior, and PDF generation with tests.
• Validate bulk selection → audit creation → scanning → reporting end-to-end.

Non-Goals

• Real-time socket-based collaboration for now.
• Automated corrections for unexpected assets.
• Full-blown notification center (email only in v1).
• Mandatory photo evidence.

Deliverables

• New audit domain services (create/update/cancel, asset logging, metadata).
• Shared audit drawer + updated BaseDrawer evaluation (support preloaded rows, status updates).
• Asset index bulk action + “Start Audit” dialog.
• Audits sidebar section with list/detail page and PDF download.
• Expanded Prisma schema/migration + docs.
• Regression tests and QA checklist.

Dependencies

• Advanced asset index filtering + bulk selection infrastructure.
• QR scanning pipeline.
• Email notification service.

Risks & Considerations

• Imports/bulk updates must stay compatible with ongoing audits.
• Multi-auditor collaboration needs clear UX for clashing scans.
• Permissions must be enforced per role (especially for base/self-service).

Next Steps

1. Create the new feature branch.
2. Copy over:
   • app/database/schema.prisma + app/database/migrations/...create_audit_session_model_and_relations
   • app/components/scanner/drawer/uses/audit-location-drawer.tsx
3. Extend Prisma models for audit name/description, assignees, per-asset records.
4. Implement audit creation dialog + index bulk action.
5. Build out drawer refactor & audit service layer.
6. Add Audits sidebar section, detail view, PDF export, metadata capture.
7. Wire up notifications and permissions.
8. Write tests + docs; QA full flow.