s''

docs/CROSS_SITE_AUTH.md

@@ -0,0 +1,50 @@
+# 跨站登录态同步说明
+
+## 原理
+
+VIP 站点在用户注册/登录时，通过 `/api/auth/sync-session` 设置 Cookie `pb_session`，域名为 `.hackrobot.cn`。  
+**浏览器会自动将该 Cookie 发送到所有 `*.hackrobot.cn` 子域**（如 digital.hackrobot.cn、meetup.hackrobot.cn），**无需从 VIP 跳转**。
+
+## 当前流程
+
+1. 用户在 vip.hackrobot.cn 点击「立即加入」→ 注册/登录
+2. AuthForm 调用 `sync-session`，服务端设置 `pb_session`（domain=.hackrobot.cn）
+3. 用户访问 digital.hackrobot.cn 或 meetup.hackrobot.cn 时，浏览器会自动带上该 Cookie
+
+## digital / meetup 需具备的能力
+
+要让 digital、meetup 显示已登录，它们需要：
+
+1. **提供 `/api/auth/me` 接口**：读取请求中的 `pb_session` Cookie，校验 token 并返回用户信息
+2. **前端调用该接口**：页面加载时请求 `/api/auth/me`，根据返回结果展示登录态
+
+### 接口规范（与 nomadvip 保持一致）
+
+- **Cookie 名**：`pb_session`
+- **Cookie 域**：`.hackrobot.cn`（环境变量 `AUTH_COOKIE_DOMAIN`）
+- **内容**：base64url 编码的 `{ token, userId, email }`
+
+### /api/auth/me 实现参考
+
+可参考 `nomadvip/app/api/auth/me/route.ts`，逻辑为：
+
+1. 读取 `pb_session` Cookie
+2. 解码得到 token
+3. 调用 PocketBase `api/users/refresh` 校验 token
+4. 返回 `{ user: { id, email } }` 或 `{ user: null }`
+
+## 常见问题
+
+### 1. 刷新 digital/meetup 仍显示未登录
+
+- 检查 digital/meetup 是否实现了 `/api/auth/me` 并读取 `pb_session`
+- 检查是否在同一根域下（如均为 `*.hackrobot.cn`）
+- 检查 `AUTH_COOKIE_DOMAIN` 是否配置为 `.hackrobot.cn`
+
+### 2. 是否必须从 VIP 跳转过去？
+
+**不需要**。Cookie 由浏览器按域名自动管理，只要 Cookie 已设置，访问任意 `*.hackrobot.cn` 时都会自动带上。
+
+### 3. 不同根域（如 digital.com）能否共享？
+
+不能。Cookie 的 `domain` 只能作用于当前域及其子域，无法跨根域共享。若 digital、meetup 与 VIP 不在同一根域，需改用 OAuth、JWT 等跨域方案。