task-oauth-callback-20261116.md 5.6 KB

B01/B02 任务书 — Buddy 应用 OAuth 回调端点初始真实现(2026-11-16)

背景

「浠艾福」项目已申请上架 WorkBuddy Buddy 应用(Client ID cb_zQeDp30U9RN6JiaCFUPY, 凭证存 buddy-app-publish/CREDENTIALS.md),当前状态「创建申请审核中」。

平台侧授权的 redirect_uri(授权回调地址)必须是一个真实可达的 https 地址。经用户拍板 路径方案,回调地址定为 https://cfc.cf-club.com/api/oauth/callback:

  • cfc-backend 部署在 Spring Boot(端口 9082),nginx 仅将 /api/** 前缀转发至后端; 不带 /api 的 /oauth/callback 会被 nginx 404 拦截(实测:nginx HTML 404 vs Spring JSON 404 可区分)。
  • 平台侧已在审核中提交了占位地址(无 /api 前缀版本),审核通过进入 pending_config 后需在应用配置页把「授权回调 URL」改为本任务产出的 /api/oauth/callback。

本任务只做后端侧:补一个真实存在、语法正确、路由已放行的 /api/oauth/callback 端点, 保证审核通过后应用配置改地址即可用,不再出现「后端无此接口」的断链。

B01 — OAuthClientController.java 初始真实现

新建文件:cfc-backend/src/main/java/com/etotem/cfc/controller/oauth/OAuthClientController.java

参考实现(照抄结构与代码风格,不臆造包路径):

  • cfc-backend/src/main/java/com/etotem/cfc/controller/huawei/HuaweiHealthController.java (5 端点、@RestController + 类级 @RequestMapping("/api/huawei-health") 的目录组织)
  • cfc-backend/src/main/java/com/etotem/cfc/controller/guide/PaymentController.java /wechat/oauth2-callback 端点(第三方回调用法先例,已在 WebConfig 放行)
  • cfg:com.etotem.cfc.common.Result / com.etotem.cfc.util.ParamUtils

要求:

  1. 包路径 com.etotem.cfc.controller.oauth,类 OAuthClientController,类级 @RequestMapping("/api/oauth"),方法级 /callback,即完整路径 POST /api/oauth/callback。
  2. 同时支持 GET 与 POST:@RequestMapping(value = "/callback", method = {RequestMethod.GET, RequestMethod.POST})。 OAuth 授权回跳典型形态是平台 302 携带 code 到 redirect_uri(query param,GET), 不能按 API_REFERENCE §17「统一 @PostMapping」一刀切——授权回调属于 「支付回调等第三方 webhook 例外」同性质的回调端点(PaymentController.oauth2-callback 同为先例),两种方法都要能到达 controller 层。
  3. 入参宽松兼容:GET 从 query param 取 code/state,POST 从 body(@RequestBody(required=false)) 取同名字段;state 缺失不报错。
  4. 初始真实现行为:只做日志记录 + 返回占位响应——
    • INFO 日志打印 code、state、clientIp、时间;
    • 返回 Result.success(data),data 至少含 received=true、state 回显、timestamp;
    • 不产 token、不落库、不调 WorkBuddy 换票接口(那是 Step 3 的任务,本任务不碰)。
  5. 类头 Javadoc 注明「初始占位实现,等待 WorkBuddy OAuth code→token 兑换任务接入」。

禁止事项:

  • 不新增任何数据库表、迁移、Mapper、Entity;
  • 不引入 HTTP 客户端调用外部平台;
  • 不改动任何现有控制器与拦截器的既有行(只追加新增)。

B02 — 放行白名单(JwtInterceptor + WebConfig)

文件 1:cfc-backend/src/main/java/com/etotem/cfc/config/JwtInterceptor.java

  • PUBLIC_PATHS 数组追加 "/api/oauth/callback"(OAuth 回调无用户 token, 按匿名放行模式;注意匹配逻辑用 boundaryPath + "/" 前缀,显式完整路径不误伤)。

文件 2:cfc-backend/src/main/java/com/etotem/cfc/config/WebConfig.java

  • jwtInterceptor.addPathPatterns("/api/**").excludePathPatterns(...) 追加 "/api/oauth/callback"(与 /api/payment/wechat/oauth2-callback 同款待遇)。
  • familyAccessInterceptor 的 excludePathPatterns(...) 追加 "/api/oauth/callback"(OAuth 回调无家庭上下文,与 /api/payment/wechat/v3-notify 同款匿名放行)。

仅追加新增条目,禁止改动既有行。

验收标准

  1. mvn -q compile -pl cfc-backend -am 通过(或既有编译命令,按 AGENTS.md 执行)。
  2. 静态核验(本机只读):
    • OAuthClientController.java 存在,含 @RequestMapping("/api/oauth") 与 /callback;
    • grep -n "api/oauth/callback" JwtInterceptor.java 命中 PUBLIC_PATHS;
    • grep -n "api/oauth/callback" WebConfig.java 命中两处 exclude;
    • grep -rn "@PostMapping\|@GetMapping" OAuthClientController.java 不得出现 (必须用平台侧声明支持的 @RequestMapping methods={GET,POST})。
  3. 契约单测:参照 CouponShareClaimContractTest 先例写一个轻量契约测试, 断言 /api/oauth/callback 路由已注册(方法 GET+POST 双达)、匿名无 token 可达 200、 响应含 received 字段;随后存量测试集不红。
  4. --clean-check 工作区干净,实现 push origin/cfclub。

平台侧衔接(本任务范围外,仅备忘)

WorkBuddy 应用当前「创建申请审核中」,基础信息锁定不可编辑;审核通过进入 pending_config 后,需在应用配置页将授权回调 URL 从占位地址改为 https://cfc.cf-club.com/api/oauth/callback。本任务覆盖后端,确保改地址即用。

后续 Step(另行派发):code → WorkBuddy POST /token 兑换 access_token(24h)/ refresh_token(60d)、scope 七项按最小集合申请、密钥只进服务端不进前端。