From b05adb1bb29d5be45c104ffe89bdfcfd258d5b04 Mon Sep 17 00:00:00 2001
From: chenhang <averych@126.com>
Date: Fri, 10 Jul 2026 17:11:21 +0800
Subject: [PATCH] feat(docs): add Facebook ASID/PSID binding and login API
 documentation

---
 .../backend/FRONTEND_FACEBOOK_IDENTITY_API.md | 225 ++++++++++++++++++
 1 file changed, 225 insertions(+)
 create mode 100644 docs/backend/FRONTEND_FACEBOOK_IDENTITY_API.md

diff --git a/docs/backend/FRONTEND_FACEBOOK_IDENTITY_API.md b/docs/backend/FRONTEND_FACEBOOK_IDENTITY_API.md
new file mode 100644
index 00000000..5ecf3f1b
--- /dev/null
+++ b/docs/backend/FRONTEND_FACEBOOK_IDENTITY_API.md
@@ -0,0 +1,225 @@
+# Facebook ASID / PSID 绑定与登录接口说明
+
+## 总原则
+
+后端不再依赖 Meta 做 ASID / PSID 实时互转。前端拿到哪个 ID 就传哪个 ID，后端只用本地数据库的绑定关系判断是不是同一个用户。
+
+- ASID: Facebook Login 返回的 app-scoped id。
+- PSID: Messenger / ManyChat / Page 链接带来的 page-scoped id。
+- 只有当同一个后端用户已经同时绑定 ASID 和 PSID 时，`psid` 才能直接当作 Facebook 登录凭据换 token。
+
+生产 API Base URL:
+
+```text
+https://api.banlv-ai.com
+```
+
+## 场景 2: 已登录用户绑定 PSID / ASID
+
+### Purpose
+
+用户已经登录 Cozsweet，前端从 URL 或 Messenger 环境拿到 `psid` 后，调用该接口把 PSID 绑定到当前登录用户。
+
+### Request URL
+
+```http
+POST https://api.banlv-ai.com/api/user/facebook/identity
+```
+
+### Authentication
+
+需要登录 token:
+
+```http
+Authorization: Bearer <TOKEN>
+```
+
+### Request Format
+
+```http
+Content-Type: application/json
+```
+
+### Parameters
+
+| Field | Type | Required | Example | Meaning |
+| --- | --- | --- | --- | --- |
+| psid | string | no | `37370387172559600` | Messenger PSID。 |
+| asid | string | no | `1582386133449953` | Facebook ASID。 |
+| fbPsid | string | no | `37370387172559600` | `psid` 的别名。 |
+| fbAsid | string | no | `1582386133449953` | `asid` 的别名。 |
+
+至少传一个字段。推荐前端只拿到 PSID 时传:
+
+```json
+{ "psid": "37370387172559600" }
+```
+
+### Request Example
+
+```bash
+curl -X POST 'https://api.banlv-ai.com/api/user/facebook/identity' \
+  -H 'Authorization: Bearer <TOKEN>' \
+  -H 'Content-Type: application/json' \
+  --data-raw '{
+    "psid": "37370387172559600"
+  }'
+```
+
+### Response Format
+
+```json
+{
+  "code": 200,
+  "message": "Facebook 身份绑定成功",
+  "success": true,
+  "data": {
+    "fbAsid": "1582386133449953",
+    "fbPsid": "37370387172559600",
+    "facebookBinding": {
+      "conflicts": [],
+      "bound": []
+    }
+  }
+}
+```
+
+### Failures
+
+| Status | Meaning |
+| --- | --- |
+| 400 | 没有传 `asid/fbAsid` 或 `psid/fbPsid`。 |
+| 401 | 未登录或 token 失效。 |
+| 409 | 该 ASID 或 PSID 已绑定到其他正式账号。 |
+
+## 场景 3: PSID 直接登录
+
+### Purpose
+
+前端只有 `psid`，希望后端用本地绑定关系直接换登录 token，不再触发 Facebook Login。
+
+### Request URL
+
+```http
+POST https://api.banlv-ai.com/api/auth/login/facebook/psid
+```
+
+### Authentication
+
+不需要 Bearer token。
+
+### Request Format
+
+```http
+Content-Type: application/json
+```
+
+### Parameters
+
+| Field | Type | Required | Example | Meaning |
+| --- | --- | --- | --- | --- |
+| psid | string | yes | `37370387172559600` | Messenger PSID。 |
+| deviceId | string | no | `web-abc` | 未匹配到账号时创建/返回游客 token 用；不传则后端按 PSID 生成稳定设备 ID。 |
+| bindToGuest | boolean | no | `true` | 未匹配到任何用户时，是否把 PSID 先绑定到游客账号，默认 true。 |
+
+### Request Example
+
+```bash
+curl -X POST 'https://api.banlv-ai.com/api/auth/login/facebook/psid' \
+  -H 'Content-Type: application/json' \
+  --data-raw '{
+    "psid": "37370387172559600"
+  }'
+```
+
+### Success Response: 已有完整绑定，直接登录
+
+同一个用户已有 ASID 和 PSID 时返回正式登录 token:
+
+```json
+{
+  "code": 200,
+  "message": "Facebook PSID 登录成功",
+  "success": true,
+  "data": {
+    "token": "<JWT>",
+    "refreshToken": "<REFRESH_TOKEN>",
+    "matchedBy": "psid",
+    "fbAsid": "1582386133449953",
+    "fbPsid": "37370387172559600",
+    "hasCompleteFacebookIdentity": true,
+    "isGuest": false,
+    "user": {
+      "id": "<USER_ID>",
+      "fbAsid": "1582386133449953",
+      "fbPsid": "37370387172559600"
+    }
+  }
+}
+```
+
+### Success Response: 未知或绑定不完整，返回游客
+
+查不到 PSID，或 PSID 对应用户还没有 ASID 时，不当作 Facebook 登录，只返回游客 token:
+
+```json
+{
+  "code": 200,
+  "message": "Facebook PSID 未匹配，已返回游客登录",
+  "success": true,
+  "data": {
+    "token": "<GUEST_JWT>",
+    "refreshToken": "",
+    "matchedBy": "guest",
+    "fbPsid": "37370387172559600",
+    "fbAsid": null,
+    "hasCompleteFacebookIdentity": false,
+    "isGuest": true,
+    "userId": "<GUEST_USER_ID>"
+  }
+}
+```
+
+如果 PSID 查到了用户，但该用户缺 ASID，`matchedBy` 会是:
+
+```text
+psid_incomplete
+```
+
+前端应继续按游客态处理，或引导用户进行 Facebook Login。
+
+### Failures
+
+| Status | Meaning |
+| --- | --- |
+| 422 | PSID 格式无效。 |
+
+## Profile 字段
+
+`GET /api/user/profile` 和登录响应里的 `user` 会包含:
+
+```json
+{
+  "fbAsid": "1582386133449953",
+  "fbPsid": "37370387172559600"
+}
+```
+
+没有绑定时字段为 `null` 或不存在。
+
+## 推荐前端流程
+
+1. 页面打开时从 URL / Messenger 环境读取 `psid`。
+2. 如果本地已有登录 token:
+   - 调 `POST /api/user/facebook/identity` 绑定 `psid` 到当前用户。
+3. 如果本地没有登录 token:
+   - 先调 `POST /api/auth/login/facebook/psid`。
+   - 如果返回 `hasCompleteFacebookIdentity=true`，保存 token，当作登录成功。
+   - 如果返回 `isGuest=true`，保存游客 token。
+
+## 重要注意
+
+- 后端不会再调用 Meta 做 ASID / PSID 互转。
+- PSID 直登只相信我们数据库里已有的绑定关系。
+- `409 FACEBOOK_ID_CONFLICT` 必须提示用户换账号或联系客服，不要在前端覆盖绑定。
+- 前端保存 token 的逻辑和原登录流程一致。