# Merchant AI HTTP API

PHP 8.2 JSON API service for merchant order statistics, offline order analysis, and merchant ranking.

## Environment

Copy `.env.example` to `.env`, then fill your real token:

```bash
MERCHANT_API_TOKEN=your-admin-api-token
MERCHANT_API_BASE_URI=https://tpoint.agrimedia.cn
MERCHANT_API_TIMEOUT=60
OFFLINE_ORDER_PAGE_LIMIT=100
```

`MERCHANT_API_TOKEN` is required. `MERCHANT_API_BASE_URI` and `MERCHANT_API_TIMEOUT` are optional.
`OFFLINE_ORDER_PAGE_LIMIT` controls each upstream pagination request size.

If the request contains `Authorization: Bearer <token>`, that token is used for the upstream merchant API request first. If the header is missing, `MERCHANT_API_TOKEN` from `.env` is used.

## Start Locally

```bash
php -S 127.0.0.1:8080 -t public
```

## Response Format

Success:

```json
{
  "success": true,
  "data": {}
}
```

Error:

```json
{
  "success": false,
  "error": {
    "code": "server_error",
    "message": "error message"
  }
}
```

## Endpoints


### `GET /health`

Returns service health status.

### `GET /tools`

Returns available API tools and input schemas.

### `POST /api/order-summary`

Returns order count, active merchant count, successful order count, and amount totals.

### `POST /api/offline-stats`

Returns status, payment type, order type, and amount distribution analysis.

### `POST /api/merchant-ranking`

Returns merchant ranking by `orderCount`, `successOrderCount`, `totalOrderAmount`, or `totalRealPay`.

## Common Parameters

- `timePreset`: preferred AI time intent. Supported values: `today`, `yesterday`, `last_7_days`, `last_30_days`, `this_week`, `last_week`, `this_month`, `last_month`, `custom`. Defaults to `today`.
- `startDate`: custom start date, required when `timePreset=custom`, format `YYYY-MM-DD`.
- `endDate`: custom end date, required when `timePreset=custom`, format `YYYY-MM-DD`.
- `date`: legacy compatible date range, for example `2026/06/23-2026/06/23`; if provided, it is sent to the upstream order API as-is.
- `status`: order status; defaults to `-1` (all). Values: `0` = pending payment, `1` = completed, `2` = cancelled, `3` = pending verification/use, `4` = refunded.
- `keyword`: search keyword, sent to upstream API as `real_name`.
- `fieldKey`: upstream `field_key`; defaults to `all`.
- `payType`: upstream `pay_type`.
- `type`: upstream order `type`.
- `btcId`: upstream merchant category ID.

`/api/merchant-ranking` also supports:

- `sortBy`: `orderCount`, `successOrderCount`, `totalOrderAmount`, or `totalRealPay`; defaults to `totalRealPay`.
- `limit`: number of merchants to return; defaults to `10`, max `100`.

## POST Example

```bash
curl -X POST http://127.0.0.1:8080/api/merchant-ranking \
  -H "Content-Type: application/json" \
  -d '{"timePreset":"today","sortBy":"totalRealPay","limit":10}'
```