docs: 增加 API OpenAPI 契约
This commit is contained in:
1 parent
3640ec46ed
commit
02554ed86c
2 files changed
+353
-4
No files matched your search
+4
-4
@@ -34,6 +34,7 @@
|
||||
- 修复 ESM 下 `bcryptjs` 导入和 Fastify 请求 ID middleware 的运行时问题。
|
||||
- API 已通过真实 HTTP 验证:健康检查、公开品牌/服务读取和管理员登录。
|
||||
- HTTP 集成测试:公开接口、管理员登录、错误密码、管理员权限边界、客户会话、预约 DTO 校验、创建/取消和状态流转,共 8 项通过。
|
||||
- OpenAPI 3.1 契约:`docs/openapi.yaml`,覆盖当前公开、客户和管理员接口。
|
||||
- 已执行多轮 Codex 代码审查并修复关键认证和权限问题。
|
||||
|
||||
## 最近提交
|
||||
@@ -51,10 +52,9 @@ b89853b fix: harden api authentication and validation
|
||||
|
||||
## 下一步优先级
|
||||
|
||||
1. 补 OpenAPI/Swagger 契约和统一响应示例。
|
||||
2. 创建类型化 `api-client`,固定前后端接口边界。
|
||||
3. 接入管理后台订单处理页面。
|
||||
4. 接入小程序品牌展示、服务列表和下单流程。
|
||||
1. 创建类型化 `api-client`,固定前后端接口边界。
|
||||
2. 接入管理后台订单处理页面。
|
||||
3. 接入小程序品牌展示、服务列表和下单流程。
|
||||
|
||||
## 未决问题
|
||||
|
||||
|
||||
@@ -0,0 +1,349 @@
|
||||
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 }
|
||||
Reference in new issue
Block a user