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