PSA/ee/docs/plans/2026-03-26-mobile-remaining-features/PRD.md

# PRD: Mobile App — Documents, Products, and Avatars

## Problem Statement

The Alga PSA mobile app is missing three capabilities that exist in the web app:

1. **Documents** — No way to view, download, or attach files to tickets from mobile. Technicians in the field need to photograph issues and attach documentation.
2. **Products/Materials** — No way to add inventory items (products) to tickets. Technicians need to record parts used during on-site work.
3. **Contact & Client Avatars** — Ticket detail shows contact and client names as plain text without avatars/logos, making it harder to quickly identify entities.

## Goals

- Allow mobile users to view attached documents and upload new files (photos + files) to tickets
- Allow mobile users to add products from the catalog to tickets as materials
- Show contact avatar and client logo in the ticket detail view

## Non-Goals

- Document editing/renaming from mobile
- Document preview/inline viewing (just list + download + open)
- Multi-currency product pricing (use default rate)
- Product creation from mobile (only pick existing products)
- Deleting materials from mobile (can be added later)

## Target Users

Field technicians and support staff who use the mobile app to manage tickets on the go.

---

## Feature 15: Contact & Client Avatars in Ticket Detail

### Overview

Add `contact_avatar_url` and `client_logo_url` to the ticket detail API response, then display them in the mobile ticket detail UI next to the contact and client names.

### Server Changes

1. In `TicketService.getById()`, after fetching the ticket, call:
   - `getContactAvatarUrl(ticket.contact_name_id, context.tenant)` if contact exists
   - `getClientLogoUrl(ticket.client_id, context.tenant)` if client exists
2. Return both URLs in the response as `contact_avatar_url` and `client_logo_url`

### Mobile Changes

1. In `TicketDetailScreen.tsx`, render `<Avatar>` next to the contact name in the KeyValue component
2. Render `<Avatar>` next to the client name
3. No type changes needed (`TicketDetail` uses `Record<string, unknown>`)

### Acceptance Criteria

- Contact avatar shows next to contact name (or initials fallback)
- Client logo shows next to client name (or initials fallback)
- No avatar/logo fields = graceful fallback (no crash, just initials)

---

## Feature 10: Documents on Tickets

### Overview

Show document list in ticket detail with count, allow downloading, and allow uploading new files (camera photos and file picker).

### Server Changes

1. **New endpoint: `POST /api/v1/tickets/{id}/documents`**
   - Accepts `multipart/form-data` with file
   - Uses `StorageService.uploadFile()` to store
   - Creates document record + association with ticket
   - Returns the created `IDocument`
   - Follow pattern from `uploadDocument()` server action

2. **Existing endpoint: `GET /api/v1/tickets/{id}/documents`**
   - Already exists and works — returns `IDocument[]`

### Mobile Changes

1. **API layer** (`src/api/documents.ts`):
   - `getTicketDocuments(ticketId)` — GET endpoint
   - `uploadTicketDocument(ticketId, file)` — POST with FormData

2. **Documents section in ticket detail**:
   - New `DocumentsSection` component below description
   - Shows document count badge
   - Lists documents: name, type icon, size, upload date
   - Tap document to download/open via `Linking.openURL` or `expo-sharing`
   - "Attach" button with options: Camera (expo-image-picker) or File (expo-document-picker)
   - Upload progress indicator

3. **Dependencies**: `expo-image-picker`, `expo-document-picker`, `expo-file-system`

### Data Model (from server)

```
IDocument {
  document_id, document_name, type_name, type_icon,
  mime_type, file_size, created_by_full_name, updated_at,
  file_id (for download URL)
}
```

### Acceptance Criteria

- Document list visible in ticket detail with count
- Tap to download/open a document
- Upload photo from camera
- Upload file from file picker
- Upload shows progress, refreshes list on completion
- Empty state when no documents

---

## Feature 11: Products/Materials on Tickets

### Overview

Allow mobile users to add products (inventory items) to tickets as materials, recording quantity and rate.

### Server Changes

1. **New endpoint: `GET /api/v1/tickets/{id}/materials`**
   - Returns `ITicketMaterial[]` for the ticket
   - Joins `service_catalog` for `service_name` and `sku`

2. **New endpoint: `POST /api/v1/tickets/{id}/materials`**
   - Accepts: `{ service_id, quantity, rate, currency_code, description? }`
   - Requires ticket's `client_id` (fetched internally)
   - Returns created `ITicketMaterial`

3. **Existing endpoint: `GET /api/v1/products`**
   - Already exists — used for product search/listing

### Mobile Changes

1. **API layer** (`src/api/materials.ts`):
   - `getTicketMaterials(ticketId)` — GET
   - `addTicketMaterial(ticketId, data)` — POST
   - Product listing already available via `GET /api/v1/products`

2. **Materials section in ticket detail**:
   - New `MaterialsSection` component
   - Lists existing materials: product name, SKU, quantity, rate, billed status
   - "Add Product" button opens product picker (EntityPickerModal with search)
   - After selecting product, prompt for quantity (default 1) and rate (pre-filled from product default_rate)
   - Submit creates material

3. **Product picker**:
   - Reuse `EntityPickerModal` with search
   - Show product name + SKU as subtitle
   - After selection, show quantity/rate input modal

### Data Model

```
ITicketMaterial {
  ticket_material_id, service_id, service_name, sku,
  quantity, rate (cents), currency_code, description,
  is_billed, created_at
}
```

### Acceptance Criteria

- Materials list visible in ticket detail
- Add product via searchable picker
- Set quantity and rate before adding
- Billed/unbilled status badge shown
- Empty state when no materials

---

## Risks

- **Document upload endpoint** doesn't exist yet — needs server-side implementation following the existing `uploadDocument` pattern
- **Materials endpoints** don't exist yet — need two new API routes
- **expo-image-picker** and **expo-document-picker** may need Expo plugin configuration in `app.json`
- Large file uploads on mobile networks may timeout — consider reasonable file size limits

## Testing Requirements

Each feature must include actual test files that are written and verified to pass. The mobile app uses **Vitest** with React Test Renderer. Run tests with `npx vitest run` from `ee/mobile/`.

### Feature 15 Tests
- `ee/mobile/src/screens/TicketDetailScreen.avatars.test.ts` — Verify Avatar components render with contact/client URLs from ticket data, and fallback to initials when URLs are null

### Feature 10 Tests
- `ee/mobile/src/api/documents.test.ts` — Unit tests for `getTicketDocuments()` and `uploadTicketDocument()` API wrappers (mock API client)
- `ee/mobile/src/features/ticketDetail/components/DocumentsSection.test.ts` — Verify document list renders items, empty state, upload trigger

### Feature 11 Tests
- `ee/mobile/src/api/materials.test.ts` — Unit tests for `getTicketMaterials()`, `addTicketMaterial()`, `listProducts()` API wrappers (mock API client)
- `ee/mobile/src/features/ticketDetail/components/MaterialsSection.test.ts` — Verify materials list renders items with product name/SKU/quantity/rate, empty state, add product flow

### Test Execution
After implementing each feature, run `npx vitest run` from `ee/mobile/` and verify all tests pass (both new and existing). Fix any failures before moving to the next feature. The existing test suite has 126 tests that must continue to pass.

## Implementation Order

1. **Feature 15** (avatars) — smallest, server + mobile UI only, no new endpoints
2. **Feature 10** (documents) — medium, needs new upload endpoint
3. **Feature 11** (materials) — medium, needs two new endpoints + product picker