# Provider Operations Dashboard and Moderation

This document is part of the public Zayuno provider contract. Any externally
visible change to provider onboarding, action visibility, payment reporting,
moderation, or lifecycle rules must update this document and the changelog in
the same change set.

## Customer contacts and business hours

In the provider workspace, open **Biznesim → Aloqa va ish vaqti**. This section is
available before and after publication. iiko connection cards also link here.
Changes do not reset certification or approval.

Owners and assigned developers (or platform admins) can read and replace these
settings with their dashboard JWT:

```http
GET /api/v1/providers/:slug/operations
PUT /api/v1/providers/:slug/operations
Authorization: Bearer <provider-dashboard-jwt>
```

PUT requires all three fields; credentials, publication and moderation fields
are rejected:

```json
{
  "supportContact": {
    "phone": "+998900000001",
    "telegram": "@restaurant_support",
    "website": "https://example.uz",
    "supportNote": "Buyurtma raqamini ayting, yordam beramiz."
  },
  "workingHours": {
    "timezone": "Asia/Tashkent",
    "schedule": [
      { "day": "MONDAY", "open": "09:00", "close": "23:00" },
      { "day": "TUESDAY", "open": "09:00", "close": "23:00" }
    ]
  },
  "acceptingOrders": true
}
```

The number and contacts above are illustrative. Public contacts may also include
`email` and `supportUrl` (HTTPS). Empty `supportContact: {}` clears contacts.
The old `supportContact.workingHours` string is retained for compatibility;
only the top-level structured `workingHours` controls order acceptance.

`schedule` contains up to 28 intervals. Days use uppercase English weekday
names. Missing days are closed. Multiple non-overlapping intervals are supported.
Opening is inclusive; closing is exclusive. `18:00–02:00` closes the following
day. `00:00–24:00` means a full day. Equal times and overlaps are rejected.
IANA timezones are validated; DST gaps and repeated times are handled by the
server. `workingHours: null` removes schedule restrictions; a configured empty
schedule closes the business all week.

GET/PUT settings and public provider discovery return `workingHours`, structured
`supportContact`, `operationalStatus` and `nextOpenAt`. `get_provider`,
`find_providers` and `list_providers` expose the same public fields in MCP.
There are no credentials or internal moderation fields in this public projection.

| Operational status | Discovery | New quote/create |
| --- | --- | --- |
| `OPEN` | Visible if published and eligible | Allowed by existing capability rules |
| `CLOSED` | Remains visible | HTTP 409 `PROVIDER_CLOSED` |
| `TEMPORARILY_UNAVAILABLE` | Manual pause remains visible | HTTP 409 `PROVIDER_TEMPORARILY_UNAVAILABLE` |
| `UNKNOWN` | Remains visible | Existing rules apply; hours have not been configured |

`acceptingOrders: false` takes precedence over hours. Existing health/publication
and compliance safeguards remain in force. Operational status is distinct from
provider lifecycle status (`ACTIVE`, `DRAFT`, etc.).

`nextOpenAt` is null while open, paused, unconfigured or closed all week. Otherwise
it is an ISO timestamp with the provider timezone offset, for example
`2026-10-06T09:00:00+05:00`. Agents should use this server decision, not calculate
hours themselves. Closed/pause error envelopes carry the same status and next
opening time, and are not retryable immediately. Idempotent replay of an existing
action, tracking, cancellation and payment for existing actions remain usable.

The mobile provider card shows status and a disclosure for support links and the
weekly schedule. Providers can still be selected while closed to view their
details; the backend remains responsible for execution safeguards.

## Provider-scoped action dashboard

Authenticated provider owners, developers, and analysts can use:

```http
GET /api/v1/providers/me/dashboard
Authorization: Bearer <provider-dashboard-jwt>
```

Supported filters:

| Parameter | Meaning |
| --- | --- |
| `query` | Action ID, external action ID, customer name, or phone |
| `status` | Normalized action status |
| `paymentStatus` | `PENDING`, `AUTHORIZED`, `PAID`, `FAILED`, or `REFUNDED` |
| `from`, `to` | ISO date or timestamp range |
| `minTotal`, `maxTotal` | Non-negative action total range |
| `sort` | `newest`, `oldest`, `total_asc`, or `total_desc` |
| `limit`, `offset` | Pagination; limit is capped at 100 |

The response includes global provider metrics, filtered action summaries, and
pagination. The API always derives the provider ID from the authenticated
account. A provider ID supplied by the browser is never trusted.

```json
{
  "metrics": {
    "totalActions": 32,
    "pendingActions": 4,
    "paidActions": 19,
    "completedActions": 17,
    "failedActions": 2
  },
  "actions": [
    {
      "publicId": "ZY-EXAMPLE-10001",
      "status": "IN_PROGRESS",
      "paymentStatus": "PAID",
      "paymentStatusSource": "PROVIDER_REPORTED",
      "total": 155000,
      "currency": "UZS",
      "customerName": "Example Customer",
      "customerPhoneMasked": "+99890***567"
    }
  ],
  "pagination": { "total": 1, "limit": 50, "offset": 0, "hasMore": false }
}
```

`PAID` means the provider integration reported that payment state. It does not
prove bank settlement unless the provider's payment integration explicitly
supplies settlement data.

## Provider-scoped action detail

```http
GET /api/v1/providers/me/actions/:actionId
Authorization: Bearer <provider-dashboard-jwt>
```

The endpoint accepts a Zayuno public ID, internal action ID, or provider
external action ID. It returns the item lines, normalized action and payment
status, provider-reported payment source, customer fulfillment details,
cancellation/failure explanation, and chronological timeline. It returns 404
for actions belonging to another provider.

## Cancellation and failure reasons

Provider adapters should send a concise, user-safe explanation for terminal
events. Prefer a stable machine-readable reason code in the event payload and
a clear human description. Suggested codes include:

- `CUSTOMER_CANCELLED`
- `PROVIDER_REJECTED`
- `ITEM_UNAVAILABLE`
- `PAYMENT_TIMEOUT`
- `PAYMENT_FAILED`
- `DUPLICATE_ACTION`
- `INVALID_CUSTOMER_INFORMATION`
- `PROVIDER_TIMEOUT`
- `SYSTEM_ERROR`
- `OTHER`

Do not place secrets, card data, passwords, OTP values, or unnecessary identity
documents in a reason or timeline description.

## Moderation lifecycle

```text
DRAFT -> PENDING_APPROVAL -> APPROVED -> ACTIVE
                     |-> CHANGES_REQUESTED -> DRAFT -> PENDING_APPROVAL
                     |-> REJECTED
ACTIVE --------------------------------------> SUSPENDED
```

Every non-approval decision requires:

- `reasonCode`: stable category;
- `reason`: partner-visible explanation (minimum 12 characters);
- `requiredChanges`: actionable checklist when applicable;
- `internalNote`: optional operations-only note.

Partner-visible reasons are returned in provider metadata. Review history and
internal notes are kept only for operations and must never be exposed by public
discovery endpoints. Resubmitting an integration clears the current visible
reason while preserving the audit history.

`CHANGES_REQUESTED` applications may update their integration and resubmit.
`REJECTED` or `SUSPENDED` applications cannot reset themselves to `DRAFT` by
editing the base URL; Operations must explicitly reopen them.

```http
POST /api/v1/admin/providers/:slug/reopen
Authorization: Bearer <admin-jwt>
```

## Operations provider filters

The admin endpoint supports filtering by query, provider status, review status,
provider type, capability, category, geography, certification state, owner
email, and registration date range:

```http
GET /api/v1/admin/providers?reviewStatus=PENDING_APPROVAL&certified=true
Authorization: Bearer <admin-jwt>
```

The response is `{ data, total, pagination }`.

## Documentation rule

The following changes require documentation and changelog updates in the same
pull request or release bundle:

- public API request or response changes;
- MCP tool or capability changes;
- provider onboarding and certification changes;
- action, payment, cancellation, or moderation lifecycle changes;
- dashboard workflows that providers depend on.

Run `pnpm test:docs-contract` before release. Internal refactors that do not
change observable behavior do not require a public contract update.
