From 02554ed86c24d281e3ab6f5b8ac052d35044e71b Mon Sep 17 00:00:00 2001 From: que01 Date: Sat, 19 Sep 2026 01:03:31 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=A2=9E=E5=8A=A0=20API=20OpenAPI=20?= =?UTF-8?q?=E5=A5=91=E7=BA=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- PROJECT_STATUS.md | 8 +- docs/openapi.yaml | 349 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 353 insertions(+), 4 deletions(-) create mode 100644 docs/openapi.yaml diff --git a/PROJECT_STATUS.md b/PROJECT_STATUS.md index 988dfd0..a8832b3 100644 --- a/PROJECT_STATUS.md +++ b/PROJECT_STATUS.md @@ -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. 接入小程序品牌展示、服务列表和下单流程。 ## 未决问题 diff --git a/docs/openapi.yaml b/docs/openapi.yaml new file mode 100644 index 0000000..5e65fb6 --- /dev/null +++ b/docs/openapi.yaml @@ -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 }