|
|
@@ -0,0 +1,89 @@
|
|
|
+# 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 七项按最小集合申请、密钥只进服务端不进前端。
|