feat(api): add staff order detail and compliance eligibility

backend/command-api/src/services/mobile-command-service.js

@@ -1,5 +1,6 @@
 import crypto from 'node:crypto';
 import { AppError } from '../lib/errors.js';
+import { buildStaffOrderEligibilityBlockers, dedupeDocumentNames } from '../lib/staff-order-eligibility.js';
 import { query, withTransaction } from './db.js';
 import { loadActorContext, requireClientContext, requireStaffContext } from './actor-context.js';
 import { recordGeofenceIncident } from './attendance-monitoring.js';
@@ -89,6 +90,53 @@ async function ensureStaffNotBlockedByBusiness(client, { tenantId, businessId, s
   }
 }
 
+async function loadMissingRequiredDocuments(client, { tenantId, roleCode, staffId }) {
+  if (!roleCode) return [];
+
+  const result = await client.query(
+    `
+    SELECT d.name
+    FROM documents d
+    WHERE d.tenant_id = $1
+      AND d.required_for_role_code = $2
+      AND d.document_type <> 'ATTIRE'
+      AND NOT EXISTS (
+        SELECT 1
+        FROM staff_documents sd
+        WHERE sd.tenant_id = d.tenant_id
+          AND sd.staff_id = $3
+          AND sd.document_id = d.id
+          AND sd.status = 'VERIFIED'
+      )
+    ORDER BY d.name ASC
+    `,
+    [tenantId, roleCode, staffId]
+  );
+
+  return dedupeDocumentNames(result.rows.map((row) => row.name));
+}
+
+function buildMissingDocumentErrorDetails({
+  roleCode,
+  orderId = null,
+  shiftId = null,
+  roleId = null,
+  missingDocumentNames = [],
+}) {
+  const blockers = buildStaffOrderEligibilityBlockers({
+    missingDocumentNames,
+  });
+
+  return {
+    orderId,
+    shiftId,
+    roleId,
+    roleCode: roleCode || null,
+    blockers,
+    missingDocuments: dedupeDocumentNames(missingDocumentNames),
+  };
+}
+
 function buildAssignmentReferencePayload(assignment) {
   return {
     assignmentId: assignment.id,
@@ -3024,6 +3072,20 @@ export async function bookOrder(actor, payload) {
       staffId: staff.id,
     });
 
+    const missingRequiredDocuments = await loadMissingRequiredDocuments(client, {
+      tenantId: context.tenant.tenantId,
+      roleCode: selectedRole.code,
+      staffId: staff.id,
+    });
+    if (missingRequiredDocuments.length > 0) {
+      throw new AppError('UNPROCESSABLE_ENTITY', 'Staff is missing required documents for this role', 422, buildMissingDocumentErrorDetails({
+        orderId: payload.orderId,
+        roleId: payload.roleId,
+        roleCode: selectedRole.code,
+        missingDocumentNames: missingRequiredDocuments,
+      }));
+    }
+
     const bookingId = crypto.randomUUID();
     const assignedShifts = [];