feat: 完成P13治理收尾并创建P14执行合同（Issue: P13-1,P13-2,P13-3,P13-4,P13-5,P13-6,P13-7,P13-8,P14-0）

server/src/routes/invoicePool/verification.js

@@ -2,6 +2,7 @@ const { z } = require("zod");
 
 const { AppError } = require("../../utils/AppError");
 const { sendData } = require("../../utils/reply");
+const { buildDataEnvelopeSchema, buildErrorEnvelopeSchema, UUID_PARAM_SCHEMA } = require("../../utils/openapi");
 const { buildAuditLogData } = require("../../utils/audit");
 const { getProvider, evaluateVerificationAccess } = require("../../services/verification");
 
@@ -9,6 +10,27 @@ const { mapVerificationRecord } = require("./shared/mappers");
 const { parseVerificationListQuery } = require("./shared/schemas");
 const { triggerVerificationJob } = require("./shared/helpers");
 
+const VERIFY_RESPONSE_SCHEMA = {
+  type: "object",
+  required: ["invoiceId", "verificationId", "provider", "triggerMode"],
+  properties: {
+    invoiceId: { type: "string", format: "uuid" },
+    verificationId: { type: "string", format: "uuid" },
+    provider: { type: "string" },
+    triggerMode: { type: "string" },
+  },
+};
+
+const RETRY_RESPONSE_SCHEMA = {
+  type: "object",
+  required: ["invoiceId", "verificationId", "status"],
+  properties: {
+    invoiceId: { type: "string", format: "uuid" },
+    verificationId: { type: "string", format: "uuid" },
+    status: { type: "string", enum: ["pending"] },
+  },
+};
+
 function throwVerificationDisabled(reason) {
   throw new AppError({
     code: "VALID_001",
@@ -89,6 +111,31 @@ function registerInvoiceVerificationRoutes(fastify) {
     "/invoice-pool/:id/verify",
     {
       preHandler: fastify.requirePermission("invoice.verify"),
+      schema: {
+        tags: ["invoice-verification"],
+        summary: "触发发票验真",
+        security: [{ bearerAuth: [] }],
+        params: UUID_PARAM_SCHEMA,
+        response: {
+          200: buildDataEnvelopeSchema(VERIFY_RESPONSE_SCHEMA, "验真任务已创建"),
+          400: buildErrorEnvelopeSchema({
+            description: "参数校验失败",
+            codeExample: "VALID_001",
+            messageExample: "参数校验失败",
+          }),
+          404: buildErrorEnvelopeSchema({
+            description: "票据不存在",
+            codeExample: "SYS_404",
+            messageExample: "Not Found",
+          }),
+          409: buildErrorEnvelopeSchema({
+            description: "触发受限（开关/频控/并发）",
+            codeExample: "VALID_001",
+            messageExample: "参数校验失败",
+            detailsExample: { verification: "disabled", featureFlag: "env_hard_off" },
+          }),
+        },
+      },
     },
     async (request, reply) => {
       const parsedInvoiceId = z.string().uuid().safeParse(request.params?.id);
@@ -319,6 +366,31 @@ function registerInvoiceVerificationRoutes(fastify) {
     "/invoice-pool/:id/verification/retry",
     {
       preHandler: fastify.requirePermission("invoice.verify"),
+      schema: {
+        tags: ["invoice-verification"],
+        summary: "重试发票验真",
+        security: [{ bearerAuth: [] }],
+        params: UUID_PARAM_SCHEMA,
+        response: {
+          200: buildDataEnvelopeSchema(RETRY_RESPONSE_SCHEMA, "验真重试任务已创建"),
+          400: buildErrorEnvelopeSchema({
+            description: "参数校验失败",
+            codeExample: "VALID_001",
+            messageExample: "参数校验失败",
+          }),
+          404: buildErrorEnvelopeSchema({
+            description: "票据不存在",
+            codeExample: "SYS_404",
+            messageExample: "Not Found",
+          }),
+          409: buildErrorEnvelopeSchema({
+            description: "重试受限（开关/频控/重试次数）",
+            codeExample: "VALID_001",
+            messageExample: "参数校验失败",
+            detailsExample: { verification: "too_frequent" },
+          }),
+        },
+      },
     },
     async (request, reply) => {
       const parsedInvoiceId = z.string().uuid().safeParse(request.params?.id);