外部入口接入说明

Facebook 等外部应用统一通过 /external-entry 进入本应用。入口先保存外部身份和短期业务意图，再跳转到对应角色页面并清理地址栏中的入口查询参数。

环境	APP HOST
预发环境 `pre`	`frontend-test.banlv-ai.com`
正式环境 `production`	`cozsweet.com`

入口格式：

https://<APP_HOST>/external-entry?<参数>

当前 Facebook 业务入口

当前正式投放固定为 4 类入口乘以 3 个角色，共 12 条链接。Facebook 业务名称与应用页面的对应关系如下：

Facebook 入口	参数组合	落地行为
私密空间	`target=chat`	进入普通聊天页，不插入任何锁定内容。
语音	`target=chat&mode=promotion&promotion_type=voice`	进入聊天页，并插入一条待解锁语音。
图片包	`target=private-zone`	进入角色的 `private-zone` 图片空间。
帮忙买咖啡	`target=tip`	进入角色的咖啡打赏页。

每条正式链接还必须显式传入：

character=elio、character=maya 或 character=nayeli；
psid=<PSID>，其中 <PSID> 必须由 Facebook 发送端替换为当前用户经过 URL 编码的 Page-scoped User ID。

完整的 12 条正式发送模板见 Facebook 12 条外部入口链接清单。

参数	可选值或格式	用途
`target`	`chat`、`tip`、`private-zone`	指定进入的页面；不传或值无效时进入聊天页。
`character`	`elio`、`maya`、`nayeli`	指定角色；不传或值无效时使用 Elio。正式投放链接必须显式传入。
`psid`	string	Facebook Page-scoped User ID。Facebook 正式投放链接必须动态传入。
`mode`	`promotion`	开启聊天促销模式。
`promotion_type`	`voice`、`image`、`private`	指定促销消息类型，仅与 `mode=promotion` 一起使用。

mode=promotion 只有在 target=chat 且同时提供有效的 promotion_type 时生效。当前 12 条正式投放链接只使用 promotion_type=voice；image 和 private 保留为兼容能力，不属于本次业务清单。

发送前必须把 <CHARACTER> 替换为角色值，把 <PSID> 替换为当前 Facebook 用户的真实 PSID；不得把占位符原样发送给用户。

私密空间（普通聊天）：

https://<APP_HOST>/external-entry?target=chat&character=<CHARACTER>&psid=<PSID>

语音：

https://<APP_HOST>/external-entry?target=chat&character=<CHARACTER>&mode=promotion&promotion_type=voice&psid=<PSID>

图片包：

https://<APP_HOST>/external-entry?target=private-zone&character=<CHARACTER>&psid=<PSID>

帮忙买咖啡：

https://<APP_HOST>/external-entry?target=tip&character=<CHARACTER>&psid=<PSID>

psid 可以和任意有效入口参数组合使用。应用会先保存 PSID，再执行登录状态判断和 Facebook Identity 绑定。详细流程见 PSID 与登录状态流程图。

所有参数值都必须进行 URL 编码。入口中禁止传递登录 Token、Page Access Token、App Secret 或其他秘密。

历史参数 target=private-room 继续兼容进入 private-zone，但不得用于新投放链接。
private_zone 等其他拼写仍按无效目标处理并回退聊天页。
promotion_type=image 和 promotion_type=private 继续由现有代码支持，但不计入当前 12 条 Facebook 业务链接。
无效或缺失的 character 继续回退 Elio；正式投放模板始终显式传入角色，不能依赖回退。