149 lines
8.3 KiB
Markdown
149 lines
8.3 KiB
Markdown
# Yaltopia Tickets App
|
|
|
|
Mobile companion to the Yaltopia Tickets web app: **Scan. Send. Reconcile.**
|
|
React Native (Expo) with NativeWind (Tailwind), React Native Reusables (shadcn-style), and orange/black theme.
|
|
|
|
## Run
|
|
|
|
```bash
|
|
npm install
|
|
npm start
|
|
```
|
|
|
|
Then choose iOS, Android, or Web.
|
|
|
|
## API Reference
|
|
|
|
Backend API is described in **`swagger.json`** (Yaltopia Invoice System API). Base URLs:
|
|
|
|
- Local: `http://localhost:3001/api/v1`
|
|
- Production: `https://api.yaltopia.com/api/v1`
|
|
|
|
Auth: Bearer JWT in `Authorization` header.
|
|
|
|
---
|
|
|
|
## Integration Task List
|
|
|
|
Use this list to wire the app to the live API. Each item maps to swagger endpoints and app screens.
|
|
|
|
### Authentication
|
|
|
|
- [ ] **Auth API client** — Create `lib/api/auth.ts` (or use a shared client) with:
|
|
- `POST /auth/register` — register
|
|
- `POST /auth/login` — login (return access + refresh)
|
|
- `POST /auth/refresh` — refresh token
|
|
- `GET /auth/profile` — current user
|
|
- `POST /auth/logout` — logout
|
|
- `GET /auth/google`, `GET /auth/google/callback` — Google OAuth (if used)
|
|
- [ ] **Token storage** — Store access/refresh tokens securely (e.g. expo-secure-store); attach Bearer to requests.
|
|
- [ ] **Login screen** — Wire `app/login.tsx` to login/register and Google; on success navigate to `/(tabs)` and store tokens.
|
|
- [ ] **Auth guard** — Protect tab/stack routes: redirect to `/login` when unauthenticated; optional “Remember me”.
|
|
|
|
### User & Profile
|
|
|
|
- [ ] **Profile API** — `GET /users/me` in `lib/api/users.ts`; return type from swagger `UserResponseDto`.
|
|
- [ ] **Profile screen** — Load user via `/users/me` in `app/(tabs)/profile.tsx`; show name, email, language; “Manage” → `/notifications`.
|
|
- [ ] **Profile update** — If backend supports PATCH/PUT for profile, add form and wire in profile screen.
|
|
|
|
### Invoices
|
|
|
|
- [ ] **Invoices API** — `lib/api/invoices.ts`:
|
|
- `GET /invoices` (with pagination, filters)
|
|
- `GET /invoices/stats`
|
|
- `GET /invoices/{id}`, `POST /invoices`, `PUT /invoices/{id}` (if needed)
|
|
- `GET /invoices/{id}/pdf`, `PATCH /invoices/{id}/status`
|
|
- `POST /invoices/share/email`, `POST /invoices/share/link`
|
|
- [ ] **Home screen** — Replace mock earnings/invoice list with `/invoices` and `/invoices/stats` (and dashboard metrics if used).
|
|
- [ ] **Invoice detail** — Add `app/invoices/[id].tsx` (or reuse share flow) for view/edit/PDF/share; wire to `GET /invoices/{id}` and PDF endpoint.
|
|
|
|
### Scan (Invoice & Payment Receipt)
|
|
|
|
- [ ] **Scan API** — `lib/api/scan.ts`:
|
|
- `POST /scan/invoice` — upload image, return extracted invoice data (match swagger request/response).
|
|
- `POST /scan/payment-receipt` — upload payment receipt image.
|
|
- `GET /scan/images/invoice/{invoiceId}`, `GET /scan/images/payment/{paymentId}` if needed.
|
|
- [ ] **Scan screen** — In `app/(tabs)/scan.tsx`: camera or image picker → upload to `POST /scan/invoice`; show “Extracting…” then result; “Save as new” / “Match to existing” using invoices API.
|
|
- [ ] **Scan → invoice** — Create or update invoice from scan result; sync with `POST /invoices` or `PUT /invoices/{id}`.
|
|
|
|
### Proforma
|
|
|
|
- [ ] **Proforma requests API** — `lib/api/proforma-requests.ts`:
|
|
- `GET /proforma-requests`, `POST /proforma-requests` (create)
|
|
- `GET /proforma-requests/{id}`, `PUT /proforma-requests/{id}`
|
|
- `POST /proforma-requests/{id}/items`, `GET /proforma-requests/{id}/items`; items CRUD if in swagger
|
|
- `GET /proforma-requests/{id}/submissions`, `GET /proforma-requests/submissions/{id}`, revision/revise/close/cancel
|
|
- `GET /proforma-requests/{id}/comparison-data` if used
|
|
- [ ] **Proforma list** — In `app/(tabs)/proforma.tsx`: replace mock with `GET /proforma-requests` (pagination, status filter); “Create new” → create request then navigate to detail.
|
|
- [ ] **Proforma detail** — In `app/proforma/[id].tsx`: load `GET /proforma-requests/{id}` and items; show submissions; “Send to contacts” → share link/email (use share endpoint or deep link from API).
|
|
- [ ] **Proforma PDF** — If swagger has `GET /proforma/{id}/pdf`, add “Download PDF” on detail.
|
|
|
|
### Payments & Payment Requests
|
|
|
|
- [ ] **Payments API** — `lib/api/payments.ts`:
|
|
- `GET /payments` (with pagination, optional `invoiceId` filter)
|
|
- `GET /payments/{id}`, `POST /payments` (create), `PUT /payments/{id}` (update)
|
|
- `POST /payments/{id}/flag`, `POST /payments/{paymentId}/associate` (associate to invoice)
|
|
- [ ] **Payments list** — In `app/(tabs)/payments.tsx`: replace mock with `GET /payments`; show pending vs reconciled (e.g. by `invoiceId` or status from API).
|
|
- [ ] **Payment detail** — In `app/payments/[id].tsx`: load `GET /payments/{id}`; “Associate to invoice” → pick invoice (from `GET /invoices`) then `POST /payments/{paymentId}/associate`.
|
|
- [ ] **Payment request flow** — If “payment request” in product means creating a payment record for someone to pay: use `POST /payments` and any “request” endpoint from swagger; add screen or modal as needed.
|
|
|
|
### Notifications
|
|
|
|
- [ ] **Notifications API** — `lib/api/notifications.ts`:
|
|
- `POST /notifications/subscribe` (push subscription payload)
|
|
- `DELETE /notifications/unsubscribe/{endpoint}`
|
|
- `GET /notifications` — list for current user
|
|
- `GET /notifications/settings`, `PUT /notifications/settings`
|
|
- `POST /notifications/invoice/{id}/reminder` (send reminder)
|
|
- [ ] **Notifications list** — In `app/notifications/index.tsx`: replace mock with `GET /notifications`; mark read if API supports it.
|
|
- [ ] **Notification settings** — In `app/notifications/settings.tsx`: load `GET /notifications/settings`, save with `PUT /notifications/settings` (invoice reminders, days before due, news, report ready).
|
|
- [ ] **Push subscription** — On login or app open, register device with `POST /notifications/subscribe` (Expo push token or web push); handle unsubscribe on logout.
|
|
|
|
### Dashboard & Reports (optional)
|
|
|
|
- [ ] **Dashboard API** — If used: `GET /dashboard/metrics`, `/dashboard/invoice-trends`, `/dashboard/revenue-trends`, `/dashboard/invoice-status`, `/dashboard/sales-purchase`, `/dashboard/scanned-invoices`.
|
|
- [ ] **Home dashboard** — Optionally show metrics/charts on Home from dashboard endpoints.
|
|
- [ ] **Reports** — `GET /reports`, `GET /reports/latest`, `POST /reports/generate`, `GET /reports/{id}/download`; add a “Reports” entry in Profile or a dedicated screen if needed.
|
|
|
|
### Share & Documents
|
|
|
|
- [ ] **Share API** — `GET /share`, `POST /share/email`, `GET /share/view/{token}`, `POST /share/{id}/deactivate`, `GET /share/{id}` if used for proforma/invoice sharing.
|
|
- [ ] **Documents API** — `POST /documents/upload`, `GET /documents`, `GET /documents/{id}/preview`, `GET /documents/{id}/download`; use for attachments or scanned files if applicable.
|
|
|
|
### General
|
|
|
|
- [ ] **API client** — Central `lib/api/client.ts`: base URL from env, `Authorization: Bearer`, error handling, 401 → refresh or redirect to login.
|
|
- [ ] **Environment** — `EXPO_PUBLIC_API_URL` or similar for API base; use in client.
|
|
- [ ] **Types** — Generate or copy DTOs from `swagger.json` (e.g. into `lib/api/types.ts`) for type-safe requests/responses.
|
|
- [ ] **Offline / sync** — Optional: queue scan and payment-associate actions when offline; sync when back online (per product spec).
|
|
|
|
---
|
|
|
|
## Screens (current)
|
|
|
|
| Route | Description |
|
|
|-------|-------------|
|
|
| `/(tabs)` | Bottom tabs: Home, Scan, Proforma, Payments, Profile |
|
|
| `/(tabs)/index` | Home — earnings summary, quick actions, invoice list |
|
|
| `/(tabs)/scan` | Scan invoice — camera placeholder, recent scans |
|
|
| `/(tabs)/proforma` | Proforma list — create, list requests; tap → detail |
|
|
| `/(tabs)/payments` | Payments — pending match, reconciled list; tap pending → detail |
|
|
| `/(tabs)/profile` | Profile — account, notifications link, login, logout |
|
|
| `/proforma/[id]` | Proforma request detail — items, send to contacts, submissions |
|
|
| `/payments/[id]` | Payment detail — associate to invoice |
|
|
| `/notifications` | Notifications list — link to settings |
|
|
| `/notifications/settings` | Notification settings — toggles |
|
|
| `/login` | Sign in — email/password, Google |
|
|
|
|
---
|
|
|
|
## Design
|
|
|
|
- **Primary:** Orange `#ea580c` (CTAs, active tab).
|
|
- **Navbar / tab bar:** Dark `#2d2d2d`; white/orange text.
|
|
- **Backgrounds:** White / light gray `#f5f5f5`.
|
|
- **Font:** DM Sans (or system fallback).
|
|
|
|
See project plan / `mobile.md` for full design system and copy.
|