Partner Payments UI

Frontend screens and components for the Partner Payments module. Built with Vue 3 (Composition API), Pinia, and the shared UI library (e.g. SectionTitle, DataTable, FileViewer, Offcanvas).

Route Structure

/partner-payments              → List of partner payments (table with filters)
/partner-payments/:id/details   → Payment detail view (breakdown, documents, actions)

Routes are registered in frontend/client/src/routes/index.js under the partner-payments prefix with layout dashboard. Access is gated by the same permissions as the API (view-partner-payments, etc.).

Screens

Partner Payments List (/partner-payments)

Main entry: paginated, filterable list of partner payments.

Layout:

• SectionTitle: Displays the title from i18n (partners.payments.title).
• Table: Custom Table component that loads data from the partner-payments API, with columns for payment id, partner, period, status, payment status, amounts, and actions.

Behavior:

• Filters (e.g. partner, date range, payment status, reference) are typically passed as query params to GET /partner-payments.
• Sorting and pagination (start/length) are handled by the table and sent to the API.
• Row actions (e.g. open details, validate documents, mark as paid, send to internal review) link or open the detail view or offcanvas modals.

Payment Details (/partner-payments/:id/details)

Detail view for a single payment: breakdown (e.g. shipments), documents, and actions (document validation, mark as paid, send to internal review).

Layout:

• Payment header (partner, period, status, amounts).
• Detail table (e.g. partner_payments_details: shipments, carriers, amounts).
• Documents section: list of documents with approve/reject actions.
• Actions: Mark as paid, Send to internal review, etc.

Document validation:

• ValidateDocuments is implemented as an offcanvas (ValidateDocuments.offcanvas.vue).
• It uses the shared FileViewer component for document preview and approval/rejection buttons.
• Approve calls PATCH .../documents/{documentId}/approve.
• Reject requires a reason and calls PATCH .../documents/{documentId}/reject with rejection_reason.

Stores / services:

• partner-payments.service.js: API client for list, details, documents, approve, reject (document), payCommission (PUT .../pay), rejectCommission (PUT .../reject), markAsPaid, sendToInternalReview.
• State (e.g. current payment, documents, loading) is typically held in the view or a small Pinia store if used.

Components

Module-specific

Component	Location	Description
Table	views/partner-payments/components/Table.vue	DataTable for the payment list: columns, filters, row actions, and API call to GET /partner-payments.
ValidateDocuments.offcanvas.vue	views/partner-payments/components/ValidateDocuments.offcanvas.vue	Offcanvas that lists documents for a payment and uses FileViewer for preview and approve/reject. Refactors document type labels to use translation keys.

Shared

Component	Use
SectionTitle	Page title on list and detail.
FileViewer	Document preview and approve/reject button styling and behavior.
DataTable (or equivalent)	Tabular data with sorting and pagination.
Modal / Offcanvas	Confirmations and document validation UI.

Constants and i18n

• partnerPayments.js (frontend constants): Payment status constants (e.g. PAYMENT_STATUS) and any labels used in the UI, aligned with backend payment_status values (including manually-paid for MANUALLY_PAID).
• Translations: Keys under partners.payments.* and any document-type or validation keys used in ValidateDocuments and FileViewer.

User Flows

View and filter payments

1. User goes to Partner Payments (sidebar or direct link to /partner-payments).
2. Table loads with default or saved filters.
3. User sets partner, date range, payment status, or other filters.
4. Table refreshes with new query params; user can sort and paginate.

Validate documents

1. User opens a payment (e.g. row action) and lands on /partner-payments/:id/details.
2. User opens the document validation offcanvas (e.g. “Validate documents”).
3. For each document, user can preview (FileViewer) and choose Approve or Reject.
4. Reject requires a reason; frontend calls reject endpoint with rejection_reason.
5. On success, list/state updates; Slack may be notified when the payment is fully approved.

Mark as paid

1. From the payment list or detail view, user chooses “Mark as paid”.
2. User enters or selects the paid date (and any required fields).
3. Frontend calls PATCH /partner-payments/{id}/mark-as-paid with paid_at.
4. Success feedback and refresh; Slack “commissions paid” notification may be sent.

Send to internal review

1. From the payment list or detail view, user chooses “Send to internal review”.
2. User enters required comments.
3. Frontend calls PATCH /partner-payments/{id}/send-to-internal-review with comments.
4. Success feedback and status update to “under review”.

Related Documentation

• Overview & data flow — Module purpose, backend structure, key decisions
• API — Endpoint reference
• User Guide — How to use partner payments in the app