feat(chat): add promotional external entry flow

docs/external-entry.md

@@ -0,0 +1,62 @@
+# 外部应用入口
+
+外部应用统一通过以下地址进入本应用：
+
+```text
+https://<APP_HOST>/external-entry
+```
+
+入口会先保存传入的身份数据，再使用 `replace` 跳转到目标页面并清理地址栏中的参数。
+
+## 参数
+
+| 参数 | 必填 | 可选值 | 说明 |
+| --- | --- | --- | --- |
+| `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 | 用户头像地址。 |
+| `mode` | 否 | `promotion` | 设置为 `promotion` 时尝试开启聊天促销模式。 |
+| `promotion_type` | 促销模式必填 | `voice`、`image`、`private` | 指定促销锁消息类型。 |
+
+参数名称只接受表格中的规范写法，不兼容 camelCase、旧 Facebook 字段名、`redirect`、`next` 或其他目标别名。
+
+## 普通入口
+
+进入聊天：
+
+```text
+https://<APP_HOST>/external-entry?target=chat&asid=<ASID>&psid=<PSID>
+```
+
+进入打赏页面：
+
+```text
+https://<APP_HOST>/external-entry?target=tip
+```
+
+进入私密空间：
+
+```text
+https://<APP_HOST>/external-entry?target=private-room
+```
+
+## 促销入口
+
+促销模式只在 `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。
+- `promotion_type` 非法时按普通聊天入口处理，不展示促销消息。
+- 不支持任意 URL 跳转；无效 `target` 固定回退到聊天页。