openapi: 3.0.3
info:
  title: Printing API
  description: |
    印染模块接口文档，包含 PrintingOrder（印染订单）和 PrintingJob（印染款式明细）的 CRUD 和自定义动作。
    所有接口仅允许印染工厂用户访问（IsPrintingFactory）。
  version: '1.0.0'
servers:
  - url: /api/v1
    description: 本地开发 API 前缀
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    PrintingOrder:
      type: object
      properties:
        id:
          type: integer
          description: 订单 ID
        human_id:
          type: string
          description: 由系统生成的人类可读编号（格式: YYYYMMDD000001）
          example: "20251112000001"
        customer:
          type: integer
          description: 客户 ID
        customer_name:
          type: string
          description: 客户名称
        customer_phone:
          type: string
          description: 客户电话
        customer_address:
          type: string
          description: 客户地址
        fabric:
          type: string
          description: 面料
          example: "纯棉布料"
        width:
          type: string
          description: 幅宽
          example: "150cm"
        is_urgent:
          type: boolean
          description: 是否紧急
          default: false
        area:
          type: string
          description: 地区
          example: "广州"
        address:
          type: string
          description: 地址
          example: "白云区xxx"
        fabric_source:
          type: string
          description: 布料来源
          example: "客户提供"
        is_fabric_received:
          type: boolean
          description: 布料是否已收
          default: false
        craft:
          type: string
          description: 工艺
          example: "活性印花"
        description:
          type: string
          description: 订单描述
        outgoing_date:
          type: string
          format: date
          description: 出货日期
          example: "2025-11-20"
        curve:
          type: string
          description: 曲线
        new_curve:
          type: string
          description: 新加曲线
        position:
          type: string
          description: 位置
        printing_warn:
          type: string
          description: 打印注意事项
        rolling_warn:
          type: string
          description: 滚筒注意事项
        production_warn:
          type: string
          description: 生产注意事项
        is_invalid:
          type: boolean
          description: 是否作废
          default: false
        created_at:
          type: string
          format: date-time
          description: 创建时间
        updated_at:
          type: string
          format: date-time
          description: 更新时间
      required: [customer, fabric, width]
    PrintingOrderCreate:
      type: object
      properties:
        customer:
          type: integer
          description: 客户 ID
        fabric:
          type: string
          description: 面料
          example: "纯棉布料"
        width:
          type: string
          description: 幅宽
          example: "150cm"
        is_urgent:
          type: boolean
          description: 是否紧急
          default: false
        area:
          type: string
          description: 地区
          example: "广州"
        address:
          type: string
          description: 地址
          example: "白云区xxx"
        fabric_source:
          type: string
          description: 布料来源
          example: "客户提供"
        is_fabric_received:
          type: boolean
          description: 布料是否已收
          default: false
        craft:
          type: string
          description: 工艺
          example: "活性印花"
        description:
          type: string
          description: 订单描述
        outgoing_date:
          type: string
          format: date
          description: 出货日期
          example: "2025-11-20"
        curve:
          type: string
          description: 曲线
        new_curve:
          type: string
          description: 新加曲线
        position:
          type: string
          description: 位置
        printing_warn:
          type: string
          description: 打印注意事项
        rolling_warn:
          type: string
          description: 滚筒注意事项
        production_warn:
          type: string
          description: 生产注意事项
        is_invalid:
          type: boolean
          description: 是否作废
          default: false
      required: [customer, fabric, width]
    PrintingJob:
      type: object
      properties:
        id:
          type: integer
          description: 款式明细 ID
        printing_order:
          type: integer
          description: 印染订单 ID
        printing_order_id:
          type: string
          description: 印染订单人类可读编号
          example: "20251112000001"
        product:
          type: integer
          description: 产品 ID
        product_name:
          type: string
          description: 产品名称
          example: "测试产品"
        product_code:
          type: string
          description: 产品编号
          example: "TEST001"
        quantity:
          type: integer
          description: 数量（必须 > 0）
          example: 100
          minimum: 1
        unit:
          type: string
          description: 单位
          example: "米"
        size:
          type: string
          description: 一段尺寸
          example: "50*60"
        pieces:
          type: integer
          description: 件数（必须 > 0）
          example: 10
          minimum: 1
        description:
          type: string
          description: 备注
        created_at:
          type: string
          format: date-time
          description: 创建时间
        updated_at:
          type: string
          format: date-time
          description: 更新时间
      required: [printing_order, product, quantity, unit, size, pieces]
    PrintingJobCreate:
      type: object
      properties:
        printing_order:
          type: integer
          description: 印染订单 ID
        product:
          type: integer
          description: 产品 ID
        quantity:
          type: integer
          description: 数量（必须 > 0）
          example: 100
          minimum: 1
        unit:
          type: string
          description: 单位
          example: "米"
        size:
          type: string
          description: 一段尺寸
          example: "50*60"
        pieces:
          type: integer
          description: 件数（必须 > 0）
          example: 10
          minimum: 1
        description:
          type: string
          description: 备注
      required: [printing_order, product, quantity, unit, size, pieces]
  parameters:
    limit:
      name: limit
      in: query
      schema:
        type: integer
      description: 返回条目上限（分页）
    offset:
      name: offset
      in: query
      schema:
        type: integer
      description: 分页偏移
    search:
      name: search
      in: query
      schema:
        type: string
      description: 全文搜索关键字
    ordering:
      name: ordering
      in: query
      schema:
        type: string
      description: 排序字段，例如 id 或 -id
paths:
  /printing-orders/:
    get:
      summary: 获取印染订单列表
      description: 支持过滤（customer, is_urgent, is_fabric_received, is_invalid, area, outgoing_date_from/to, created_date_from/to）、search、ordering 和分页。
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/ordering'
        - name: customer
          in: query
          schema:
            type: integer
          description: 客户 ID
        - name: customer_name
          in: query
          schema:
            type: string
          description: 客户名称（模糊）
        - name: customer_phone
          in: query
          schema:
            type: string
          description: 客户电话（模糊）
        - name: fabric
          in: query
          schema:
            type: string
          description: 面料（模糊）
        - name: is_urgent
          in: query
          schema:
            type: boolean
        - name: is_fabric_received
          in: query
          schema:
            type: boolean
        - name: is_invalid
          in: query
          schema:
            type: boolean
        - name: area
          in: query
          schema:
            type: string
        - name: outgoing_date_from
          in: query
          schema:
            type: string
            format: date
        - name: outgoing_date_to
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: 列表
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/PrintingOrder'
                  - type: object
                    properties:
                      count:
                        type: integer
                      results:
                        type: array
                        items:
                          $ref: '#/components/schemas/PrintingOrder'
        '401':
          description: 未认证
        '403':
          description: 没有权限
      security:
        - BearerAuth: []
    post:
      summary: 创建印染订单
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrintingOrderCreate'
      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrintingOrder'
        '400':
          description: 校验错误
        '403':
          description: 没有权限
      security:
        - BearerAuth: []
  /printing-orders/{id}/:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    get:
      summary: 获取印染订单详情
      responses:
        '200':
          description: 详情
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrintingOrder'
        '404':
          description: 未找到
      security:
        - BearerAuth: []
    put:
      summary: 更新印染订单（全量）
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrintingOrderCreate'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrintingOrder'
        '400':
          description: 校验错误
        '403':
          description: 没有权限
      security:
        - BearerAuth: []
    patch:
      summary: 更新印染订单（部分）
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrintingOrderCreate'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrintingOrder'
        '400':
          description: 校验错误
      security:
        - BearerAuth: []
    delete:
      summary: 删除（不支持）
      description: 删除操作已禁用，请使用 作废 操作。
      responses:
        '405':
          description: 不支持删除
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
      security:
        - BearerAuth: []
  /printing-orders/{id}/invalidate/:
    post:
      summary: 作废订单
      description: 将订单标记为已作废（需要 printing.can_invalidate_printingorder 权限）。
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 作废成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  data:
                    $ref: '#/components/schemas/PrintingOrder'
        '400':
          description: 已作废或请求错误
        '403':
          description: 没有权限
      security:
        - BearerAuth: []
  /printing-orders/{id}/activate/:
    post:
      summary: 恢复订单
      description: 将订单从作废状态恢复（需要 printing.can_activate_printingorder 权限）。
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 恢复成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  data:
                    $ref: '#/components/schemas/PrintingOrder'
        '400':
          description: 未作废或请求错误
        '403':
          description: 没有权限
      security:
        - BearerAuth: []
  /printing-orders/{id}/mark_fabric_received/:
    post:
      summary: 标记布料已收
      description: 将订单标记为布料已收到。
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 标记成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  data:
                    $ref: '#/components/schemas/PrintingOrder'
        '400':
          description: 已标记或请求错误
      security:
        - BearerAuth: []

  /printing-jobs/:
    get:
      summary: 获取印染款式明细列表
      description: 支持过滤（printing_order, product, product_name, unit, quantity_min/max, pieces_min/max）、search、ordering 和分页。
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/ordering'
        - name: printing_order
          in: query
          schema:
            type: integer
        - name: product
          in: query
          schema:
            type: integer
        - name: product_name
          in: query
          schema:
            type: string
        - name: unit
          in: query
          schema:
            type: string
        - name: quantity_min
          in: query
          schema:
            type: integer
        - name: quantity_max
          in: query
          schema:
            type: integer
        - name: pieces_min
          in: query
          schema:
            type: integer
        - name: pieces_max
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: 列表
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/PrintingJob'
                  - type: object
                    properties:
                      count:
                        type: integer
                      results:
                        type: array
                        items:
                          $ref: '#/components/schemas/PrintingJob'
        '401':
          description: 未认证
        '403':
          description: 没有权限
      security:
        - BearerAuth: []
    post:
      summary: 创建印染款式明细
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrintingJobCreate'
      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrintingJob'
        '400':
          description: 校验错误
        '403':
          description: 没有权限
      security:
        - BearerAuth: []

  /printing-jobs/{id}/:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    get:
      summary: 获取款式明细详情
      responses:
        '200':
          description: 详情
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrintingJob'
        '404':
          description: 未找到
      security:
        - BearerAuth: []
    put:
      summary: 更新款式明细（全量）
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrintingJobCreate'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrintingJob'
        '400':
          description: 校验错误
      security:
        - BearerAuth: []
    patch:
      summary: 更新款式明细（部分）
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrintingJobCreate'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrintingJob'
        '400':
          description: 校验错误
      security:
        - BearerAuth: []
    delete:
      summary: 删除（不支持）
      description: 删除操作已禁用，请使用所需的业务操作。
      responses:
        '405':
          description: 不支持删除
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
      security:
        - BearerAuth: []

components_end: {}