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/offerings: get: operationId: listPublicOfferings responses: "200": description: Enabled public services content: application/json: schema: type: array items: $ref: "#/components/schemas/PublicOffering" /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/session/logout: post: operationId: logoutCustomer security: [bearerAuth: []] responses: "201": description: Customer session revoked content: application/json: schema: $ref: "#/components/schemas/LoggedOut" /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/session/logout: post: operationId: logoutAdmin security: [bearerAuth: []] responses: "201": description: Admin session revoked content: application/json: schema: $ref: "#/components/schemas/LoggedOut" /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"] } PublicOffering: 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 } LoggedOut: type: object required: [loggedOut] properties: loggedOut: { type: boolean, enum: [true] } 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 }