Spaces:

kamau1
/

swiftops-backend

Sleeping

swiftops-backend / docs /features /inventory /INVENTORY_REQUIREMENTS_QUICK_REF.md

feat(filtering): implement complete end-to-end server-side filtering infrastructure and migrate tickets/projects to new system

7b90d84 5 months ago

preview code

raw

history blame contribute delete

4.88 kB

Inventory Requirements - Quick Reference

TL;DR

Inventory requirements define what inventory types can be used in a project. Items marked as "installed" automatically appear in ticket completion forms.

Quick Setup

1. Define Requirements in Project

{
  "inventory_requirements": {
    "ONT-ZTE-F670L": {
      "code": "ONT-ZTE-F670L",
      "name": "ZTE F670L ONT Device",
      "description": "Fiber optic network terminal",
      "usage_type": "installed",
      "unit": "pieces",
      "requires_serial_number": true,
      "category": "Equipment",
      "include_in_completion": true,
      "completion_field_label": "ONT Serial Number",
      "completion_required": true
    },
    "CABLE-FIBER-SM": {
      "code": "CABLE-FIBER-SM",
      "name": "Single Mode Fiber Cable",
      "description": "Outdoor fiber cable",
      "usage_type": "consumed",
      "unit": "meters",
      "requires_serial_number": false,
      "category": "Cable"
    }
  }
}

2. Get Dropdown Options for Receiving

GET /api/v1/projects/{project_id}/inventory-requirements/dropdown

3. Receive Inventory

POST /api/v1/inventory
{
  "project_id": "...",
  "equipment_type": "ONT-ZTE-F670L",  // Must match a code
  "quantity_received": 100
}

4. Ticket Completion (Automatic)

Installed items automatically appear in completion checklist:

{
  "field_items": [
    {
      "field_name": "inventory_ONT-ZTE-F670L",
      "label": "ONT Serial Number",
      "required": true
    }
  ]
}

Field Reference

Field	Required	Description	Example
`code`	Yes	Unique identifier	`"ONT-ZTE-F670L"`
`name`	Yes	Display name	`"ZTE F670L ONT Device"`
`description`	No	Detailed description	`"Fiber optic network terminal"`
`usage_type`	Yes	`"installed"` or `"consumed"`	`"installed"`
`unit`	Yes	Unit of measurement	`"pieces"`, `"meters"`
`requires_serial_number`	No	Track serial numbers	`true`
`category`	No	Grouping category	`"Equipment"`
`include_in_completion`	No	Show in completion form	`true` (default)
`completion_field_label`	No	Custom label	`"ONT Serial Number"`
`completion_required`	No	Required in completion	`true` (default)

Usage Types

`installed`

Equipment installed at customer sites
Appears in ticket completion forms (if include_in_completion=true)
Examples: ONT devices, routers, CPE equipment

`consumed`

Materials used up during work
Does NOT appear in completion forms
Examples: cables, connectors, fasteners

API Endpoints

Endpoint	Purpose
`GET /projects/{id}/inventory-requirements`	Get all requirements
`GET /projects/{id}/inventory-requirements/dropdown`	Get dropdown options
`GET /projects/{id}/inventory-requirements/completion-items`	Get completion items
`GET /projects/{id}/inventory-requirements/categories`	Get categories

Common Patterns

Equipment with Serial Numbers

{
  "code": "ONT-ZTE-F670L",
  "usage_type": "installed",
  "requires_serial_number": true,
  "include_in_completion": true,
  "completion_field_label": "ONT Serial Number"
}

Consumable Materials

{
  "code": "CABLE-FIBER-SM",
  "usage_type": "consumed",
  "requires_serial_number": false,
  "include_in_completion": false
}

Optional Equipment

{
  "code": "ROUTER-TP-C6",
  "usage_type": "installed",
  "include_in_completion": true,
  "completion_required": false  // Optional in completion
}

Validation Rules

Receiving Inventory: equipment_type must match a code in requirements
Ticket Completion: Installed items with completion_required=true must be provided
Serial Numbers: Items with requires_serial_number=true get automatic validation regex

Tips

Use descriptive codes: ONT-ZTE-F670L not ONT1
Group by category for better organization
Mark optional items with completion_required: false
Use consumed for materials that don't need completion tracking
Set include_in_completion: false for items that don't need serial tracking

Error Messages

Invalid inventory code:

{
  "message": "Invalid equipment_type 'INVALID-CODE'. Must match a code from project inventory requirements.",
  "available_codes": ["ONT-ZTE-F670L", "CABLE-FIBER-SM"],
  "hint": "Use GET /api/v1/projects/{project_id}/inventory-requirements to see valid inventory types"
}