快捷入口

客户端集成说明（OAuth 2.0，非完整 OIDC）

本 AS 基于 Spring Authorization Server，对外暴露标准 OAuth 端点；与常见 OIDC 客户端库的默认假设并不完全一致，集成前请先阅读本节。

协议定位

Scope 约定（常见踩坑）

• OAuth 2.0 不规定 scope 必须叫什么；但 authorize 请求的每一个 scope都必须在管理端为该 Client 预先登记，否则回调为 ?error=invalid_scope。
• 管理端「授权 Scope」通常选客户端租户下的角色名（与 RS 验权一致），不会自动包含 openid、profile、offline_access。
• openid：仅在使用 OIDC / 需要 id_token 时按需登记；不是授权码流程的必选项。
• profile、offline_access：OIDC 常见 scope，均为可选；未登记却请求 → invalid_scope。
• 若只需 access_token 调业务 API：authorize 的 scope 填 Client 已登记的角色名即可，不必照搬 OIDC 库默认三件套。
• 多个 scope 用空格分隔（URL 中可为 +），不要用逗号。

Scope 携带建议

authorize 的 scope 只能是该 Client 在管理端已登记 scope 的子集。集成前请与OAuth Client 登记人（管理端 → OAuth 客户端）确认下表所列名称后再编码到客户端。

1. 角色 scope（业务主路径，通常必带）

管理端创建 Client 时，「授权 Scope」下拉来自客户端租户（默认 tenantId=1）下已定义的角色名称。authorize 应携带与 RS 业务 API @RequireScope 一致的角色 scope。

协作建议：Client 登记人导出该 Client 的「授权 Scope」列表 → 客户端开发按列表配置 authorize；不要自行假设 OIDC 默认 scope 已登记。

2. 可选标准 scope（按需登记后再携带）

下列为 OIDC / OAuth 生态常见 scope 名；仅当管理端已为该 Client 勾选/登记时才能在 authorize 中请求。

3. 常见组合示例

access_token（JWT）除 scope 外还含 role_codes（用户在该租户下的实际角色），RS 上 @RequireRole 看 role_codes，@RequireScope 看 token 中的 scope；两者可能同时存在，集成时请与后端约定。

推荐集成步骤

1. 管理端 OAuth 客户端 新建 PKCE 公开客户端，填写实际 redirect_uri，勾选需要的「授权 Scope」。
2. 客户端 authorize 的 scope 与上一步登记完全一致（或为其子集）。
3. 浏览器打开 /oauth2/authorize?... → 登录（/oauth2/login）→ 按需 consent → 回调带 code。
4. POST /oauth2/token（grant_type=authorization_code + PKCE）换取 access_token（及默认启用的 refresh_token；scope 含 openid 时另有 id_token）。
5. （可选）GET /.well-known/openid-configuration 读取 Discovery；GET /oauth2/userinfo 携带 Authorization: Bearer {access_token} 获取身份 Claims。

Discovery / UserInfo 示例

curl -s http://127.0.0.1:8080/.well-known/openid-configuration

curl -s http://127.0.0.1:8080/oauth2/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

UserInfo 要求 access_token 授权 scope 含 openid；profile/email/phone claims 须对应 scope 已登记且 authorize 已携带。

authorize 链接示例

GET /oauth2/authorize
  ?response_type=code
  &client_id={管理端创建的 client_id}
  &redirect_uri={须与 Client 登记完全一致，需 URL 编码}
  &scope={与 Client 登记的 scope 一致，空格分隔}
  &state={随机串}
  &code_challenge={S256 挑战码}
  &code_challenge_method=S256

OAuth Client

发行版不预置演示 Client。请先在管理端 OAuth 客户端 中新建 PKCE 公共客户端，redirect_uri 可填示例： http://127.0.0.1:8080/demo/callback，再按上文拼接 /oauth2/authorize 链接进行验收。

用户反馈（C 端跳转提交）

业务 App 在用户本地已登录后，携带 client_id 与 email 跳转至 AS 内置反馈页，无需在授权服务器再次登录即可提交文字与图片。提交成功后按 OAuth Client 配置的「反馈通知邮箱」异步发信；管理端可只读查阅历史反馈。

跳转 URL

GET /oauth2/feedback?client_id={clientId}&email={urlEncodedEmail}&returnUrl={可选}

email 由业务 App 从本地登录态读取并自行 URL 编码（如 encodeURIComponent）。示例（将 {client_id} 换为管理端已创建的 Client ID）：

http://127.0.0.1:8080/oauth2/feedback?client_id={client_id}&email=user%40example.com&returnUrl=http%3A%2F%2F127.0.0.1%3A8080%2Fdemo%2Fcallback

集成要点

• 免登录：反馈页不检查 AS Cookie，不重定向 /oauth2/login。
• returnUrl 可选；非空时其 scheme + authority 须与 Client 任一 redirect_uri 一致，否则忽略（不展示返回链接，不阻断提交）。
• 图片须先由宿主提供 POST /file/upload，将响应中的文件名随 POST /oauth2/feedback 表单提交（字段 imageUrls）。
• 邮件通知：管理端 OAuth 客户端表单填写「反馈通知邮箱」；服务端须配置 spring.mail.*。未配置邮箱或 SMTP 时反馈仍落库，仅跳过发信。
• 管理端查阅：部署后导入 管理端默认菜单.csv，侧栏打开 用户反馈（/client/feedback）；API 为 POST /manage/feedback/list、POST /manage/feedback/detail/{id}（只读）。

站内信（C 端拉取与消费）

管理端在侧栏 站内信 发信后，业务 App 持 OAuth access_token 定时拉取本渠道未读消息，并在用户阅读/作答后一次性消费（ack）。按 OAuth client_id 渠道可见；本期仅场景二。

API

POST /oauth2/message/pull
Authorization: Bearer {access_token}
Content-Type: application/json

{"clientId":"{client_id}","limit":20}

POST /oauth2/message/ack
Authorization: Bearer {access_token}
Content-Type: application/json

{"clientId":"{client_id}","messageId":"...","answers":[
  {"questionId":"q1","optionIndexes":[0]},
  {"questionId":"q2","optionIndexes":[0,2]},
  {"questionId":"q3","text":"补充说明"}
]}

出参（统一 BaseResponse）

业务体在 data；HTTP 200 仍可能业务失败（看 code）。鉴权失败为 401（无 JSON 体或由容器返回）。

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

pull 成功时 data

{
  "items": [
    {
      "messageId": "msg-…",
      "createTime": "2026-07-26T12:00:00.000+08:00",
      "expireAt": "2026-08-25T12:00:00.000+08:00",
      "blocks": [
        { "type": "TEXT", "body": "维护通知…" },
        { "type": "SINGLE", "id": "q1", "title": "是否收到？", "options": ["是", "否"] },
        { "type": "MULTI", "id": "q2", "title": "常用功能", "options": ["下单", "售后"] },
        { "type": "TEXT_REPLY", "id": "q3", "title": "补充", "maxLength": 500 }
      ]
    }
  ]
}

ack 成功时 data

data 为 null（或省略）；以 code == 0 表示成功。重复 ack 幂等成功（同渠道已消费不再改答案）。

常见业务错误（HTTP 200，code != 0）

• 参数 / 身份：clientId 空、与 JWT aud 不一致、令牌缺声明、messageId 空等。
• 功能关闭：com.mfs.user.message.enabled=false 时返回业务错误。
• ack 校验：消息不存在/非可消费状态/已过期；若携带 answers 但不完整/不合法等（见响应 message）。

集成要点

• Bearer 必填：无 token 或 JWT 无效返回 401；请求体 clientId 必须等于 JWT aud（换 token 时的 OAuth client_id）。
• pull：仅返回未 ack、未过期、已 fan-out（SENT）的信（含 blocks）；建议轮询间隔由 App 自定（如 30s～2min）。
• ack：answers 可选——省略或 [] 仅标记已读（不落答案）；若携带非空 answers 则须一次覆盖全部题目；成功后同渠道不再下发；重复 ack 幂等成功。
• 过期：每信有 expireAt；过期未读不再出现，避免久未登录刷屏。
• 管理端：导入菜单 CSV 后侧栏「站内信」发信/统计（/client/site-message）。
• 非目标：本期不提供服务端历史收件箱；场景一/三不交付。

PKCE 参数（换 token 时使用）

{state=ewNV-utBxHHRLzvj0lt1Fw, code_verifier=496EOpAv8iaPx4mvq9ey_fkwXsCQd7V98Mr8k7AJ1jk, code_challenge=75kj6NNPpEXgnHAQiM4pCUCqwCFel4-nS3uE95KMrpk}

管理端 UC 登录示例

curl -X POST http://127.0.0.1:8080/user/login \
  -H "Content-Type: application/json" \
  -d '{"tenantId":"2","userCode":"admin","password":"123456"}'

预置说明

• 管理端：执行 sql/03-tenant-seed.sql 后使用 admin / 123456（tenantId=2）
• OAuth Client：须在管理端创建（见 README「管理端侧栏菜单」）
• 管理端 Web UI：须先构建 admin-ui，见 admin-ui/README.md