forked from erp-dev/erp
feat: printing module
This commit is contained in:
710
printing/printing_api.yml
Normal file
710
printing/printing_api.yml
Normal file
@@ -0,0 +1,710 @@
|
||||
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: {}
|
||||
Reference in New Issue
Block a user