# Backend API 文档

生成日期：2026-05-08
生成依据：`backend/routes/api.php`、`php artisan route:list --path=api`、`app/Http/Controllers/Api/**`、`app/Services/**`

本文档是当前 backend API 的唯一维护入口。`backend/docs` 下的旧 API 文档已移除，后续接口变更统一更新本文件。

本文档只覆盖当前 `backend` 暴露的 API 路由，共 43 个路由入口。Laravel 自动支持的 `HEAD` 不单独列出。

## 通用约定

### Base URL

生产或本地部署时以实际后端域名为准，下文统一写作：

```text
{BACKEND_API_BASE_URL}/api
```

本地默认通常是：

```text
http://127.0.0.1:8000/api
```

### 请求头

| 请求头                                               | 适用接口               | 说明                                                                                                                                                                                           |
|---------------------------------------------------|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Content-Type: application/json`                  | 有 JSON body 的接口    | 请求体使用 JSON。                                                                                                                                                                                  |
| `Authorization: Bearer <sanctum_token>`           | Dashboard / 当前用户接口 | Laravel Sanctum Web 用户 token。邮箱已验证账号可由 `/api/auth/login` 返回；邮箱未验证账号必须先通过 `/api/auth/email/verify-code`，验证码校验成功后才返回 token；重置密码仅在账号邮箱已验证时返回 token。Dashboard 路由会拒绝扩展 token。                     |
| `Authorization: Bearer <extension_sanctum_token>` | Chrome 扩展接口        | 扩展专用 Sanctum token，由 `/api/auth/extension-pair` 或 `/api/auth/refresh-extension-token` 返回；后端会校验 `storeai_extension` token name 和 `extension:*` ability。扩展 token 只能访问扩展接口和 `/api/auth/logout`。 |
| `X-Ext-Version: <version>`                        | 扩展扫描相关接口           | 用于扩展版本门禁，低于 `MIN_EXT_VERSION` 会返回 `ext_outdated`。                                                                                                                                            |
| `Authorization: Bearer <CRON_SECRET>`             | Cron 接口            | 配置 `CRON_SECRET` 后必填；生产环境未配置会返回 `misconfigured`。                                                                                                                                             |
| `Stripe-Signature: <signature>`                   | Stripe webhook     | Stripe webhook 原始 body 签名。                                                                                                                                                                   |
| `X-Telegram-Bot-Api-Secret-Token: <secret>`       | Telegram webhook   | Telegram webhook secret token。                                                                                                                                                               |

### 响应格式

所有 backend API 统一返回三元素 envelope。前端已确定重写，不再保留旧 `{ ok: ... }` 顶层兼容格式。

```json
{
  "code": 1,
  "message": "ok",
  "data": {}
}
```

失败响应的顶层 `code` 放整型 status，旧接口字符串错误码统一放入 `data.apiCode`；异常响应不改变实际 HTTP status code，HTTP
层保持 200：

```json
{
  "code": 400,
  "message": "Validation failed.",
  "data": {
    "apiCode": "invalid_payload"
  }
}
```

部分错误会附带额外字段：

```json
{
  "code": 400,
  "message": "schema validation failed",
  "data": {
    "apiCode": "invalid_payload",
    "details": {
      "fieldErrors": {
        "payload.today.orders": ["must be an integer"]
      }
    }
  }
}
```

空业务数据返回空数组或空对象，取决于控制器业务返回值；客户端只应依赖外层 `code/message/data`。

```json
{
  "code": 1,
  "message": "ok",
  "data": {}
}
```

### 通用错误

下表的 `响应 code` 指 JSON 响应体里的 `code` 字段，不是 HTTP status code；异常响应的 HTTP status 保持 200。

| 响应 code | data.apiCode                                                            | 说明                          |
|--------:|-------------------------------------------------------------------------|-----------------------------|
|     400 | `invalid_payload` / `invalid_email` / `invalid_code`                    | 请求参数格式错误。                   |
|     401 | `unauthorized`                                                          | 缺少 token、token 无效、签名错误或未登录。 |
|     402 | `subscription_required`                                                 | 当前订阅状态不允许扫描。                |
|     404 | `not_found`                                                             | 资源不存在、无权访问或 debug 门禁关闭。     |
|     409 | `platform_account_mismatch` / `subscription_active` / `agreement_stale` | 业务状态冲突。                     |
|     426 | `ext_outdated`                                                          | Chrome 扩展版本低于后端要求。          |
|     429 | `too_many_requests` / `rate_limited`                                    | 请求过于频繁或手动扫描达到日限额。           |
|     500 | `server_error` / `config_error` / `stripe_error` / `handler_error`      | 服务端错误、配置缺失或第三方调用失败。         |
|     503 | `misconfigured`                                                         | 生产环境缺少必需配置。                 |

## 公共对象

### `User`

| 字段                | 类型           | 说明               |
|-------------------|--------------|------------------|
| `id`              | string       | Laravel 用户 UUID。 |
| `email`           | string       | 邮箱。              |
| `name`            | string\|null | 用户名，可为空。         |
| `emailVerifiedAt` | string\|null | 邮箱验证时间，ISO 字符串。  |

### `ApiUser`

| 字段      | 类型           | 说明           |
|---------|--------------|--------------|
| `id`    | string       | 当前登录用户 UUID。 |
| `email` | string\|null | 当前登录用户邮箱。    |

### `BrandCore`

`BrandCore` 是 Dashboard 读接口返回的品牌基础对象。不同接口会按页面需要裁剪或追加字段。

| 字段                       | 类型            | 说明                                              |
|--------------------------|---------------|-------------------------------------------------|
| `id`                     | string        | 品牌 UUID。                                        |
| `name`                   | string        | 品牌名称。                                           |
| `timezone`               | string\|null  | 品牌时区，例如 `Asia/Kuala_Lumpur`。                    |
| `morning_brief_hour`     | integer\|null | 早报本地小时，0-23。                                    |
| `evening_recap_hour`     | integer\|null | 晚报本地小时，0-23。                                    |
| `last_morning_brief_at`  | string\|null  | 最近早报发送时间。                                       |
| `last_evening_recap_at`  | string\|null  | 最近晚报发送时间。                                       |
| `subscription_status`    | string\|null  | 订阅状态，例如 `trial`、`active`、`past_due`、`canceled`。 |
| `trial_ends_at`          | string\|null  | 试用结束时间。                                         |
| `subscription_cancel_at` | string\|null  | 订阅预约取消时间。                                       |
| `is_comp`                | boolean       | 是否内部赠送账号。                                       |
| `telegram_chat_id`       | string\|null  | Telegram chat id。                               |
| `platform_account_id`    | string\|null  | 已绑定 Shopee seller id。                           |
| `created_at`             | string\|null  | 创建时间。                                           |
| `last_extension_version` | string\|null  | 最近扩展心跳版本。                                       |
| `stores`                 | array         | 店铺列表，元素为 `{ id: string }`。                      |

#### `subscription_status` 枚举

`subscription_status` 是 `brands` 表保存的原始账单状态；前端判断“是否可用 / 是否到期”时还要结合 `is_comp`、`trial_ends_at`
和 `subscription_cancel_at`。

| 值            | 含义                                             | 到期时间口径                                                                                |
|--------------|------------------------------------------------|---------------------------------------------------------------------------------------|
| `trial`      | 试用中。创建首个品牌时后端写入 `trial_ends_at = now + 1 day`。 | 使用 `trial_ends_at` 判断试用到期；为空时按试用可用但无倒计时时间处理。                                          |
| `active`     | Stripe 订阅有效。                                   | `subscription_cancel_at` 为空表示当前无已知到期时间；若为未来时间，表示已预约取消，付费权益到 `subscription_cancel_at`。 |
| `past_due`   | Stripe 付款异常或 `unpaid`。                         | 当前 API 不给确定到期时间；Stripe 后续重试失败并发送 deleted webhook 后会变为 `canceled`。                     |
| `canceled`   | 订阅已取消或 Stripe `incomplete_expired`。            | 已到期，不再使用未来到期时间；后端会清空 `subscription_cancel_at`。                                        |
| `null` / 其它值 | 旧数据或异常数据。                                      | 按无有效订阅处理。                                                                             |

有效订阅状态的派生规则：

| 条件                                                                    | 派生状态               | 扫描权限             |
|-----------------------------------------------------------------------|--------------------|------------------|
| `is_comp = true`                                                      | `comp`             | 允许，内部赠送账号优先级最高。  |
| `subscription_status = trial` 且 `trial_ends_at` 为空或晚于当前 UTC 时间        | `trial_active`     | 允许。              |
| `subscription_status = trial` 且 `trial_ends_at` 已过期或无法解析              | `trial_expired`    | 不允许。             |
| `subscription_status = active` 且 `subscription_cancel_at` 为空          | `active`           | 允许。              |
| `subscription_status = active` 且 `subscription_cancel_at` 晚于当前 UTC 时间 | `active_canceling` | 允许，展示“已预约取消”。    |
| `subscription_status = active` 且 `subscription_cancel_at` 已过期或无法解析    | `canceled`         | 不允许。             |
| `subscription_status = past_due`                                      | `past_due`         | 允许，但应提示用户更新付款方式。 |
| `subscription_status = canceled`                                      | `canceled`         | 不允许。             |

如果前端要展示“订阅到期时间”，优先按以下顺序取值：`is_comp=true` 时无到期时间；`trial` 取 `trial_ends_at`；`active` 且已预约取消时取
`subscription_cancel_at`；普通 `active` 当前没有到期时间字段，因为后端暂未保存 Stripe `current_period_end`。

### `ScanRow`

| 字段                    | 类型            | 说明                         |
|-----------------------|---------------|----------------------------|
| `id`                  | string        | scan UUID。                 |
| `scanned_at`          | string        | 扫描时间。                      |
| `status`              | string        | `ok`、`partial` 或 `failed`。 |
| `error`               | string\|null  | 扩展提取错误文本。                  |
| `payload`             | object\|null  | 扫描原始 payload。              |
| `telegram_message_id` | integer\|null | 手动扫描 Telegram 回声消息 id。     |

### `AlertRow`

| 字段             | 类型      | 说明                  |
|----------------|---------|---------------------|
| `id`           | string  | alert UUID。         |
| `rule_id`      | string  | 规则 ID。              |
| `priority`     | string  | 告警优先级，例如 `P1`、`P2`。 |
| `confidence`   | string  | 置信度。                |
| `title`        | string  | 标题。                 |
| `diagnosis`    | string  | 诊断文案。               |
| `action`       | string  | 建议动作。               |
| `data`         | object  | 告警附加 JSON。          |
| `acknowledged` | boolean | 是否已确认。              |
| `created_at`   | string  | 创建时间。               |

### `StoreBrief`

| 字段                      | 类型           | 说明              |
|-------------------------|--------------|-----------------|
| `verdict_tier`          | string\|null | AI 今日结论等级。      |
| `verdict_headline`      | string\|null | AI 今日结论标题。      |
| `verdict_factors`       | array        | AI 结论因素。        |
| `verdict_action`        | string\|null | AI 建议行动。        |
| `bottleneck_stage`      | string\|null | 增长瓶颈阶段。         |
| `growth_diagnosis_json` | object\|null | AI 增长诊断 JSON。   |
| `top_actions_json`      | array\|null  | AI Top Actions。 |
| `confidence`            | object       | AI 置信度 JSON。    |

## 系统接口

### GET `/api/health`

鉴权：无。

入参：无。

请求示例：

```bash
curl -X GET "{BACKEND_API_BASE_URL}/api/health"
```

响应参数：

| 字段                 | 类型           | 说明                       |
|--------------------|--------------|--------------------------|
| `code`             | integer      | 成功为 `1`。                 |
| `message`          | string       | 成功为 `ok`。                |
| `data.service`     | string       | 固定为 `storeai-api`。       |
| `data.version`     | string\|null | `config('app.version')`。 |
| `data.environment` | string       | 当前 Laravel 环境。           |

## 认证接口

### POST `/api/auth/register`

鉴权：无。

入参：

| 位置   | 字段         | 类型           | 必填 | 说明                    |
|------|------------|--------------|----|-----------------------|
| body | `email`    | string       | 是  | 合法邮箱，服务端会转小写并 trim。   |
| body | `password` | string       | 是  | 8-128 字符。             |
| body | `name`     | string\|null | 否  | 最多 120 字符，空字符串按 null。 |

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "owner@example.test",
    "password": "secure-password",
    "name": "Store Owner"
  }'
```

响应参数：

| 字段                               | 类型      | 说明                         |
|----------------------------------|---------|----------------------------|
| `code`                           | integer | 成功为 `1`。                   |
| `message`                        | string  | 成功为 `ok`。                  |
| `data.requiresEmailVerification` | boolean | 固定为 `true`，表示必须先完成邮箱验证码校验。 |
| `data.email`                     | string  | 标准化后的邮箱。                   |
| `data.user`                      | `User`  | 新建用户。                      |
| `data.sent`                      | boolean | 是否已发送邮箱验证码。                |
| `data.expiresInSeconds`          | integer | 验证码剩余有效秒数。                 |

错误：

| 响应 code | data.apiCode      | 说明         |
|--------:|-------------------|------------|
|     400 | `invalid_payload` | 邮箱或密码格式错误。 |
|     400 | `duplicate_email` | 邮箱已注册。     |

备注：注册成功后会发送 6 位邮箱验证码，但不会签发登录 token；只有 `/api/auth/email/verify-code` 校验成功后才会签发 Web
Sanctum token。`users.id` 同时作为业务 `account_id` 使用。

### POST `/api/auth/login`

鉴权：无。

入参：

| 位置   | 字段         | 类型     | 必填 | 说明        |
|------|------------|--------|----|-----------|
| body | `email`    | string | 是  | 合法邮箱。     |
| body | `password` | string | 是  | 8-128 字符。 |

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "owner@example.test",
    "password": "secure-password"
  }'
```

响应参数：

| 字段                               | 类型      | 说明                                          |
|----------------------------------|---------|---------------------------------------------|
| `code`                           | integer | 成功为 `1`。                                    |
| `message`                        | string  | 成功为 `ok`。                                   |
| `data.user`                      | `User`  | 登录用户。邮箱未验证时也会返回，`emailVerifiedAt` 为 `null`。 |
| `data.token`                     | string  | 邮箱已验证时返回的新签发 Sanctum Bearer token。          |
| `data.requiresEmailVerification` | boolean | 邮箱未验证时返回 `true`。                            |
| `data.email`                     | string  | 邮箱未验证时返回的标准化邮箱。                             |
| `data.sent`                      | boolean | 邮箱未验证时表示是否已发送新的验证码。                         |
| `data.expiresInSeconds`          | integer | 新验证码剩余有效秒数。                                 |
| `data.retryAfterSeconds`         | integer | 验证码重发限流时返回。                                 |

错误：

| 响应 code | data.apiCode          | 说明       |
|--------:|-----------------------|----------|
|     400 | `invalid_payload`     | 入参格式错误。  |
|     401 | `invalid_credentials` | 邮箱或密码错误。 |

备注：邮箱已验证时，登录成功会先删除当前账号所有旧 Sanctum token，包括旧 Web token 和扩展 token，再签发新的 Web
token；扩展需要重新配对。邮箱未验证时不会返回 token，会清理该账号旧 token 并返回 `requiresEmailVerification=true`
，前端应进入邮箱验证码流程。

### GET `/api/auth/me`

鉴权：Sanctum。仅 Web/Dashboard token 可调用，扩展 token 会被 `dashboard.token` 门禁拒绝。

入参：无。

请求示例：

```bash
curl -X GET "{BACKEND_API_BASE_URL}/api/auth/me" \
  -H "Authorization: Bearer <sanctum_token>"
```

响应参数：

| 字段          | 类型           | 说明             |
|-------------|--------------|----------------|
| `code`      | integer      | 成功为 `1`。       |
| `message`   | string       | 成功为 `ok`。      |
| `data.user` | `User`\|null | 当前 token 对应用户。 |

### POST `/api/auth/logout`

鉴权：Sanctum。

入参：无。

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/auth/logout" \
  -H "Authorization: Bearer <sanctum_token>"
```

响应参数：

| 字段        | 类型      | 说明        |
|-----------|---------|-----------|
| `code`    | integer | 成功为 `1`。  |
| `message` | string  | 成功为 `ok`。 |

备注：退出登录会删除当前账号所有 Sanctum token，包括 Web token 和扩展 token，让 Dashboard 和 Chrome 扩展同时下线。

### POST `/api/auth/rotate-session`

鉴权：Sanctum。

入参：无。

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/auth/rotate-session" \
  -H "Authorization: Bearer <sanctum_token>"
```

响应参数：

| 字段             | 类型      | 说明                                                     |
|----------------|---------|--------------------------------------------------------|
| `code`         | integer | 成功为 `1`。                                               |
| `message`      | string  | 成功为 `ok`。                                              |
| `data.rotated` | boolean | 固定为 `false`。                                           |
| `data.reason`  | string  | 固定为 `sanctum_bearer_tokens_are_already_device_scoped`。 |

备注：兼容 Origin 的 Supabase session rotate 调用；Sanctum 下是 no-op。

### PATCH `/api/auth/password`

鉴权：Sanctum。

入参：

| 位置   | 字段         | 类型     | 必填 | 说明            |
|------|------------|--------|----|---------------|
| body | `password` | string | 是  | 新密码，8-128 字符。 |

请求示例：

```bash
curl -X PATCH "{BACKEND_API_BASE_URL}/api/auth/password" \
  -H "Authorization: Bearer <sanctum_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "new-secure-password"
  }'
```

响应参数：

| 字段        | 类型      | 说明        |
|-----------|---------|-----------|
| `code`    | integer | 成功为 `1`。  |
| `message` | string  | 成功为 `ok`。 |

错误：

| 响应 code | data.apiCode      | 说明       |
|--------:|-------------------|----------|
|     400 | `invalid_payload` | 密码长度不合法。 |

### GET `/api/auth/check-verified`

鉴权：无。

入参：

| 位置    | 字段      | 类型     | 必填 | 说明          |
|-------|---------|--------|----|-------------|
| query | `email` | string | 是  | 要查询验证状态的邮箱。 |

请求示例：

```bash
curl -X GET "{BACKEND_API_BASE_URL}/api/auth/check-verified?email=owner%40example.test"
```

响应参数：

| 字段              | 类型      | 说明                              |
|-----------------|---------|---------------------------------|
| `code`          | integer | 成功为 `1`。                        |
| `message`       | string  | 成功为 `ok`。                       |
| `data.verified` | boolean | `users.email_verified_at` 是否非空。 |

错误：

| 响应 code | data.apiCode    | 说明      |
|--------:|-----------------|---------|
|     400 | `invalid_email` | 邮箱格式错误。 |

备注：响应头包含 `cache-control: no-store`。

### POST `/api/auth/email/verification-code`

鉴权：无。

入参：

| 位置   | 字段      | 类型     | 必填 | 说明         |
|------|---------|--------|----|------------|
| body | `email` | string | 是  | 要发送验证码的邮箱。 |

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/auth/email/verification-code" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "owner@example.test"
  }'
```

响应参数：

| 字段                      | 类型      | 说明                              |
|-------------------------|---------|---------------------------------|
| `code`                  | integer | 成功为 `1`。                        |
| `message`               | string  | 成功为 `ok`。                       |
| `data.sent`             | boolean | 是否触发发送。未知邮箱也返回 `true` 以防账号枚举。   |
| `data.alreadyVerified`  | boolean | 已验证邮箱返回 `true`，此时 `sent=false`。 |
| `data.expiresInSeconds` | integer | 验证码剩余有效秒数，实际发送时返回。              |

错误：

| 响应 code | data.apiCode        | 说明                              |
|--------:|---------------------|---------------------------------|
|     400 | `invalid_email`     | 邮箱格式错误。                         |
|     429 | `too_many_requests` | 发送过于频繁，响应含 `retryAfterSeconds`。 |

### POST `/api/auth/email/verify-code`

鉴权：无。

入参：

| 位置   | 字段      | 类型     | 必填 | 说明        |
|------|---------|--------|----|-----------|
| body | `email` | string | 是  | 邮箱。       |
| body | `code`  | string | 是  | 6 位数字验证码。 |

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/auth/email/verify-code" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "owner@example.test",
    "code": "123456"
  }'
```

响应参数：

| 字段              | 类型      | 说明                        |
|-----------------|---------|---------------------------|
| `code`          | integer | 成功为 `1`。                  |
| `message`       | string  | 成功为 `ok`。                 |
| `data.verified` | boolean | 成功为 `true`。               |
| `data.user`     | `User`  | 已验证用户。                    |
| `data.token`    | string  | 新签发 Sanctum Bearer token。 |

错误：

| 响应 code | data.apiCode    | 说明                          |
|--------:|-----------------|-----------------------------|
|     400 | `invalid_email` | 邮箱格式错误。                     |
|     400 | `invalid_code`  | 验证码格式错误、邮箱不存在、验证码不存在或验证码错误。 |
|     400 | `expired_code`  | 验证码已过期。                     |

备注：校验成功等价于一次 Web 登录，会删除当前账号所有旧 Web/扩展 token，并签发新 Web token。

### POST `/api/auth/password/forgot`

鉴权：无。

入参：

| 位置   | 字段      | 类型     | 必填 | 说明        |
|------|---------|--------|----|-----------|
| body | `email` | string | 是  | 要重置密码的邮箱。 |

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/auth/password/forgot" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "owner@example.test"
  }'
```

响应参数：

| 字段                      | 类型      | 说明                          |
|-------------------------|---------|-----------------------------|
| `code`                  | integer | 成功为 `1`。                    |
| `message`               | string  | 成功为 `ok`。                   |
| `data.sent`             | boolean | 固定按成功处理；未知邮箱不发信但仍返回 `true`。 |
| `data.expiresInSeconds` | integer | 验证码有效秒数，实际发信时返回。            |

错误：

| 响应 code | data.apiCode        | 说明                              |
|--------:|---------------------|---------------------------------|
|     400 | `invalid_email`     | 邮箱格式错误。                         |
|     429 | `too_many_requests` | 发送过于频繁，响应含 `retryAfterSeconds`。 |

### POST `/api/auth/password/reset`

鉴权：无。

入参：

| 位置   | 字段         | 类型     | 必填 | 说明            |
|------|------------|--------|----|---------------|
| body | `email`    | string | 是  | 邮箱。           |
| body | `code`     | string | 是  | 6 位数字验证码。     |
| body | `password` | string | 是  | 新密码，8-128 字符。 |

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/auth/password/reset" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "owner@example.test",
    "code": "123456",
    "password": "new-secure-password"
  }'
```

响应参数：

| 字段                               | 类型      | 说明                                 |
|----------------------------------|---------|------------------------------------|
| `code`                           | integer | 成功为 `1`。                           |
| `message`                        | string  | 成功为 `ok`。                          |
| `data.reset`                     | boolean | 成功为 `true`。                        |
| `data.user`                      | `User`  | 重置密码后的用户。                          |
| `data.token`                     | string  | 邮箱已验证时返回的新签发 Sanctum Bearer token。 |
| `data.requiresEmailVerification` | boolean | 账号邮箱未验证时返回 `true`，此时不返回 `token`。   |
| `data.email`                     | string  | 账号邮箱未验证时返回的标准化邮箱。                  |
| `data.sent`                      | boolean | 账号邮箱未验证时表示是否已发送邮箱验证验证码。            |
| `data.expiresInSeconds`          | integer | 邮箱验证验证码剩余有效秒数。                     |
| `data.retryAfterSeconds`         | integer | 邮箱验证验证码重发限流时返回。                    |

错误：

| 响应 code | data.apiCode      | 说明                          |
|--------:|-------------------|-----------------------------|
|     400 | `invalid_email`   | 邮箱格式错误。                     |
|     400 | `invalid_code`    | 验证码格式错误、邮箱不存在、验证码不存在或验证码错误。 |
|     400 | `expired_code`    | 验证码已过期。                     |
|     400 | `invalid_payload` | 新密码不符合长度要求。                 |

备注：成功后会消费该邮箱所有未使用重置码。若账号邮箱已验证，会删除当前账号所有旧 Web/扩展 token，并签发新 Web
token；若账号邮箱未验证，只更新密码、清理旧 token、发送邮箱验证验证码并返回 `requiresEmailVerification=true`。

### POST `/api/auth/extension-pair`

鉴权：Sanctum。

入参：

| 位置   | 字段      | 类型     | 必填 | 说明                  |
|------|---------|--------|----|---------------------|
| body | `label` | string | 否  | 扩展设备标签，最多保留 120 字符。 |

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/auth/extension-pair" \
  -H "Authorization: Bearer <sanctum_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Chrome - Store Owner Laptop"
  }'
```

响应参数：

| 字段                                | 类型           | 说明                                                            |
|-----------------------------------|--------------|---------------------------------------------------------------|
| `code`                            | integer      | 成功为 `1`。                                                      |
| `message`                         | string       | 成功为 `ok`。                                                     |
| `data.token`                      | string       | 扩展专用 Sanctum plaintext token，格式为 Sanctum 标准 `<id>\|<secret>`。 |
| `data.expiresAt`                  | string       | 扩展 token 过期时间。                                                |
| `data.userEmail`                  | string\|null | 当前用户邮箱。                                                       |
| `data.apiBaseUrl`                 | string       | 后续扩展请求使用的 API base URL。                                       |
| `data.priorTokensRevoked`         | integer      | 本次撤销的旧扩展 token 数量。                                            |
| `data.priorTokensFromOtherDevice` | boolean      | 是否踢掉了其他设备 token。                                              |

备注：扩展 token 明文只返回一次，数据库写入 `personal_access_tokens`，`name` 为 `storeai_extension` 或
`storeai_extension:<label>`，abilities 只包含扩展权限；新配对会删除该账号所有旧扩展 token，保持扩展侧单设备策略，但不会删除当前
Web token。普通 Dashboard Sanctum token 不能调用扩展接口。

### POST `/api/auth/refresh-extension-token`

鉴权：扩展机器 token。
必需 header：`Authorization: Bearer <extension_sanctum_token>`。

入参：无。

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/auth/refresh-extension-token" \
  -H "Authorization: Bearer <extension_sanctum_token>"
```

响应参数：

| 字段               | 类型      | 说明                                                             |
|------------------|---------|----------------------------------------------------------------|
| `code`           | integer | 成功为 `1`。                                                       |
| `message`        | string  | 成功为 `ok`。                                                      |
| `data.token`     | string  | 新扩展专用 Sanctum plaintext token，格式为 Sanctum 标准 `<id>\|<secret>`。 |
| `data.expiresAt` | string  | 新 token 过期时间。                                                  |

错误：

| 响应 code | data.apiCode   | 说明                                      |
|--------:|----------------|-----------------------------------------|
|     401 | `unauthorized` | 缺少、格式错误、已删除、已过期或缺少对应扩展 ability 的 token。 |

备注：刷新成功会先创建新扩展 token，再删除同账号其它扩展 token；删除范围只限扩展 token，不删除 Web token。

## Dashboard 与 Onboarding

### GET `/api/dashboard/shell`

鉴权：Sanctum。

入参：无。

请求示例：

```bash
curl -X GET "{BACKEND_API_BASE_URL}/api/dashboard/shell" \
  -H "Authorization: Bearer <sanctum_token>"
```

响应参数：

| 字段                                  | 类型           | 说明                                        |
|-------------------------------------|--------------|-------------------------------------------|
| `code`                              | integer      | 成功为 `1`。                                  |
| `message`                           | string       | 成功为 `ok`。                                 |
| `data.user`                         | `ApiUser`    | 当前用户。                                     |
| `data.brand`                        | object\|null | 当前账号第一品牌的 shell 信息。                       |
| `data.brand.id`                     | string       | 品牌 UUID。                                  |
| `data.brand.name`                   | string       | 品牌名。                                      |
| `data.brand.subscription_status`    | string       | 订阅状态，枚举见 `BrandCore.subscription_status`。 |
| `data.brand.trial_ends_at`          | string\|null | 试用结束时间。                                   |
| `data.brand.subscription_cancel_at` | string\|null | 预约取消时间。                                   |
| `data.brand.is_comp`                | boolean      | 是否内部赠送账号。                                 |

### GET `/api/dashboard`

鉴权：Sanctum。

入参：无。

请求示例：

```bash
curl -X GET "{BACKEND_API_BASE_URL}/api/dashboard" \
  -H "Authorization: Bearer <sanctum_token>"
```

响应参数：

| 字段                         | 类型                 | 说明                                             |
|----------------------------|--------------------|------------------------------------------------|
| `code`                     | integer            | 成功为 `1`。                                       |
| `message`                  | string             | 成功为 `ok`。                                      |
| `data.user`                | `ApiUser`          | 当前用户。                                          |
| `data.brand`               | `BrandCore`\|null  | 当前账号第一品牌。无品牌时只返回 `user` 和 `brand:null`。        |
| `data.latestScan`          | `ScanRow`\|null    | 最近一次扫描。                                        |
| `data.previousScan`        | `ScanRow`\|null    | 最近一次可对比的历史成功扫描。                                |
| `data.scanDots`            | array              | 最近 12 次扫描轻量列表，元素 `{ id, scanned_at, status }`。 |
| `data.alerts`              | `AlertRow[]`       | 最近扫描下的告警列表。                                    |
| `data.competitorMeta`      | array              | 竞品元数据，元素 `{ product_url, label }`。             |
| `data.storeBrief`          | `StoreBrief`\|null | 最近扫描 AI brief。                                 |
| `data.dismissedKeys`       | string[]           | 当前品牌本地日已 Mark done 的 action key。               |
| `data.skuMatrixEntries`    | array\|null        | 当日 SKU Matrix 条目，来自 `sku_matrix.matrix_json`。  |
| `data.skuMatrixConfidence` | string\|null       | SKU Matrix 置信度。                                |
| `data.gmvRows`             | array              | 最近 40 条成功 scan 的 `{ scanned_at, payload }`。    |

### GET `/api/dashboard/settings`

鉴权：Sanctum。

入参：无。

请求示例：

```bash
curl -X GET "{BACKEND_API_BASE_URL}/api/dashboard/settings" \
  -H "Authorization: Bearer <sanctum_token>"
```

响应参数：

| 字段                     | 类型                | 说明                                                               |
|------------------------|-------------------|------------------------------------------------------------------|
| `code`                 | integer           | 成功为 `1`。                                                         |
| `message`              | string            | 成功为 `ok`。                                                        |
| `data.user`            | `ApiUser`         | 当前用户。                                                            |
| `data.brand`           | `BrandCore`\|null | 设置页品牌信息；附加 `thresholds`、`platform_account_id_bound_at`、`stores`。 |
| `data.manualUsedToday` | integer           | 品牌本地日内已使用手动扫描次数。                                                 |
| `data.lastAutoScanAt`  | string\|null      | 最近一次 scheduled scan 时间。                                          |
| `data.competitors`     | array             | 竞品列表，元素 `{ id, product_url, label, created_at }`。                |

### GET `/api/dashboard/billing`

鉴权：Sanctum。

入参：无。

请求示例：

```bash
curl -X GET "{BACKEND_API_BASE_URL}/api/dashboard/billing" \
  -H "Authorization: Bearer <sanctum_token>"
```

响应参数：

| 字段             | 类型                | 说明                                            |
|----------------|-------------------|-----------------------------------------------|
| `code`         | integer           | 成功为 `1`。                                      |
| `message`      | string            | 成功为 `ok`。                                     |
| `data.user`    | `ApiUser`         | 当前用户。                                         |
| `data.brand`   | `BrandCore`\|null | 账单页品牌信息，含 Stripe customer/subscription id 字段。 |
| `data.billing` | null              | 当前固定为 null，保留给前端兼容。                           |

### GET `/api/onboarding/status`

鉴权：Sanctum。

入参：无。

请求示例：

```bash
curl -X GET "{BACKEND_API_BASE_URL}/api/onboarding/status" \
  -H "Authorization: Bearer <sanctum_token>"
```

响应参数：

| 字段                | 类型                | 说明                                 |
|-------------------|-------------------|------------------------------------|
| `code`            | integer           | 成功为 `1`。                           |
| `message`         | string            | 成功为 `ok`。                          |
| `data.user`       | `ApiUser`         | 当前用户。                              |
| `data.brand`      | `BrandCore`\|null | Onboarding 所需品牌信息。                 |
| `data.lastScanAt` | string\|null      | 当前店铺最近一次 `ok` 或 `partial` scan 时间。 |

## 当前用户与扩展接口

### POST `/api/me/brand`

鉴权：Sanctum。

入参：

| 位置   | 字段         | 类型     | 必填 | 说明                   |
|------|------------|--------|----|----------------------|
| body | `name`     | string | 是  | 品牌名称，trim 后 1-80 字符。 |
| body | `timezone` | string | 是  | PHP 支持的时区名，最长 64 字符。 |

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/me/brand" \
  -H "Authorization: Bearer <sanctum_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "StoreAI Demo Brand",
    "timezone": "Asia/Kuala_Lumpur"
  }'
```

响应参数：

| 字段                    | 类型      | 说明            |
|-----------------------|---------|---------------|
| `code`                | integer | 成功为 `1`。      |
| `message`             | string  | 成功为 `ok`。     |
| `data.brand.id`       | string  | 新品牌 UUID。     |
| `data.brand.name`     | string  | 品牌名称。         |
| `data.brand.timezone` | string  | 品牌时区。         |
| `data.store.id`       | string  | 同步创建的店铺 UUID。 |

错误：

| 响应 code | data.apiCode      | 说明          |
|--------:|-------------------|-------------|
|     400 | `invalid_payload` | 品牌名或时区格式错误。 |
|     400 | `brand_exists`    | 当前账号已有品牌。   |

### PATCH `/api/me/brand`

鉴权：Sanctum。

入参：

| 位置   | 字段         | 类型     | 必填 | 说明                   |
|------|------------|--------|----|----------------------|
| body | `name`     | string | 否  | 品牌名称，trim 后 1-80 字符。 |
| body | `timezone` | string | 否  | PHP 支持的时区名，最长 64 字符。 |

请求示例：

```bash
curl -X PATCH "{BACKEND_API_BASE_URL}/api/me/brand" \
  -H "Authorization: Bearer <sanctum_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "StoreAI Demo Brand",
    "timezone": "Asia/Kuala_Lumpur"
  }'
```

响应参数：

| 字段           | 类型      | 说明                               |
|--------------|---------|----------------------------------|
| `code`       | integer | 成功为 `1`。                         |
| `message`    | string  | 成功为 `ok`。                        |
| `data.brand` | object  | 有变更时返回 `{ id, name, timezone }`。 |
| `data.noop`  | boolean | 没有可更新字段时返回 `true`。               |

错误：

| 响应 code | data.apiCode      | 说明                   |
|--------:|-------------------|----------------------|
|     400 | `invalid_payload` | 品牌名或时区格式错误。          |
|     500 | `server_error`    | 当前账号没有可更新品牌或更新后读取失败。 |

### DELETE `/api/me/account`

鉴权：Sanctum。

入参：无。

请求示例：

```bash
curl -X DELETE "{BACKEND_API_BASE_URL}/api/me/account" \
  -H "Authorization: Bearer <sanctum_token>"
```

响应参数：

| 字段        | 类型      | 说明        |
|-----------|---------|-----------|
| `code`    | integer | 成功为 `1`。  |
| `message` | string  | 成功为 `ok`。 |

错误：

| 响应 code | data.apiCode          | 说明                                      |
|--------:|-----------------------|-----------------------------------------|
|     409 | `subscription_active` | 品牌仍有 active 或 past_due 订阅，必须先取消或等待周期结束。 |

### POST `/api/me/action/dismiss`

鉴权：Sanctum。

入参：

| 位置   | 字段           | 类型     | 必填 | 说明                       |
|------|--------------|--------|----|--------------------------|
| body | `action_key` | string | 是  | Top Action key，1-200 字符。 |

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/me/action/dismiss" \
  -H "Authorization: Bearer <sanctum_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action_key": "sku:SKU-001:fix_conversion"
  }'
```

响应参数：

| 字段        | 类型      | 说明        |
|-----------|---------|-----------|
| `code`    | integer | 成功为 `1`。  |
| `message` | string  | 成功为 `ok`。 |

错误：

| 响应 code | data.apiCode      | 说明                    |
|--------:|-------------------|-----------------------|
|     400 | `no_brand`        | 当前账号没有品牌。             |
|     400 | `invalid_payload` | `action_key` 缺失或长度非法。 |

备注：`dismiss_date` 使用品牌本地日开始时间转 UTC 后的日期键，与 Dashboard 和定时报表过滤逻辑一致。

### GET `/api/me/competitors`

鉴权：扩展机器 token。
必需 header：`Authorization: Bearer <extension_sanctum_token>`、`X-Ext-Version`。

入参：无。

请求示例：

```bash
curl -X GET "{BACKEND_API_BASE_URL}/api/me/competitors" \
  -H "Authorization: Bearer <extension_sanctum_token>" \
  -H "X-Ext-Version: 0.1.0"
```

响应参数：

| 字段                               | 类型           | 说明             |
|----------------------------------|--------------|----------------|
| `code`                           | integer      | 成功为 `1`。       |
| `message`                        | string       | 成功为 `ok`。      |
| `data.competitors`               | array        | 当前账号所有品牌已登记竞品。 |
| `data.competitors[].id`          | string       | 竞品 UUID。       |
| `data.competitors[].brand_id`    | string       | 品牌 UUID。       |
| `data.competitors[].product_url` | string       | Shopee 商品 URL。 |
| `data.competitors[].label`       | string\|null | 竞品备注。          |

错误：

| 响应 code | data.apiCode   | 说明              |
|--------:|----------------|-----------------|
|     401 | `unauthorized` | 扩展 token 缺失或无效。 |
|     426 | `ext_outdated` | 扩展版本过旧。         |

### GET `/api/me/scan-quota`

鉴权：扩展机器 token。
必需 header：`Authorization: Bearer <extension_sanctum_token>`、`X-Ext-Version`。

入参：无。

请求示例：

```bash
curl -X GET "{BACKEND_API_BASE_URL}/api/me/scan-quota" \
  -H "Authorization: Bearer <extension_sanctum_token>" \
  -H "X-Ext-Version: 0.1.0"
```

响应参数：

| 字段                            | 类型           | 说明                                                      |
|-------------------------------|--------------|---------------------------------------------------------|
| `code`                        | integer      | 成功为 `1`。                                                |
| `message`                     | string       | 成功为 `ok`。                                               |
| `data.allowed`                | boolean      | 是否允许手动扫描。                                               |
| `data.reason`                 | string       | 不允许时返回，例如 `subscription_required`、`manual_cap_reached`。 |
| `message`                     | string       | 不允许时的用户提示。                                              |
| `data.manualUsed`             | integer      | 品牌本地日已使用手动扫描次数。                                         |
| `data.manualCap`              | integer      | 每日手动扫描上限，默认 3。                                          |
| `data.remaining`              | integer      | 剩余手动扫描次数。                                               |
| `data.boundPlatformAccountId` | string\|null | 品牌已绑定 Shopee seller id。                                 |
| `data.subState`               | string       | 计算后的订阅状态。                                               |
| `data.trialEndsAt`            | string\|null | 试用结束时间。                                                 |
| `data.latestExtVersion`       | string       | 后端配置的最新扩展版本。                                            |
| `data.extDownloadUrl`         | string       | 扩展下载地址。                                                 |

错误：

| 响应 code | data.apiCode   | 说明               |
|--------:|----------------|------------------|
|     401 | `unauthorized` | 扩展 token 缺失或无效。  |
|     404 | `not_found`    | 当前账号没有品牌或品牌没有店铺。 |
|     426 | `ext_outdated` | 扩展版本过旧。          |

### POST `/api/extension/heartbeat`

鉴权：扩展机器 token。
必需 header：`Authorization: Bearer <extension_sanctum_token>`。

入参：

| 位置   | 字段            | 类型           | 必填 | 说明                      |
|------|---------------|--------------|----|-------------------------|
| body | `skip_reason` | string\|null | 是  | 扩展本轮跳过扫描原因，可为 null。     |
| body | `ext_version` | string       | 是  | 扩展版本，1-40 字符。           |
| body | `tick_at`     | string       | 是  | 客户端心跳时间，可被解析为 datetime。 |

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/extension/heartbeat" \
  -H "Authorization: Bearer <extension_sanctum_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "skip_reason": "Shopee tab not open",
    "ext_version": "0.1.0",
    "tick_at": "2026-05-08T10:15:00Z"
  }'
```

响应参数：

| 字段        | 类型      | 说明                         |
|-----------|---------|----------------------------|
| `code`    | integer | 成功为 `1`。                   |
| `message` | string  | 成功为 `ok`。                  |
| `code`    | string  | 更新失败时可能返回 `update_failed`。 |

错误：

| 响应 code | data.apiCode      | 说明                 |
|--------:|-------------------|--------------------|
|     400 | `invalid_payload` | 请求体格式错误。           |
|     401 | `unauthorized`    | 扩展 token 缺失或无效。    |
|     404 | `not_found`       | 当前 token 所属账号没有品牌。 |

## 品牌设置接口

### GET `/api/brands/{id}/competitors`

鉴权：Sanctum。

入参：

| 位置   | 字段   | 类型     | 必填 | 说明       |
|------|------|--------|----|----------|
| path | `id` | string | 是  | 品牌 UUID。 |

请求示例：

```bash
curl -X GET "{BACKEND_API_BASE_URL}/api/brands/00000000-0000-4000-8000-000000000101/competitors" \
  -H "Authorization: Bearer <sanctum_token>"
```

响应参数：

| 字段                               | 类型           | 说明                          |
|----------------------------------|--------------|-----------------------------|
| `code`                           | integer      | 成功为 `1`。                    |
| `message`                        | string       | 成功为 `ok`。                   |
| `data.competitors`               | array        | 竞品列表。无权访问品牌时返回空数组，不泄露品牌存在性。 |
| `data.competitors[].id`          | string       | 竞品 UUID。                    |
| `data.competitors[].product_url` | string       | Shopee 商品 URL。              |
| `data.competitors[].label`       | string\|null | 竞品备注。                       |
| `data.competitors[].created_at`  | string\|null | 创建时间。                       |

错误：

| 响应 code | data.apiCode      | 说明             |
|--------:|-------------------|----------------|
|     400 | `invalid_payload` | 品牌 id 不是 UUID。 |

### POST `/api/brands/{id}/competitors`

鉴权：Sanctum。

入参：

| 位置   | 字段           | 类型           | 必填 | 说明                                          |
|------|--------------|--------------|----|---------------------------------------------|
| path | `id`         | string       | 是  | 品牌 UUID。                                    |
| body | `productUrl` | string       | 是  | Shopee 商品页 URL，必须匹配 `-i.<shopId>.<itemId>`。 |
| body | `label`      | string\|null | 否  | 竞品备注，最多 80 字符。                              |

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/brands/00000000-0000-4000-8000-000000000101/competitors" \
  -H "Authorization: Bearer <sanctum_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "productUrl": "https://shopee.com.my/example-product-i.123456.987654321",
    "label": "Main competitor"
  }'
```

响应参数：

| 字段                            | 类型           | 说明             |
|-------------------------------|--------------|----------------|
| `code`                        | integer      | 成功为 `1`。       |
| `message`                     | string       | 成功为 `ok`。      |
| `data.competitor.id`          | string       | 新竞品 UUID。      |
| `data.competitor.product_url` | string       | Shopee 商品 URL。 |
| `data.competitor.label`       | string\|null | 竞品备注。          |
| `data.competitor.created_at`  | string\|null | 创建时间。          |

错误：

| 响应 code | data.apiCode      | 说明              |
|--------:|-------------------|-----------------|
|     400 | `invalid_payload` | URL 或备注格式错误。    |
|     400 | `duplicate`       | 已登记相同 URL。      |
|     400 | `over_limit`      | 超过每品牌 10 个竞品上限。 |
|     404 | `not_found`       | 品牌不存在或不属于当前用户。  |

### DELETE `/api/brands/{id}/competitors/{competitorId}`

鉴权：Sanctum。

入参：

| 位置   | 字段             | 类型     | 必填 | 说明       |
|------|----------------|--------|----|----------|
| path | `id`           | string | 是  | 品牌 UUID。 |
| path | `competitorId` | string | 是  | 竞品 UUID。 |

请求示例：

```bash
curl -X DELETE "{BACKEND_API_BASE_URL}/api/brands/00000000-0000-4000-8000-000000000101/competitors/00000000-0000-4000-8000-000000000201" \
  -H "Authorization: Bearer <sanctum_token>"
```

响应参数：

| 字段        | 类型      | 说明        |
|-----------|---------|-----------|
| `code`    | integer | 成功为 `1`。  |
| `message` | string  | 成功为 `ok`。 |

错误：

| 响应 code | data.apiCode      | 说明              |
|--------:|-------------------|-----------------|
|     400 | `invalid_payload` | path UUID 格式错误。 |

备注：删除是幂等的，行不存在或无权删除也返回成功。

### PATCH `/api/brands/{id}/notifications`

鉴权：Sanctum。

入参：

| 位置   | 字段                 | 类型      | 必填 | 说明                                              |
|------|--------------------|---------|----|-------------------------------------------------|
| path | `id`               | string  | 是  | 品牌 UUID。                                        |
| body | `morningBriefHour` | integer | 否  | 早报本地小时，0-23。                                    |
| body | `eveningRecapHour` | integer | 否  | 晚报本地小时，0-23。                                    |
| body | `pushMode`         | string  | 否  | 兼容旧字段，只接受 `daily_digest` 或 `instant_alert`，不写库。 |
| body | `dailyReportHour`  | integer | 否  | 兼容旧字段，仅校验，不写库。                                  |
| body | `silentStartHour`  | integer | 否  | 兼容旧字段，仅校验，不写库。                                  |
| body | `silentEndHour`    | integer | 否  | 兼容旧字段，仅校验，不写库。                                  |

请求示例：

```bash
curl -X PATCH "{BACKEND_API_BASE_URL}/api/brands/00000000-0000-4000-8000-000000000101/notifications" \
  -H "Authorization: Bearer <sanctum_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "morningBriefHour": 9,
    "eveningRecapHour": 18,
    "pushMode": "daily_digest",
    "dailyReportHour": 9,
    "silentStartHour": 22,
    "silentEndHour": 8
  }'
```

响应参数：

| 字段                        | 类型      | 说明                 |
|---------------------------|---------|--------------------|
| `code`                    | integer | 成功为 `1`。           |
| `message`                 | string  | 成功为 `ok`。          |
| `data.morning_brief_hour` | integer | 更新后的早报小时，有实际更新时返回。 |
| `data.evening_recap_hour` | integer | 更新后的晚报小时，有实际更新时返回。 |
| `data.noop`               | boolean | 没有可写字段时返回 `true`。  |

错误：

| 响应 code | data.apiCode      | 说明                               |
|--------:|-------------------|----------------------------------|
|     400 | `invalid_payload` | 小时值不是整数、范围不在 0-23，或同一请求内早晚报小时相同。 |
|     404 | `not_found`       | 品牌不存在或不属于当前用户。                   |

### PATCH `/api/brands/{id}/telegram`

鉴权：Sanctum。

入参：

| 位置   | 字段       | 类型           | 必填 | 说明                                                |
|------|----------|--------------|----|---------------------------------------------------|
| path | `id`     | string       | 是  | 品牌 UUID。                                          |
| body | `chatId` | string\|null | 是  | Telegram chat id，必须匹配 `^-?\d{1,20}$`；传 null 表示解绑。 |

请求示例：

```bash
curl -X PATCH "{BACKEND_API_BASE_URL}/api/brands/00000000-0000-4000-8000-000000000101/telegram" \
  -H "Authorization: Bearer <sanctum_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "-1001234567890"
  }'
```

响应参数：

| 字段                    | 类型           | 说明                     |
|-----------------------|--------------|------------------------|
| `code`                | integer      | 成功为 `1`。               |
| `message`             | string       | 成功为 `ok`。              |
| `data.telegramChatId` | string\|null | 更新后的 Telegram chat id。 |

错误：

| 响应 code | data.apiCode      | 说明                |
|--------:|-------------------|-------------------|
|     400 | `invalid_payload` | `chatId` 缺失或格式错误。 |
|     404 | `not_found`       | 品牌不存在或不属于当前用户。    |

### POST `/api/brands/{id}/telegram/pair`

鉴权：Sanctum。

入参：

| 位置   | 字段   | 类型     | 必填 | 说明       |
|------|------|--------|----|----------|
| path | `id` | string | 是  | 品牌 UUID。 |

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/brands/00000000-0000-4000-8000-000000000101/telegram/pair" \
  -H "Authorization: Bearer <sanctum_token>"
```

响应参数：

| 字段                | 类型      | 说明                                              |
|-------------------|---------|-------------------------------------------------|
| `code`            | integer | 成功为 `1`。                                        |
| `message`         | string  | 成功为 `ok`。                                       |
| `data.token`      | string  | 一次性配对 token，格式 `pair_<36hex>`。                  |
| `data.expiresAt`  | string  | 过期时间。                                           |
| `data.deeplink`   | string  | Telegram `https://t.me/<bot>?start=<token>` 链接。 |
| `data.ttlSeconds` | integer | 固定 900 秒。                                       |

错误：

| 响应 code | data.apiCode    | 说明                        |
|--------:|-----------------|---------------------------|
|     404 | `not_found`     | 品牌不存在或不属于当前用户。            |
|     500 | `misconfigured` | 缺少 `TELEGRAM_BOT_HANDLE`。 |

### PATCH `/api/brands/{id}/thresholds`

鉴权：Sanctum。

入参：

| 位置   | 字段           | 类型     | 必填 | 说明                                |
|------|--------------|--------|----|-----------------------------------|
| path | `id`         | string | 是  | 品牌 UUID。                          |
| body | `thresholds` | object | 是  | 阈值覆盖对象；未知 key 会忽略；值为 null 表示移除覆盖。 |

请求示例：

```bash
curl -X PATCH "{BACKEND_API_BASE_URL}/api/brands/00000000-0000-4000-8000-000000000101/thresholds" \
  -H "Authorization: Bearer <sanctum_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "thresholds": {
      "SALES_01_GMV_DECLINE": 0.25,
      "SALES_01_MIN_ORDERS": 5,
      "SALES_02_ZERO_HOURS": 3,
      "SALES_04_DAYS_LEFT": 4,
      "SALES_05_RATING_MAX": 3,
      "AD_01_MIN_SPEND": 50,
      "AD_02_KEYWORD_SHARE": 0.5,
      "AD_03_ROAS_MIN": 2.5,
      "COMP_01_GAP": 0.12,
      "COMP_02_DROP": null
    }
  }'
```

允许的 `thresholds` key：

| key                    | 类型      | 范围       | 说明        |
|------------------------|---------|----------|-----------|
| `SALES_01_GMV_DECLINE` | number  | 0.1-0.5  | GMV 下降阈值。 |
| `SALES_01_MIN_ORDERS`  | integer | 3-20     | 最小订单数。    |
| `SALES_02_ZERO_HOURS`  | integer | 1-6      | 连续零单小时数。  |
| `SALES_04_DAYS_LEFT`   | integer | 1-7      | 库存剩余天数。   |
| `SALES_05_RATING_MAX`  | integer | 1-4      | 低评分上限。    |
| `AD_01_MIN_SPEND`      | integer | 10-200   | 广告最低花费。   |
| `AD_02_KEYWORD_SHARE`  | number  | 0.3-0.8  | 关键词花费占比。  |
| `AD_03_ROAS_MIN`       | number  | 1.5-5.0  | 最低 ROAS。  |
| `COMP_01_GAP`          | number  | 0.05-0.3 | 竞品价差阈值。   |
| `COMP_02_DROP`         | number  | 0.05-0.3 | 竞品降价阈值。   |

响应参数：

| 字段                | 类型      | 说明              |
|-------------------|---------|-----------------|
| `code`            | integer | 成功为 `1`。        |
| `message`         | string  | 成功为 `ok`。       |
| `data.thresholds` | object  | 合并保存后的品牌阈值覆盖对象。 |

错误：

| 响应 code | data.apiCode      | 说明                                            |
|--------:|-------------------|-----------------------------------------------|
|     400 | `invalid_payload` | `thresholds` 不是对象、值不是数字/null、整数 key 传小数或超出范围。 |
|     404 | `not_found`       | 品牌不存在或不属于当前用户。                                |

## 告警接口

### POST `/api/alerts/{id}/ack`

鉴权：Sanctum。

入参：

| 位置   | 字段    | 类型      | 必填 | 说明               |
|------|-------|---------|----|------------------|
| path | `id`  | string  | 是  | Alert UUID。      |
| body | `ack` | boolean | 否  | 是否确认；缺省为 `true`。 |

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/alerts/00000000-0000-4000-8000-000000000301/ack" \
  -H "Authorization: Bearer <sanctum_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ack": true
  }'
```

响应参数：

| 字段                  | 类型      | 说明          |
|---------------------|---------|-------------|
| `code`              | integer | 成功为 `1`。    |
| `message`           | string  | 成功为 `ok`。   |
| `data.id`           | string  | Alert UUID。 |
| `data.acknowledged` | boolean | 更新后的确认状态。   |

错误：

| 响应 code | data.apiCode      | 说明                   |
|--------:|-------------------|----------------------|
|     400 | `invalid_payload` | Alert id 不是 UUID。    |
|     404 | `not_found`       | Alert 不存在或不属于当前用户品牌。 |

## 扫描上传接口

### POST `/api/ingest/scan`

鉴权：扩展机器 token。
必需 header：`Authorization: Bearer <extension_sanctum_token>`、`X-Ext-Version`。

顶层入参：

| 位置   | 字段                  | 类型           | 必填 | 说明                                          |
|------|---------------------|--------------|----|---------------------------------------------|
| body | `brandId`           | string       | 是  | 品牌 UUID。                                    |
| body | `storeId`           | string       | 是  | 店铺 UUID。                                    |
| body | `scannedAt`         | string       | 是  | 扫描时间，可解析为 datetime。                         |
| body | `payload`           | object       | 是  | 扫描业务数据，见下方 schema。                          |
| body | `extractorStatus`   | string       | 是  | `ok`、`partial` 或 `failed`。                  |
| body | `extractorErrors`   | string[]     | 否  | 提取错误列表，最多 50 项，缺省 `[]`。                     |
| body | `trigger`           | string       | 否  | `manual` 或 `scheduled`，缺省 `manual`。         |
| body | `platformAccountId` | string\|null | 否  | Shopee seller id，1-64 字符；4 位以上纯数字才会参与绑定/比对。 |
| body | `fieldMeta`         | object       | 否  | 字段采集来源元数据，缺省 `{}`。                          |

`payload.today`：

| 字段                                    | 类型            | 必填 | 说明            |
|---------------------------------------|---------------|----|---------------|
| `orders`                              | integer       | 是  | 今日订单数，>=0。    |
| `gmv_cents`                           | integer       | 是  | 今日 GMV 分，>=0。 |
| `cancel_rate`                         | number        | 是  | 取消率，0-1。      |
| `return_rate`                         | number        | 是  | 退货率，0-1。      |
| `gmv_delta_yesterday_pct`             | number\|null  | 否  | GMV 较昨日变化比例。  |
| `gmv_net_cents`                       | integer\|null | 否  | 净 GMV 分，>=0。  |
| `conversion_rate`                     | number\|null  | 否  | 转化率。          |
| `visitors`                            | integer\|null | 否  | 访客数，>=0。      |
| `product_clicks`                      | integer\|null | 否  | 商品点击数，>=0。    |
| `aov_cents`                           | integer\|null | 否  | 客单价分，>=0。     |
| `orders_delta_yesterday_pct`          | number\|null  | 否  | 订单较昨日变化比例。    |
| `conversion_rate_delta_yesterday_pct` | number\|null  | 否  | 转化率较昨日变化比例。   |
| `visitors_delta_yesterday_pct`        | number\|null  | 否  | 访客较昨日变化比例。    |
| `product_clicks_delta_yesterday_pct`  | number\|null  | 否  | 商品点击较昨日变化比例。  |
| `aov_delta_yesterday_pct`             | number\|null  | 否  | 客单价较昨日变化比例。   |

`payload.skus[]`：

| 字段                 | 类型            | 必填 | 说明                                     |
|--------------------|---------------|----|----------------------------------------|
| `sku_id`           | string        | 是  | SKU id。                                |
| `name`             | string        | 是  | SKU 名称。                                |
| `price_cents`      | integer\|null | 否  | 价格分，>=0。                               |
| `l30d_sales`       | integer\|null | 否  | 近 30 天销量，>=0。                          |
| `l30d_impressions` | integer\|null | 否  | 近 30 天曝光，>=0。                          |
| `impressions`      | integer       | 是  | 曝光，>=0。                                |
| `clicks`           | integer       | 是  | 点击，>=0。                                |
| `add_to_cart`      | integer       | 是  | 加购，>=0。                                |
| `orders`           | integer       | 是  | 订单，>=0。                                |
| `gmv_cents`        | integer       | 是  | GMV 分，>=0。                             |
| `stock`            | integer       | 是  | 库存，>=0。                                |
| `status`           | string        | 是  | `on_sale`、`unlisted` 或 `out_of_stock`。 |

`payload.ads[]`：

| 字段                       | 类型            | 必填 | 说明                                           |
|--------------------------|---------------|----|----------------------------------------------|
| `campaign_id`            | string        | 是  | 广告活动 id。                                     |
| `campaign_name`          | string        | 是  | 广告活动名称。                                      |
| `type`                   | string        | 否  | 广告类型，缺省 `unknown`。                           |
| `state`                  | string        | 否  | `ongoing`、`paused` 或 `unknown`，缺省 `unknown`。 |
| `spend_cents`            | integer       | 是  | 花费分，>=0。                                     |
| `clicks`                 | integer       | 是  | 点击，>=0。                                      |
| `orders`                 | integer       | 是  | 订单，>=0。                                      |
| `revenue_cents`          | integer       | 是  | 收入分，>=0。                                     |
| `impressions`            | integer       | 否  | 曝光，>=0，缺省 0。                                 |
| `roas`                   | number        | 否  | ROAS，>=0，缺省 0。                               |
| `target_roas`            | number\|null  | 否  | 目标 ROAS，>=0。                                 |
| `daily_budget_cents`     | integer\|null | 否  | 日预算分，>=0。                                    |
| `keywords`               | array         | 是  | 关键词列表。                                       |
| `keywords[].keyword`     | string        | 是  | 关键词。                                         |
| `keywords[].spend_cents` | integer       | 是  | 关键词花费分，>=0。                                  |
| `keywords[].clicks`      | integer       | 是  | 关键词点击，>=0。                                   |
| `keywords[].orders`      | integer       | 是  | 关键词订单，>=0。                                   |

其他 `payload` 字段：

| 字段                   | 类型           | 必填 | 说明                                                                                                  |
|----------------------|--------------|----|-----------------------------------------------------------------------------------------------------|
| `store_id`           | string       | 是  | 店铺 UUID。                                                                                            |
| `scanned_at`         | string       | 是  | 扫描时间。                                                                                               |
| `recent_3h[]`        | array        | 是  | 元素 `{ hour:string, orders:integer>=0, gmv_cents:integer>=0 }`。                                      |
| `reviews[]`          | array        | 是  | 元素 `{ review_id, sku_id:null\|string, rating:1-5, text, replied:boolean, created_at }`。             |
| `competitors[]`      | array        | 是  | 元素 `{ product_url:url, price_cents:integer>=0, rating:null\|number 0-5, sold_label:null\|string }`。 |
| `review_summary`     | object\|null | 否  | 包含 `shop_rating`、`total_reviews_l30d`、`unanswered_negative`、`rating_histogram`。                     |
| `product_aggregates` | object\|null | 否  | 数值字典，值可为 number 或 null。                                                                             |
| `traffic_sources`    | array\|null  | 否  | 流量来源数组，含 source、sales、clicks、conversion 等字段。                                                        |
| `shop_health`        | object\|null | 否  | 店铺健康对象；传 null 表示本次未采集，传 object 时内部字段见下表。                                                            |

`payload.shop_health`：

| 字段                              | 类型            | 必填 | 说明                                                 |
|---------------------------------|---------------|----|----------------------------------------------------|
| `rating_overall`                | string\|null  | 是  | 店铺健康评级，允许 `excellent`、`good`、`fair`、`poor` 或 null。 |
| `penalty_points`                | integer\|null | 是  | 当前罚分，>=0，未知传 null。                                 |
| `penalty_threshold`             | integer\|null | 是  | 触发风险提示的罚分阈值，>=1，未知传 null。                          |
| `metrics`                       | object        | 是  | 健康指标字典，key 为指标名，value 见下方 `metrics.*`。             |
| `metrics.*.value`               | number\|null  | 是  | 指标当前值。                                             |
| `metrics.*.target`              | number\|null  | 是  | 指标目标值。                                             |
| `metrics.*.target_op`           | string\|null  | 是  | 达标比较符，允许 `lt`、`lte`、`gt`、`gte` 或 null。             |
| `metrics.*.counts_toward_score` | boolean       | 是  | 是否参与店铺健康评分。                                        |

`fieldMeta` 元素：

| 字段                | 类型     | 必填 | 说明                                                              |
|-------------------|--------|----|-----------------------------------------------------------------|
| `source`          | string | 是  | `fetch_hook`、`dom`、`json_ld`、`og_meta`、`aggregate` 或 `missing`。 |
| `selectorMatch`   | string | 否  | `primary`、`fallback` 或 `text_anchor`。                           |
| `shopeeDataStamp` | string | 否  | Shopee 数据戳。                                                     |
| `ageMinutes`      | number | 否  | 数据年龄分钟数。                                                        |

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/ingest/scan" \
  -H "Authorization: Bearer <extension_sanctum_token>" \
  -H "X-Ext-Version: 0.1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "00000000-0000-4000-8000-000000000101",
    "storeId": "00000000-0000-4000-8000-000000000102",
    "scannedAt": "2026-05-08T10:15:00Z",
    "extractorStatus": "ok",
    "extractorErrors": [],
    "trigger": "manual",
    "platformAccountId": "1234567890",
    "fieldMeta": {
      "today.orders": {
        "source": "fetch_hook",
        "selectorMatch": "primary",
        "shopeeDataStamp": "seller-center-v1",
        "ageMinutes": 2
      },
      "ads[0].spend_cents": {
        "source": "dom",
        "selectorMatch": "fallback",
        "ageMinutes": 5
      }
    },
    "payload": {
      "store_id": "00000000-0000-4000-8000-000000000102",
      "scanned_at": "2026-05-08T10:15:00Z",
      "today": {
        "orders": 18,
        "gmv_cents": 258000,
        "cancel_rate": 0.02,
        "return_rate": 0.01,
        "gmv_delta_yesterday_pct": -0.18,
        "gmv_net_cents": 252000,
        "conversion_rate": 0.042,
        "visitors": 1200,
        "product_clicks": 260,
        "aov_cents": 14333,
        "orders_delta_yesterday_pct": -0.12,
        "conversion_rate_delta_yesterday_pct": -0.08,
        "visitors_delta_yesterday_pct": 0.06,
        "product_clicks_delta_yesterday_pct": -0.03,
        "aov_delta_yesterday_pct": -0.04
      },
      "recent_3h": [
        { "hour": "2026-05-08T08:00:00Z", "orders": 3, "gmv_cents": 42000 },
        { "hour": "2026-05-08T09:00:00Z", "orders": 0, "gmv_cents": 0 },
        { "hour": "2026-05-08T10:00:00Z", "orders": 1, "gmv_cents": 12000 }
      ],
      "skus": [
        {
          "sku_id": "SKU-001",
          "name": "Hydrating Serum 30ml",
          "price_cents": 6900,
          "l30d_sales": 180,
          "l30d_impressions": 12000,
          "impressions": 2800,
          "clicks": 210,
          "add_to_cart": 36,
          "orders": 12,
          "gmv_cents": 82800,
          "stock": 24,
          "status": "on_sale"
        }
      ],
      "ads": [
        {
          "campaign_id": "AD-001",
          "campaign_name": "Hero SKU Search Ads",
          "type": "search",
          "state": "ongoing",
          "spend_cents": 4200,
          "clicks": 96,
          "orders": 5,
          "revenue_cents": 34500,
          "impressions": 3600,
          "roas": 8.21,
          "target_roas": 5,
          "daily_budget_cents": 10000,
          "keywords": [
            { "keyword": "serum", "spend_cents": 1600, "clicks": 36, "orders": 1 },
            { "keyword": "hydrating serum", "spend_cents": 2600, "clicks": 60, "orders": 4 }
          ]
        }
      ],
      "reviews": [
        {
          "review_id": "REV-001",
          "sku_id": "SKU-001",
          "rating": 2,
          "text": "Bottle leaked during shipping",
          "replied": false,
          "created_at": "2026-05-08T04:00:00Z"
        }
      ],
      "competitors": [
        {
          "product_url": "https://shopee.com.my/example-product-i.123456.987654321",
          "price_cents": 6200,
          "rating": 4.8,
          "sold_label": "1.2k sold"
        }
      ],
      "review_summary": {
        "shop_rating": 4.7,
        "total_reviews_l30d": 42,
        "unanswered_negative": 3,
        "rating_histogram": { "1": 1, "2": 2, "3": 4, "4": 12, "5": 23 }
      },
      "product_aggregates": {
        "avg_price_cents": 7200,
        "active_sku_count": 18,
        "out_of_stock_count": 2
      },
      "traffic_sources": [
        {
          "source": "search",
          "sales": 12,
          "clicks": 180,
          "conversion_rate": 0.066,
          "gmv_cents": 168000
        }
      ],
      "shop_health": {
        "rating_overall": "good",
        "penalty_points": 0,
        "penalty_threshold": 3,
        "metrics": {
          "late_shipment_rate": {
            "value": 0.01,
            "target": 0.03,
            "target_op": "lte",
            "counts_toward_score": true
          },
          "chat_response_rate": {
            "value": 0.92,
            "target": 0.85,
            "target_op": "gte",
            "counts_toward_score": true
          }
        }
      }
    }
  }'
```

响应参数：

| 字段                   | 类型      | 说明                  |
|----------------------|---------|---------------------|
| `code`               | integer | 成功为 `1`。            |
| `message`            | string  | 成功为 `ok`。           |
| `data.scanId`        | string  | 新 scan UUID。        |
| `data.alertsEmitted` | integer | 本次规则引擎产生的 alert 数量。 |

错误：

| 响应 code | data.apiCode                | 说明                                        |
|--------:|-----------------------------|-------------------------------------------|
|     400 | `invalid_payload`           | JSON 非法或 schema 校验失败。                     |
|     401 | `unauthorized`              | 扩展 token 缺失或无效。                           |
|     402 | `subscription_required`     | 当前订阅状态不允许扫描。                              |
|     403 | `brand_mismatch`            | 品牌不属于 token 账号，或店铺不属于品牌。                  |
|     409 | `platform_account_mismatch` | 当前 Shopee seller id 与品牌已绑定 seller id 不一致。 |
|     426 | `ext_outdated`              | 扩展版本过旧。                                   |
|     429 | `rate_limited`              | 手动扫描达到每日上限。                               |

备注：成功后会写入 scans、SKU/ad/competitor snapshots，执行规则告警和 AI 派生数据生成；手动扫描会尝试发送 Telegram
回声，scheduled 扫描会尝试补发 catch-up brief。

## Cron 定时报表接口

### GET|POST `/api/cron/scheduled-report`

鉴权：Cron secret。生产环境要求 `CRON_SECRET` 已配置并通过 `Authorization: Bearer <CRON_SECRET>` 传入。非生产环境未配置
secret 时开放。

入参：无。

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/cron/scheduled-report" \
  -H "Authorization: Bearer <CRON_SECRET>"
```

响应参数：

| 字段                                   | 类型      | 说明                        |
|--------------------------------------|---------|---------------------------|
| `code`                               | integer | 成功为 `1`。                  |
| `message`                            | string  | 成功为 `ok`。                 |
| `data.runAt`                         | string  | 本次 cron UTC 执行时间。         |
| `data.report.scannedBrands`          | integer | 扫描的品牌数量。                  |
| `data.report.fired`                  | integer | 实际发送报表数量。                 |
| `data.report.skipped.wrong_hour`     | integer | 未到品牌本地发送窗口数量。             |
| `data.report.skipped.cooldown`       | integer | 仍在 22 小时冷却期或并发抢占失败数量。     |
| `data.report.skipped.no_channel`     | integer | 无 Telegram/WhatsApp 渠道数量。 |
| `data.report.skipped.no_store`       | integer | 无店铺数量。                    |
| `data.report.skipped.invalid_config` | integer | 报表小时配置非法数量。               |
| `data.report.errors`                 | integer | 单品牌处理异常数量。                |
| `data.trialReport.scanned`           | integer | 扫描试用到期提醒的品牌数量。            |
| `data.trialReport.sent4h`            | integer | 发送 4 小时试用提醒数量。            |
| `data.trialReport.sent1h`            | integer | 发送 1 小时试用提醒数量。            |
| `data.trialReport.errors`            | integer | 试用提醒异常数量。                 |

错误：

| 响应 code | data.apiCode    | 说明                     |
|--------:|-----------------|------------------------|
|     401 | `unauthorized`  | Cron secret 不匹配。       |
|     503 | `misconfigured` | 生产环境未配置 `CRON_SECRET`。 |

备注：服务端按品牌本地 `morning_brief_hour` / `evening_recap_hour` 判断发送窗口，并使用 `last_morning_brief_at` /
`last_evening_recap_at` 做跨入口防重复。

### GET `/api/cron/daily-digest`

鉴权：同 `/api/cron/scheduled-report`。

入参：无。

请求示例：

```bash
curl -X GET "{BACKEND_API_BASE_URL}/api/cron/daily-digest" \
  -H "Authorization: Bearer <CRON_SECRET>"
```

响应参数：完全复用 `/api/cron/scheduled-report`。

备注：这是旧 daily digest URL 的兼容入口，当前直接复用 twice-daily scheduled-report 业务服务。

## Stripe 接口

### POST `/api/stripe/checkout`

鉴权：Sanctum。

入参：

| 位置     | 字段                  | 类型     | 必填   | 说明                                                      |
|--------|---------------------|--------|------|---------------------------------------------------------|
| body   | `agreement_version` | string | 条件必填 | 当前品牌首次订阅且尚未接受 SaaS 协议时必填，必须等于 `SAAS_AGREEMENT_VERSION`。 |
| header | `x-forwarded-for`   | string | 否    | 审计 IP，优先取第一段。                                           |
| header | `User-Agent`        | string | 否    | 协议接受审计 UA，最多保存 500 字符。                                  |

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/stripe/checkout" \
  -H "Authorization: Bearer <sanctum_token>" \
  -H "Content-Type: application/json" \
  -H "x-forwarded-for: 203.0.113.10, 10.0.0.1" \
  -H "User-Agent: StoreAI Web/1.0" \
  -d '{
    "agreement_version": "2"
  }'
```

响应参数：

| 字段         | 类型      | 说明                   |
|------------|---------|----------------------|
| `code`     | integer | 成功为 `1`。             |
| `message`  | string  | 成功为 `ok`。            |
| `data.url` | string  | Stripe Checkout URL。 |

错误：

| 响应 code | data.apiCode         | 说明                     |
|--------:|----------------------|------------------------|
|     400 | `no_brand`           | 当前账号没有品牌。              |
|     400 | `agreement_required` | 首次订阅缺少协议版本。            |
|     409 | `agreement_stale`    | 协议版本不是当前版本。            |
|     500 | `config_error`       | 缺少 Stripe price id 配置。 |
|     500 | `stripe_error`       | Stripe API 调用失败。       |
|     500 | `server_error`       | Stripe 未返回 URL。        |

### POST `/api/stripe/portal`

鉴权：Sanctum。

入参：无。

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/stripe/portal" \
  -H "Authorization: Bearer <sanctum_token>"
```

响应参数：

| 字段         | 类型      | 说明                         |
|------------|---------|----------------------------|
| `code`     | integer | 成功为 `1`。                   |
| `message`  | string  | 成功为 `ok`。                  |
| `data.url` | string  | Stripe Billing Portal URL。 |

错误：

| 响应 code | data.apiCode   | 说明                         |
|--------:|----------------|----------------------------|
|     400 | `no_customer`  | 当前品牌没有 Stripe customer id。 |
|     500 | `stripe_error` | Stripe API 调用失败。           |
|     500 | `server_error` | Stripe 未返回 URL。            |

### POST `/api/stripe/webhook`

鉴权：Stripe 签名。请求必须保留 Stripe 原始 body。

入参：

| 位置       | 字段                 | 类型     | 必填 | 说明                 |
|----------|--------------------|--------|----|--------------------|
| header   | `Stripe-Signature` | string | 是  | Stripe webhook 签名。 |
| raw body | event              | object | 是  | Stripe event JSON。 |

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/stripe/webhook" \
  -H "Stripe-Signature: t=1715150000,v1=<stripe_signature>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "evt_123",
    "type": "checkout.session.completed",
    "data": {
      "object": {
        "id": "cs_test_123",
        "customer": "cus_123",
        "metadata": {
          "brand_id": "00000000-0000-4000-8000-000000000101"
        },
        "subscription": "sub_123"
      }
    }
  }'
```

支持事件：

| 事件                                                 | 处理                                         |
|----------------------------------------------------|--------------------------------------------|
| `checkout.session.completed`                       | 写回品牌 `stripe_customer_id`。                 |
| `customer.subscription.created`                    | 更新订阅状态、subscription id、customer id、预约取消时间。 |
| `customer.subscription.updated`                    | 同上；首次进入 `past_due` 会尝试 Telegram 提醒。        |
| `customer.subscription.deleted`                    | 标记 canceled，清空 subscription id 和预约取消时间。    |
| `charge.dispute.created`                           | 写入 dispute 审计，尝试通知管理员 Telegram。            |
| `charge.dispute.updated` / `charge.dispute.closed` | 更新 dispute 状态。                             |

响应参数：

| 字段              | 类型      | 说明                    |
|-----------------|---------|-----------------------|
| `code`          | integer | 成功为 `1`。              |
| `message`       | string  | 成功为 `ok`。             |
| `data.received` | string  | 已处理事件类型。              |
| `data.deduped`  | boolean | 重复已完成事件返回 `true`。     |
| `data.eventId`  | string  | 被去重的 Stripe event id。 |

错误：

| 响应 code | data.apiCode        | 说明                                               |
|--------:|---------------------|--------------------------------------------------|
|     400 | `missing_signature` | 缺少 `Stripe-Signature`。                           |
|     400 | `bad_signature`     | 签名校验失败、webhook secret 缺失或 body 非法。               |
|     500 | `handler_error`     | handler 异常，HTTP 仍返回 200；后端记录 failed 审计行，响应体表达失败。 |

## Telegram 接口

### POST `/api/telegram/webhook`

鉴权：Telegram webhook secret。

入参：

| 位置     | 字段                                | 类型      | 必填   | 说明                                |
|--------|-----------------------------------|---------|------|-----------------------------------|
| header | `X-Telegram-Bot-Api-Secret-Token` | string  | 是    | 必须等于后端 `TELEGRAM_WEBHOOK_SECRET`。 |
| body   | `message.chat.id`                 | integer | 条件必填 | Telegram chat id；无 chat id 会忽略。   |
| body   | `message.text`                    | string  | 条件必填 | 配对命令，格式 `/start pair_<hex>`。      |
| body   | `message.from.first_name`         | string  | 否    | 成功提示中使用。                          |

请求示例：

```bash
curl -X POST "{BACKEND_API_BASE_URL}/api/telegram/webhook" \
  -H "X-Telegram-Bot-Api-Secret-Token: <TELEGRAM_WEBHOOK_SECRET>" \
  -H "Content-Type: application/json" \
  -d '{
    "update_id": 100001,
    "message": {
      "message_id": 10,
      "text": "/start pair_1234567890abcdef1234567890abcdef1234",
      "chat": {
        "id": -1001234567890,
        "type": "group",
        "title": "StoreAI Alerts"
      },
      "from": {
        "id": 123456,
        "first_name": "Owner"
      }
    }
  }'
```

响应参数：

| 字段             | 类型      | 说明                                                                                                      |
|----------------|---------|---------------------------------------------------------------------------------------------------------|
| `code`         | integer | 成功为 `1`。                                                                                                |
| `message`      | string  | 成功为 `ok`。                                                                                               |
| `data.brandId` | string  | 成功消费配对 token 后返回品牌 UUID。                                                                                |
| `data.ignored` | string  | 非配对或无法消费时返回原因：`no_chat_id`、`not_pair_command`、`unknown_token`、`already_consumed`、`expired`、`race_lost`。 |

错误：

| 响应 code | data.apiCode      | 说明                             |
|--------:|-------------------|--------------------------------|
|     400 | `invalid_payload` | 请求体不是合法 JSON。                  |
|     401 | `unauthorized`    | Secret header 不匹配。             |
|     503 | `misconfigured`   | 后端未配置 Telegram webhook secret。 |

## Debug 接口

Debug 路由默认关闭。必须配置 `ENABLE_DEBUG_ROUTES=true` 后才可访问；关闭时返回 404
`{ "code":0, "message":"Not found.", "data": { "error":"not_found" } }`。开启后仍要求 Sanctum 鉴权。

### GET `/api/debug/last-scan`

鉴权：Debug 门禁 + Sanctum。

入参：无。

请求示例：

```bash
curl -X GET "{BACKEND_API_BASE_URL}/api/debug/last-scan" \
  -H "Authorization: Bearer <sanctum_token>"
```

响应参数：

| 字段                            | 类型           | 说明                                                                                      |
|-------------------------------|--------------|-----------------------------------------------------------------------------------------|
| `code`                        | integer      | 成功为 `1`。                                                                                |
| `message`                     | string       | 成功为 `ok`。                                                                               |
| `data.diagnosis`              | string       | 无品牌、无店铺、无扫描等状态下返回，例如 `no_brand`、`no_store`、`no_scans`。                                  |
| `data.message`                | string       | 诊断说明。                                                                                   |
| `data.brand`                  | object       | 品牌摘要，含时区、报表小时、Telegram 是否存在。                                                            |
| `data.latest_scan`            | object       | 最新 scan 摘要 `{ id, scanned_at, status, error }`。                                         |
| `data.field_presence`         | object\|null | payload 关键字段是否存在的统计。                                                                    |
| `data.audit_dump`             | object\|null | 最近 scan 的 today、商品、广告、竞品等排障摘录。                                                          |
| `data.latest_store_brief`     | object\|null | 最近 scan 的 AI brief 原始摘要。                                                                |
| `data.sku_matrix`             | object\|null | 最近 SKU Matrix，含 `computed_for`、`generated_at`、`confidence`、`quadrant_counts`、`entries`。 |
| `data.history_depth`          | object       | 历史 scan 深度统计。                                                                           |
| `data.competitor_diag`        | object       | 竞品配置和最近 10 次 scan 竞品字段统计。                                                               |
| `data.rules_dry_run`          | object\|null | 规则引擎只读 dry-run 结果。                                                                      |
| `data.ai`                     | object       | AI provider 与 key 存在性诊断，不返回真实 key。                                                      |
| `data.live_verdict_reattempt` | object       | 只读 AI verdict 重试结果。                                                                     |
| `data.live_growth_reattempt`  | object       | 只读 AI growth 重试结果。                                                                      |
| `data.diagnostics`            | string[]     | 额外排障建议。                                                                                 |

错误：

| 响应 code | data.apiCode   | 说明           |
|--------:|----------------|--------------|
|     401 | `unauthorized` | 未登录。         |
|     404 | `not_found`    | Debug 门禁未开启。 |

备注：该接口只读，不写 `alerts`、`store_briefs`、`sku_matrix` 或业务表。

### GET `/api/debug/test-verdict`

鉴权：Debug 门禁 + Sanctum。

入参：无。

请求示例：

```bash
curl -X GET "{BACKEND_API_BASE_URL}/api/debug/test-verdict" \
  -H "Authorization: Bearer <sanctum_token>"
```

响应参数：

| 字段                                | 类型           | 说明                                                                                 |
|-----------------------------------|--------------|------------------------------------------------------------------------------------|
| `code`                            | integer      | 成功为 `1`。                                                                           |
| `message`                         | string       | 成功为 `ok`。                                                                          |
| `data.diagnosis`                  | string       | 诊断失败原因：`no_store`、`no_scan_payload`、`no_api_key`、`unsupported_provider_for_debug`。 |
| `data.provider`                   | string       | 当前 `DIAGNOSIS_PROVIDER`。                                                           |
| `data.model`                      | string       | 实际请求 DeepSeek 的模型；`deepseek-v4-flash`、`deepseek-reasoner` 会改写为 `deepseek-chat`。    |
| `data.api_key_length`             | integer      | API key 长度，不返回真实 key。                                                              |
| `data.request.endpoint`           | string       | DeepSeek endpoint。                                                                 |
| `data.request.tool_name`          | string       | 固定 `emit_verdict`。                                                                 |
| `data.request.user_prompt_chars`  | integer      | prompt 字符数。                                                                        |
| `data.response.http_status`       | integer      | DeepSeek HTTP 状态码。                                                                 |
| `data.response.duration_ms`       | integer      | 请求耗时毫秒。                                                                            |
| `data.response.network_error`     | string\|null | 网络异常摘要。                                                                            |
| `data.response.body_preview`      | string       | 响应前 2000 字符。                                                                       |
| `data.response.body_json_present` | boolean      | 响应是否可解析为 JSON。                                                                     |
| `data.tool_call_summary`          | object\|null | tool call 摘要，含 finish reason、tool name、raw args、usage 等。                           |

错误：

| 响应 code | data.apiCode   | 说明           |
|--------:|----------------|--------------|
|     401 | `unauthorized` | 未登录。         |
|     404 | `not_found`    | Debug 门禁未开启。 |

备注：该接口只支持 DeepSeek wire format 诊断；Anthropic provider 请使用 `/api/debug/last-scan` 查看 provider 包装层诊断。