fix(file): support optional legal ID and order import files

2026-09-01 19:52:42 +08:00
parent 2ec8fcb886
commit b4e496e9cb
13 changed files with 530 additions and 57 deletions
@@ -0,0 +1,118 @@
+openapi: 3.0.3
+info:
+  title: Order Batch Import File Internal API
+  version: 1.0.0
+  description: >-
+    Order批量导入源文件与错误报告均为客户所有的不可变XLSX对象；businessId固定为Order生成的batchNo。
+    File只保存并校验对象归属，不复制导入任务状态。
+  x-lifecycle-owner: ORDER
+  x-file-object-semantics: IMMUTABLE_CREATE_ONLY
+paths:
+  /internal/file/v1/business-files/{tenantId}/{businessType}/{batchNo}:
+    post:
+      summary: Order上传批量导入源文件或错误报告
+      security: [{internalServiceToken: []}]
+      parameters:
+        - {$ref: '#/components/parameters/OperatorId'}
+        - {$ref: '#/components/parameters/TenantId'}
+        - {$ref: '#/components/parameters/BusinessType'}
+        - {$ref: '#/components/parameters/BatchNo'}
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [file]
+              properties:
+                file:
+                  type: string
+                  format: binary
+                  description: 有效XLSX文件，最大5MiB
+      responses:
+        '200': {$ref: '#/components/responses/Metadata'}
+  /internal/file/v1/business-files/{tenantId}/{businessType}/{batchNo}/{fileId}:
+    get:
+      summary: Order精确校验批量导入文件元数据
+      security: [{internalServiceToken: []}]
+      parameters:
+        - {$ref: '#/components/parameters/TenantId'}
+        - {$ref: '#/components/parameters/BusinessType'}
+        - {$ref: '#/components/parameters/BatchNo'}
+        - {$ref: '#/components/parameters/FileId'}
+      responses:
+        '200': {$ref: '#/components/responses/Metadata'}
+  /internal/file/v1/business-files/{tenantId}/{businessType}/{batchNo}/{fileId}/content:
+    get:
+      summary: Order下载批量导入源文件或错误报告
+      security: [{internalServiceToken: []}]
+      parameters:
+        - {$ref: '#/components/parameters/TenantId'}
+        - {$ref: '#/components/parameters/BusinessType'}
+        - {$ref: '#/components/parameters/BatchNo'}
+        - {$ref: '#/components/parameters/FileId'}
+      responses:
+        '200':
+          description: 精确归属的XLSX附件；错误客户、类别、batchNo或fileId不得命中
+          headers:
+            Cache-Control: {schema: {type: string, enum: [no-store]}}
+            Content-Disposition: {schema: {type: string}}
+          content:
+            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
+              schema: {type: string, format: binary}
+components:
+  securitySchemes:
+    internalServiceToken: {type: apiKey, in: header, name: X-Internal-Service-Token}
+  parameters:
+    OperatorId:
+      name: X-Operator-Id
+      in: header
+      required: true
+      schema: {$ref: '#/components/schemas/Id'}
+    TenantId:
+      name: tenantId
+      in: path
+      required: true
+      description: 当前客户ID，必须大于0
+      schema: {$ref: '#/components/schemas/Id'}
+    BusinessType:
+      name: businessType
+      in: path
+      required: true
+      schema: {type: string, enum: [ORDER_BATCH_IMPORT_SOURCE, ORDER_BATCH_IMPORT_ERROR_REPORT]}
+    BatchNo:
+      name: batchNo
+      in: path
+      required: true
+      schema: {type: string, pattern: '^OBI-[0-9A-F]{20}$'}
+    FileId:
+      name: fileId
+      in: path
+      required: true
+      schema: {$ref: '#/components/schemas/Id'}
+  responses:
+    Metadata:
+      description: 客户批量导入文件元数据
+      content:
+        application/json:
+          schema:
+            type: object
+            required: [code, data]
+            properties:
+              code: {type: string, enum: ['200']}
+              data: {$ref: '#/components/schemas/Metadata'}
+  schemas:
+    Id: {type: string, pattern: '^[1-9][0-9]*$'}
+    Metadata:
+      type: object
+      required: [fileId, ownerScope, tenantId, businessType, businessId, fileName, sha256, contentType, sizeBytes]
+      properties:
+        fileId: {$ref: '#/components/schemas/Id'}
+        ownerScope: {type: string, enum: [CUSTOMER]}
+        tenantId: {$ref: '#/components/schemas/Id'}
+        businessType: {type: string, enum: [ORDER_BATCH_IMPORT_SOURCE, ORDER_BATCH_IMPORT_ERROR_REPORT]}
+        businessId: {type: string, pattern: '^OBI-[0-9A-F]{20}$'}
+        fileName: {type: string}
+        sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
+        contentType: {type: string, enum: [application/vnd.openxmlformats-officedocument.spreadsheetml.sheet]}
+        sizeBytes: {type: integer, format: int64, minimum: 1, maximum: 5242880}
@@ -0,0 +1,113 @@
+openapi: 3.0.3
+info:
+  title: Qualification Required Package API
+  version: 1.0.0
+  description: 营业执照为必填资质；法人身份证为选填资质，缺省时不创建、不替换法人身份证记录。
+paths:
+  /api/merchant/v1/files/qualifications/required-package:
+    post:
+      summary: 客户上传必需资质包
+      description: 需要 merchant:qualification:upload；营业执照必填，法人身份证选填。
+      security: [{bearerAuth: []}]
+      parameters:
+        - {$ref: '#/components/parameters/UnifiedSocialCreditCode'}
+        - {$ref: '#/components/parameters/BusinessLicenseValidTo'}
+        - {$ref: '#/components/parameters/LegalPersonIdValidTo'}
+        - {$ref: '#/components/parameters/ReplaceBusinessLicense'}
+        - {$ref: '#/components/parameters/ReplaceLegalPersonId'}
+      requestBody: {$ref: '#/components/requestBodies/RequiredPackage'}
+      responses:
+        '200': {$ref: '#/components/responses/PackageResult'}
+  /api/platform/v1/files/qualifications/{tenantId}/required-package:
+    post:
+      summary: 平台为客户上传必需资质包
+      description: 需要 platform:customer:create 或 platform:customer:edit；营业执照必填，法人身份证选填。
+      security: [{bearerAuth: []}]
+      parameters:
+        - {$ref: '#/components/parameters/TenantId'}
+        - {$ref: '#/components/parameters/UnifiedSocialCreditCode'}
+        - {$ref: '#/components/parameters/BusinessLicenseValidTo'}
+        - {$ref: '#/components/parameters/LegalPersonIdValidTo'}
+        - {$ref: '#/components/parameters/ReplaceBusinessLicense'}
+        - {$ref: '#/components/parameters/ReplaceLegalPersonId'}
+      requestBody: {$ref: '#/components/requestBodies/RequiredPackage'}
+      responses:
+        '200': {$ref: '#/components/responses/PackageResult'}
+components:
+  securitySchemes:
+    bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
+  parameters:
+    TenantId:
+      name: tenantId
+      in: path
+      required: true
+      schema: {$ref: '#/components/schemas/Id'}
+    UnifiedSocialCreditCode:
+      name: unifiedSocialCreditCode
+      in: query
+      required: true
+      schema: {type: string, pattern: '^[0-9A-Za-z]{18}$'}
+    BusinessLicenseValidTo:
+      name: businessLicenseValidTo
+      in: query
+      required: false
+      schema: {type: string, format: date}
+    LegalPersonIdValidTo:
+      name: legalPersonIdValidTo
+      in: query
+      required: false
+      description: 仅上传legalPersonId时允许填写
+      schema: {type: string, format: date}
+    ReplaceBusinessLicense:
+      name: replaceBusinessLicense
+      in: query
+      required: false
+      schema: {type: boolean, default: false}
+    ReplaceLegalPersonId:
+      name: replaceLegalPersonId
+      in: query
+      required: false
+      description: 未上传legalPersonId时必须为false
+      schema: {type: boolean, default: false}
+  requestBodies:
+    RequiredPackage:
+      required: true
+      content:
+        multipart/form-data:
+          schema:
+            type: object
+            required: [businessLicense]
+            properties:
+              businessLicense:
+                type: string
+                format: binary
+                description: 营业执照，必填；PDF/JPG/PNG，最大5MB
+              legalPersonId:
+                type: string
+                format: binary
+                nullable: true
+                description: 法人身份证，选填；PDF/JPG/PNG，最大5MB
+  responses:
+    PackageResult:
+      description: 资质包上传结果
+      content:
+        application/json:
+          schema:
+            type: object
+            required: [code, data]
+            properties:
+              code: {type: string, enum: ['200']}
+              data: {$ref: '#/components/schemas/PackageUploadResult'}
+  schemas:
+    Id: {type: string, pattern: '^[1-9][0-9]*$'}
+    PackageUploadResult:
+      type: object
+      required: [businessLicenseQualificationId, tenantStatus, businessLicenseDocumentUrl]
+      properties:
+        businessLicenseQualificationId: {$ref: '#/components/schemas/Id'}
+        legalPersonIdQualificationId:
+          allOf: [{$ref: '#/components/schemas/Id'}]
+          nullable: true
+        tenantStatus: {type: string}
+        businessLicenseDocumentUrl: {type: string, minLength: 1}
+        legalPersonIdDocumentUrl: {type: string, nullable: true}