Hugging Face's logo

Spaces:
kamau1
/
swiftops-backend
Sleeping

App Files Community
swiftops-backend / docs /spec /USER_STORIES.md
kamau1's picture
kamau1
Iniital Commit
74de430
preview code
|
raw
history blame contribute delete
30.8 kB

User Stories & API Endpoints

Overview

This document outlines user stories for the Field Service Management Platform, organized by user role. Each story includes acceptance criteria and required FastAPI backend endpoints.

Architecture: FastAPI backend handles all database interactions. Frontend queries the backend via REST API.

User Roles:

  • Platform Admin
  • Client Admin (Telecom Operator)
  • Contractor Admin
  • Project Manager
  • Dispatcher
  • Field Agent
  • Sales Agent
  • Sales Manager

1. PLATFORM ADMIN

1.1 Organization Management

US-PA-001: Create Client Organization

  • As a Platform Admin
  • I want to create new client organizations (telecom operators)
  • So that they can use the platform for their field operations

Acceptance Criteria:

  • Can create client with name, industry, contact details
  • System validates unique client name and email
  • Client is created with default SLA settings
  • Client admin user is automatically invited

API Endpoints:

POST   /api/v1/clients
GET    /api/v1/clients
GET    /api/v1/clients/{client_id}
PUT    /api/v1/clients/{client_id}
DELETE /api/v1/clients/{client_id}

US-PA-002: Create Contractor Organization

  • As a Platform Admin
  • I want to create contractor organizations
  • So that they can be assigned to client projects

Acceptance Criteria:

  • Can create contractor with name, competencies, contact details
  • System validates unique contractor name
  • Contractor admin user is automatically invited
  • Can specify contractor specializations (FTTH, Fixed Wireless, etc.)

API Endpoints:

POST   /api/v1/contractors
GET    /api/v1/contractors
GET    /api/v1/contractors/{contractor_id}
PUT    /api/v1/contractors/{contractor_id}
DELETE /api/v1/contractors/{contractor_id}

1.2 Platform Billing Management

US-PA-003: Manage Billing Plans

  • As a Platform Admin
  • I want to create and manage billing plans
  • So that organizations can subscribe to different service tiers

Acceptance Criteria:

  • Can create plans with pricing, features, and limits
  • Can set user limits, project limits, and storage quotas
  • Can mark plans as public or private
  • Can activate/deactivate plans

API Endpoints:

POST   /api/v1/billing/plans
GET    /api/v1/billing/plans
GET    /api/v1/billing/plans/{plan_id}
PUT    /api/v1/billing/plans/{plan_id}
DELETE /api/v1/billing/plans/{plan_id}

US-PA-004: Monitor Platform Usage

  • As a Platform Admin
  • I want to view usage metrics across all organizations
  • So that I can monitor platform health and billing

Acceptance Criteria:

  • Can view active users, projects, tickets per organization
  • Can see storage usage and API call counts
  • Can filter by date range and organization type
  • Can export usage reports

API Endpoints:

GET    /api/v1/usage-metrics
GET    /api/v1/usage-metrics/summary
GET    /api/v1/usage-metrics/by-organization
POST   /api/v1/usage-metrics/export

2. CLIENT ADMIN (Telecom Operator)

2.1 Project Setup

US-CA-001: Initiate Project Creation

  • As a Client Admin
  • I want to initiate a project and invite a contractor
  • So that we can collaborate on field work

Acceptance Criteria:

  • Can create project with title, description, service type
  • Can invite contractor from available contractors
  • Contractor receives invitation to join project
  • Project is created in 'pending' state until contractor accepts
  • Can set project dates and budget
  • Can define activation requirements (ONT serial, MAC address, etc.)
  • Can specify photo requirements for installations

API Endpoints:

POST   /api/v1/projects/initiate                  # Client initiates
POST   /api/v1/projects/invitations               # Send contractor invitation
GET    /api/v1/projects
GET    /api/v1/projects/{project_id}
PUT    /api/v1/projects/{project_id}
DELETE /api/v1/projects/{project_id}
POST   /api/v1/projects/{project_id}/close

US-CA-002: Define Project Regions

  • As a Client Admin
  • I want to create regional hubs within a project
  • So that inventory and teams can be organized geographically

Acceptance Criteria:

  • Can create regions with name, location, and manager
  • Can assign regional manager from project team
  • Regions are used for inventory distribution
  • Can view all regions on a map

API Endpoints:

POST   /api/v1/projects/{project_id}/regions
GET    /api/v1/projects/{project_id}/regions
GET    /api/v1/regions/{region_id}
PUT    /api/v1/regions/{region_id}
DELETE /api/v1/regions/{region_id}

2.2 User Management

US-CA-003: Invite Users

  • As a Client Admin
  • I want to invite users to my organization
  • So that they can access the platform

Acceptance Criteria:

  • Can invite users with email and role
  • System sends invitation email
  • Can set user role (sales_manager, project_manager, dispatcher, sales_agent)
  • User receives onboarding instructions

API Endpoints:

POST   /api/v1/users/invite
GET    /api/v1/users
GET    /api/v1/users/{user_id}
PUT    /api/v1/users/{user_id}
DELETE /api/v1/users/{user_id}
POST   /api/v1/users/{user_id}/suspend
POST   /api/v1/users/{user_id}/activate

3. CONTRACTOR ADMIN

3.1 Project Collaboration

US-CO-001: Accept or Initiate Project

  • As a Contractor Admin
  • I want to accept project invitations from clients or initiate projects
  • So that I can collaborate with clients on field work

Acceptance Criteria:

  • Can view pending project invitations from clients
  • Can accept or decline project invitations
  • Can also initiate projects and invite clients
  • Project becomes 'active' when both parties agree
  • Can negotiate project terms before acceptance

API Endpoints:

GET    /api/v1/projects/invitations/pending
POST   /api/v1/projects/invitations/{invitation_id}/accept
POST   /api/v1/projects/invitations/{invitation_id}/decline
POST   /api/v1/projects/initiate                  # Contractor initiates
POST   /api/v1/projects/invitations               # Invite client

3.2 Team Management

US-CO-002: Manage Field Agents

  • As a Contractor Admin
  • I want to add and manage field agents
  • So that they can be assigned to projects

Acceptance Criteria:

  • Can add field agents with contact details
  • Can record health & safety information
  • Can record PPE sizes for equipment allocation
  • Can assign financial accounts for payouts
  • Can track agent location in real-time

API Endpoints:

POST   /api/v1/field-agents
GET    /api/v1/field-agents
GET    /api/v1/field-agents/{agent_id}
PUT    /api/v1/field-agents/{agent_id}
GET    /api/v1/field-agents/{agent_id}/location
POST   /api/v1/field-agents/{agent_id}/financial-accounts

US-CO-003: Invite Team Members to Project

  • As a Contractor Admin
  • I want to invite my team members to join a project
  • So that they can be assigned work

Acceptance Criteria:

  • Can invite field agents to specific projects
  • Can set project role and compensation structure
  • Can assign agents to specific regions
  • Team members receive invitation notification
  • Can track agent availability across projects

API Endpoints:

POST   /api/v1/projects/{project_id}/team/invite
GET    /api/v1/projects/{project_id}/team/invitations
POST   /api/v1/projects/{project_id}/team/invitations/{id}/resend
DELETE /api/v1/projects/{project_id}/team/invitations/{id}/cancel
GET    /api/v1/projects/{project_id}/team
DELETE /api/v1/projects/{project_id}/team/{member_id}
GET    /api/v1/field-agents/{agent_id}/projects

4. PROJECT MANAGER

4.1 Sales Order Management

US-PM-001: Create Sales Order (Single)

  • As a Project Manager
  • I want to create individual sales orders
  • So that I can add orders one at a time

Acceptance Criteria:

  • Can enter customer details (name, phone, address)
  • System deduplicates customers by phone number
  • Can specify package, price, and installation details
  • Can set preferred installation date/time
  • Can add installation address with GPS coordinates
  • Order is created with 'pending' status

API Endpoints:

POST   /api/v1/sales-orders
GET    /api/v1/sales-orders
GET    /api/v1/sales-orders/{order_id}
PUT    /api/v1/sales-orders/{order_id}
DELETE /api/v1/sales-orders/{order_id}
POST   /api/v1/customers/check-duplicate

US-PM-002: Upload Sales Orders (CSV Bulk Import)

  • As a Project Manager
  • I want to upload sales orders via CSV
  • So that installation tickets can be generated in bulk

Acceptance Criteria:

  • Can upload CSV with customer details and installation addresses
  • System validates and deduplicates customers by phone
  • System creates SalesOrder records in batch
  • Can preview orders before confirming
  • Can see validation errors for invalid rows
  • Can download error report for failed rows
  • Successfully imported orders are marked as 'pending'

API Endpoints:

POST   /api/v1/sales-orders/upload-csv
POST   /api/v1/sales-orders/validate-csv
POST   /api/v1/sales-orders/confirm-csv-import
GET    /api/v1/sales-orders/import-history
GET    /api/v1/sales-orders/import/{import_id}/errors

US-PM-002: Generate Tickets from Sales Orders

  • As a Project Manager
  • I want to convert unprocessed sales orders into tickets
  • So that field agents can execute installations

Acceptance Criteria:

  • Can select multiple sales orders to process
  • System creates installation tickets with cached location data
  • Tickets are created with 'open' status
  • Sales orders are marked as 'processed'
  • Can bulk generate tickets

API Endpoints:

POST   /api/v1/sales-orders/{order_id}/create-ticket
POST   /api/v1/sales-orders/bulk-create-tickets
GET    /api/v1/sales-orders/unprocessed

4.2 Inventory Management

US-PM-003: Receive Inventory from Client

  • As a Project Manager
  • I want to record inventory received from the client
  • So that equipment can be tracked and distributed

Acceptance Criteria:

  • Can record equipment type, quantity, and serial numbers
  • Can specify if items are tools (returnable) or equipment (installable)
  • Can record delivery note reference
  • Can track inventory value

API Endpoints:

POST   /api/v1/projects/{project_id}/inventory
GET    /api/v1/projects/{project_id}/inventory
GET    /api/v1/inventory/{inventory_id}
PUT    /api/v1/inventory/{inventory_id}
GET    /api/v1/inventory/{inventory_id}/serial-numbers

US-PM-004: Distribute Inventory to Regional Hubs

  • As a Project Manager
  • I want to distribute inventory from main office to regional hubs
  • So that field agents can collect equipment locally

Acceptance Criteria:

  • Can allocate quantities to specific regions
  • Can track serial numbers per region
  • System updates available quantities
  • Can view inventory levels per region

API Endpoints:

POST   /api/v1/inventory/{inventory_id}/distribute
GET    /api/v1/regions/{region_id}/inventory
GET    /api/v1/inventory-distribution/{distribution_id}
PUT    /api/v1/inventory-distribution/{distribution_id}

4.3 Task Management (Infrastructure Projects)

US-PM-005: Create Infrastructure Tasks

  • As a Project Manager
  • I want to create tasks for infrastructure rollout
  • So that contractors can execute infrastructure work

Acceptance Criteria:

  • Can create tasks with title, description, location
  • Can set task type (installation, maintenance, survey, testing)
  • Can assign priority and schedule date
  • Can generate tickets from tasks

API Endpoints:

POST   /api/v1/projects/{project_id}/tasks
GET    /api/v1/projects/{project_id}/tasks
GET    /api/v1/tasks/{task_id}
PUT    /api/v1/tasks/{task_id}
DELETE /api/v1/tasks/{task_id}
POST   /api/v1/tasks/{task_id}/create-ticket

4.4 Financial Management

US-PM-006: Track Project Finances

  • As a Project Manager
  • I want to record project income and expenses
  • So that I can monitor project cash flow

Acceptance Criteria:

  • Can record inflows (funding from finance department)
  • Can record outflows (payroll, equipment, transport)
  • Can link transactions to specific entities (tickets, payroll, invoices)
  • Can view financial summary and balance

API Endpoints:

POST   /api/v1/projects/{project_id}/finance
GET    /api/v1/projects/{project_id}/finance
GET    /api/v1/projects/{project_id}/finance/summary
GET    /api/v1/finance/{transaction_id}
PUT    /api/v1/finance/{transaction_id}
POST   /api/v1/finance/{transaction_id}/approve
POST   /api/v1/finance/{transaction_id}/reject

US-PM-007: Generate Contractor Invoices

  • As a Project Manager
  • I want to generate invoices for contractor work
  • So that contractors can be paid for completed tickets

Acceptance Criteria:

  • Can select completed tickets for invoicing
  • System calculates total based on compensation structure
  • Can add line items and adjustments
  • Can mark invoice as paid

API Endpoints:

POST   /api/v1/projects/{project_id}/invoices
GET    /api/v1/projects/{project_id}/invoices
GET    /api/v1/invoices/{invoice_id}
PUT    /api/v1/invoices/{invoice_id}
POST   /api/v1/invoices/{invoice_id}/mark-paid
GET    /api/v1/invoices/{invoice_id}/tickets

5. DISPATCHER

5.1 Ticket Assignment

US-DI-001: View Available Tickets

  • As a Dispatcher
  • I want to view all open tickets
  • So that I can assign them to field agents

Acceptance Criteria:

  • Can view tickets filtered by status, priority, region
  • Can see ticket details including location and requirements
  • Can view tickets on a map
  • Can see agent availability and current workload

API Endpoints:

GET    /api/v1/tickets
GET    /api/v1/tickets/open
GET    /api/v1/tickets/by-region/{region_id}
GET    /api/v1/tickets/map-view
GET    /api/v1/field-agents/availability

US-DI-002: Assign Tickets to Field Agents

  • As a Dispatcher
  • I want to assign tickets to field agents
  • So that work can be executed

Acceptance Criteria:

  • Can assign single or multiple tickets to an agent
  • Can set scheduled date and time slot
  • System creates ticket assignment record
  • Agent receives notification
  • Ticket status changes to 'assigned'

API Endpoints:

POST   /api/v1/tickets/{ticket_id}/assign
POST   /api/v1/tickets/bulk-assign
GET    /api/v1/tickets/{ticket_id}/assignments
POST   /api/v1/tickets/{ticket_id}/reassign
POST   /api/v1/tickets/{ticket_id}/unassign

5.2 Inventory Issuance

US-DI-003: Issue Equipment to Field Agents

  • As a Dispatcher
  • I want to issue equipment to field agents from regional hub
  • So that they have materials for installations

Acceptance Criteria:

  • Can scan or enter serial numbers/box numbers
  • Can issue multiple items at once
  • System tracks who issued and who received
  • Can link equipment to specific tickets
  • System updates inventory quantities

API Endpoints:

POST   /api/v1/regions/{region_id}/issue-equipment
GET    /api/v1/field-agents/{agent_id}/equipment
GET    /api/v1/equipment-assignments
POST   /api/v1/equipment-assignments/{assignment_id}/return
GET    /api/v1/equipment-assignments/unreturned

5.3 Expense Approval

US-DI-004: Review and Approve Expenses

  • As a Dispatcher
  • I want to review expense claims from field agents
  • So that valid expenses can be reimbursed

Acceptance Criteria:

  • Can view pending expense claims
  • Can see expense details, receipts, and location verification
  • Can approve or reject with reason
  • Can filter by agent, date, or ticket
  • System validates location before approval

API Endpoints:

GET    /api/v1/expenses/pending
GET    /api/v1/expenses/{expense_id}
POST   /api/v1/expenses/{expense_id}/approve
POST   /api/v1/expenses/{expense_id}/reject
GET    /api/v1/tickets/{ticket_id}/expenses
GET    /api/v1/field-agents/{agent_id}/expenses

6. FIELD AGENT

6.1 Ticket Management

US-FA-001: View My Assigned Tickets

  • As a Field Agent
  • I want to view tickets assigned to me
  • So that I know what work I need to do

Acceptance Criteria:

  • Can view assigned tickets in list or map view
  • Can see ticket details, customer info, and location
  • Can filter by status and priority
  • Can see route to customer location
  • Can set execution order for my tickets

API Endpoints:

GET    /api/v1/field-agents/me/tickets
GET    /api/v1/field-agents/me/tickets/today
GET    /api/v1/tickets/{ticket_id}
PUT    /api/v1/tickets/{ticket_id}/execution-order
GET    /api/v1/tickets/{ticket_id}/route

US-FA-002: Accept or Reject Ticket Assignment

  • As a Field Agent
  • I want to accept or reject assigned tickets
  • So that I can manage my workload

Acceptance Criteria:

  • Can accept ticket (status changes to 'in_progress')
  • Can reject ticket with reason
  • Can request reassignment
  • System records response timestamp
  • Dispatcher is notified of rejection

API Endpoints:

POST   /api/v1/tickets/{ticket_id}/accept
POST   /api/v1/tickets/{ticket_id}/reject
POST   /api/v1/tickets/{ticket_id}/request-reassignment

US-FA-003: Start Journey to Customer Site

  • As a Field Agent
  • I want to start journey tracking when I leave for a ticket
  • So that my travel can be monitored

Acceptance Criteria:

  • Can start journey with one tap
  • System records journey start location and time
  • GPS tracking begins (breadcrumb trail)
  • Can see estimated arrival time
  • Can pause/resume journey

API Endpoints:

POST   /api/v1/tickets/{ticket_id}/start-journey
POST   /api/v1/tickets/{ticket_id}/pause-journey
POST   /api/v1/tickets/{ticket_id}/resume-journey
POST   /api/v1/tickets/{ticket_id}/location-update
GET    /api/v1/tickets/{ticket_id}/journey-status

US-FA-004: Mark Arrival at Customer Site

  • As a Field Agent
  • I want to mark when I arrive at customer location
  • So that my arrival time is recorded

Acceptance Criteria:

  • Can mark arrival with GPS verification
  • System validates location matches customer address
  • Journey tracking stops
  • Arrival time is recorded
  • Can proceed to work execution

API Endpoints:

POST   /api/v1/tickets/{ticket_id}/mark-arrival
GET    /api/v1/tickets/{ticket_id}/verify-location

6.2 Customer Communication

US-FA-005: Contact Customer

  • As a Field Agent
  • I want to record customer communication attempts
  • So that contact history is tracked

Acceptance Criteria:

  • Can record call, SMS, WhatsApp, or in-person contact
  • Can record outcome (successful, no answer, busy, etc.)
  • Can schedule follow-up
  • Can see previous communication history
  • Can initiate call from app

API Endpoints:

POST   /api/v1/tickets/{ticket_id}/communications
GET    /api/v1/tickets/{ticket_id}/communications
GET    /api/v1/customers/{customer_id}/communications
POST   /api/v1/communications/{comm_id}/follow-up

6.3 Work Execution

US-FA-006: Complete Installation

  • As a Field Agent
  • I want to record installation details and activate service
  • So that customer can start using the service

Acceptance Criteria:

  • Can enter equipment details (ONT serial, MAC address, etc.)
  • Can capture before/after photos
  • Can record activation details
  • Can create subscription record
  • Ticket status changes to 'completed'
  • System validates all required fields

API Endpoints:

POST   /api/v1/tickets/{ticket_id}/complete
POST   /api/v1/tickets/{ticket_id}/photos
POST   /api/v1/tickets/{ticket_id}/equipment-details
POST   /api/v1/subscriptions
GET    /api/v1/projects/{project_id}/activation-requirements

US-FA-007: Log Expenses

  • As a Field Agent
  • I want to record expenses incurred during ticket execution
  • So that I can be reimbursed

Acceptance Criteria:

  • Can log transport, materials, meals, etc.
  • Can attach receipt photos
  • Can specify quantity and unit cost
  • System validates location (must be at customer site)
  • Can see expense approval status

API Endpoints:

POST   /api/v1/tickets/{ticket_id}/expenses
GET    /api/v1/field-agents/me/expenses
GET    /api/v1/expenses/{expense_id}
PUT    /api/v1/expenses/{expense_id}
DELETE /api/v1/expenses/{expense_id}

6.4 Inventory Management

US-FA-008: View My Equipment

  • As a Field Agent
  • I want to view equipment issued to me
  • So that I know what I have and what needs to be returned

Acceptance Criteria:

  • Can see all equipment currently in my possession
  • Can see tools that need to be returned
  • Can see equipment installed at customer sites
  • Can scan equipment for quick lookup

API Endpoints:

GET    /api/v1/field-agents/me/equipment
GET    /api/v1/field-agents/me/equipment/unreturned
GET    /api/v1/equipment/{serial_number}

US-FA-009: Return Equipment

  • As a Field Agent
  • I want to return tools to the regional hub
  • So that they can be reissued to other agents

Acceptance Criteria:

  • Can scan equipment to return
  • Can specify condition (good, damaged, worn)
  • Can add return notes
  • System updates inventory quantities
  • Dispatcher confirms receipt

API Endpoints:

POST   /api/v1/equipment-assignments/{assignment_id}/return
POST   /api/v1/equipment-assignments/bulk-return

6.5 Attendance & Timesheets

US-FA-010: Clock In/Out

  • As a Field Agent
  • I want to record my daily attendance
  • So that my work hours are tracked

Acceptance Criteria:

  • Can clock in at start of day
  • Can clock out at end of day
  • System records timestamps and location
  • Can view my timesheet history
  • Can request leave

API Endpoints:

POST   /api/v1/field-agents/me/clock-in
POST   /api/v1/field-agents/me/clock-out
GET    /api/v1/field-agents/me/timesheets
POST   /api/v1/field-agents/me/request-leave

7. SALES AGENT

7.1 Sales Order Management

US-SA-001: Create Sales Order

  • As a Sales Agent
  • I want to create sales orders for new customers
  • So that installations can be scheduled

Acceptance Criteria:

  • Can enter customer details (name, phone, address)
  • System deduplicates customers by phone number
  • Can specify package and price
  • Can set preferred installation date/time
  • Can add installation address with GPS coordinates

API Endpoints:

POST   /api/v1/sales-orders
GET    /api/v1/sales-agents/me/orders
GET    /api/v1/sales-orders/{order_id}
PUT    /api/v1/sales-orders/{order_id}
POST   /api/v1/customers/check-duplicate

US-SA-002: Track My Sales

  • As a Sales Agent
  • I want to view my sales performance
  • So that I can track my commissions

Acceptance Criteria:

  • Can view total orders, completed installations, pending
  • Can see commission earned and pending
  • Can filter by date range
  • Can see conversion funnel (orders → tickets → installations)

API Endpoints:

GET    /api/v1/sales-agents/me/stats
GET    /api/v1/sales-agents/me/commissions
GET    /api/v1/sales-agents/me/conversion-funnel

8. SALES MANAGER

8.1 Team Performance

US-SM-001: View Team Sales Performance

  • As a Sales Manager
  • I want to view sales performance across my team
  • So that I can identify top performers and areas for improvement

Acceptance Criteria:

  • Can view sales by agent, region, package type
  • Can see conversion rates and average deal size
  • Can filter by date range
  • Can export reports

API Endpoints:

GET    /api/v1/sales/team-performance
GET    /api/v1/sales/by-agent
GET    /api/v1/sales/by-region
GET    /api/v1/sales/by-package
POST   /api/v1/sales/export-report

9. SUPPORT TICKETS (All Roles)

9.1 Incident Management

US-SUP-001: Create Support Incident

  • As a Support Staff
  • I want to create incidents for customer complaints
  • So that support tickets can be generated

Acceptance Criteria:

  • Can search for customer by phone or subscription
  • Can record incident type and description
  • Can set priority
  • System creates support ticket automatically
  • Customer is notified

API Endpoints:

POST   /api/v1/incidents
GET    /api/v1/incidents
GET    /api/v1/incidents/{incident_id}
PUT    /api/v1/incidents/{incident_id}
POST   /api/v1/incidents/{incident_id}/create-ticket
POST   /api/v1/incidents/{incident_id}/resolve

10. COMMON ENDPOINTS

10.1 Authentication & Authorization

API Endpoints:

POST   /api/v1/auth/login
POST   /api/v1/auth/logout
POST   /api/v1/auth/refresh-token
GET    /api/v1/auth/me
PUT    /api/v1/auth/me/profile
POST   /api/v1/auth/change-password
POST   /api/v1/auth/forgot-password
POST   /api/v1/auth/reset-password

10.2 Dashboard & Analytics

API Endpoints:

GET    /api/v1/dashboard/overview
GET    /api/v1/dashboard/tickets-pipeline
GET    /api/v1/dashboard/sla-compliance
GET    /api/v1/dashboard/team-performance
GET    /api/v1/dashboard/financial-summary
GET    /api/v1/dashboard/inventory-status
GET    /api/v1/dashboard/map-view

10.3 Notifications

API Endpoints:

GET    /api/v1/notifications
GET    /api/v1/notifications/unread
POST   /api/v1/notifications/{notification_id}/mark-read
POST   /api/v1/notifications/mark-all-read
DELETE /api/v1/notifications/{notification_id}

10.4 Documents & Files

API Endpoints:

POST   /api/v1/documents/upload
GET    /api/v1/documents/{document_id}
GET    /api/v1/documents/{document_id}/download
DELETE /api/v1/documents/{document_id}
GET    /api/v1/tickets/{ticket_id}/documents
GET    /api/v1/users/{user_id}/documents

10.5 Search & Filters

API Endpoints:

GET    /api/v1/search/customers
GET    /api/v1/search/tickets
GET    /api/v1/search/users
GET    /api/v1/search/global

11. WORKFLOW ENDPOINTS

11.1 Sales Order → Installation Workflow

Complete Flow:

1. POST   /api/v1/sales-orders                    # Create order
2. POST   /api/v1/sales-orders/{id}/create-ticket # Generate ticket
3. POST   /api/v1/tickets/{id}/assign             # Assign to agent
4. POST   /api/v1/tickets/{id}/accept             # Agent accepts
5. POST   /api/v1/tickets/{id}/start-journey      # Start travel
6. POST   /api/v1/tickets/{id}/mark-arrival       # Arrive at site
7. POST   /api/v1/tickets/{id}/complete           # Complete work
8. POST   /api/v1/subscriptions                   # Activate service

11.2 Support Incident → Resolution Workflow

Complete Flow:

1. POST   /api/v1/incidents                       # Create incident
2. POST   /api/v1/incidents/{id}/create-ticket    # Generate ticket
3. POST   /api/v1/tickets/{id}/assign             # Assign to agent
4. POST   /api/v1/tickets/{id}/accept             # Agent accepts
5. POST   /api/v1/tickets/{id}/start-journey      # Start travel
6. POST   /api/v1/tickets/{id}/mark-arrival       # Arrive at site
7. POST   /api/v1/tickets/{id}/complete           # Complete repair
8. POST   /api/v1/incidents/{id}/resolve          # Mark resolved

11.3 Infrastructure Task → Completion Workflow

Complete Flow:

1. POST   /api/v1/projects/{id}/tasks             # Create task
2. POST   /api/v1/tasks/{id}/create-ticket        # Generate ticket
3. POST   /api/v1/tickets/{id}/assign             # Assign to contractor
4. POST   /api/v1/tickets/{id}/accept             # Contractor accepts
5. POST   /api/v1/tickets/{id}/start-journey      # Start travel
6. POST   /api/v1/tickets/{id}/mark-arrival       # Arrive at site
7. POST   /api/v1/tickets/{id}/complete           # Complete work

12. API DESIGN PRINCIPLES

12.1 RESTful Conventions

  • GET - Retrieve resources
  • POST - Create new resources
  • PUT - Update entire resource
  • PATCH - Partial update
  • DELETE - Remove resource

12.2 Response Format

Success Response:

{
  "success": true,
  "data": { ... },
  "message": "Operation completed successfully",
  "timestamp": "2024-01-15T10:30:00Z"
}

Error Response:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": { ... }
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

12.3 Pagination

Query Parameters:

?page=1&limit=25&sort_by=created_at&sort_order=desc

Response:

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 150,
    "total_pages": 6
  }
}

12.4 Filtering & Search

Query Parameters:

?status=open&priority=high&region_id=uuid&search=customer_name

12.5 Authentication

Header:

Authorization: Bearer <jwt_token>

12.6 Rate Limiting

Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000

13. PRIORITY IMPLEMENTATION ORDER

Phase 1: Core Foundation (MVP)

  1. Authentication & User Management
  2. Organization Management (Clients, Contractors)
  3. Project Setup
  4. User Invitations

Phase 2: Sales & Ticketing

  1. Sales Order Management
  2. Customer Management
  3. Ticket Generation
  4. Ticket Assignment

Phase 3: Field Operations

  1. Field Agent Ticket Management
  2. Journey Tracking
  3. Work Completion
  4. Subscription Activation

Phase 4: Inventory & Expenses

  1. Inventory Management
  2. Equipment Issuance
  3. Expense Logging
  4. Expense Approval

Phase 5: Financial & Reporting

  1. Project Finance Tracking
  2. Contractor Invoicing
  3. Payroll Management
  4. Dashboard Analytics

Phase 6: Advanced Features

  1. Support Incidents
  2. Infrastructure Tasks
  3. Document Management
  4. Advanced Analytics

14. TECHNICAL NOTES

14.1 Database Access

  • All database operations go through FastAPI backend
  • Frontend NEVER queries Supabase directly
  • Backend handles all business logic and validation

14.2 Real-time Updates

  • Use WebSockets for real-time location tracking
  • Use Server-Sent Events (SSE) for notifications
  • Polling for dashboard updates (every 30 seconds)

14.3 File Uploads

  • Images uploaded to Supabase Storage
  • Backend generates signed URLs
  • Maximum file size: 10MB per file
  • Supported formats: JPG, PNG, PDF

14.4 GPS & Location

  • Location accuracy threshold: 50 meters
  • Location updates every 30 seconds during journey
  • Offline support: Queue location updates, sync when online

14.5 Security

  • JWT tokens with 24-hour expiry
  • Refresh tokens with 30-day expiry
  • Role-based access control (RBAC)
  • Row-level security (RLS) in database
  • API rate limiting: 1000 requests/hour per user

Document Version: 1.0
Last Updated: 2024-01-15
Status: Draft - Ready for Backend Implementation