# 外部应用入口

外部应用统一通过以下地址进入本应用：

```text
https://<APP_HOST>/external-entry
```

入口会先保存传入的身份数据，再使用 `replace` 跳转到目标页面。身份参数和入口控制参数会从地址栏中移除；目标页面自身需要的状态参数会保留，例如打赏页的 `coffee_type`。

如果进入时已经是 Email、Google 或 Facebook 正式登录用户，并且携带 ASID 或 PSID，入口会额外调用一次 Facebook Identity 绑定接口。普通启动、刷新、Guest 和未登录状态不会调用绑定接口，绑定失败也不会阻止目标页面跳转。

## 参数

| 参数 | 必填 | 可选值 | 说明 |
| --- | --- | --- | --- |
| `target` | 否 | `chat`、`tip`、`private-room` | 最终页面，缺失或无效时进入 `chat`。 |
| `device_id` | 否 | string | 外部设备 ID。 |
| `asid` | 否 | string | Facebook App-scoped User ID。 |
| `psid` | 否 | string | Facebook Page-scoped User ID。 |
| `avatar_url` | 否 | URL string | 用户头像地址。 |
| `coffee_type` | 打赏入口可选 | `small`、`medium`、`large` | `target=tip` 时指定咖啡档位，缺失或非法时默认为 `small`。 |
| `mode` | 否 | `promotion` | 设置为 `promotion` 时尝试开启聊天促销模式。 |
| `promotion_type` | 促销模式必填 | `voice`、`image`、`private` | 指定促销锁消息类型。 |

参数名称只接受表格中的规范写法，不兼容 camelCase、旧 Facebook 字段名、`redirect`、`next` 或其他目标别名。

## 普通入口

进入聊天：

```text
https://<APP_HOST>/external-entry?target=chat&asid=<ASID>&psid=<PSID>
```

进入打赏页面（默认 Small Coffee）：

```text
https://<APP_HOST>/external-entry?target=tip
```

入口会跳转到规范地址：

```text
https://<APP_HOST>/tip?coffee_type=small
```

进入私密空间：

```text
https://<APP_HOST>/external-entry?target=private-room
```

## 咖啡打赏入口

打赏入口支持三种咖啡档位：

| `coffee_type` | 展示名称 | 价格 | 后端套餐 `planId` |
| --- | --- | --- | --- |
| `small` | Small Coffee | US$4.99 | `tip_coffee_small` |
| `medium` | Medium Coffee | US$9.99 | `tip_coffee_medium` |
| `large` | Large Coffee | US$19.99 | `tip_coffee_large` |

分别进入三种咖啡打赏页面：

```text
https://<APP_HOST>/external-entry?target=tip&coffee_type=small
https://<APP_HOST>/external-entry?target=tip&coffee_type=medium
https://<APP_HOST>/external-entry?target=tip&coffee_type=large
```

外部入口会将它们规范化为 `/tip?coffee_type=<type>`。`coffee_type` 会在登录、Stripe 回跳和 Ezpay 回跳期间保留，确保支付流程始终使用最初选择的咖啡档位。

实际创建订单时，前端只使用对应 `planId` 的后端套餐；Small 额外兼容旧套餐 `tip_coffee`。最终支付金额以后端返回的套餐数据为准，若找不到对应套餐，页面会禁止下单，避免使用错误档位。

## 促销入口

促销模式只在 `target=chat` 时生效，并且 `mode` 与 `promotion_type` 必须同时有效：

```text
https://<APP_HOST>/external-entry?target=chat&mode=promotion&promotion_type=voice&asid=<ASID>&psid=<PSID>
```

进入聊天后，正常历史仍会加载，列表底部会额外展示一条对应类型的锁定促销消息。消息首次解锁使用前端生成的 `clientLockId`，真实内容、积分价格和后端 `messageId` 均由 `/api/chat/unlock-private` 返回。

促销入口只消费一次。普通刷新或主动离开聊天页后不会再次注入；登录或充值回跳会继续恢复当前解锁流程。

## 接入要求

- 所有参数必须使用 URL 编码，尤其是 `avatar_url`。
- 不要通过入口传递登录 token、Page Access Token 或 App Secret。
- `coffee_type` 仅在 `target=tip` 时生效；缺失或非法时使用 `small`。
- `promotion_type` 非法时按普通聊天入口处理，不展示促销消息。
- 不支持任意 URL 跳转；无效 `target` 固定回退到聊天页。