document-management/backend/openapi/paths/borrow-settings.yaml

# 契约1.54 审批相关设置：调阅说明与调阅审批单模板（sys_setting 通用键值表，
# 行不存在=未设置；模板 PDF 落盘存储根 settings/borrow-template.pdf）。

BorrowSettings:
  get:
    operationId: getBorrowSettings
    summary: 读取审批相关设置（调阅说明与模板文件名）
    description: 契约1.54。任意登录用户可调（调阅对话框与系统管理页共用）；响应data={notice,templateFileName}，null=未设置。
    security:
      - BearerAuth: []
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200':
        description: 审批设置（null=未设置）
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [notice, templateFileName]
              properties:
                notice: {type: [string, 'null'], description: 调阅说明文本，最长4000字，null=未设置}
                templateFileName: {type: [string, 'null'], description: 已上传模板的原始文件名，null=未上传}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}
  put:
    operationId: updateBorrowNotice
    summary: 保存调阅说明
    description: 契约1.54。manage_system管理位；请求体必含且仅含notice（传null或空白即清空；超过4000字返回400 INVALID_ARGUMENT「调阅说明不能超过4000字」）；审计BORROW_SETTINGS_UPDATE（detail kind=notice，targetType=SYSTEM）。
    security:
      - BearerAuth: []
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            required: [notice]
            properties:
              notice: {type: [string, 'null'], description: 调阅说明，null/空白即清空}
    responses:
      '200': {description: 已保存（data=null）}
      '400': {$ref: '../components/responses.yaml#/InvalidArgument'}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}

BorrowTemplate:
  post:
    operationId: uploadBorrowTemplate
    summary: 上传调阅审批单模板（PDF，覆盖替换）
    description: 契约1.54。manage_system管理位；multipart file必须，仅PDF（415 UNSUPPORTED_FILE_TYPE「调阅审批单模板只允许PDF文件」）且不超过DMS_MAX_FILE_SIZE（413 PAYLOAD_TOO_LARGE，流式计量含魔数校验）；落盘存储根settings/borrow-template.pdf固定路径（临时文件+原子替换），元数据（原始文件名/字节数）存sys_setting的borrow.template行；响应data={templateFileName}；审计BORROW_SETTINGS_UPDATE（detail kind=template-upload，targetType=SYSTEM）。
    security:
      - BearerAuth: []
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            additionalProperties: false
            required: [file]
            properties:
              file: {type: string, format: binary, description: 模板PDF文件}
    responses:
      '200':
        description: 上传结果
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [templateFileName]
              properties:
                templateFileName: {type: string, description: 已保存模板的原始文件名}
      '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'}
  delete:
    operationId: deleteBorrowTemplate
    summary: 清除调阅审批单模板
    description: 契约1.54。manage_system管理位；删除sys_setting的borrow.template行并删除盘上模板文件（未上传视为成功）；审计BORROW_SETTINGS_UPDATE（detail kind=template-delete，targetType=SYSTEM）。
    security:
      - BearerAuth: []
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200': {description: 已清除（data=null）}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '403': {$ref: '../components/responses.yaml#/Forbidden'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}
  get:
    operationId: downloadBorrowTemplate
    summary: 下载调阅审批单模板
    description: 契约1.54。任意登录用户可调（调阅对话框「下载模板」入口）；PDF附件直出（Content-Disposition filename*=UTF-8''编码原始文件名）；未上传返回404 NOT_FOUND「调阅审批单模板未上传」。
    security:
      - BearerAuth: []
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200': {description: 模板PDF二进制, 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'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}