feat: Implement Safety Gates and Permit Management (Sprint 3 Remediat…

SPRINTS.md

@@ -81,3 +81,14 @@ This document maps the implementation tasks (DCMMS-XXX) to their respective Spri
 ## Sprint 19: Energy Bias Fix & Forecasting
 **Focus:** Wind/Solar Bias Fix, Weather API
 - DCMMS-158
+
+## Gap Remediation: Phase 0 (Dec 2025)
+**Focus:** Emergency Workflow Fixes (Mobile, Safety)
+
+### Sprint 3 (Remediation): Safety & Compliance
+**Focus:** Permit Management, Safety Gates
+- DCMMS-025-R, DCMMS-026-R
+
+### Sprint 4 (Remediation): Mobile Offline Foundation
+**Focus:** Offline Sync, Local DB, Technician Auth
+- DCMMS-MO-01 to DCMMS-MO-05

SPRINT_STATUS_TRACKER.md

@@ -737,4 +737,40 @@ Three pull requests restored missing work:
 
 **Maintained By:** Product Manager
 **Update Frequency:** After each sprint completion / major PR merge
-**Last Verified:** November 19, 2025, 09:30 UTC
+
+---
+
+## Gap Remediation - Phase 0: Emergency Workflow Fixes
+**Goal:** Unblock Technician and Buyer personas (Mobile Offline + Safety Gates)
+**Status:** In Progress
+**Reference:** `docs/GAP_REMEDIATION_PLAN.md`
+
+### ✅ Sprint 3 (Remediation): Safety & Compliance
+**Goal:** Enforce permits for critical work
+**Status:** ✅ Complete
+
+- [x] **DCMMS-025-R** - Permit Management API
+  - Verified: `backend/src/services/permit.service.ts`
+  - Verified: `backend/src/routes/permits.ts`
+  - Notes: Full CRUD implemented.
+
+- [x] **DCMMS-026-R** - Safety Gates
+  - Verified: `PermitGuard` logic in `WorkOrderService`
+  - Verified: `backend/test/e2e/permits.e2e.test.ts`
+  - Notes: Blocks critical/emergency WO transition without active permit.
+
+### 🔄 Sprint 4 (Remediation): Mobile Offline Foundation
+**Goal:** Unblock Technician offline workflow
+**Status:** 🔄 In Progress
+
+- [x] **DCMMS-001E** - Mobile Project Setup
+  - Verified: `mobile/` Flutter project structure
+  - Verified: `mobile/lib/core/database/database.dart` (Drift setup)
+
+- [ ] **DCMMS-0XX-R** - Offline Sync Engine
+  - Pending: `SyncRepository` implementation
+  - Pending: Queue management
+  - Pending: Conflict resolution
+
+- [ ] **DCMMS-0XX-R** - Offline Authentication
+  - Pending: Long-lived token / PIN logic

backend/src/db/schema.ts

@@ -1062,6 +1062,25 @@ export const workOrderLaborRelations = relations(workOrderLabor, ({ one }) => ({
   }),
 }));
 
+export const permitsRelations = relations(permits, ({ one }) => ({
+  tenant: one(tenants, {
+    fields: [permits.tenantId],
+    references: [tenants.id],
+  }),
+  workOrder: one(workOrders, {
+    fields: [permits.workOrderId],
+    references: [workOrders.id],
+  }),
+  issuer: one(users, {
+    fields: [permits.issuedBy],
+    references: [users.id],
+  }),
+  approver: one(users, {
+    fields: [permits.approvedBy],
+    references: [users.id],
+  }),
+}));
+
 export const alertsRelations = relations(alerts, ({ one }) => ({
   tenant: one(tenants, {
     fields: [alerts.tenantId],

backend/src/routes/permits.ts

@@ -0,0 +1,167 @@
+import { FastifyInstance } from "fastify";
+import { ZodTypeProvider, serializerCompiler, validatorCompiler } from "fastify-type-provider-zod";
+import { z } from "zod";
+import { PermitService } from "../services/permit.service";
+
+const CreatePermitSchema = z.object({
+    workOrderId: z.string().uuid(),
+    type: z.enum(["hot_work", "confined_space", "electrical", "height"]), // Add other types as needed or keep string
+    status: z.enum(["requested", "active", "expired", "revoked", "completed"]).default("requested"),
+    issuerId: z.string().uuid().optional(),
+    validFrom: z.string().datetime(),
+    validUntil: z.string().datetime(),
+    metadata: z.any().optional(),
+});
+
+const UpdatePermitSchema = z.object({
+    status: z.enum(["requested", "active", "expired", "revoked", "completed"]).optional(),
+    approverId: z.string().uuid().optional(),
+    approvedAt: z.string().datetime().optional(),
+    validFrom: z.string().datetime().optional(),
+    validUntil: z.string().datetime().optional(),
+    metadata: z.any().optional(),
+});
+
+export const permitRoutes = async (app: FastifyInstance) => {
+    app.setValidatorCompiler(validatorCompiler);
+    app.setSerializerCompiler(serializerCompiler);
+    const server = app.withTypeProvider<ZodTypeProvider>();
+    const authenticate = (app as any).authenticate;
+
+    server.post(
+        "/",
+        {
+            schema: {
+                tags: ["permits"],
+                body: CreatePermitSchema,
+                security: [{ bearerAuth: [] }],
+                response: {
+                    201: z.object({
+                        id: z.string().uuid(),
+                        permitId: z.string(),
+                    })
+                }
+            },
+            preHandler: authenticate,
+        },
+        async (request, reply) => {
+            const user = request.user as any;
+            const data = {
+                ...request.body,
+                tenantId: user.tenantId,
+                validFrom: new Date(request.body.validFrom),
+                validUntil: new Date(request.body.validUntil),
+                issuerId: request.body.issuerId || user.id // Default to creator if not sent
+            };
+
+            // Auto-generate permitId
+            const permitPrefix = `PER-${new Date().toISOString().slice(0, 10).replace(/-/g, "")}`;
+            const permitSuffix = Math.random().toString(36).substring(2, 6).toUpperCase();
+            const permitId = `${permitPrefix}-${permitSuffix}`;
+
+            const permit = await PermitService.create({ ...data, permitId } as any);
+            return reply.status(201).send(permit);
+        }
+    );
+
+    server.get(
+        "/",
+        {
+            schema: {
+                tags: ["permits"],
+                querystring: z.object({
+                    page: z.coerce.number().default(1),
+                    limit: z.coerce.number().default(10),
+                    workOrderId: z.string().uuid().optional(),
+                    type: z.string().optional(),
+                    status: z.string().optional(),
+                    search: z.string().optional(),
+                    sortBy: z.string().optional(),
+                    sortOrder: z.enum(["asc", "desc"]).optional(),
+                }),
+                security: [{ bearerAuth: [] }],
+            },
+            preHandler: authenticate,
+        },
+        async (request) => {
+            const user = request.user as any;
+            const { page, limit, sortBy, sortOrder, ...filters } = request.query;
+
+            return PermitService.list(
+                user.tenantId,
+                filters,
+                { page, limit, sortBy, sortOrder }
+            );
+        }
+    );
+
+    server.get(
+        "/:id",
+        {
+            schema: {
+                tags: ["permits"],
+                params: z.object({
+                    id: z.string().uuid(),
+                }),
+                security: [{ bearerAuth: [] }],
+            },
+            preHandler: authenticate,
+        },
+        async (request) => {
+            const user = request.user as any;
+            const { id } = request.params;
+            return PermitService.getById(id, user.tenantId);
+        }
+    );
+
+    server.patch(
+        "/:id",
+        {
+            schema: {
+                tags: ["permits"],
+                params: z.object({
+                    id: z.string().uuid(),
+                }),
+                body: UpdatePermitSchema,
+                security: [{ bearerAuth: [] }],
+            },
+            preHandler: authenticate,
+        },
+        async (request) => {
+            const user = request.user as any;
+            const { id } = request.params;
+            const data = {
+                ...request.body,
+                approvedAt: request.body.approvedAt ? new Date(request.body.approvedAt) : undefined,
+                validFrom: request.body.validFrom ? new Date(request.body.validFrom) : undefined,
+                validUntil: request.body.validUntil ? new Date(request.body.validUntil) : undefined,
+            };
+            return PermitService.update(id, user.tenantId, data);
+        }
+    );
+
+    server.delete(
+        "/:id",
+        {
+            schema: {
+                tags: ["permits"],
+                params: z.object({
+                    id: z.string().uuid(),
+                }),
+                security: [{ bearerAuth: [] }],
+                response: {
+                    200: z.object({ success: z.boolean() })
+                }
+            },
+            preHandler: authenticate,
+        },
+        async (request) => {
+            const user = request.user as any;
+            const { id } = request.params;
+            await PermitService.delete(id, user.tenantId);
+            return { success: true };
+        }
+    );
+};
+
+export default permitRoutes;

backend/src/server.ts

@@ -22,6 +22,7 @@ import siteRoutes from "./routes/sites";
 import telemetryRoutes from "./routes/telemetry";
 import notificationRoutes from "./routes/notifications";
 import webhookRoutes from "./routes/webhooks";
+import permitRoutes from "./routes/permits";
 import alertRoutes from "./routes/alerts";
 import integrationRoutes from "./routes/integrations";
 import analyticsAdminRoutes from "./routes/analytics-admin";
@@ -311,6 +312,7 @@ A modern CMMS API for managing assets, work orders, sites, and maintenance opera
   await server.register(healthRoutes, { prefix: "/health" });
   await server.register(authRoutes, { prefix: "/api/v1/auth" });
   await server.register(workOrderRoutes, { prefix: "/api/v1/work-orders" });
+  await server.register(permitRoutes, { prefix: "/api/v1/permits" });
   await server.register(assetRoutes, { prefix: "/api/v1/assets" });
   await server.register(siteRoutes, { prefix: "/api/v1/sites" });
   await server.register(telemetryRoutes, { prefix: "/api/v1/telemetry" });