document-management/backend/openapi/paths/documents.yaml

Documents:
  get:
    operationId: listDocuments
    summary: 分页查询主案和子方案
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
      - {name: documentType, in: query, schema: {type: string, default: MAIN}}
      - {name: categoryId, in: query, schema: {$ref: '../components/schemas.yaml#/StringId'}}
      - name: includeDescendants
        in: query
        description: 与categoryId同时使用时，是否包含全部有效后代分类；默认false。
        schema: {type: boolean, default: false}
      - {name: keyword, in: query, schema: {type: string}}
      - {name: securityLevel, in: query, schema: {$ref: '../components/schemas.yaml#/SecurityLevel'}}
      - {name: visibilityType, in: query, schema: {$ref: '../components/schemas.yaml#/VisibilityType'}}
      - {name: status, in: query, schema: {$ref: '../components/schemas.yaml#/DocumentStatus'}}
      - $ref: '../components/parameters.yaml#/UpdatedFrom'
      - $ref: '../components/parameters.yaml#/UpdatedTo'
      - name: sortBy
        in: query
        schema:
          type: string
          enum: [documentName, createdAt, updatedAt, viewCount, downloadCount]
          default: updatedAt
      - {name: sortDirection, in: query, schema: {type: string, enum: [asc, desc], default: desc}}
      - {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
      - {name: pageSize, in: query, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
    responses:
      '200': {description: 方案分页, content: {application/json: {schema: {$ref: '../components/schemas.yaml#/DocumentPageResponse'}}}}
      '400': {$ref: '../components/responses.yaml#/InvalidArgument'}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '404': {$ref: '../components/responses.yaml#/NotFound'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}
  post:
    operationId: createDocument
    summary: 上传主案或子方案
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            additionalProperties: false
            required: [file, metadata]
            properties:
              file: {type: string, format: binary}
              metadata:
                type: string
                description: DocumentCreateMetadata的JSON字符串。
    responses:
      '201': {description: 上传成功, content: {application/json: {schema: {$ref: '../components/schemas.yaml#/DocumentDetailResponse'}}}}
      '400': {$ref: '../components/responses.yaml#/InvalidArgument'}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '404': {$ref: '../components/responses.yaml#/NotFound'}
      '409': {$ref: '../components/responses.yaml#/Conflict'}
      '413': {$ref: '../components/responses.yaml#/PayloadTooLarge'}
      '415': {$ref: '../components/responses.yaml#/UnsupportedMedia'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}

Document:
  parameters:
    - {name: id, in: path, required: true, schema: {$ref: '../components/schemas.yaml#/StringId'}}
  get:
    operationId: getDocument
    summary: 查询主案或子方案详情
    responses:
      '200': {description: 方案详情, content: {application/json: {schema: {$ref: '../components/schemas.yaml#/DocumentDetailResponse'}}}}
      '400': {$ref: '../components/responses.yaml#/InvalidArgument'}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '404': {$ref: '../components/responses.yaml#/NotFound'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}
  put:
    operationId: updateDocument
    summary: 编辑方案文档元数据
    requestBody:
      required: true
      content:
        application/json:
          schema: {$ref: '../components/schemas.yaml#/UpdateDocumentRequest'}
    responses:
      '200': {description: 编辑成功, content: {application/json: {schema: {$ref: '../components/schemas.yaml#/DocumentDetailResponse'}}}}
      '400': {$ref: '../components/responses.yaml#/InvalidArgument'}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '404': {$ref: '../components/responses.yaml#/NotFound'}
      '409': {$ref: '../components/responses.yaml#/Conflict'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}
  delete:
    operationId: deleteDocument
    summary: 逻辑删除方案文档
    parameters:
      - {name: rowVersion, in: query, required: true, schema: {type: integer, minimum: 0}}
    responses:
      '200': {description: 删除成功, content: {application/json: {schema: {$ref: '../components/schemas.yaml#/DeleteDocumentResponse'}}}}
      '400': {$ref: '../components/responses.yaml#/InvalidArgument'}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '404': {$ref: '../components/responses.yaml#/NotFound'}
      '409': {$ref: '../components/responses.yaml#/Conflict'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}

SubPlans:
  parameters:
    - {name: id, in: path, required: true, schema: {$ref: '../components/schemas.yaml#/StringId'}}
  get:
    operationId: listMainPlanSubPlans
    summary: 查询主案的直接子方案
    parameters:
      - {name: keyword, in: query, schema: {type: string}}
      - {name: status, in: query, schema: {$ref: '../components/schemas.yaml#/DocumentStatus'}}
      - $ref: '../components/parameters.yaml#/UpdatedFrom'
      - $ref: '../components/parameters.yaml#/UpdatedTo'
      - name: sortBy
        in: query
        schema: {type: string, enum: [documentName, createdAt, updatedAt, viewCount, downloadCount], default: updatedAt}
      - {name: sortDirection, in: query, schema: {type: string, enum: [asc, desc], default: desc}}
      - {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
      - {name: pageSize, in: query, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
    responses:
      '200': {description: 子方案分页, content: {application/json: {schema: {$ref: '../components/schemas.yaml#/DocumentPageResponse'}}}}
      '400': {$ref: '../components/responses.yaml#/InvalidArgument'}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '404': {$ref: '../components/responses.yaml#/NotFound'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}

Attachments:
  get:
    operationId: listAttachments
    summary: ADMIN分页查询独立共享附件库
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
      - {name: keyword, in: query, schema: {type: string}}
      - {name: attachmentType, in: query, schema: {$ref: '../components/schemas.yaml#/AttachmentType'}}
      - {name: fileExtension, in: query, schema: {type: string}}
      - $ref: '../components/parameters.yaml#/UpdatedFrom'
      - $ref: '../components/parameters.yaml#/UpdatedTo'
      - name: sortBy
        in: query
        schema: {type: string, enum: [documentName, createdAt, updatedAt, viewCount, downloadCount], default: updatedAt}
      - {name: sortDirection, in: query, schema: {type: string, enum: [asc, desc], default: desc}}
      - {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
      - {name: pageSize, in: query, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
    responses:
      '200': {description: 附件分页, content: {application/json: {schema: {$ref: '../components/schemas.yaml#/DocumentPageResponse'}}}}
      '400': {$ref: '../components/responses.yaml#/InvalidArgument'}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '404': {$ref: '../components/responses.yaml#/NotFound'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}
  post:
    operationId: createAttachment
    summary: 上传共享附件
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            additionalProperties: false
            required: [file, metadata]
            properties:
              file: {type: string, format: binary}
              metadata:
                type: string
                description: AttachmentCreateMetadata的JSON字符串。
    responses:
      '201': {description: 上传成功, content: {application/json: {schema: {$ref: '../components/schemas.yaml#/DocumentDetailResponse'}}}}
      '400': {$ref: '../components/responses.yaml#/InvalidArgument'}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '413': {$ref: '../components/responses.yaml#/PayloadTooLarge'}
      '415': {$ref: '../components/responses.yaml#/UnsupportedMedia'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}

Attachment:
  parameters:
    - {name: id, in: path, required: true, schema: {$ref: '../components/schemas.yaml#/StringId'}}
  get:
    operationId: getAttachment
    summary: 查询共享附件详情
    responses:
      '200': {description: 附件详情, content: {application/json: {schema: {$ref: '../components/schemas.yaml#/DocumentDetailResponse'}}}}
      '400': {$ref: '../components/responses.yaml#/InvalidArgument'}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '404': {$ref: '../components/responses.yaml#/NotFound'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}
  put:
    operationId: updateAttachment
    summary: 编辑共享附件元数据
    requestBody:
      required: true
      content:
        application/json:
          schema: {$ref: '../components/schemas.yaml#/UpdateAttachmentRequest'}
    responses:
      '200': {description: 编辑成功, content: {application/json: {schema: {$ref: '../components/schemas.yaml#/DocumentDetailResponse'}}}}
      '400': {$ref: '../components/responses.yaml#/InvalidArgument'}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '404': {$ref: '../components/responses.yaml#/NotFound'}
      '409': {$ref: '../components/responses.yaml#/Conflict'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}
  delete:
    operationId: deleteAttachment
    summary: 逻辑删除共享附件
    parameters:
      - {name: rowVersion, in: query, required: true, schema: {type: integer, minimum: 0}}
    responses:
      '200': {description: 删除成功, content: {application/json: {schema: {$ref: '../components/schemas.yaml#/DeleteDocumentResponse'}}}}
      '400': {$ref: '../components/responses.yaml#/InvalidArgument'}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '404': {$ref: '../components/responses.yaml#/NotFound'}
      '409': {$ref: '../components/responses.yaml#/Conflict'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}

DocumentBatchImport:
  post:
    operationId: batchImportDocuments
    summary: 批量导入主案和子方案
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            $ref: '../components/schemas.yaml#/BatchImportMultipart'
    responses:
      '200': {description: 逐文件导入结果, content: {application/json: {schema: {$ref: '../components/schemas.yaml#/BatchImportResponse'}}}}
      '400': {$ref: '../components/responses.yaml#/InvalidArgument'}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '413': {$ref: '../components/responses.yaml#/PayloadTooLarge'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}

AttachmentBatchImport:
  post:
    operationId: batchImportAttachments
    summary: 批量导入共享附件
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            $ref: '../components/schemas.yaml#/BatchImportMultipart'
    responses:
      '200': {description: 逐文件导入结果, content: {application/json: {schema: {$ref: '../components/schemas.yaml#/BatchImportResponse'}}}}
      '400': {$ref: '../components/responses.yaml#/InvalidArgument'}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '413': {$ref: '../components/responses.yaml#/PayloadTooLarge'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}

DocumentPreview:
  parameters:
    - {name: id, in: path, required: true, schema: {$ref: '../components/schemas.yaml#/StringId'}}
  get:
    operationId: previewDocument
    summary: PDF直接预览；DOC、DOCX由LibreOffice离线转换为PDF后预览
    responses:
      '200':
        description: PDF文件流（PDF原文件或DOC/DOCX转换后的PDF）
        headers:
          X-Request-Id: {schema: {type: string, format: uuid}}
        content:
          application/pdf: {schema: {type: string, format: binary}}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '404': {$ref: '../components/responses.yaml#/NotFound'}
      '415': {$ref: '../components/responses.yaml#/UnsupportedMedia'}
      '502': {$ref: '../components/responses.yaml#/PreviewConversionFailed'}
      '503': {$ref: '../components/responses.yaml#/PreviewConverterUnavailable'}
      '504': {$ref: '../components/responses.yaml#/PreviewConversionTimeout'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}

DocumentDownload:
  parameters:
    - {name: id, in: path, required: true, schema: {$ref: '../components/schemas.yaml#/StringId'}}
  get:
    operationId: downloadDocument
    summary: 下载原始文档
    responses:
      '200':
        description: 原始文件流
        headers:
          X-Request-Id: {schema: {type: string, format: uuid}}
        content:
          application/octet-stream: {schema: {type: string, format: binary}}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '404': {$ref: '../components/responses.yaml#/NotFound'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}

AttachmentMainPlans:
  parameters:
    - {name: id, in: path, required: true, schema: {$ref: '../components/schemas.yaml#/StringId'}}
  get:
    operationId: listAttachmentMainPlans
    summary: 查询共享附件挂载的可见主案
    responses:
      '200': {description: 主案简要集合, content: {application/json: {schema: {$ref: '../components/schemas.yaml#/MainPlanBriefCollectionResponse'}}}}
      '400': {$ref: '../components/responses.yaml#/InvalidArgument'}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '404': {$ref: '../components/responses.yaml#/NotFound'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}

MainPlanAttachments:
  parameters:
    - {name: id, in: path, required: true, schema: {$ref: '../components/schemas.yaml#/StringId'}}
  get:
    operationId: listMainPlanAttachments
    summary: 查询主案已挂载共享附件
    parameters:
      - {name: keyword, in: query, schema: {type: string}}
      - {name: attachmentType, in: query, schema: {$ref: '../components/schemas.yaml#/AttachmentType'}}
      - $ref: '../components/parameters.yaml#/UpdatedFrom'
      - $ref: '../components/parameters.yaml#/UpdatedTo'
      - {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
      - {name: pageSize, in: query, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
    responses:
      '200': {description: 挂载附件分页, content: {application/json: {schema: {$ref: '../components/schemas.yaml#/AttachmentBindingPageResponse'}}}}
      '400': {$ref: '../components/responses.yaml#/InvalidArgument'}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '404': {$ref: '../components/responses.yaml#/NotFound'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}

MainPlanAttachmentBinding:
  parameters:
    - {name: id, in: path, required: true, schema: {$ref: '../components/schemas.yaml#/StringId'}}
  post:
    operationId: bindMainPlanAttachments
    summary: 批量挂载共享附件到主案
    requestBody:
      required: true
      content:
        application/json:
          schema: {$ref: '../components/schemas.yaml#/BindAttachmentsRequest'}
    responses:
      '200': {description: 挂载结果, content: {application/json: {schema: {$ref: '../components/schemas.yaml#/BindAttachmentsResponse'}}}}
      '400': {$ref: '../components/responses.yaml#/InvalidArgument'}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '404': {$ref: '../components/responses.yaml#/NotFound'}
      '409': {$ref: '../components/responses.yaml#/Conflict'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}

MainPlanAttachment:
  parameters:
    - {name: id, in: path, required: true, schema: {$ref: '../components/schemas.yaml#/StringId'}}
    - {name: attachmentId, in: path, required: true, schema: {$ref: '../components/schemas.yaml#/StringId'}}
  delete:
    operationId: unbindMainPlanAttachment
    summary: 解除主案和共享附件的挂载
    parameters:
      - {name: mainPlanRowVersion, in: query, required: true, schema: {type: integer, minimum: 0}}
    responses:
      '200': {description: 解除挂载结果, content: {application/json: {schema: {$ref: '../components/schemas.yaml#/UnbindAttachmentResponse'}}}}
      '400': {$ref: '../components/responses.yaml#/InvalidArgument'}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '404': {$ref: '../components/responses.yaml#/NotFound'}
      '409': {$ref: '../components/responses.yaml#/Conflict'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}

DocumentPermissions:
  parameters:
    - {name: id, in: path, required: true, schema: {$ref: '../components/schemas.yaml#/StringId'}}
  get:
    operationId: getDocumentPermissions
    summary: 查询主案权限或子方案继承权限
    responses:
      '200': {description: 权限详情, content: {application/json: {schema: {$ref: '../components/schemas.yaml#/PermissionDetailResponse'}}}}
      '400': {$ref: '../components/responses.yaml#/InvalidArgument'}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '404': {$ref: '../components/responses.yaml#/NotFound'}
      '409': {$ref: '../components/responses.yaml#/Conflict'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}
  put:
    operationId: saveDocumentPermissions
    summary: 全量保存主案权限
    requestBody:
      required: true
      content:
        application/json:
          schema: {$ref: '../components/schemas.yaml#/SavePermissionsRequest'}
    responses:
      '200': {description: 保存后的权限详情, content: {application/json: {schema: {$ref: '../components/schemas.yaml#/PermissionDetailResponse'}}}}
      '400': {$ref: '../components/responses.yaml#/InvalidArgument'}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '404': {$ref: '../components/responses.yaml#/NotFound'}
      '409': {$ref: '../components/responses.yaml#/Conflict'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}