sso-portal/ADAPTATION_GUIDE.md

SSO-Portal → 真实后端 适配指南

目标：后端已落地真实 SSO 接口。把 sso-portal 从「自造一次性 code + 内存 codeStore」切换为「纯透传真实后端」，external-app 改用标准 OAuth2 授权码流程换 token。 本文以 2026-07 后端提供的三个真实接口为准。

⚠️ 与早期设想不同：真实后端没有采用「单端点 auth/index + login_type 区分」的设计，而是按登录方式拆成独立端点（/sso/account、/sso/phone/smscode），再用一个标准 OAuth2 端点（/sso/access_token）把授权 code 换成 access_token。

---

1. 后端提供的三个真实接口

#	用途	接口（POST）	调用方	必须
①	账号密码登录 → 返回授权 code	/api/v1/basis/sso/account	sso-portal	✅
②	手机验证码登录 → 返回授权 code	/api/v1/basis/sso/phone/smscode	sso-portal	✅
③	授权 code → access_token	/api/v1/basis/sso/access_token	external-app（服务端）	✅

宿主：http://172.16.115.31:6610（即 NEXT_PUBLIC_SHARED_API_PATH）

固定凭据（SSO 应用注册值）：

字段	值	持有方
client_id	6wds5qua3b76hu748zrjmall	sso-portal（随 URL app_id 传入）+ external-app
client_secret	oXwSxxrRUA0ijJ9N62qWI4oUrVJpLf5F	仅 external-app 服务端 env，绝不下发浏览器

不变项：

• 发送手机验证码：依旧走 POST /api/v1/basis/user/phone/code（body { phone, tntkey }），sso-portal 的 app/api/getVerifyCode/route.ts 不改。
• 飞书扫码：UI 已暂时隐藏，后端未提供对应 SSO 端点，不在本流程内。

---

2. 接口契约（字段级）

① 账号密码登录 — POST /api/v1/basis/sso/account

// 请求体
{
  "account": "string",
  "password": "string",
  "tenant": "string",                 // 租户标识，取自 SSO_TENANT（默认 cowarobot）
  "client_id": "6wds5qua3b76hu748zrjmall",
  "client_redirect_uri": "<external-app>/callback"
}
// 响应
{ "code": "<授权 code，一次性、短时效>" }

② 手机验证码登录 — POST /api/v1/basis/sso/phone/smscode

// 请求体
{
  "phone": "string",                  // 如 "+8613800000000"
  "smscode": "string",                // 6 位短信验证码
  "tenant": "string",
  "client_id": "6wds5qua3b76hu748zrjmall",
  "client_redirect_uri": "<external-app>/callback"
}
// 响应
{ "code": "<授权 code，一次性、短时效>" }

验证码发送仍走 /api/v1/basis/user/phone/code（不变），与登录接口 /sso/phone/smscode 是两个不同端点，别混淆。

③ 授权 code 换 token — POST /api/v1/basis/sso/access_token

// 请求体
{
  "client_id": "6wds5qua3b76hu748zrjmall",
  "client_secret": "oXwSxxrRUA0ijJ9N62qWI4oUrVJpLf5F",  // ⚠️ 仅服务端
  "code": "<①或②返回的授权 code>",
  "grant_type": "authorization_code",                     // 标准 OAuth2 取值
  "tenant": "string"
}
// 响应（按 OAuth2 习惯，以后端实测为准）
{ "access_token": "...", "refresh_token": "...", "expires_in": 7200, "token_type": "Bearer", "user": { ... } }

⚠️ code 语义冲突：basis 旧接口通常包一层业务外壳 { code: 200, data: {...}, message }（此处 code 是业务状态码）；而 ①②③ 里 code 是授权码字符串。落地时请以后端实测响应为准：若 ①② 返回的是平铺 { code: "<授权码>" }，则直接取；若包了外壳 { code:200, data:{ code:"..." } }，则取 data.code。下文代码示意两种都兼容。

---

3. 标准流程（OAuth2 授权码流程）

external-app
  → 跳转 sso-portal: /login?app_id=6wds5qua3b76hu748zrjmall&app_url=<external-app>/callback
       ↓ 用户在 sso-portal 登录（账号 / 手机）
  → sso-portal ① 或 ② 调 /sso/account | /sso/phone/smscode  ⇒ 授权 code
  → sso-portal 重定向: <app_url>?sso_code=<code>
       ↓
  → external-app /api/callback（服务端）③ POST /sso/access_token
        { client_id, client_secret, code, grant_type, tenant }  ⇒ access_token
  → external-app 写 httpOnly Cookie，建立本地会话

要点：

• client_secret 只在 external-app 服务端出现，sso-portal 全程不持有。
• 授权 code 一次性、短时效，由后端保证，sso-portal 不再自造、不再存内存。

---

4. sso-portal 需要改哪些文件

4.1 app/api/login/route.ts —— 改为透传 /sso/*，删除 codeStore

现状：调 basis 原始登录端点 → 拿 user + access_token → codeStore.set() 自造 code。 改为：按 type 调对应 /sso/* 端点，把后端返回的授权 code 原样透传，删除 codeStore / generateCode。

字段映射（前端解密后 body → 后端请求体）：

type	前端字段	后端字段（/sso/*）
account	account, password, abbr, client_id, client_redirect_uri	account, password, tenant(来自 SSO_TENANT env), client_id, client_redirect_uri
phone	phone, verify_code, tntkey, client_id, client_redirect_uri	phone, smscode(=verify_code), tenant(来自 SSO_TENANT env), client_id, client_redirect_uri

代码示意：

// ... decrypt() 不变，删除 import { codeStore } / generateCode ...

async function callSsoApi(path: string, body: object) {
  const res = await fetch(`${SHARED_API}${path}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  })
  const text = await res.text()
  try {
    return JSON.parse(text)
  } catch {
    throw new Error(`后端返回非 JSON [${res.status}]: ${text.slice(0, 200)}`)
  }
}

export async function POST(req: Request) {
  const decryptData = await req.json()
  const body = JSON.parse(decrypt(decryptData))
  const type = body?.type
  // tenant 由环境变量 SSO_TENANT 驱动（默认 cowarobot），ssoBody 显式使用、callSsoApi 纯透传
  const tenant = process.env.SSO_TENANT || 'cowarobot'

  let ssoRes: any
  if (type === 'account') {
    ssoRes = await callSsoApi('/api/v1/basis/sso/account', {
      account: body.account,
      password: body.password,
      tenant,
      client_id: body.client_id,
      client_redirect_uri: body.client_redirect_uri,
    })
  } else if (type === 'phone') {
    ssoRes = await callSsoApi('/api/v1/basis/sso/phone/smscode', {
      phone: body.phone,
      smscode: body.verify_code,
      tenant,
      client_id: body.client_id,
      client_redirect_uri: body.client_redirect_uri,
    })
  } else {
    return NextResponse.json({ error: `不支持的登录方式: ${type}` })
  }

  // ⚠️ 删除旧的 `if (res?.code !== 200)` 判断 —— 现在 code 是授权码字符串，不是业务状态码。
  //    兼容平铺 / 外壳两种响应；失败时回显后端 message。
  const authCode = ssoRes?.code ?? ssoRes?.data?.code
  if (!authCode || typeof authCode !== 'string') {
    return NextResponse.json({
      error: ssoRes?.message || ssoRes?.msg || '登录失败，后端未返回授权 code',
    })
  }
  return NextResponse.json({ code: authCode })
}

前端 components/login/index.tsx 的 postLogin() 已携带 client_id / client_redirect_uri，无需改动。handleLoginSuccess 已按 { code } 跳转，与新透传结构一致。

4.2 utils/code-store.ts —— 删除

授权 code 的签发 / 校验 / 一次性 / 过期全部由后端负责，内存 store 不再需要。同步移除 login/route.ts 里所有 import { codeStore }。

4.3 app/api/auth/verify/route.ts —— 删除

external-app 改为直连后端 /sso/access_token（见 §5），sso-portal 不再提供 code 换用户信息的代理。

4.4 app/api/getVerifyCode/route.ts —— 不变

继续代理 POST /api/v1/basis/user/phone/code（验证码发送逻辑沿用）。

---

5. external-app 需要改哪些文件

5.1 app/api/callback/route.ts —— 改为直连后端 /sso/access_token

现状：把 sso_code POST 给 sso-portal /api/auth/verify 换用户信息。 改为：服务端直接调后端 /api/v1/basis/sso/access_token，带 client_secret，拿 token 写 httpOnly Cookie。

代码示意：

const BACKEND = (process.env.SSO_BACKEND_API || 'http://172.16.115.31:6610').replace(/\/+$/, '')

export async function POST(req: Request) {
  const { code } = await req.json()
  if (!code) {
    return NextResponse.json({ error: '缺少 code 参数' }, { status: 400 })
  }

  const res = await fetch(`${BACKEND}/api/v1/basis/sso/access_token`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_id: process.env.NEXT_PUBLIC_SSO_APP_ID, // 6wds5qua3b76hu748zrjmall
      client_secret: process.env.SSO_CLIENT_SECRET, // ⚠️ 仅服务端 env，不下发浏览器
      code,
      grant_type: 'authorization_code',
      tenant: process.env.SSO_TENANT || 'cowarobot',
    }),
  })

  const data = await res.json().catch(() => ({}))
  if (!res.ok) {
    return NextResponse.json(
      { error: data?.message || data?.msg || '换 token 失败' },
      { status: 401 },
    )
  }

  const token = data?.access_token ?? data?.data?.access_token
  const refreshToken = data?.refresh_token ?? data?.data?.refresh_token
  const user = data?.user ?? data?.data?.user

  const response = NextResponse.json({ success: true })
  if (token) {
    response.cookies.set('token', token, { httpOnly: true, path: '/', maxAge: 86400 })
  }
  if (refreshToken) {
    response.cookies.set('refresh_token', refreshToken, {
      httpOnly: true, path: '/', maxAge: 86400 * 7,
    })
  }
  if (user) {
    response.cookies.set('user', JSON.stringify(user), { path: '/', maxAge: 86400 })
  }
  return response
}

5.2 跳转链接 —— app_id 改为真实 client_id

app/DashboardPage.tsx 跳 sso-portal 时 app_id 即 OAuth2 client_id，需改为 6wds5qua3b76hu748zrjmall，并把硬编码的 localhost 地址改为环境变量 NEXT_PUBLIC_SSO_APP_ID / NEXT_PUBLIC_SSO_URL / NEXT_PUBLIC_APP_URL（见 §6）。

---

6. 环境变量

sso-portal（.env.development / .env.staging / .env.production）

变量	说明	dev / staging	production
NEXT_PUBLIC_SHARED_API_PATH	/sso/* 宿主	http://172.16.115.31:6610/	http://basis-app-svc:6610
NEXT_PUBLIC_BASE_PATH	部署子路径，无则留空	""	""
SSO_TENANT	SSO 接口的租户标识（account / phone-smscode / access_token 共用）	cowarobot	cowarobot

sso-portal 不持有 client_secret（仅 external-app 服务端有）；SSO_TENANT 驱动所有 SSO 接口的 tenant 字段。

external-app

变量	端	说明	值 / 示例
NEXT_PUBLIC_SSO_APP_ID	两端	OAuth2 client_id，作为 URL app_id 传给 sso-portal	6wds5qua3b76hu748zrjmall
NEXT_PUBLIC_SSO_URL	客户端	sso-portal 登录页地址，客户端跳转 /login 用	dev: http://localhost:5501，prod: http://sso-portal-svc:5501
NEXT_PUBLIC_APP_URL	客户端	本应用地址，作为 client_redirect_uri	dev: http://localhost:4000
SSO_CLIENT_SECRET	服务端	/sso/access_token 鉴权用，仅服务端	oXwSxxrRUA0ijJ9N62qWI4oUrVJpLf5F
SSO_BACKEND_API	服务端	/sso/access_token 宿主	dev: http://172.16.115.31:6610，prod: http://basis-app-svc:6610
SSO_TENANT	服务端	租户标识（与 sso-portal 的 SSO_TENANT 一致）	cowarobot

SSO_CLIENT_SECRET 含敏感信息，建议生产环境通过部署平台密钥注入，不入库；本地私有覆盖写入 .env*.local（已被 .gitignore 忽略）。NEXT_PUBLIC_SSO_URL（指向 sso-portal）用于客户端跳转 /login，故带 NEXT_PUBLIC_ 前缀。

---

7. 迁移检查清单

• 后端就绪：/sso/account 返回授权 code
• 后端就绪：/sso/phone/smscode 返回授权 code
• 后端就绪：/sso/access_token 返回 access_token
• 确认 ①②③ 响应外壳：code 是平铺授权码还是包在 data.code（决定解析方式）
• tenant 取值已确认：cowarobot（sso-portal 与 external-app 均用此值）；grant_type 仍待确认（暂定 authorization_code）
• sso-portal login/route.ts：改为透传 /sso/account / /sso/phone/smscode，删 codeStore / generateCode，去掉 code !== 200 判断
• sso-portal 删除 utils/code-store.ts、app/api/auth/verify/route.ts 及相关 import
• external-app app/api/callback/route.ts：改为服务端直连 /sso/access_token
• external-app env：新增 NEXT_PUBLIC_SSO_URL / SSO_CLIENT_SECRET / SSO_BACKEND_API / SSO_TENANT，NEXT_PUBLIC_SSO_APP_ID 改为 6wds5qua3b76hu748zrjmall
• client_secret 仅在 external-app 服务端 env，前端代码 / 网络请求中无泄露
• 端到端：账号登录 → 拿 code → external-app 换 token → 建会话；手机登录同路径；验证码发送正常

---

8. 安全注意

• client_secret 绝不下发浏览器；/sso/access_token 一律由 external-app 的服务端 route handler 调用。
• access_token / refresh_token 用 httpOnly Cookie 存储，前端不可读。
• 授权 code 一次性、短时效，由后端签发与校验，sso-portal 不再自造、不缓存。
• client_redirect_uri 必须与 SSO 注册的回调地址一致，防止开放重定向。

---

9. 前端侧现状（无需改动）

登录组件已满足新契约的调用要求：

• components/login/index.tsx postLogin()：账号 / 手机登录已携带 client_id / client_redirect_uri，handleLoginSuccess 已按 { code } 重定向回 external-app。
• 飞书扫码 tab 已暂时隐藏（Tabs.Tab value="feishu" 注释 + Tabs.Panel 以 {false && ...} 屏蔽），恢复时取消对应注释即可。