external-app/README.md

External App（SSO 接入示例）

基于 Next.js 的示例应用，演示如何接入 Mock SSO：跳转到 sso-mock 登录 → 在 /callback 收到一次性 sso_code → 用 code 换取用户信息并写入 Cookie 建立会话。

快速开始

pnpm install
pnpm dev        # http://localhost:4000

需同时启动 sso-mock（默认 http://localhost:5501）。

环境变量

按环境拆分，已随仓库提交（参考 uirefbase 约定）：.env.development / .env.staging / .env.production。 本地私有覆盖请写入 .env*.local（已被 .gitignore 忽略，不入库）。

变量	端	说明	示例
SSO_URL	服务端	Mock SSO 服务地址，/api/callback 用它调 /api/auth/verify 换用户信息	dev: http://localhost:5501 prod: http://sso-mock-svc:5501
NEXT_PUBLIC_APP_URL	客户端	本应用地址，作为 SSO 回调 app_url 传给 sso-mock	http://localhost:4000
SSO_APP_ID	服务端	注册在 SSO 的应用 ID（app_id）	app_demo_001

无密钥，可安全入库。.env.production 中的 SSO_URL / NEXT_PUBLIC_APP_URL 为占位值，请按实际部署填写。

SSO 接入流程

1. 应用跳转到 sso-mock：{SSO_URL}/login?app_id={SSO_APP_ID}&app_url={NEXT_PUBLIC_APP_URL}/callback
2. 用户在 sso-mock 登录（账号 / 手机 / 飞书）
3. sso-mock 回跳：{app_url}?sso_code=xxxxx
4. 本应用 /callback 页把 sso_code POST 给 /api/callback → 服务端调 sso-mock /api/auth/verify 换取 { user, token } → 写入 Cookie

接口

接口	方法	说明
/api/callback	POST	用 sso_code 换用户信息并写 Cookie
/api/logout	POST	清除会话 Cookie