docs(identity): 发布统一认证管理契约

为配对、策略、验证、激活、回滚、禁用和公开运行时接口补充 OpenAPI 注解，并将通用 Identity 类型加入生成范围。生成契约不包含 Exchange Token、Machine Secret 或 Secret 引用。\n\n验证：pnpm openapi；OpenAPI 敏感字段扫描通过

apps/api/docs/swagger.yaml

@@ -823,6 +823,70 @@ definitions:
       billing:
         $ref: '#/definitions/httpapi.desktopBillingConfigResponse'
     type: object
+  httpapi.identityConfigurationView:
+    properties:
+      active:
+        $ref: '#/definitions/identity.Revision'
+      draft:
+        $ref: '#/definitions/identity.Revision'
+      pairing:
+        $ref: '#/definitions/identity.PairingExchange'
+      previous:
+        $ref: '#/definitions/identity.Revision'
+      runtime:
+        $ref: '#/definitions/httpapi.identityRuntimeStatus'
+    type: object
+  httpapi.identityPolicyPatch:
+    properties:
+      jitEnabled:
+        type: boolean
+      legacyJwtEnabled:
+        type: boolean
+      localTenantKey:
+        type: string
+      rolePrefix:
+        type: string
+      sessionAbsoluteSeconds:
+        type: integer
+      sessionIdleSeconds:
+        type: integer
+      sessionRefreshSeconds:
+        type: integer
+    type: object
+  httpapi.identityRuntimeStatus:
+    properties:
+      enabled:
+        type: boolean
+      jit:
+        type: string
+      lastAuditId:
+        type: string
+      lastErrorCategory:
+        type: string
+      lastTraceId:
+        type: string
+      login:
+        type: string
+      revisionId:
+        type: string
+      sessionRevocation:
+        type: string
+      tokenIntrospection:
+        type: string
+    type: object
+  httpapi.publicIdentityConfiguration:
+    properties:
+      enabled:
+        type: boolean
+      loginUrl:
+        type: string
+      logoutUrl:
+        type: string
+      oidcLogin:
+        type: boolean
+      status:
+        type: string
+    type: object
   httpapi.updatePlatformDynamicPriorityRequest:
     properties:
       dynamicPriority:
@@ -868,6 +932,157 @@ definitions:
         example: manual recharge
         type: string
     type: object
+  identity.PairingExchange:
+    properties:
+      authCenterAuditId:
+        type: string
+      createdAt:
+        type: string
+      expiresAt:
+        type: string
+      id:
+        type: string
+      lastErrorCategory:
+        type: string
+      lastTraceId:
+        type: string
+      remoteExchangeId:
+        type: string
+      remoteVersion:
+        type: integer
+      revisionId:
+        type: string
+      status:
+        $ref: '#/definitions/identity.PairingStatus'
+      updatedAt:
+        type: string
+      version:
+        type: integer
+    type: object
+  identity.PairingInput:
+    properties:
+      authCenterUrl:
+        type: string
+      legacyJwtEnabled:
+        type: boolean
+      localTenantKey:
+        type: string
+      onboardingCode:
+        type: string
+      publicBaseUrl:
+        type: string
+      webBaseUrl:
+        type: string
+    type: object
+  identity.PairingStatus:
+    enum:
+    - metadata_pending
+    - preparing
+    - ready
+    - credentials_saved
+    - completed
+    - failed
+    - expired
+    type: string
+    x-enum-varnames:
+    - PairingMetadataPending
+    - PairingPreparing
+    - PairingReady
+    - PairingCredentialsSaved
+    - PairingCompleted
+    - PairingFailed
+    - PairingExpired
+  identity.Revision:
+    properties:
+      activatedAt:
+        type: string
+      applicationId:
+        type: string
+      audience:
+        type: string
+      authCenterUrl:
+        type: string
+      browserClientId:
+        type: string
+      capabilities:
+        items:
+          type: string
+        type: array
+      createdAt:
+        type: string
+      id:
+        type: string
+      issuer:
+        type: string
+      jitEnabled:
+        type: boolean
+      lastAuditId:
+        type: string
+      lastErrorCategory:
+        type: string
+      lastTraceId:
+        type: string
+      legacyJwtEnabled:
+        type: boolean
+      localTenantKey:
+        type: string
+      machineClientId:
+        type: string
+      publicBaseUrl:
+        type: string
+      rolePrefix:
+        type: string
+      schemaVersion:
+        type: integer
+      scopes:
+        items:
+          type: string
+        type: array
+      securityEventAudience:
+        type: string
+      securityEventConfigurationUrl:
+        type: string
+      securityEventIssuer:
+        type: string
+      sessionAbsoluteSeconds:
+        type: integer
+      sessionIdleSeconds:
+        type: integer
+      sessionRefreshSeconds:
+        type: integer
+      sessionRevocation:
+        type: boolean
+      state:
+        $ref: '#/definitions/identity.RevisionState'
+      supersededAt:
+        type: string
+      tenantId:
+        type: string
+      tokenIntrospection:
+        type: boolean
+      updatedAt:
+        type: string
+      validatedAt:
+        type: string
+      version:
+        type: integer
+      webBaseUrl:
+        type: string
+    type: object
+  identity.RevisionState:
+    enum:
+    - draft
+    - validated
+    - active
+    - superseded
+    - failed
+    type: string
+    x-enum-varnames:
+    - RevisionDraft
+    - RevisionValidated
+    - RevisionActive
+    - RevisionSuperseded
+    - RevisionFailed
   store.APIKey:
     properties:
       createdAt:
@@ -4372,6 +4587,374 @@ paths:
       summary: 更新文件存储设置
       tags:
       - system
+  /api/admin/system/identity/configuration:
+    get:
+      description: 返回 Active、Draft、Previous Revision、配对进度和脱敏运行时健康状态。
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/httpapi.identityConfigurationView'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "403":
+          description: Forbidden
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "503":
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+      security:
+      - BearerAuth: []
+      summary: 获取统一认证配置
+      tags:
+      - identity
+  /api/admin/system/identity/disable:
+    post:
+      description: 保留 Superseded Revision 供回滚，清理 BFF Session，并继续允许本地管理登录。
+      parameters:
+      - description: 幂等键
+        in: header
+        name: Idempotency-Key
+        required: true
+        type: string
+      - description: 当前 Active Revision ETag
+        in: header
+        name: If-Match
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/identity.Revision'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "403":
+          description: Forbidden
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "412":
+          description: Precondition Failed
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "428":
+          description: Precondition Required
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+      security:
+      - BearerAuth: []
+      summary: 禁用统一认证
+      tags:
+      - identity
+  /api/admin/system/identity/pairings:
+    post:
+      consumes:
+      - application/json
+      description: 使用一次性接入码创建 Draft 和异步 Exchange。接入码仅允许出现在请求 Body。
+      parameters:
+      - description: 幂等键
+        in: header
+        name: Idempotency-Key
+        required: true
+        type: string
+      - description: 首次配对固定为 W/\
+        in: header
+        name: If-Match
+        required: true
+        type: string
+      - description: 配对参数
+        in: body
+        name: body
+        required: true
+        schema:
+          $ref: '#/definitions/identity.PairingInput'
+      produces:
+      - application/json
+      responses:
+        "202":
+          description: Accepted
+          schema:
+            $ref: '#/definitions/identity.PairingExchange'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "403":
+          description: Forbidden
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "428":
+          description: Precondition Required
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+      security:
+      - BearerAuth: []
+      summary: 启动统一认证配对
+      tags:
+      - identity
+  /api/admin/system/identity/pairings/{pairingID}:
+    get:
+      parameters:
+      - description: 配对 ID
+        in: path
+        name: pairingID
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/identity.PairingExchange'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "403":
+          description: Forbidden
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+      security:
+      - BearerAuth: []
+      summary: 查询统一认证配对状态
+      tags:
+      - identity
+  /api/admin/system/identity/revisions/{revisionID}:
+    patch:
+      consumes:
+      - application/json
+      parameters:
+      - description: Revision ID
+        in: path
+        name: revisionID
+        required: true
+        type: string
+      - description: 幂等键
+        in: header
+        name: Idempotency-Key
+        required: true
+        type: string
+      - description: 当前 Revision ETag
+        in: header
+        name: If-Match
+        required: true
+        type: string
+      - description: Gateway 本地策略
+        in: body
+        name: body
+        required: true
+        schema:
+          $ref: '#/definitions/httpapi.identityPolicyPatch'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/identity.Revision'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "403":
+          description: Forbidden
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "412":
+          description: Precondition Failed
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "428":
+          description: Precondition Required
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+      security:
+      - BearerAuth: []
+      summary: 修改统一认证 Draft 策略
+      tags:
+      - identity
+  /api/admin/system/identity/revisions/{revisionID}/activate:
+    post:
+      description: 在完整候选 Runtime 验证成功且本地 Break-glass Manager 可用后原子热切换。
+      parameters:
+      - description: Revision ID
+        in: path
+        name: revisionID
+        required: true
+        type: string
+      - description: 幂等键
+        in: header
+        name: Idempotency-Key
+        required: true
+        type: string
+      - description: 当前 Revision ETag
+        in: header
+        name: If-Match
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/identity.Revision'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "403":
+          description: Forbidden
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "412":
+          description: Precondition Failed
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "428":
+          description: Precondition Required
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+      security:
+      - BearerAuth: []
+      summary: 激活统一认证 Revision
+      tags:
+      - identity
+  /api/admin/system/identity/revisions/{revisionID}/rollback:
+    post:
+      parameters:
+      - description: Revision ID
+        in: path
+        name: revisionID
+        required: true
+        type: string
+      - description: 幂等键
+        in: header
+        name: Idempotency-Key
+        required: true
+        type: string
+      - description: 当前 Revision ETag
+        in: header
+        name: If-Match
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/identity.Revision'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "403":
+          description: Forbidden
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "412":
+          description: Precondition Failed
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "428":
+          description: Precondition Required
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+      security:
+      - BearerAuth: []
+      summary: 回滚统一认证 Revision
+      tags:
+      - identity
+  /api/admin/system/identity/revisions/{revisionID}/validate:
+    post:
+      parameters:
+      - description: Revision ID
+        in: path
+        name: revisionID
+        required: true
+        type: string
+      - description: 幂等键
+        in: header
+        name: Idempotency-Key
+        required: true
+        type: string
+      - description: 当前 Revision ETag
+        in: header
+        name: If-Match
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/identity.Revision'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "403":
+          description: Forbidden
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "412":
+          description: Precondition Failed
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "428":
+          description: Precondition Required
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "502":
+          description: Bad Gateway
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+      security:
+      - BearerAuth: []
+      summary: 验证统一认证 Revision
+      tags:
+      - identity
   /api/admin/tenants:
     get:
       description: 管理端返回网关租户列表。
@@ -5951,6 +6534,19 @@ paths:
       summary: 获取公开客户端自定义设置
       tags:
       - system
+  /api/v1/public/identity:
+    get:
+      description: 返回 Web 运行时需要的启用状态和非敏感登录、退出入口，不返回 Client、Secret 或内部标识。
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/httpapi.publicIdentityConfiguration'
+      summary: 获取公开统一认证状态
+      tags:
+      - identity
   /api/v1/reranks:
     post:
       consumes: