refactor(oapi): 提供方强制验签迁 starter——enforce-patterns+trust-registry（审计 P1-6 / L2-8）

- 删自写 svcitem/config/OpenApiAuthEnforceConfiguration（yh-app-auth starter 版
  RequireAppSignFilter 承接，order+11 行为等价；/oapi/site/list 面无签名即 401）
- yh.app-auth.server.enforce-patterns=[/oapi/*] + trust-registry=true（中央密钥链组合：
  trusted-apps 100018 先、Redis sign:app:* 链后，Notice/flow-center 同款）
- data-redis 自 test scope 提升编译期（yh-app-auth 侧 optional 不传递，生产 classpath
  此前并无该依赖）；management.health.redis.enabled=false 防 Redis 抖动拉 DOWN 健康
- 测试 yml 同步 enforce-patterns：删自写副本后 SiteOapiIT 的 /oapi/** 401 断言由
  starter 过滤器承接；trust-registry 不进测试配置（IT 密封性，签名用例 100018 走
  trusted-apps 命中）

门禁：mvn test -Dskip.tests=false 413/413 绿（含 SiteOapiIT 6/6，本机 MySQL8+Redis）

pom.xml

@@ -103,11 +103,14 @@
             <artifactId>spring-boot-starter-test</artifactId>
             <scope>test</scope>
         </dependency>
-        <!-- 单测专用：验证方案 §12「缓存切 Redis 仅改配置」的演进承诺（生产仍为 Caffeine，零影响） -->
+        <!-- 入站验签走中央密钥链（注册表模式 yh.app-auth.trust-registry）必须编译期引入 data-redis：
+             yh-app-auth 的该依赖是 optional、不传递（Notice/flow-center/svc-hall 同款，2026-10-05 自
+             test scope 提升）。副作用是 RedisHealthIndicator 会被装配，故 yml 里关掉
+             management.health.redis.enabled，防 Redis 抖动把 /actuator/health 拉成 DOWN(503)。
+             RedisCacheEvolutionIT（缓存演进验证）继续复用本依赖。 -->
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-data-redis</artifactId>
-            <scope>test</scope>
         </dependency>
     </dependencies>
 

src/main/java/com/yunhai/cms/controller/oapi/site/SiteOapiController.java

@@ -2,6 +2,7 @@ package com.yunhai.cms.controller.oapi.site;
 
 import com.yunhai.cms.entity.CmsSite;
 import com.yunhai.cms.repository.CmsSiteRepository;
+import com.yunhai.cms.utils.ExtJsonUtils;
 import com.yunhai.platform.apistd.BizException;
 import com.yunhai.platform.utils.exception.ErrorCode;
 import lombok.Data;
@@ -11,7 +12,9 @@ import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
+import java.util.LinkedHashMap;
 import java.util.List;
+import java.util.Map;
 
 /**
  * 站点目录开放接口（/oapi/site/list，appKey 签名访问；V2.0 Part C.3）。
@@ -51,14 +54,34 @@ public class SiteOapiController {
         vo.setSiteCode(site.getCode());
         vo.setName(site.getName());
         vo.setSchId(site.getSchId() == null ? null : site.getSchId().longValue());
+        // T1 主题联动（2026-10-03）：theme 空=default；themeParams=config_json.theme_params
+        // 原样键值（解析写法对齐 PortalSiteSnapshot.of），未配=空对象（消费方免判空两写）
+        vo.setTheme(site.getTheme() == null || site.getTheme().isEmpty()
+                ? "default" : site.getTheme());
+        Map<String, Object> config = ExtJsonUtils.parse(site.getConfigJson());
+        Object tp = config == null ? null : config.get("theme_params");
+        Map<String, String> params = new LinkedHashMap<>();
+        if (tp instanceof Map) {
+            for (Map.Entry<?, ?> e : ((Map<?, ?>) tp).entrySet()) {
+                if (e.getKey() != null && e.getValue() != null) {
+                    params.put(String.valueOf(e.getKey()), String.valueOf(e.getValue()));
+                }
+            }
+        }
+        vo.setThemeParams(params);
         return vo;
     }
 
-    /** 站点选项（siteCode 为办事大厅侧定位键；schId 用于权限与租户定界） */
+    /** 站点选项（siteCode 为办事大厅侧定位键；schId 用于权限与租户定界；
+     * theme/themeParams raw 透传——消费方（svc-hall hall 用户面）按皮肤声明自行过滤） */
     @Data
     public static class SiteOptionVo {
         private String siteCode;
         private String name;
         private Long schId;
+        /** CMS 皮肤包名（空已兜底为 default） */
+        private String theme;
+        /** CMS config_json.theme_params 原样键值（未配置=空对象） */
+        private Map<String, String> themeParams = new LinkedHashMap<>();
     }
 }

src/main/java/com/yunhai/cms/controller/portal/PortalController.java

@@ -19,6 +19,7 @@ import com.yunhai.cms.svcitem.model.vo.PortalServiceItem;
 import com.yunhai.cms.svcitem.model.vo.PortalServiceListData;
 import com.yunhai.cms.svcitem.service.SvcItemQuery;
 import com.yunhai.cms.utils.PortalUrlHelper;
+import com.yunhai.cms.utils.SvcHallLinks;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Value;
@@ -491,18 +492,15 @@ public class PortalController {
         // "我要办理"三态（§5.3）：① ext_json.apply_url 手填外链（最高优先）
         // ② 未填且站点配了 svc_hall_base 且事项开通在线办理（onlineFlag=1 且绑流程，§3.7——
         //    与 svc-hall 侧 submit 校验"未开通在线办理"口径对齐，线下/纯指南事项不再渲染按钮）
+        //    ——深链带 from=指南页回跳地址，hall 据此显示"返回门户"按钮（T4 闭环）
         // ③ 其余 → 不注入（模板不渲染按钮）
         String applyUrl = item.getApplyUrl();
         boolean onlineHandlable = item.getOnlineFlag() != null && item.getOnlineFlag() == 1
                 && StringUtils.hasText(item.getFlowGuid());
         if ((applyUrl == null || applyUrl.trim().isEmpty()) && onlineHandlable
                 && site.getSvcHallBase() != null && !site.getSvcHallBase().trim().isEmpty()) {
-            String base = site.getSvcHallBase().trim();
-            while (base.endsWith("/")) {
-                base = base.substring(0, base.length() - 1);
-            }
-            applyUrl = base + "/#/apply?siteCode=" + urlEncodeValue(site.getCode())
-                    + "&itemCode=" + urlEncodeValue(item.getItemCode());
+            applyUrl = SvcHallLinks.build(site.getSvcHallBase(), site.getCode(),
+                    item.getItemCode(), url.serviceItem(itemId));
         }
         if (applyUrl != null && !applyUrl.trim().isEmpty()) {
             model.addAttribute("applyUrl", applyUrl);
@@ -687,14 +685,6 @@ public class PortalController {
         return trimmed.isEmpty() ? null : trimmed;
     }
 
-    private static String urlEncodeValue(String value) {
-        try {
-            return java.net.URLEncoder.encode(value == null ? "" : value, "UTF-8");
-        } catch (java.io.UnsupportedEncodingException e) {
-            return value;
-        }
-    }
-
 
     /**
      * 站点身份解析（W4）：优先按门户 path（siteSnapshotByPath）；

src/main/java/com/yunhai/cms/svcitem/config/OpenApiAuthEnforceConfiguration.java

@@ -1,49 +0,0 @@
-package com.yunhai.cms.svcitem.config;
-
-import com.yunhai.platform.appauth.AppAuthFilter;
-import org.springframework.boot.web.servlet.FilterRegistrationBean;
-import org.springframework.context.annotation.Bean;
-import org.springframework.context.annotation.Configuration;
-import org.springframework.core.Ordered;
-
-import javax.servlet.Filter;
-import javax.servlet.FilterChain;
-import javax.servlet.ServletException;
-import javax.servlet.ServletRequest;
-import javax.servlet.ServletResponse;
-import javax.servlet.http.HttpServletRequest;
-import javax.servlet.http.HttpServletResponse;
-import java.io.IOException;
-
-/**
- * 开放接口签名强制（事项库详细设计 §3.4，照 UserBase OpenApiAuthEnforceConfiguration 范式）：
- * yh-app-auth 的 {@link AppAuthFilter}（order +10，全路由）设计为「无签名头则放行」以兼容浏览器
- * CAS 流；本过滤器（order +11）只挂 /oapi/**，校验其写入的请求属性——已验签放行，否则 401。
- * CMS 的 /oapi/** 无用户会话语义，一律应用签名（X-App-Key/X-Timestamp/X-Signature 三件套）。
- */
-@Configuration
-public class OpenApiAuthEnforceConfiguration {
-
-    @Bean
-    public FilterRegistrationBean<RequireAppSignFilter> requireAppSignFilter() {
-        FilterRegistrationBean<RequireAppSignFilter> bean = new FilterRegistrationBean<>();
-        bean.setFilter(new RequireAppSignFilter());
-        bean.addUrlPatterns("/oapi/*");
-        bean.setOrder(Ordered.HIGHEST_PRECEDENCE + 11);
-        return bean;
-    }
-
-    public static class RequireAppSignFilter implements Filter {
-        @Override
-        public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
-                throws IOException, ServletException {
-            HttpServletRequest req = (HttpServletRequest) request;
-            HttpServletResponse res = (HttpServletResponse) response;
-            if (req.getAttribute(AppAuthFilter.APP_AUTH_ATTR) == null) {
-                res.sendError(HttpServletResponse.SC_UNAUTHORIZED, "missing app signature");
-                return;
-            }
-            chain.doFilter(request, response);
-        }
-    }
-}

src/main/java/com/yunhai/cms/utils/SvcHallLinks.java

@@ -0,0 +1,44 @@
+package com.yunhai.cms.utils;
+
+import java.io.UnsupportedEncodingException;
+import java.net.URLEncoder;
+
+/**
+ * 「我要办理」深链构造器（T4 回跳闭环，2026-10-03 执行方案）。
+ * 纯函数无状态：base 尾斜杠裁剪、参数 UTF-8 urlencode、from 缺省不追加。
+ */
+public final class SvcHallLinks {
+
+    private SvcHallLinks() {
+    }
+
+    /**
+     * 「我要办理」深链（双端契约：hall/src/router/routes.ts 依赖此形态，改参数名两侧同步）。
+     *
+     * @param base     svc-hall hall 部署基地址（站点 svc_hall_base，尾斜杠容忍）
+     * @param siteCode 站点编码
+     * @param itemCode 事项编码
+     * @param fromUrl  指南页绝对 URL（回跳地址；null/空=不追加 from 段，hall 不显示返回门户）
+     */
+    public static String build(String base, String siteCode, String itemCode, String fromUrl) {
+        String url = trimTail(base) + "/#/apply?siteCode=" + enc(siteCode)
+                + "&itemCode=" + enc(itemCode);
+        return fromUrl == null || fromUrl.isEmpty() ? url : url + "&from=" + enc(fromUrl);
+    }
+
+    private static String trimTail(String url) {
+        String s = url == null ? "" : url.trim();
+        while (s.endsWith("/")) {
+            s = s.substring(0, s.length() - 1);
+        }
+        return s;
+    }
+
+    private static String enc(String value) {
+        try {
+            return URLEncoder.encode(value, "UTF-8");
+        } catch (UnsupportedEncodingException e) {
+            return value;
+        }
+    }
+}

src/main/resources/application.yml

@@ -60,8 +60,18 @@ yh:
     # UserBase 注册后分配（进白名单），与 yh.open 保持一致；生产由 projman 注入
     app-key: 100005
     app-secret: 2c7885de594742cc840b8762910b2d2e
-    # 入站验签白名单：办事大厅 svc-hall（站点目录 /oapi/site/list 消费方，appKey=100018；
-    # P0-1 修复）。secret 与 svc-hall application.yml yh.app-auth.app-secret 逐字一致（联调态），
+    # 提供方强制验签（两级模型 §4.1，flow-center/Notice 同款）：本地 svcitem/config/
+    # OpenApiAuthEnforceConfiguration 副本已删（2026-10-05），换此一行——/oapi/**（站点目录
+    # /oapi/site/list）无签名三件套即 401（starter 版 RequireAppSignFilter，order +11 行为等价）
+    server:
+      enforce-patterns: [/oapi/*]
+    # 中央密钥链（两级模型 §4.2）：trusted-apps 先（确定性兜底），未命中走 SignKeyResolver
+    # （Redis sign:app:* → Caffeine → UserBase 兜底端点）——任何在 UserBase 注册过的 appKey
+    # 自动可验。需 data-redis 编译期依赖（yh-app-auth 侧 optional 不传递，pom 已提升 scope）
+    trust-registry: true
+    # 入站验签白名单（组合链第一层，Redis 停摆时确定性工作）：办事大厅 svc-hall
+    # （站点目录 /oapi/site/list 消费方，appKey=100018；P0-1 修复）。
+    # secret 与 svc-hall application.yml yh.app-auth.app-secret 逐字一致（联调态），
     # 生产两侧由 projman/Nacos 注入同一密钥对
     trusted-apps:
       "100018": "svc-hall-dev-secret-100018"
@@ -120,6 +130,11 @@ management:
   endpoint:
     health:
       show-details: never
+  # 密钥链验签依赖 Redis（sign:app:*）。关掉 Redis 健康指标：Redis 抖动不应把 /actuator/health
+  # 拉成 DOWN(503)，否则部署健康检查与探活会误判整机不可用（Notice/flow-center/svc-hall 同口径）
+  health:
+    redis:
+      enabled: false
 
 # 文件上传（同 UserHome 双 key 约定，方案 §7.3）
 # FILE_WEB_PATH 只接受相对路径（默认 /cms/upload/，含 context-path）或公网可达绝对地址；

src/test/java/com/yunhai/cms/controller/oapi/SiteOapiIT.java

@@ -23,7 +23,9 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
  * <ul>
  *   <li>鉴权：/oapi/** 无签名 401（RequireAppSignFilter）、错密钥 401；</li>
  *   <li>契约：schId 可选——不传=全部启用站点（含跨校），传了=按校过滤；</li>
- *   <li>出参形态：data[] 元素键=siteCode/name/schId（消费方 mapToVos 按这三键解析）。</li>
+ *   <li>出参形态：data[] 元素键=siteCode/name/schId/theme/themeParams（消费方 mapToVos 按前
+ *       三键解析；theme/themeParams 为 T1 主题联动新增，raw 透传——theme 空=default，
+ *       themeParams=config_json.theme_params 原样键值，未配=空对象，消费方自行过滤）。</li>
  * </ul>
  * 签名 canonical 与平台 AppSignInterceptor 一致：METHOD + "\n" + path[?sortedQuery] + "\n" + ts，
  * HmacSHA256 输出 Base64（见 SignUtil.signRequest / AppAuthFilter.buildSignedTarget）。
@@ -42,6 +44,11 @@ class SiteOapiIT extends CmsIntegrationTestBase {
     void seed() {
         purgeTables();
         CmsSite demo1 = persistSite("demo1", 1, "演示站点一");
+        // T1 主题联动（2026-10-03）：demo1 配置皮肤包与主题参数（经 /oapi/site/list raw 透传）
+        demo1.setTheme("campus-glow");
+        demo1.setConfigJson("{\"theme_params\":{\"primary\":\"#0e8a5f\",\"colorScheme\":\"custom\"},"
+                + "\"svc_hall_base\":\"http://localhost:8089\"}");
+        siteRepository.saveAndFlush(demo1);
         // schx 为 demo1 的院系子站：《院系子站方案》接入口径——子站不进办事大厅，
         // 按校下发（svc-hall 站点选择器 listSites(schId)）只含主站；反解全量仍含子站。
         persistSite("schx", 1, "主站X子站", demo1.getId());
@@ -111,6 +118,22 @@ class SiteOapiIT extends CmsIntegrationTestBase {
         assertThat(body).contains("\"name\":\"演示站点一\"").contains("\"schId\":1");
     }
 
+    @Test
+    @DisplayName("T1 主题联动：theme/themeParams raw 透传；未配置站点 theme=default、themeParams=空对象")
+    void themeFields_dispatchedRawWithFallback() throws Exception {
+        MvcResult result = mockMvc.perform(get("/oapi/site/list").headers(signHeaders("/oapi/site/list")))
+                .andExpect(status().isOk())
+                .andReturn();
+        String body = result.getResponse().getContentAsString(StandardCharsets.UTF_8);
+        // demo1：theme 原样下发，theme_params 内的键值原样透传（不解析别名、不注 colorScheme）
+        assertThat(body).contains("\"siteCode\":\"demo1\"")
+                .contains("\"theme\":\"campus-glow\"")
+                .contains("\"themeParams\":{\"primary\":\"#0e8a5f\",\"colorScheme\":\"custom\"}");
+        // demo2 未配置主题参数：theme 兜底 default，themeParams 空对象（消费方免判空两写）
+        assertThat(body).contains("\"siteCode\":\"demo2\"").contains("\"theme\":\"default\"");
+        assertThat(body).doesNotContain("\"themeParams\":null");
+    }
+
     /** 按平台 AppSignInterceptor 规则生成签名头（path + 排序 query，与 AppAuthFilter 服务端验签对齐） */
     private static org.springframework.http.HttpHeaders signHeaders(String target) {
         String ts = String.valueOf(System.currentTimeMillis());

src/test/java/com/yunhai/cms/portal/ServicePortalIT.java

@@ -122,12 +122,13 @@ class ServicePortalIT extends CmsIntegrationTestBase {
         siteRepository.saveAndFlush(site);
         clearCaches();
 
-        // 在线办理事项（onlineFlag=1 且绑流程）：自动生成发起页 URL
+        // 在线办理事项（onlineFlag=1 且绑流程）：自动生成发起页 URL（T4 起带 from=指南页回跳地址）
         stub.seed(2001, siteId, "ON-1", "在线事项", "jw", null);
         assertThat(body(mockMvc.perform(get("/portal/demo1/sv/{id}", 2001))
                 .andExpect(status().isOk()).andReturn()))
                 .contains("svc-apply-btn")
-                .contains("http://localhost:8087/#/apply?siteCode=demo1&itemCode=ON-1");
+                .contains("http://localhost:8087/#/apply?siteCode=demo1&itemCode=ON-1")
+                .contains("&from=");
 
         // 线下事项（onlineFlag=0 未绑流程）：即使站点配了基地址也不出按钮（§3.7 收紧）
         stub.seed(2002, siteId, "OFF-1", "线下事项", "jw", null);

src/test/java/com/yunhai/cms/utils/SvcHallLinksTest.java

@@ -0,0 +1,42 @@
+package com.yunhai.cms.utils;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * 「我要办理」深链构造器单测（T4 回跳闭环，2026-10-03 执行方案）。
+ * 覆盖：base 尾斜杠裁剪、siteCode/itemCode/from 的 UTF-8 urlencode、
+ * from 为 null/空时不追加 from 段（手填外链状态①不受影响）。
+ */
+@DisplayName("SvcHallLinks - 我要办理深链")
+class SvcHallLinksTest {
+
+    @Test
+    @DisplayName("四参形态：base 尾斜杠裁剪 + from 追加且编码")
+    void build_withFrom() {
+        assertThat(SvcHallLinks.build(
+                "http://h/svc-hall/hall/", "demo1", "SVC-001", "http://cms/portal/demo1/sv/12"))
+                .isEqualTo("http://h/svc-hall/hall/#/apply?siteCode=demo1&itemCode=SVC-001"
+                        + "&from=http%3A%2F%2Fcms%2Fportal%2Fdemo1%2Fsv%2F12");
+    }
+
+    @Test
+    @DisplayName("from 为 null：不追加 from 段（状态①手填外链路径不经过，兜底保护）")
+    void build_withoutFrom() {
+        assertThat(SvcHallLinks.build("http://h/svc-hall/hall", "demo1", "SVC-001", null))
+                .isEqualTo("http://h/svc-hall/hall/#/apply?siteCode=demo1&itemCode=SVC-001");
+        assertThat(SvcHallLinks.build("http://h/svc-hall/hall", "demo1", "SVC-001", ""))
+                .isEqualTo("http://h/svc-hall/hall/#/apply?siteCode=demo1&itemCode=SVC-001");
+    }
+
+    @Test
+    @DisplayName("siteCode/itemCode 中文与保留字符过 UTF-8 urlencode")
+    void build_encodesUtf8() throws java.io.UnsupportedEncodingException {
+        String url = SvcHallLinks.build("http://h/hall", "演示站点", "事项/01", "http://cms/sv/1?a=1&b=2");
+        assertThat(url).startsWith("http://h/hall/#/apply?siteCode=%E6%BC%94%E7%A4%BA%E7%AB%99%E7%82%B9");
+        assertThat(url).contains("&itemCode=" + java.net.URLEncoder.encode("事项/01", "UTF-8"));
+        assertThat(url).contains("&from=http%3A%2F%2Fcms%2Fsv%2F1%3Fa%3D1%26b%3D2");
+    }
+}

src/test/resources/application.yml

@@ -57,6 +57,12 @@ yh:
     enabled: true
     app-key: 100XXX
     app-secret: xxxxxxxx
+    # 提供方强制验签（与主配置同款，2026-10-05）：自写 OpenApiAuthEnforceConfiguration 副本已删，
+    # SiteOapiIT 的 /oapi/** 无签名 401 断言由 starter 版 RequireAppSignFilter（本配置驱动）承接；
+    # trust-registry 不进测试配置（IT 密封性：签名用例 100018 在下方 trusted-apps 命中即可，
+    # 不引入对 Redis 密钥链/UserBase 兜底端点的依赖）
+    server:
+      enforce-patterns: [/oapi/*]
     # 入站验签白名单：svc-hall 站点目录调用（与主配置同款联调密钥，SiteOapiIT 咬合用）
     trusted-apps:
       "100018": "svc-hall-dev-secret-100018"
@@ -90,6 +96,9 @@ management:
   endpoint:
     health:
       show-details: never
+  health:
+    redis:
+      enabled: false
 
 # 本地 Redis（单测 Redis 演进用例连接参数）
 cms.test.redis: