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 }