refactor(docs): streamline external entry documentation and update links

docs/external-entry-links.md

@@ -1,43 +1,29 @@
 # 外部入口链接清单
 
-以下链接可以直接点击打开，用于验证聊天、促销模式、咖啡打赏和私密空间入口。
+以下链接可以直接点击打开。PSID 示例统一使用 `27511427698460020`。
 
 ## 测试环境
 
-APP HOST：`frontend-test.banlv-ai.com`
+| 入口 | 链接 |
-
+| --- | --- |
-| 模式 | `mode` | `promotion_type` | 链接 |
+| 普通聊天 | [打开普通聊天](https://frontend-test.banlv-ai.com/external-entry?target=chat) |
-| --- | --- | --- | --- |
+| 携带 PSID 的聊天 | [打开 PSID 聊天示例](https://frontend-test.banlv-ai.com/external-entry?target=chat&psid=27511427698460020) |
-| 普通聊天 | 不传 | 不传 | [打开普通聊天](https://frontend-test.banlv-ai.com/external-entry?target=chat) |
+| 语音促销 | [打开语音促销](https://frontend-test.banlv-ai.com/external-entry?target=chat&mode=promotion&promotion_type=voice) |
-| 语音促销 | `promotion` | `voice` | [打开语音促销](https://frontend-test.banlv-ai.com/external-entry?target=chat&mode=promotion&promotion_type=voice) |
+| 图片促销 | [打开图片促销](https://frontend-test.banlv-ai.com/external-entry?target=chat&mode=promotion&promotion_type=image) |
-| 图片促销 | `promotion` | `image` | [打开图片促销](https://frontend-test.banlv-ai.com/external-entry?target=chat&mode=promotion&promotion_type=image) |
+| 私密文本促销 | [打开私密文本促销](https://frontend-test.banlv-ai.com/external-entry?target=chat&mode=promotion&promotion_type=private) |
-| 私密文本促销 | `promotion` | `private` | [打开私密文本促销](https://frontend-test.banlv-ai.com/external-entry?target=chat&mode=promotion&promotion_type=private) |
+| 咖啡打赏 | [打开咖啡打赏](https://frontend-test.banlv-ai.com/external-entry?target=tip) |
-
+| 私密空间 | [打开私密空间](https://frontend-test.banlv-ai.com/external-entry?target=private-room) |
-### 咖啡打赏
-
-[打开咖啡打赏档位选择页](https://frontend-test.banlv-ai.com/external-entry?target=tip)
-
-### 私密空间
-
-[打开私密空间](https://frontend-test.banlv-ai.com/external-entry?target=private-room)
 
 ## 正式环境
 
-APP HOST：`cozsweet.com`
+| 入口 | 链接 |
+| --- | --- |
+| 普通聊天 | [打开普通聊天](https://cozsweet.com/external-entry?target=chat) |
+| 携带 PSID 的聊天 | [打开 PSID 聊天示例](https://cozsweet.com/external-entry?target=chat&psid=27511427698460020) |
+| 语音促销 | [打开语音促销](https://cozsweet.com/external-entry?target=chat&mode=promotion&promotion_type=voice) |
+| 图片促销 | [打开图片促销](https://cozsweet.com/external-entry?target=chat&mode=promotion&promotion_type=image) |
+| 私密文本促销 | [打开私密文本促销](https://cozsweet.com/external-entry?target=chat&mode=promotion&promotion_type=private) |
+| 咖啡打赏 | [打开咖啡打赏](https://cozsweet.com/external-entry?target=tip) |
+| 私密空间 | [打开私密空间](https://cozsweet.com/external-entry?target=private-room) |
 
-| 模式 | `mode` | `promotion_type` | 链接 |
+如需在其他入口携带 PSID，在链接末尾追加 `&psid=27511427698460020`。
-| --- | --- | --- | --- |
-| 普通聊天 | 不传 | 不传 | [打开普通聊天](https://cozsweet.com/external-entry?target=chat) |
-| 语音促销 | `promotion` | `voice` | [打开语音促销](https://cozsweet.com/external-entry?target=chat&mode=promotion&promotion_type=voice) |
-| 图片促销 | `promotion` | `image` | [打开图片促销](https://cozsweet.com/external-entry?target=chat&mode=promotion&promotion_type=image) |
-| 私密文本促销 | `promotion` | `private` | [打开私密文本促销](https://cozsweet.com/external-entry?target=chat&mode=promotion&promotion_type=private) |
-
-### 咖啡打赏
-
-[打开咖啡打赏档位选择页](https://cozsweet.com/external-entry?target=tip)
-
-### 私密空间
-
-[打开私密空间](https://cozsweet.com/external-entry?target=private-room)
-
-如需传递 Facebook 身份信息，可在任一链接末尾追加 `&psid=<PSID>`。PSID 为可选参数。

docs/external-entry.md

@@ -1,88 +1,75 @@
-# 外部应用入口
+# 外部入口接入说明
 
-外部应用统一通过 `/external-entry` 进入本应用。当前 APP HOST：
+外部应用通过 `/external-entry` 进入本应用。
 
 | 环境 | APP HOST |
 | --- | --- |
 | 测试环境 | `frontend-test.banlv-ai.com` |
 | 正式环境 | `cozsweet.com` |
 
-普通模式和促销模式的可点击链接统一维护在 [外部入口链接清单](./external-entry-links.md)。
+入口格式：
-
-入口会先保存传入的身份数据，再使用 `replace` 跳转到目标页面。身份参数和入口控制参数会从地址栏中移除。
-
-如果进入时已经是 Email、Google 或 Facebook 正式登录用户，并且携带 PSID，入口会额外调用一次 Facebook Identity 绑定接口。普通启动、刷新、Guest 和未登录状态不会调用绑定接口，绑定失败也不会阻止目标页面跳转。
-
-## 参数
-
-| 参数 | 必填 | 可选值 | 说明 |
-| --- | --- | --- | --- |
-| `target` | 否 | `chat`、`tip`、`private-room` | 最终页面，缺失或无效时进入 `chat`。 |
-| `psid` | 否 | string | Facebook Page-scoped User ID。 |
-| `mode` | 否 | `promotion` | 设置为 `promotion` 时尝试开启聊天促销模式。 |
-| `promotion_type` | 促销模式必填 | `voice`、`image`、`private` | 指定促销锁消息类型。 |
-
-对外接入应使用表格中的公开参数及规范写法，不兼容 camelCase、旧 Facebook 字段名、`redirect`、`next` 或其他目标别名。
-
-## 普通入口
-
-下述为链接格式。测试环境和正式环境的可点击链接见 [外部入口链接清单](./external-entry-links.md)。
-
-进入聊天：
 
 ```text
-https://<APP_HOST>/external-entry?target=chat&psid=<PSID>
+https://<APP_HOST>/external-entry?<参数>
 ```
 
-进入打赏页面：
+## 可选参数
+
+所有参数均为可选参数。
+
+| 参数 | 可选值或格式 | 用途 |
+| --- | --- | --- |
+| `target` | `chat`、`tip`、`private-room` | 指定进入的页面；不传或值无效时进入聊天页。 |
+| `psid` | string | 传入 Facebook Page-scoped User ID。 |
+| `mode` | `promotion` | 开启聊天促销模式。 |
+| `promotion_type` | `voice`、`image`、`private` | 指定促销消息类型，仅与 `mode=promotion` 一起使用。 |
+
+`mode=promotion` 只有在 `target=chat` 且同时提供有效的 `promotion_type` 时生效。
+
+## 使用示例
+
+普通聊天：
+
+```text
+https://<APP_HOST>/external-entry?target=chat
+```
+
+携带 PSID 进入聊天，示例 PSID 为 `27511427698460020`：
+
+```text
+https://<APP_HOST>/external-entry?target=chat&psid=27511427698460020
+```
+
+语音促销聊天：
+
+```text
+https://<APP_HOST>/external-entry?target=chat&mode=promotion&promotion_type=voice
+```
+
+图片促销聊天：
+
+```text
+https://<APP_HOST>/external-entry?target=chat&mode=promotion&promotion_type=image
+```
+
+私密文本促销聊天：
+
+```text
+https://<APP_HOST>/external-entry?target=chat&mode=promotion&promotion_type=private
+```
+
+咖啡打赏：
 
 ```text
 https://<APP_HOST>/external-entry?target=tip
 ```
 
-入口会跳转到规范地址，并在页面内默认选择 Medium 档位：
+私密空间：
-
-```text
-https://<APP_HOST>/tip
-```
-
-进入私密空间：
 
 ```text
 https://<APP_HOST>/external-entry?target=private-room
 ```
 
-## 咖啡打赏入口
+`psid` 可以与任意 `target` 或聊天促销参数组合使用。参数值需要进行 URL 编码，不要在入口中传递登录 Token、Page Access Token 或 App Secret。
 
-打赏页同时展示三种咖啡档位，由用户进入页面后选择：
+测试环境和正式环境的完整可点击示例见 [外部入口链接清单](./external-entry-links.md)。
-
-| 档位 | 展示名称 | 价格 | 后端套餐 `planId` |
-| --- | --- | --- | --- |
-| Small | Velvet Espresso | US$4.99 | `tip_coffee_usd_4_99` |
-| Medium（默认） | Golden Reserve | US$9.99 | `tip_coffee_usd_9_99` |
-| Large | Imperial Grand Cru | US$19.99 | `tip_coffee_usd_19_99` |
-
-外部应用只需使用统一入口：
-
-```text
-https://<APP_HOST>/external-entry?target=tip
-```
-
-咖啡档位不再由外部入口指定。用户选择后，前端会在登录、Stripe 和 Ezpay 回跳期间恢复当前档位。
-
-实际创建订单时，前端通过 `/api/payment/tip-plans` 获取套餐，并只使用接口返回的对应 `planId`。最终支付金额以后端返回的套餐数据为准，若找不到对应套餐，页面会禁止下单，避免使用错误档位。
-
-## 促销入口
-
-促销模式只在 `target=chat` 时生效，并且 `mode` 与 `promotion_type` 必须同时有效。所有有效组合及其测试、正式环境链接见 [外部入口链接清单](./external-entry-links.md)。
-
-进入聊天后，正常历史仍会加载，列表底部会额外展示一条对应类型的锁定促销消息。消息首次解锁使用前端生成的 `clientLockId`，真实内容、积分价格和后端 `messageId` 均由 `/api/chat/unlock-private` 返回。
-
-促销入口只消费一次。普通刷新或主动离开聊天页后不会再次注入；登录或充值回跳会继续恢复当前解锁流程。
-
-## 接入要求
-
-- 所有参数值必须使用 URL 编码。
-- 不要通过入口传递登录 token、Page Access Token 或 App Secret。
-- `promotion_type` 非法时按普通聊天入口处理，不展示促销消息。
-- 不支持任意 URL 跳转；无效 `target` 固定回退到聊天页。

scripts/tools/new.sh

@@ -1,5 +0,0 @@
-PAGE_ID="122111097783118257"
-PAGE_ACCESS_TOKEN="EAAvjxLgXZB1YBRZCYO2s5qEQF4XeO6En1CfP6OZCfKZCEUwwbmwkKG3q0q4GNdZBPwxp3NF9ZATlSf0dN62I0fDErsJH8Iko5kUNbksh18QZAfQBxOwHoUyovMjZCrVzsN2lsglDOznqbHjMsv3d4XaNe4xWfyfpQdgffM3BXhTi2Nv7gZBf65LZBMlmqpNrZCTM0jXq2OAy6rV"
-
-curl -G "https://graph.facebook.com/v25.0/$PAGE_ID/subscribed_apps" \
-    --data-urlencode "access_token=$PAGE_ACCESS_TOKEN"

scripts/tools/page.sh

@@ -1,5 +0,0 @@
-PAGE_ACCESS_TOKEN="EAAvjxLgXZB1YBRZCYO2s5qEQF4XeO6En1CfP6OZCfKZCEUwwbmwkKG3q0q4GNdZBPwxp3NF9ZATlSf0dN62I0fDErsJH8Iko5kUNbksh18QZAfQBxOwHoUyovMjZCrVzsN2lsglDOznqbHjMsv3d4XaNe4xWfyfpQdgffM3BXhTi2Nv7gZBf65LZBMlmqpNrZCTM0jXq2OAy6rV";
-
-curl -G "https://graph.facebook.com/v25.0/me" \
-    --data-urlencode "fields=id,name" \
-    --data-urlencode "access_token=$PAGE_ACCESS_TOKEN"

scripts/tools/psid.sh

@@ -1,6 +0,0 @@
-PSID="27511427698460020"
-PAGE_ACCESS_TOKEN="EAAvjxLgXZB1YBRZCYO2s5qEQF4XeO6En1CfP6OZCfKZCEUwwbmwkKG3q0q4GNdZBPwxp3NF9ZATlSf0dN62I0fDErsJH8Iko5kUNbksh18QZAfQBxOwHoUyovMjZCrVzsN2lsglDOznqbHjMsv3d4XaNe4xWfyfpQdgffM3BXhTi2Nv7gZBf65LZBMlmqpNrZCTM0jXq2OAy6rV"
-
-curl -G "https://graph.facebook.com/v25.0/$PSID" \
-    --data-urlencode "fields=id" \
-    --data-urlencode "access_token=$PAGE_ACCESS_TOKEN"