docs: 增加 API OpenAPI 契约

This commit is contained in:
que01 committed 2026-09-19 01:03:31 +08:00
1 parent 3640ec46ed
commit 02554ed86c
2 files changed
+353 -4

No files matched your search

+4 -4
View File
@@ -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. 接入小程序品牌展示、服务列表和下单流程。
## 未决问题
+349
View File
@@ -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 }