Fault Resolution

The Fault Resolution Workflow manages issues discovered during jobs, from initial reporting through quote creation, remediation work, and final resolution.

Overview

Flow: Discovery Job → Fault Report → Quote (optional) → Remediation Job → Resolution Key Files:

apps/workbooks-api/src/trpc/routers/faults.ts
apps/workbooks-dashboard/src/lib/workflow/fault-flow-transformer.ts

Fault Status States

type FaultStatus = "open" | "investigating" | "resolved" | "closed";

type FaultPriority = "critical" | "high" | "medium" | "low";

Workflow Diagram

Discovery Phase

Issue Discovered

During routine work, technician identifies a problem with equipment.

Create Fault Report

Technician documents the issue:

interface FaultReport {
  title: string;
  description: string;
  priority: FaultPriority;
  assetId: string;
  photos: Photo[];
  notes: string;
  discoveryJobId: string;
}

Job Continues/Completes

Discovery job finishes normally with fault noted in report.

Fault Processing

Status Flow

Status	Description	Actions Available
Open	Just reported	Begin investigation
Investigating	Being assessed	Create quote, resolve, close
Resolved	Work completed	Close fault
Closed	Finalized	None (terminal)

Priority Levels

Critical

Safety hazard, immediate attention required

High

Significant issue, address within 24-48 hours

Medium

Should be addressed soon

Low

Minor issue, schedule when convenient

Resolution Paths

Create Quote
Resolve Immediately
Not an Issue

Complex Resolution

For issues requiring:

Customer approval
Parts ordering
Multiple visits
Significant cost

Create Quote

Generate quote from fault with estimated costs.

Customer Approval

Send quote, wait for acceptance.

Remediation Job

Create job from approved quote.

Complete Work

Execute remediation, verify resolution.

Close Fault

Mark fault resolved and closed.

Fault Lineage

Faults maintain full traceability:

interface FaultLineage {
  // Discovery context
  discoveryJobId: string;
  discoveryDate: Date;
  discoveredBy: string;
  
  // Asset context
  assetId: string;
  locationId: string;
  customerId: string;
  
  // Resolution context
  quoteId?: string;
  remediationJobId?: string;
  resolvedBy?: string;
  resolvedAt?: Date;
  
  // Related faults
  previousFaultIds?: string[];  // Recurring issue tracking
  relatedFaultIds?: string[];   // Multiple issues same asset
}

Recurring Fault Detection

System tracks patterns:

// Flag potential recurring issues
const checkRecurringFault = async (fault: Fault) => {
  const history = await getFaultHistory({
    assetId: fault.assetId,
    months: 12,
  });
  
  const similar = history.filter(f => 
    f.category === fault.category &&
    f.id !== fault.id
  );
  
  if (similar.length >= 2) {
    await flagAsRecurring(fault.id, similar.map(f => f.id));
    await notifyTeam({
      type: "recurring_fault",
      message: `Asset has ${similar.length + 1} similar faults in past year`,
    });
  }
};

Notifications

Event	Recipients	Channel
Fault created	Team admins	In-app, email (critical)
Priority critical	Team owner	Email, SMS
Quote created	Customer	Email
Quote approved	Assigned tech	In-app, email
Fault resolved	Customer (optional)	Email

Database Schema

export const faults = pgTable("faults", {
  id: uuid("id").primaryKey().defaultRandom(),
  teamId: uuid("team_id").references(() => teams.id),
  
  // Content
  title: text("title").notNull(),
  description: text("description"),
  priority: text("priority").notNull(), // critical, high, medium, low
  status: text("status").notNull(), // open, investigating, resolved, closed
  
  // Relationships
  assetId: uuid("asset_id").references(() => assets.id),
  customerId: uuid("customer_id").references(() => customers.id),
  locationId: uuid("location_id").references(() => locations.id),
  discoveryJobId: uuid("discovery_job_id").references(() => jobs.id),
  remediationJobId: uuid("remediation_job_id").references(() => jobs.id),
  quoteId: uuid("quote_id").references(() => quotes.id),
  
  // Resolution
  resolvedBy: uuid("resolved_by").references(() => users.id),
  resolvedAt: timestamp("resolved_at"),
  resolutionNotes: text("resolution_notes"),
  
  // Metadata
  photos: jsonb("photos").$type<Photo[]>(),
  createdAt: timestamp("created_at").defaultNow(),
  updatedAt: timestamp("updated_at"),
});

API Endpoints

Endpoint	Method	Description
`faults.list`	Query	List faults with filters
`faults.getById`	Query	Get fault details
`faults.create`	Mutation	Create fault from job
`faults.updateStatus`	Mutation	Change fault status
`faults.createQuote`	Mutation	Generate quote from fault
`faults.resolve`	Mutation	Mark fault resolved
`faults.getByAsset`	Query	Get asset fault history

Customer Lifecycle

Quote creation and job workflow

Asset Compliance

Asset health tracking

Developer - Overview

Core Workflows

Billing & Subscriptions

Integrations

Team Management

Onboarding Wizards

Reference

Overview

Fault Status States

Workflow Diagram

Discovery Phase

Fault Processing

Status Flow

Priority Levels

Critical

High

Medium

Low

Resolution Paths

Complex Resolution

Simple Resolution

False Positive

Fault Lineage

Recurring Fault Detection

Notifications

Database Schema

API Endpoints

Customer Lifecycle

Asset Compliance

​Overview

​Fault Status States

​Workflow Diagram

​Discovery Phase

​Fault Processing

​Status Flow

​Priority Levels

Critical

High

Medium

Low

​Resolution Paths

​Complex Resolution

​Simple Resolution

​False Positive

​Fault Lineage

​Recurring Fault Detection

​Notifications

​Database Schema

​API Endpoints

​Related Documentation

Customer Lifecycle

Asset Compliance

Overview

Fault Status States

Workflow Diagram

Discovery Phase

Fault Processing

Status Flow

Priority Levels

Resolution Paths

Complex Resolution

Simple Resolution

False Positive

Fault Lineage

Recurring Fault Detection

Notifications

Database Schema

API Endpoints

Related Documentation