forked from erp-dev/erp
711 lines
19 KiB
YAML
711 lines
19 KiB
YAML
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: {}
|