家庭邀请页面文档

家庭邀请页面接口文档

概览

• 路径: /invite/:code
• 方法: GET
• 是否鉴权: 否（公开路由）
• 响应类型: text/html; charset=utf-8
• 说明: 返回 H5 邀请落地页。无 token 时展示下载引导页；携带有效 token 时自动尝试加入家庭并返回结果页。

---

路径参数

---

可选认证参数

本接口支持两种方式传入用户 JWT Token，用于在 H5 页面内自动完成加入动作：

优先级：请求头 > Query 参数。不携带 token 时展示引导用户打开 App 或下载 App 的页面。

---

页面行为说明

---

Deep Link 格式

---

响应示例

1. 未携带 token（引导页）

GET /invite/abc123xyz

返回 HTTP 200，Content-Type: text/html; charset=utf-8，页面内容示意：

🐾 好友邀请您加入家庭
点击下方按钮在 App 内查看邀请详情并加入家庭。

[已有 App？点此打开]   → xunswei://invite/abc123xyz
[下载 App]             → {AppDownloadURL}

---

2. 携带有效 token，加入成功

GET /invite/abc123xyz?token=<JWT>

返回 HTTP 200，页面内容示意：

✅ 加入成功！
您已成功加入家庭《我的家庭》，请回到 App 查看家庭信息。

[在 App 内查看]  → xunswei://family/{familyId}

---

3. token 无效或加入失败

GET /invite/abc123xyz?token=<无效JWT>

返回 HTTP 200，页面内容示意：

⚠️ 邀请失效
登录信息已过期，请重新登录 App。

[已有 App？点此打开]  → xunswei://invite/abc123xyz
[下载 App]            → {AppDownloadURL}

---

使用流程

1. App 调用 POST /api/family/invite 获取邀请码和邀请链接
2. 用户将链接分享给好友（链接形如 [https://example.com/invite/{code}](https://example.com/invite/{code})）
3. 好友在浏览器打开链接：
   a. 未安装 App → 点击"下载 App"按钮
   b. 已安装 App → 点击"在 App 内打开"触发 Deep Link，进入 App 后调用
      POST /api/family/join 完成加入
   c. H5 页面内携带 token → 自动加入，无需跳转 App

---

邀请码有效期

邀请码由 /api/family/invite 生成，有效期 24 小时（86400 秒）。超时后访问本页面将展示"邀请失效"页。

---

注意事项

• 本接口始终返回 HTTP 200，通过页面内容区分不同状态，不使用 JSON 统一响应格式。
• AppDownloadURL 由服务端配置项 server.app_download_url 决定。
• 接口无跨域限制，可直接在浏览器访问。