openapi: 3.0.3 info: title: 云印享 - 付费打印服务 API description: | 云印享是一个基于 gRPC 的付费打印服务后端系统 API 文档。 ## 认证说明 - 大多数接口需要在请求头中携带 `Authorization: Bearer ` - Login 和 Admin.Login 接口不需要认证 version: 1.0.0 contact: name: CloudPrint Support servers: - url: http://localhost:8080 description: gRPC Server (需通过 gRPC gateway 转换) tags: - name: Auth description: 用户认证相关接口 - name: File description: 文件管理相关接口 - name: Order description: 订单相关接口 - name: Print description: 打印服务相关接口 - name: Library description: 文库相关接口 - name: Price description: 价目表相关接口 - name: Pay description: 支付相关接口 - name: Admin description: 管理后台相关接口 paths: # ==================== Auth Service ==================== /cloudprint.AuthService/Login: post: tags: [Auth] summary: 微信登录 description: 用户通过微信授权码登录系统 requestBody: required: true content: application/json: schema: type: object properties: code: type: string description: 微信授权码 example: "xxxxx" responses: "200": description: 登录成功 content: application/json: schema: type: object properties: access_token: type: string description: 访问令牌 refresh_token: type: string description: 刷新令牌 user: type: object properties: id: type: integer description: 用户ID openid: type: string description: 微信OpenID nickname: type: string description: 昵称 avatar: type: string description: 头像URL balance: type: number description: 余额 created_at: type: string format: date-time /cloudprint.AuthService/RefreshToken: post: tags: [Auth] summary: 刷新令牌 requestBody: required: true content: application/json: schema: type: object properties: refresh_token: type: string responses: "200": description: 刷新成功 content: application/json: schema: type: object properties: access_token: type: string /cloudprint.AuthService/GetUserInfo: post: tags: [Auth] summary: 获取用户信息 security: - bearerAuth: [] responses: "200": description: 成功 content: application/json: schema: $ref: '#/components/schemas/User' /cloudprint.AuthService/UpdateUser: post: tags: [Auth] summary: 更新用户信息 security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: nickname: type: string avatar: type: string responses: "200": description: 更新成功 content: application/json: schema: $ref: '#/components/schemas/User' # ==================== File Service ==================== /cloudprint.FileService/Upload: post: tags: [File] summary: 上传文件（流式） description: 支持分片上传，用于大文件传输 security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: file_name: type: string description: 文件名 file_type: type: string description: 文件类型 file_size: type: integer format: int64 description: 文件大小 data: type: string format: binary description: 文件数据（base64） is_last_chunk: type: boolean description: 是否最后一块 chunk_id: type: string description: 分片ID chunk_index: type: integer description: 分片索引 total_chunks: type: integer description: 总分片数 responses: "200": description: 上传成功 content: application/json: schema: type: object properties: file_id: type: integer file_path: type: string file_url: type: string /cloudprint.FileService/GetFileList: post: tags: [File] summary: 获取文件列表 security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: uploader_type: type: string uploader_id: type: integer page: type: integer page_size: type: integer responses: "200": description: 成功 content: application/json: schema: type: object properties: files: type: array items: $ref: '#/components/schemas/FileInfo' total: type: integer /cloudprint.FileService/DeleteFile: post: tags: [File] summary: 删除文件 security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: file_id: type: integer responses: "200": description: 删除成功 /cloudprint.FileService/AddWatermark: post: tags: [File] summary: 添加水印 security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: file_id: type: integer text: type: string opacity: type: number format: float position: type: integer enum: [1, 2, 3, 4, 5] description: "1: 左上 2: 右上 3: 左下 4: 右下 5: 居中" font_size: type: integer responses: "200": description: 成功 # ==================== Order Service ==================== /cloudprint.OrderService/CreateOrder: post: tags: [Order] summary: 创建订单 security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: items: type: array items: type: object properties: file_id: type: integer printer_id: type: integer copies: type: integer color: type: boolean duplex: type: boolean page_range: type: string remark: type: string responses: "200": description: 创建成功 content: application/json: schema: type: object properties: order_no: type: string total_amount: type: number /cloudprint.OrderService/GetOrder: post: tags: [Order] summary: 获取订单详情 security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: order_no: type: string responses: "200": description: 成功 content: application/json: schema: $ref: '#/components/schemas/Order' /cloudprint.OrderService/GetOrderList: post: tags: [Order] summary: 获取订单列表 security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: user_id: type: integer status: type: integer page: type: integer page_size: type: integer responses: "200": description: 成功 content: application/json: schema: type: object properties: orders: type: array items: $ref: '#/components/schemas/Order' total: type: integer /cloudprint.OrderService/UpdateOrderStatus: post: tags: [Order] summary: 更新订单状态 security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: order_no: type: string status: type: integer enum: [0, 1, 2, 3, 4] responses: "200": description: 更新成功 /cloudprint.OrderService/CancelOrder: post: tags: [Order] summary: 取消订单 security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: order_no: type: string responses: "200": description: 取消成功 # ==================== Print Service ==================== /cloudprint.PrintService/GetPrinters: post: tags: [Print] summary: 获取打印机列表 security: - bearerAuth: [] responses: "200": description: 成功 content: application/json: schema: type: object properties: printers: type: array items: $ref: '#/components/schemas/Printer' /cloudprint.PrintService/GetPrinterStatus: post: tags: [Print] summary: 获取打印机状态 security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: printer_id: type: integer responses: "200": description: 成功 content: application/json: schema: type: object properties: printer: $ref: '#/components/schemas/Printer' queue_count: type: integer /cloudprint.PrintService/RegisterPrinter: post: tags: [Print] summary: 注册打印机 security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: name: type: string display_name: type: string api_key: type: string responses: "200": description: 注册成功 content: application/json: schema: type: object properties: printer_id: type: integer token: type: string /cloudprint.PrintService/PrinterHeartbeat: post: tags: [Print] summary: 打印机心跳 requestBody: content: application/json: schema: type: object properties: printer_id: type: integer status: type: integer enum: [0, 1, 2] token: type: string responses: "200": description: 成功 /cloudprint.PrintService/SubmitPrintJob: post: tags: [Print] summary: 提交打印任务 security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: order_item_id: type: integer printer_id: type: integer file_path: type: string copies: type: integer color: type: boolean duplex: type: boolean page_range: type: string responses: "200": description: 提交成功 content: application/json: schema: type: object properties: job_no: type: string /cloudprint.PrintService/CancelPrintJob: post: tags: [Print] summary: 取消打印任务 security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: job_no: type: string responses: "200": description: 取消成功 /cloudprint.PrintService/ReportJobStatus: post: tags: [Print] summary: 上报任务状态 requestBody: content: application/json: schema: type: object properties: job_no: type: string status: type: string enum: [pending, printing, completed, failed, cancelled] progress: type: integer error_msg: type: string responses: "200": description: 上报成功 # ==================== Library Service ==================== /cloudprint.LibraryService/GetCategories: post: tags: [Library] summary: 获取文库分类 responses: "200": description: 成功 content: application/json: schema: type: object properties: categories: type: array items: $ref: '#/components/schemas/LibraryCategory' /cloudprint.LibraryService/GetFiles: post: tags: [Library] summary: 获取文库文件列表 requestBody: content: application/json: schema: type: object properties: category_id: type: integer page: type: integer page_size: type: integer responses: "200": description: 成功 content: application/json: schema: type: object properties: files: type: array items: $ref: '#/components/schemas/LibraryFile' total: type: integer /cloudprint.LibraryService/UploadFile: post: tags: [Library] summary: 上传文库文件 security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: category_id: type: integer title: type: string description: type: string data: type: string format: binary file_name: type: string file_type: type: string responses: "200": description: 上传成功 /cloudprint.LibraryService/DeleteFile: post: tags: [Library] summary: 删除文库文件 security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: library_file_id: type: integer responses: "200": description: 删除成功 # ==================== Price Service ==================== /cloudprint.PriceService/GetPriceList: post: tags: [Price] summary: 获取价目表 responses: "200": description: 成功 content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/PriceItem' /cloudprint.PriceService/CreatePriceItem: post: tags: [Price] summary: 创建价目项 security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: name: type: string type: type: string price: type: number unit: type: string color_enabled: type: boolean responses: "200": description: 创建成功 /cloudprint.PriceService/UpdatePriceItem: post: tags: [Price] summary: 更新价目项 security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/PriceItem' responses: "200": description: 更新成功 # ==================== Pay Service ==================== /cloudprint.PayService/CreateWxPayOrder: post: tags: [Pay] summary: 创建微信支付订单 security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: order_no: type: string amount: type: number description: type: string openid: type: string client_ip: type: string responses: "200": description: 创建成功 content: application/json: schema: type: object properties: prepay_id: type: string code_url: type: string mweb_url: type: string /cloudprint.PayService/QueryPayStatus: post: tags: [Pay] summary: 查询支付状态 security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: order_no: type: string responses: "200": description: 成功 content: application/json: schema: type: object properties: status: type: integer enum: [0, 1, 2, 3] description: "0: 待支付 1: 支付中 2: 成功 3: 失败" transaction_id: type: string /cloudprint.PayService/HandlePayCallback: post: tags: [Pay] summary: 处理支付回调 requestBody: content: application/json: schema: type: object properties: body: type: string description: 微信支付回调XML内容 responses: "200": description: 处理成功 /cloudprint.PayService/PayByBalance: post: tags: [Pay] summary: 余额支付 security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: order_no: type: string user_id: type: integer responses: "200": description: 支付成功 # ==================== Admin Service ==================== /cloudprint.AdminService/Login: post: tags: [Admin] summary: 管理员登录 requestBody: content: application/json: schema: type: object properties: username: type: string password: type: string responses: "200": description: 登录成功 content: application/json: schema: type: object properties: access_token: type: string admin: $ref: '#/components/schemas/Admin' /cloudprint.AdminService/GetStatistics: post: tags: [Admin] summary: 获取统计数据 security: - bearerAuth: [] responses: "200": description: 成功 content: application/json: schema: type: object properties: total_users: type: integer total_orders: type: integer today_orders: type: integer today_revenue: type: number pending_orders: type: integer active_printers: type: integer /cloudprint.AdminService/CreateAdmin: post: tags: [Admin] summary: 创建管理员账号 description: 创建新的管理员账号，密码将使用bcrypt进行哈希处理 security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - username - password properties: username: type: string description: 管理员用户名 example: "admin" password: type: string description: 管理员密码 example: "admin123" nickname: type: string description: 昵称 example: "管理员" role: type: integer description: 角色 (1-普通管理员, 2-超级管理员) example: 1 responses: "200": description: 创建成功 content: application/json: schema: type: object properties: admin: $ref: '#/components/schemas/Admin' /cloudprint.AdminService/GetAdminList: post: tags: [Admin] summary: 获取管理员列表 security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: page: type: integer description: 页码 example: 1 page_size: type: integer description: 每页数量 example: 10 responses: "200": description: 成功 content: application/json: schema: type: object properties: admins: type: array items: $ref: '#/components/schemas/Admin' total: type: integer description: 总数 /cloudprint.AdminService/UpdateAdmin: post: tags: [Admin] summary: 更新管理员信息 security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - id properties: id: type: integer description: 管理员ID example: 1 nickname: type: string description: 昵称 example: "新昵称" role: type: integer description: 角色 (1-普通管理员, 2-超级管理员) example: 2 responses: "200": description: 更新成功 content: application/json: schema: $ref: '#/components/schemas/Admin' /cloudprint.AdminService/DeleteAdmin: post: tags: [Admin] summary: 删除管理员 security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - id properties: id: type: integer description: 管理员ID example: 1 responses: "200": description: 删除成功 content: application/json: schema: type: object components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT schemas: User: type: object properties: id: type: integer openid: type: string nickname: type: string avatar: type: string balance: type: number created_at: type: string format: date-time Admin: type: object properties: id: type: integer username: type: string nickname: type: string role: type: integer enum: [1, 2] description: "1: 普通管理员 2: 超级管理员" created_at: type: string format: date-time FileInfo: type: object properties: id: type: integer file_name: type: string file_path: type: string file_type: type: string file_size: type: integer format: int64 uploader_type: type: string uploader_id: type: integer created_at: type: string format: date-time Order: type: object properties: id: type: integer order_no: type: string user_id: type: integer status: type: integer enum: [0, 1, 2, 3, 4] description: "0: 待支付 1: 已支付 2: 打印中 3: 已完成 4: 已取消" total_amount: type: number remark: type: string created_at: type: string format: date-time paid_at: type: string format: date-time items: type: array items: $ref: '#/components/schemas/OrderItem' OrderItem: type: object properties: id: type: integer order_id: type: integer file_id: type: integer printer_id: type: integer copies: type: integer color: type: boolean duplex: type: boolean page_range: type: string price: type: number Printer: type: object properties: id: type: integer name: type: string display_name: type: string is_active: type: boolean status: type: integer enum: [0, 1, 2] description: "0: 空闲 1: 打印中 2: 离线" last_heartbeat: type: string format: date-time PrintJob: type: object properties: id: type: integer job_no: type: string printer_id: type: integer order_item_id: type: integer status: type: string enum: [pending, printing, completed, failed, cancelled] progress: type: integer error_msg: type: string started_at: type: string format: date-time completed_at: type: string format: date-time LibraryCategory: type: object properties: id: type: integer name: type: string icon: type: string sort_order: type: integer LibraryFile: type: object properties: id: type: integer category_id: type: integer file_id: type: integer title: type: string description: type: string page_count: type: integer download_count: type: integer created_at: type: string format: date-time PriceItem: type: object properties: id: type: integer name: type: string type: type: string description: 纸张类型 A4/A3/照片纸 price: type: number unit: type: string color_enabled: type: boolean is_active: type: boolean