docs(auth): document authority recovery contract

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

docs/verification/issue-640.md

@@ -5,7 +5,7 @@
 - Issue: <https://github.com/iflytek/skillhub/issues/640>
 - Pull request: <https://github.com/iflytek/skillhub/pull/643>
 - Integration target: `big-main`
-- Validation environment: dedicated Hong Kong test server
+- Validation environment: isolated, production-equivalent test deployment
 - Production/default branch: not modified
 
 This record covers P1 / PR 1 from
@@ -15,7 +15,7 @@ plugins remain outside this PR.
 
 ## Automated gates
 
-The following checks ran on the Hong Kong test server:
+The following checks ran against the isolated test deployment:
 
 | Gate | Result |
 |---|---|
@@ -27,11 +27,9 @@ The following checks ran on the Hong Kong test server:
 | DCO | passed |
 | CLA | passed |
 
-The server image used for pre-integration runtime validation was
-`skillhub-server:identity-core-9818333c`, image ID
-`sha256:a9055606ad2a551f12319e66f7056e4bda072a8e14a238882cdbdbeb871cf6c8`.
 The clean PR branch was rebuilt from the latest `big-main`; its unified-identity
-file tree is identical to the validated feature tree.
+file tree is identical to the validated feature tree. Runtime artifact identity
+and operational logs are intentionally omitted from the public repository.
 
 ## PostgreSQL and runtime scenarios
 

server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/admin/IdentityProviderAdminController.java

@@ -7,6 +7,9 @@ import com.iflytek.skillhub.dto.ApiResponseFactory;
 import com.iflytek.skillhub.dto.IdentityProviderAuthorityRecoveryResponse;
 import com.iflytek.skillhub.service.AuditRequestContext;
 import com.iflytek.skillhub.service.IdentityProviderAdminAppService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import jakarta.servlet.http.HttpServletRequest;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
@@ -31,6 +34,27 @@ public class IdentityProviderAdminController extends BaseApiController {
         this.providerAdminAppService = providerAdminAppService;
     }
 
+    @Operation(
+            summary = "Recover an identity provider authority lock",
+            description = "Restores a provider from AUTHORITY_MISMATCH only when the current "
+                    + "trusted configuration matches its pinned authority.")
+    @ApiResponses({
+            @io.swagger.v3.oas.annotations.responses.ApiResponse(
+                    responseCode = "200",
+                    description = "Provider recovered or already ready"),
+            @io.swagger.v3.oas.annotations.responses.ApiResponse(
+                    responseCode = "403",
+                    description = "Caller is not a super administrator",
+                    content = @Content),
+            @io.swagger.v3.oas.annotations.responses.ApiResponse(
+                    responseCode = "404",
+                    description = "Enabled provider configuration not found",
+                    content = @Content),
+            @io.swagger.v3.oas.annotations.responses.ApiResponse(
+                    responseCode = "409",
+                    description = "Current configuration does not match the pinned authority",
+                    content = @Content)
+    })
     @PostMapping("/{providerCode}/authority/recover")
     @PreAuthorize("hasRole('SUPER_ADMIN')")
     public ApiResponse<IdentityProviderAuthorityRecoveryResponse>

web/src/api/generated/schema.d.ts

@@ -1629,6 +1629,10 @@ export interface paths {
         };
         get?: never;
         put?: never;
+        /**
+         * Recover an identity provider authority lock
+         * @description Restores a provider from AUTHORITY_MISMATCH only when the current trusted configuration matches its pinned authority.
+         */
         post: operations["recoverSameAuthority"];
         delete?: never;
         options?: never;
@@ -8367,7 +8371,7 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description OK */
+            /** @description Provider recovered or already ready */
             200: {
                 headers: {
                     [name: string]: unknown;
@@ -8376,6 +8380,27 @@ export interface operations {
                     "*/*": components["schemas"]["ApiResponseIdentityProviderAuthorityRecoveryResponse"];
                 };
             };
+            /** @description Caller is not a super administrator */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Enabled provider configuration not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Current configuration does not match the pinned authority */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
         };
     };
     verify: {