350 lines
10 KiB
YAML
350 lines
10 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: Personal Brand API
|
|
version: 0.1.0
|
|
description: 单品牌个人经营者小程序与管理后台 API。
|
|
servers:
|
|
- url: http://localhost:3001
|
|
paths:
|
|
/health:
|
|
get:
|
|
operationId: getHealth
|
|
responses:
|
|
"200":
|
|
description: API health status
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Health"
|
|
/public/brand:
|
|
get:
|
|
operationId: getPublicBrand
|
|
responses:
|
|
"200":
|
|
description: Public brand profile
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/BrandProfile"
|
|
/public/services:
|
|
get:
|
|
operationId: listPublicServices
|
|
responses:
|
|
"200":
|
|
description: Enabled public services
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/PublicService"
|
|
/customer/session/wechat:
|
|
post:
|
|
operationId: createCustomerSession
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [code]
|
|
properties:
|
|
code:
|
|
type: string
|
|
responses:
|
|
"201":
|
|
description: Customer session token
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/TokenResponse"
|
|
/customer/bookings:
|
|
get:
|
|
operationId: listCustomerBookings
|
|
security: [bearerAuth: []]
|
|
responses:
|
|
"200":
|
|
description: Current customer's bookings
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Booking"
|
|
post:
|
|
operationId: createCustomerBooking
|
|
security: [bearerAuth: []]
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CreateBooking"
|
|
responses:
|
|
"201":
|
|
description: Created booking summary
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/BookingSummary"
|
|
/customer/bookings/{id}/cancel:
|
|
post:
|
|
operationId: cancelCustomerBooking
|
|
security: [bearerAuth: []]
|
|
parameters:
|
|
- $ref: "#/components/parameters/BookingId"
|
|
responses:
|
|
"201":
|
|
description: Cancelled booking
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Booking"
|
|
/admin/session/login:
|
|
post:
|
|
operationId: createAdminSession
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AdminLogin"
|
|
responses:
|
|
"201":
|
|
description: Admin session token
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AdminTokenResponse"
|
|
/admin/bookings:
|
|
get:
|
|
operationId: listAdminBookings
|
|
security: [bearerAuth: []]
|
|
parameters:
|
|
- in: query
|
|
name: status
|
|
schema:
|
|
$ref: "#/components/schemas/BookingStatus"
|
|
- in: query
|
|
name: unreadOnly
|
|
schema:
|
|
type: boolean
|
|
- in: query
|
|
name: tagId
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Admin booking list
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Booking"
|
|
/admin/bookings/unread-count:
|
|
get:
|
|
operationId: getAdminUnreadBookingCount
|
|
security: [bearerAuth: []]
|
|
responses:
|
|
"200":
|
|
description: Number of unread bookings
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [count]
|
|
properties:
|
|
count: { type: integer, minimum: 0 }
|
|
/admin/bookings/{id}:
|
|
get:
|
|
operationId: getAdminBooking
|
|
security: [bearerAuth: []]
|
|
parameters:
|
|
- $ref: "#/components/parameters/BookingId"
|
|
responses:
|
|
"200":
|
|
description: Admin booking detail
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Booking"
|
|
/admin/bookings/{id}/status:
|
|
post:
|
|
operationId: updateAdminBookingStatus
|
|
security: [bearerAuth: []]
|
|
parameters:
|
|
- $ref: "#/components/parameters/BookingId"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/UpdateBookingStatus"
|
|
responses:
|
|
"201":
|
|
description: Updated booking
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Booking"
|
|
/admin/bookings/{id}/read:
|
|
post:
|
|
operationId: markAdminBookingRead
|
|
security: [bearerAuth: []]
|
|
parameters:
|
|
- $ref: "#/components/parameters/BookingId"
|
|
responses:
|
|
"201":
|
|
description: Updated booking
|
|
/admin/bookings/tags:
|
|
get:
|
|
operationId: listAdminTags
|
|
security: [bearerAuth: []]
|
|
responses:
|
|
"200":
|
|
description: Enabled tags
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Tag"
|
|
post:
|
|
operationId: createAdminTag
|
|
security: [bearerAuth: []]
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [name]
|
|
properties:
|
|
name: { type: string, maxLength: 24 }
|
|
responses:
|
|
"201":
|
|
description: Created tag
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Tag"
|
|
components:
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
parameters:
|
|
BookingId:
|
|
in: path
|
|
name: id
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
schemas:
|
|
Health:
|
|
type: object
|
|
required: [status, service]
|
|
properties:
|
|
status: { type: string, example: ok }
|
|
service: { type: string, example: personal-brand-api }
|
|
BrandProfile:
|
|
type: object
|
|
required: [id, name]
|
|
properties:
|
|
id: { type: string, format: uuid }
|
|
name: { type: string }
|
|
tagline: { type: [string, "null"] }
|
|
description: { type: [string, "null"] }
|
|
avatarUrl: { type: [string, "null"], format: uri }
|
|
coverUrl: { type: [string, "null"], format: uri }
|
|
hours: { type: [string, "null"] }
|
|
address: { type: [string, "null"] }
|
|
deliveryNote: { type: [string, "null"] }
|
|
PublicService:
|
|
type: object
|
|
required: [id, name, description, bookingEnabled]
|
|
properties:
|
|
id: { type: string, format: uuid }
|
|
name: { type: string }
|
|
description: { type: string }
|
|
coverUrl: { type: [string, "null"], format: uri }
|
|
priceText: { type: [string, "null"] }
|
|
priceAmount: { type: [integer, "null"], minimum: 0 }
|
|
bookingEnabled: { type: boolean }
|
|
BookingStatus:
|
|
type: string
|
|
enum: [received, contacting, confirmed, completed, cancelled]
|
|
BookingItemInput:
|
|
type: object
|
|
required: [serviceId, quantity]
|
|
properties:
|
|
serviceId: { type: string, format: uuid }
|
|
quantity: { type: integer, minimum: 1, maximum: 50 }
|
|
CreateBooking:
|
|
type: object
|
|
required: [requestType, customerName, contactPreference, items]
|
|
properties:
|
|
requestType: { type: string, enum: [package, private_chef] }
|
|
customerName: { type: string }
|
|
phone: { type: string }
|
|
wechatId: { type: string }
|
|
contactPreference: { type: string, enum: [wechat, phone, none] }
|
|
fulfillmentType: { type: string, enum: [pickup, delivery] }
|
|
serviceId: { type: string, format: uuid }
|
|
requestedDate: { type: string, format: date-time }
|
|
requestedTime: { type: string }
|
|
deliveryAddress: { type: string }
|
|
note: { type: string }
|
|
extraData: { type: object, additionalProperties: true }
|
|
items:
|
|
type: array
|
|
items: { $ref: "#/components/schemas/BookingItemInput" }
|
|
BookingSummary:
|
|
type: object
|
|
required: [bookingNo, status, estimatedAmount, createdAt]
|
|
properties:
|
|
bookingNo: { type: string }
|
|
status: { $ref: "#/components/schemas/BookingStatus" }
|
|
estimatedAmount: { type: [integer, "null"] }
|
|
createdAt: { type: string, format: date-time }
|
|
Booking:
|
|
allOf:
|
|
- $ref: "#/components/schemas/BookingSummary"
|
|
- type: object
|
|
properties:
|
|
id: { type: string, format: uuid }
|
|
customerName: { type: string }
|
|
adminNote: { type: [string, "null"] }
|
|
AdminLogin:
|
|
type: object
|
|
required: [username, password]
|
|
properties:
|
|
username: { type: string }
|
|
password: { type: string, format: password }
|
|
TokenResponse:
|
|
type: object
|
|
required: [token]
|
|
properties:
|
|
token: { type: string }
|
|
AdminTokenResponse:
|
|
allOf:
|
|
- $ref: "#/components/schemas/TokenResponse"
|
|
- type: object
|
|
required: [displayName]
|
|
properties:
|
|
displayName: { type: string }
|
|
UpdateBookingStatus:
|
|
type: object
|
|
required: [status]
|
|
properties:
|
|
status: { $ref: "#/components/schemas/BookingStatus" }
|
|
adminNote: { type: string }
|
|
Tag:
|
|
type: object
|
|
required: [id, name, isEnabled]
|
|
properties:
|
|
id: { type: string, format: uuid }
|
|
name: { type: string }
|
|
isPreset: { type: boolean }
|
|
isEnabled: { type: boolean }
|