docs/spec/USER_STORIES.md

# 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:**
```json
{
  "success": true,
  "data": { ... },
  "message": "Operation completed successfully",
  "timestamp": "2024-01-15T10:30:00Z"
}
```

**Error Response:**
```json
{
  "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:**
```json
{
  "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