docs(auth): define unified identity federation architecture

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

docs/03-authentication-design.md

@@ -1,5 +1,11 @@
 # skillhub 认证与授权设计
 
+> 外部身份架构说明：LDAP、DingTalk、CAS、SAML、可信代理及其他新外部身份接入，
+> 以 [统一身份联邦设计](./21-unified-identity-federation-design.md) 为准。本文现有
+> `OAuthClaims`、`DirectAuthProvider` 和 `PassiveSessionAuthenticator` 接口描述的是
+> 当前兼容实现，不是新 Provider 的目标扩展契约；新 Provider 只能返回协议验证结果，
+> 由统一核心归一化为 `IdentityAssertion`，不得直接返回 `PlatformPrincipal`。
+
 ## 0. 身份标识约束
 
 - `PlatformPrincipal.userId` 必须是稳定的字符串标识，而不是 `Long`。

docs/11-auth-extensibility-and-private-sso.md

@@ -1,5 +1,12 @@
 # 认证扩展与私有 SSO 兼容设计
 
+> 状态说明：本文记录当前 Direct/Passive 私有 SSO 兼容入口。新外部身份实现和这些入口的
+> 后续迁移，以 [统一身份联邦设计](./21-unified-identity-federation-design.md) 为准。
+> `DirectAuthProvider` 和 `PassiveSessionAuthenticator` 直接返回
+> `PlatformPrincipal` 的方式属于待迁移设计，不应继续扩展到 LDAP、CAS、DingTalk、
+> SAML 或新的私有 SSO。新 Adapter 只返回协议验证结果，由统一核心归一化为
+> `IdentityAssertion`。
+
 ## 1. 目标
 
 在不影响当前开源版 OAuth 和本地账号登录能力的前提下，为未来私有仓库接入企业 SSO 预留稳定扩展点，并把代码差异控制在 provider 实现层和少量配置层。
@@ -145,4 +152,4 @@ public interface DirectAuthProvider {
 
 更详细的私有 SSO 接入步骤、最佳实践、测试矩阵和给后续 coding agent 的执行约束，见：
 
-- [12-private-sso-integration-playbook.md](/Users/xudongsun/github/skillhub/docs/12-private-sso-integration-playbook.md)
+- [12-private-sso-integration-playbook.md](./12-private-sso-integration-playbook.md)

docs/12-private-sso-integration-playbook.md

@@ -1,5 +1,10 @@
 # 私有 SSO 接入兼容层实施手册
 
+> 状态说明：本文是现有私有 SSO 兼容入口的历史实施手册。新接入应先遵循
+> [统一身份联邦设计](./21-unified-identity-federation-design.md)，由 Provider 返回协议
+> 验证结果，再由统一核心归一化为 `IdentityAssertion`；不得直接构造
+> `PlatformPrincipal`。本文中相反的代码示例只用于理解当前兼容实现。
+
 ## 1. 文档目的
 
 本文档面向两类读者：
@@ -11,10 +16,10 @@
 
 相关文档：
 
-- [03-authentication-design.md](/Users/xudongsun/github/skillhub/docs/03-authentication-design.md)
-- [06-api-design.md](/Users/xudongsun/github/skillhub/docs/06-api-design.md)
-- [08-frontend-architecture.md](/Users/xudongsun/github/skillhub/docs/08-frontend-architecture.md)
-- [11-auth-extensibility-and-private-sso.md](/Users/xudongsun/github/skillhub/docs/11-auth-extensibility-and-private-sso.md)
+- [03-authentication-design.md](./03-authentication-design.md)
+- [06-api-design.md](./06-api-design.md)
+- [08-frontend-architecture.md](./08-frontend-architecture.md)
+- [11-auth-extensibility-and-private-sso.md](./11-auth-extensibility-and-private-sso.md)
 
 ## 2. 当前上下文与已确认约束
 
@@ -54,9 +59,9 @@
 
 关键代码位置：
 
-- [DirectAuthProvider.java](/Users/xudongsun/github/skillhub/server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/direct/DirectAuthProvider.java)
-- [PassiveSessionAuthenticator.java](/Users/xudongsun/github/skillhub/server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/bootstrap/PassiveSessionAuthenticator.java)
-- [PlatformSessionService.java](/Users/xudongsun/github/skillhub/server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/session/PlatformSessionService.java)
+- [DirectAuthProvider.java](../server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/direct/DirectAuthProvider.java)
+- [PassiveSessionAuthenticator.java](../server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/bootstrap/PassiveSessionAuthenticator.java)
+- [PlatformSessionService.java](../server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/session/PlatformSessionService.java)
 
 ### 3.2 后端公共协议
 
@@ -415,7 +420,7 @@ skillhub:
 
 如果后续由 AI 继续在私有仓库上完成接入，建议严格遵守以下执行规则：
 
-- 先读 [11-auth-extensibility-and-private-sso.md](/Users/xudongsun/github/skillhub/docs/11-auth-extensibility-and-private-sso.md) 和本文档
+- 先读 [11-auth-extensibility-and-private-sso.md](./11-auth-extensibility-and-private-sso.md) 和本文档
 - 不要重构现有公共认证主链路，除非发现明确 bug
 - 私有 SSO 的具体实现优先写成 provider、authenticator、client、identity service
 - 不要复制 `PlatformSessionService` 逻辑