feat(appearance): 外观偏好同源读代理端点 GET /api/appearance（oapi 代理轮）

- YschOpenCall(target=userhome) 经 open-gateway 签名直调，JsonNode 整体透传；下游不可达 503 静默降级
2026-10-08 23:27:48 +08:00
parent eb0a8ded2f
commit 54682cb72b
1 changed files with 59 additions and 0 deletions
@@ -0,0 +1,59 @@
+package com.yunhai.svchall.controller.api;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.yunhai.platform.openapi.core.YschOpenCall;
+import com.yunhai.platform.utils.model.BoaUser;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.http.HttpStatus;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.server.ResponseStatusException;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * 外观偏好同源读代理（oapi 代理轮 2026-10-08，全端统一形态）。
+ *
+ * <p>浏览器（通道 init 异步段）只与本应用【同源】取数——CAS 会话天然有效，无需 iframe 引导；
+ * 后端经 open-gateway 签名直调 UserHome（target=userhome，寻址走 yh.open.services，
+ * 勿写死 host）。设置入口收敛在 UserHome 设置中心，本端点【只读不写】。</p>
+ *
+ * <p>契约 = UserHome /oapi/appearance 出参【整体透传】（JsonNode 哑管道）：字段加减只在
+ * UserHome + 通道 init 两端演进，本应用零改动。现行字段 {@code {theme, avatar, logoUrl}}——
+ * theme/avatar 为服务端合成后的【生效值】（个人→学校→平台级联，不拆 my/sch）；
+ * null=未配置，init 侧清对应本地键回落默认观感。</p>
+ *
+ * <p>降级铁律：UserHome/网关不可达时【必须】以非 2xx 返回（503），绝不能伪装成 200+全 null——
+ * init 会把全 null 收敛成清键，等于 UserHome 停服一次就清空全员本地观感。</p>
+ */
+@RestController
+@RequestMapping(value = "/api")
+public class AppearanceProxyController {
+
+    private static final Logger log = LoggerFactory.getLogger(AppearanceProxyController.class);
+
+    /** open_api_target 注册表中的 userhome；寻址 yh.call.targets → yh.open.services → 枚举兜底 */
+    private static final String TARGET_USERHOME = "userhome";
+
+    private final YschOpenCall openCall;
+
+    public AppearanceProxyController(YschOpenCall openCall) {
+        this.openCall = openCall;
+    }
+
+    @GetMapping("appearance")
+    public JsonNode appearance(BoaUser authUserWithDept) {
+        try {
+            Map<String, String> q = new HashMap<>();
+            q.put("userId", String.valueOf(authUserWithDept.getId())); // 服务端取登录人，不收前端参数
+            return openCall.get(TARGET_USERHOME, "/oapi/appearance", q, JsonNode.class);
+        } catch (Exception e) {
+            log.warn("[appearance] UserHome 外观偏好不可达（503，init 侧静默不动本地键）userId={}：{}",
+                    authUserWithDept.getId(), e.toString());
+            throw new ResponseStatusException(HttpStatus.SERVICE_UNAVAILABLE, "appearance unavailable");
+        }
+    }
+}