From d0234effd6fefe3dc00b08984c13312a4041b524 Mon Sep 17 00:00:00 2001
From: zhangheng <zhangheng@cowarobot.com>
Date: Mon, 6 Jul 2026 19:47:08 +0800
Subject: [PATCH] docs: add README with SSO flow and environment variables

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 README.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d0cda92
--- /dev/null
+++ b/README.md
@@ -0,0 +1,39 @@
+# External App（SSO 接入示例）
+
+基于 Next.js 的示例应用，演示如何接入 Mock SSO：跳转到 sso-mock 登录 → 在 `/callback` 收到一次性 `sso_code` → 用 code 换取用户信息并写入 Cookie 建立会话。
+
+## 快速开始
+
+```bash
+pnpm install
+pnpm dev        # http://localhost:4000
+```
+
+> 需同时启动 [`sso-mock`](../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`<br>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 |