9.17/1
This commit is contained in:
316
doc/openapi.yaml
316
doc/openapi.yaml
@@ -7,6 +7,30 @@ info:
|
||||
servers:
|
||||
- url: /
|
||||
paths:
|
||||
/api/dashboard/overview:
|
||||
get:
|
||||
summary: 首页概览（✅ Fully Implemented）
|
||||
description: 订单口径的今日销售额（approved）、近似本月毛利（按当前进价近似）与库存总量。支持 X-Shop-Id 或 X-User-Id（优先从用户解析店铺）。后端与前端均已接入。
|
||||
parameters:
|
||||
- in: header
|
||||
name: X-Shop-Id
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
description: 店铺ID，缺省为 1
|
||||
- in: header
|
||||
name: X-User-Id
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
description: 用户ID；当未提供 X-Shop-Id 时将用其所属店铺进行统计
|
||||
responses:
|
||||
'200':
|
||||
description: 成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/DashboardOverview'
|
||||
/api/notices:
|
||||
get:
|
||||
summary: 公告列表（✅ Fully Implemented）
|
||||
@@ -104,8 +128,8 @@ paths:
|
||||
format: int64
|
||||
/api/products:
|
||||
get:
|
||||
summary: 商品搜索（❌ Partially Implemented）
|
||||
description: 前端已接入查询参数 kw/page/size，后端待实现或对齐。
|
||||
summary: 商品搜索（✅ Fully Implemented）
|
||||
description: 支持 kw/page/size/categoryId；返回 {list:[]} 以兼容前端。
|
||||
parameters:
|
||||
- in: query
|
||||
name: kw
|
||||
@@ -131,6 +155,178 @@ paths:
|
||||
- type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Product'
|
||||
post:
|
||||
summary: 新建商品（✅ Fully Implemented）
|
||||
description: 保存商品、价格、库存与图片（当前图片统一占位图 URL）。
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CreateProductRequest'
|
||||
responses:
|
||||
'200':
|
||||
description: 成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: integer
|
||||
format: int64
|
||||
/api/products/{id}:
|
||||
get:
|
||||
summary: 商品详情（✅ Fully Implemented）
|
||||
parameters:
|
||||
- in: path
|
||||
name: id
|
||||
required: true
|
||||
schema: { type: integer }
|
||||
responses:
|
||||
'200':
|
||||
description: 成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ProductDetail'
|
||||
put:
|
||||
summary: 更新商品（✅ Fully Implemented）
|
||||
parameters:
|
||||
- in: path
|
||||
name: id
|
||||
required: true
|
||||
schema: { type: integer }
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CreateProductRequest'
|
||||
responses:
|
||||
'200':
|
||||
description: 成功
|
||||
/api/product-categories:
|
||||
get:
|
||||
summary: 类别列表（✅ Fully Implemented）
|
||||
responses:
|
||||
'200':
|
||||
description: 成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
oneOf:
|
||||
- type: array
|
||||
items: { $ref: '#/components/schemas/Category' }
|
||||
- type: object
|
||||
properties:
|
||||
list:
|
||||
type: array
|
||||
items: { $ref: '#/components/schemas/Category' }
|
||||
post:
|
||||
summary: 新增类别（❌ Partially Implemented）
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
name: { type: string }
|
||||
/api/product-categories/{id}:
|
||||
put:
|
||||
summary: 更新类别（❌ Partially Implemented）
|
||||
parameters:
|
||||
- in: path
|
||||
name: id
|
||||
required: true
|
||||
schema: { type: integer }
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
name: { type: string }
|
||||
delete:
|
||||
summary: 删除类别（❌ Partially Implemented）
|
||||
parameters:
|
||||
- in: path
|
||||
name: id
|
||||
required: true
|
||||
schema: { type: integer }
|
||||
responses: { '200': { description: 成功 } }
|
||||
/api/product-units:
|
||||
get:
|
||||
summary: 单位列表（✅ Fully Implemented）
|
||||
responses:
|
||||
'200':
|
||||
description: 成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
oneOf:
|
||||
- type: array
|
||||
items: { $ref: '#/components/schemas/Unit' }
|
||||
- type: object
|
||||
properties:
|
||||
list:
|
||||
type: array
|
||||
items: { $ref: '#/components/schemas/Unit' }
|
||||
post:
|
||||
summary: 新增单位（❌ Partially Implemented）
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
name: { type: string }
|
||||
/api/product-units/{id}:
|
||||
put:
|
||||
summary: 更新单位（❌ Partially Implemented）
|
||||
parameters:
|
||||
- in: path
|
||||
name: id
|
||||
required: true
|
||||
schema: { type: integer }
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
name: { type: string }
|
||||
delete:
|
||||
summary: 删除单位（❌ Partially Implemented）
|
||||
parameters:
|
||||
- in: path
|
||||
name: id
|
||||
required: true
|
||||
schema: { type: integer }
|
||||
responses: { '200': { description: 成功 } }
|
||||
/api/product-settings:
|
||||
get:
|
||||
summary: 货品设置读取（❌ Partially Implemented）
|
||||
responses:
|
||||
'200':
|
||||
description: 成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ProductSettings'
|
||||
put:
|
||||
summary: 货品设置保存（❌ Partially Implemented）
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ProductSettings'
|
||||
responses: { '200': { description: 成功 } }
|
||||
- type: object
|
||||
properties:
|
||||
list:
|
||||
@@ -195,8 +391,63 @@ paths:
|
||||
format: int64
|
||||
orderNo:
|
||||
type: string
|
||||
/api/attachments:
|
||||
post:
|
||||
summary: 上传附件（✅ Fully Implemented，占位图方案）
|
||||
description: 接收 multipart 上传但忽略文件内容，始终返回占位图 URL（后端配置项 `attachments.placeholder.image-path` 指向本地占位图片；URL 固定 `/api/attachments/placeholder` 可通过 `attachments.placeholder.url-path` 覆盖）。
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
multipart/form-data:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
file:
|
||||
type: string
|
||||
format: binary
|
||||
ownerType:
|
||||
type: string
|
||||
ownerId:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: 成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
url:
|
||||
type: string
|
||||
/api/attachments/placeholder:
|
||||
get:
|
||||
summary: 附件占位图读取（✅ Fully Implemented）
|
||||
description: 返回后端配置的本地占位图内容，路径由 `attachments.placeholder.image-path` 指定。
|
||||
responses:
|
||||
'200':
|
||||
description: 图片二进制
|
||||
content:
|
||||
image/png:
|
||||
schema:
|
||||
type: string
|
||||
format: binary
|
||||
components:
|
||||
schemas:
|
||||
DashboardOverview:
|
||||
type: object
|
||||
properties:
|
||||
todaySalesAmount:
|
||||
type: number
|
||||
example: 1250.00
|
||||
monthSalesAmount:
|
||||
type: number
|
||||
example: 26500.00
|
||||
monthGrossProfit:
|
||||
type: number
|
||||
example: 3560.25
|
||||
stockTotalQuantity:
|
||||
type: number
|
||||
example: 1300
|
||||
Notice:
|
||||
type: object
|
||||
properties:
|
||||
@@ -306,6 +557,67 @@ components:
|
||||
type: number
|
||||
stock:
|
||||
type: number
|
||||
ProductDetail:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/Product'
|
||||
- type: object
|
||||
properties:
|
||||
brand: { type: string }
|
||||
model: { type: string }
|
||||
spec: { type: string }
|
||||
categoryId: { type: integer, format: int64, nullable: true }
|
||||
unitId: { type: integer, format: int64 }
|
||||
safeMin: { type: number, nullable: true }
|
||||
safeMax: { type: number, nullable: true }
|
||||
purchasePrice: { type: number }
|
||||
retailPrice: { type: number }
|
||||
distributionPrice: { type: number }
|
||||
wholesalePrice: { type: number }
|
||||
bigClientPrice: { type: number }
|
||||
images:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties: { url: { type: string } }
|
||||
CreateProductRequest:
|
||||
type: object
|
||||
properties:
|
||||
name: { type: string }
|
||||
barcode: { type: string, nullable: true }
|
||||
brand: { type: string, nullable: true }
|
||||
model: { type: string, nullable: true }
|
||||
spec: { type: string, nullable: true }
|
||||
categoryId: { type: integer, format: int64, nullable: true }
|
||||
unitId: { type: integer, format: int64 }
|
||||
safeMin: { type: number, nullable: true }
|
||||
safeMax: { type: number, nullable: true }
|
||||
prices:
|
||||
type: object
|
||||
properties:
|
||||
purchasePrice: { type: number }
|
||||
retailPrice: { type: number }
|
||||
distributionPrice: { type: number }
|
||||
wholesalePrice: { type: number }
|
||||
bigClientPrice: { type: number }
|
||||
stock: { type: number, nullable: true }
|
||||
images:
|
||||
type: array
|
||||
items: { type: string, description: '图片URL' }
|
||||
Category:
|
||||
type: object
|
||||
properties:
|
||||
id: { type: integer, format: int64 }
|
||||
name: { type: string }
|
||||
Unit:
|
||||
type: object
|
||||
properties:
|
||||
id: { type: integer, format: int64 }
|
||||
name: { type: string }
|
||||
ProductSettings:
|
||||
type: object
|
||||
properties:
|
||||
hideZeroStock: { type: boolean }
|
||||
hidePurchasePrice: { type: boolean }
|
||||
Customer:
|
||||
type: object
|
||||
properties:
|
||||
|
||||
Reference in New Issue
Block a user