docs: 注释明确转介人门户专用认证链边界与「不经网关直连」部署约定

yd-csf-api/src/main/java/com/yd/csf/api/security/ReferrerPortalSecurityConfig.java

@@ -25,14 +25,24 @@ import java.util.Collection;
 import java.util.List;
 import java.util.List;
 
 
 /**
 /**
- * 转介人门户独立安全链。
+ * 转介人门户专用认证链（独立于内勤后台体系）。
+ *
+ * <p><b>边界</b>：仅匹配容器内 {@code /c/**}（对外 {@code /csf/api/c/**}），其余请求落老链
+ * （{@code /**} 兜底）。转介人门户的所有接口都必须挂在该前缀下，才能进入本链。</p>
+ *
+ * <p><b>身份来源</b>：Casdoor OIDC 签发的 access token，由 {@link ReferrerIdentityFilter}
+ * 用 JWKS 验签（RS256 + iss + aud），再按 {@code sub} 调 yd-user 解析转介人并做门禁。
+ * 认证完全由本服务完成，<b>不依赖网关注入身份</b>。</p>
+ *
+ * <p><b>部署约定（重要）</b>：本门户在 nginx 层直连 yd-csf-api，<b>不经过内勤网关</b>；
+ * 网关的统一 JWT 校验不认 Casdoor 签发方，走网关会导致登录后接口全 401、前端循环跳转。
+ * 若未来必须接入网关，应先让网关信任 Casdoor 的 jwks/issuer/aud，而不是改 nginx 或本链。</p>
  *
  *
  * <p>必须沿用 {@link WebSecurityConfigurerAdapter} 老式风格：yd-auth-core 的后台链也是
  * <p>必须沿用 {@link WebSecurityConfigurerAdapter} 老式风格：yd-auth-core 的后台链也是
  * Adapter 风格，Spring Security 5.6 不允许 Adapter 与 {@code SecurityFilterChain} Bean 混用，
  * Adapter 风格，Spring Security 5.6 不允许 Adapter 与 {@code SecurityFilterChain} Bean 混用，
  * 否则启动报 “Found WebSecurityConfigurerAdapter as well as SecurityFilterChain”。</p>
  * 否则启动报 “Found WebSecurityConfigurerAdapter as well as SecurityFilterChain”。</p>
  *
  *
- * <p>多个 Adapter 凭 {@link Order} 共存：本链 {@code @Order(1)} 优先匹配容器内
- * {@code /c/**}（对外 {@code /csf/api/c/**}），其余请求落老链（兜底 {@code /**}）。</p>
+ * <p>多个 Adapter 凭 {@link Order} 共存：本链 {@code @Order(1)}，先于老链匹配。</p>
  */
  */
 @Configuration
 @Configuration
 @Order(1)
 @Order(1)