docs(deploy): clarify Feishu OAuth configuration and validation

Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>

docs/03-authentication-design.md

@@ -330,7 +330,7 @@ OAUTH2_FEISHU_USER_INFO_URI=https://open.feishu.cn/open-apis/authen/v1/user_info
 选择对应的标准 token endpoint；如需代理、区域或私有化 endpoint，可通过
 `OAUTH2_FEISHU_TOKEN_URI` 覆盖。授权和 userinfo endpoint 也分别通过
 `OAUTH2_FEISHU_AUTHORIZATION_URI`、`OAUTH2_FEISHU_USER_INFO_URI` 配置。协议版本不合法
-时应用启动失败。不会在 v3 失败后自动使用 v2，因为 authorization code 只能使用一次，
+时发布配置校验失败，应用也会拒绝启动。不会在 v3 失败后自动使用 v2，因为 authorization code 只能使用一次，
 自动重试可能造成重复请求并掩盖配置错误。旧的 `OAUTH2_FEISHU_AUTHORIZE_URI` 和
 `OAUTH2_FEISHU_BASE_URI` 仍作为 base-URI 兼容回退，但新部署应使用完整 endpoint 变量。
 

docs/09-deployment.md

@@ -303,6 +303,37 @@ services:
   确认，因此 `emailVerified` 恒为 false；若在 `application.yml` 中把
   `skillhub.access-policy.mode` 设为 `EMAIL_DOMAIN`，该策略会拒绝所有未验证邮箱，
   飞书登录将一律失败。启用飞书时请保留默认的 `OPEN` 或改用其他准入模式。
+
+  启用飞书前，使用一个测试租户完成一次真实回调验收。不要把真实 client secret
+  写入仓库、报告或聊天记录；只在受控的 `.env.release`、CI Secret 或 Kubernetes
+  Secret 中注入：
+
+  1. 在飞书自建应用中登记
+     `https://<公网域名>/login/oauth2/code/feishu`，并开启用户信息所需权限。
+  2. 在受控环境设置 `OAUTH2_FEISHU_CLIENT_ID`、`OAUTH2_FEISHU_CLIENT_SECRET`，确认
+     `OAUTH2_FEISHU_PROTOCOL_VERSION` 与 token endpoint 匹配，然后运行：
+
+     ```bash
+     make validate-release-config
+     docker compose --env-file .env.release -f compose.release.yml up -d
+     curl -fsS http://127.0.0.1:8080/actuator/health
+     curl -fsS http://127.0.0.1:8080/api/v1/auth/methods
+     ```
+
+  3. 在登录页选择“飞书”，确认浏览器跳转到配置的授权域名；完成授权后应回到
+     `/login/oauth2/code/feishu`，最终进入 `/` 或原始的 root-relative `returnTo`。
+  4. 用同一个飞书账号再次登录，确认仍绑定同一个 SkillHub 账号；再用已禁用的
+     SkillHub 账号登录，预期跳转 `/access-denied`，且不创建新 Session。
+  5. 检查日志中只有 provider、HTTP 状态、错误码和阶段信息，不应出现 client secret、
+     authorization code、access token、`open_id` 或上游错误文本：
+
+     ```bash
+     docker compose -f compose.release.yml logs --tail=200 server \
+       | rg -i 'client_secret|authorization code|access[_-]?token|open_id|secret|token'
+     ```
+
+  本地 mock 回调只能证明 SkillHub 与协议形状的集成，不能替代上述真实租户验收。
+  没有可用飞书租户时，应将该项记录为“未验证”，不要宣称 Feishu 登录已通过。
 - 如果要启用密码重置验证码邮件，参见：`docs/19-smtp-password-reset-email-setup.md`
 
 ## 8 OIDC 登录配置

scripts/tests/validate-release-config-test.sh

@@ -70,6 +70,28 @@ valid_env="$tmp/valid.env"
 write_env "$valid_env" "release-download-secret-32-bytes-minimum"
 "$SCRIPT" "$valid_env" >/dev/null
 
+valid_feishu_env="$tmp/valid-feishu.env"
+write_env "$valid_feishu_env" "release-download-secret-32-bytes-minimum"
+cat >>"$valid_feishu_env" <<'EOF'
+OAUTH2_FEISHU_CLIENT_ID=cli_test
+OAUTH2_FEISHU_CLIENT_SECRET=secret_test
+OAUTH2_FEISHU_PROTOCOL_VERSION=v2
+OAUTH2_FEISHU_AUTHORIZATION_URI=https://accounts.feishu.cn/open-apis/authen/v1/authorize
+OAUTH2_FEISHU_TOKEN_URI=https://open.feishu.cn/open-apis/authen/v2/oauth/token
+OAUTH2_FEISHU_USER_INFO_URI=https://open.feishu.cn/open-apis/authen/v1/user_info
+EOF
+"$SCRIPT" "$valid_feishu_env" >/dev/null
+
+invalid_feishu_protocol_env="$tmp/invalid-feishu-protocol.env"
+write_env "$invalid_feishu_protocol_env" "release-download-secret-32-bytes-minimum"
+printf '%s\n' "OAUTH2_FEISHU_PROTOCOL_VERSION=v1" >>"$invalid_feishu_protocol_env"
+expect_fail "$invalid_feishu_protocol_env" "OAUTH2_FEISHU_PROTOCOL_VERSION must be either v2 or v3"
+
+invalid_feishu_endpoint_env="$tmp/invalid-feishu-endpoint.env"
+write_env "$invalid_feishu_endpoint_env" "release-download-secret-32-bytes-minimum"
+printf '%s\n' "OAUTH2_FEISHU_TOKEN_URI=https://open.feishu.cn/oauth/token?tenant=prod" >>"$invalid_feishu_endpoint_env"
+expect_fail "$invalid_feishu_endpoint_env" "OAUTH2_FEISHU_TOKEN_URI must not contain a query"
+
 disabled_builtin_skills_env="$tmp/disabled-builtin-skills.env"
 write_env "$disabled_builtin_skills_env" "release-download-secret-32-bytes-minimum"
 printf '%s\n' "SKILLHUB_BUILTIN_SKILLS_ENABLED=false" >>"$disabled_builtin_skills_env"

scripts/validate-release-config.sh

@@ -391,6 +391,21 @@ for provider in GITHUB GITLAB FEISHU; do
   fi
 done
 
+feishu_protocol="${OAUTH2_FEISHU_PROTOCOL_VERSION:-v3}"
+case "$feishu_protocol" in
+  v2|v3) ;;
+  *) error "OAUTH2_FEISHU_PROTOCOL_VERSION must be either v2 or v3" ;;
+esac
+
+# OAuth endpoints are sent directly to the provider. Validate them here so a
+# typo fails before the release container starts.
+for feishu_endpoint in OAUTH2_FEISHU_AUTHORIZATION_URI OAUTH2_FEISHU_TOKEN_URI OAUTH2_FEISHU_USER_INFO_URI; do
+  eval "feishu_endpoint_value=\${$feishu_endpoint:-}"
+  if [ -n "$feishu_endpoint_value" ]; then
+    validate_url "$feishu_endpoint"
+  fi
+done
+
 if [ "$errors" -gt 0 ]; then
   echo "Release config validation failed: $errors error(s), $warnings warning(s)." >&2
   exit 1