{ "openapi": "3.0.3", "info": { "title": "一车帝服务平台接口", "version": "2.0.0", "description": "所有接口统一使用POST。查询条件和服务id放在JSON请求体，上传为原始图片二进制。所有业务接口须验签。健康检查POST /health不验签。时间戳使用Unix秒，允许服务器时间前后300秒。nonce为16至64位字母数字下划线横线且每次请求唯一；重复返回409。HMAC-SHA256输出小写十六进制。签名原文为以下7行（以LF分隔，无末尾换行）：\nPOST\n原始请求路径及查询字符串\nX-App-Id\nX-Timestamp\nX-Nonce\nSHA256(Authorization完整值，无则空字符串)\nSHA256(原始请求体字节，无则空字节)。\n示例客户端见scripts/client.py。签名密钥由环境变量提供。共享客户端密钥不能作为用户身份或业务授权依据；浏览器/小程序无法保密，应由可信后端签名。登录令牌有效期7天。限流：每IP每接口每分钟认证接口20次，其他120次。所有业务响应为中文。" }, "servers": [ { "url": "https://yiche.qianluoxi.cn", "description": "生产环境" }, { "url": "http://127.0.0.1:8086", "description": "本地开发" } ], "paths": { "/api/v1/auth/register": { "post": { "summary": "用户注册", "description": "", "tags": [ "用户认证" ], "security": [ { "AppId": [], "Timestamp": [], "Nonce": [], "Signature": [] } ], "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ], "description": "0表示成功" }, "message": { "type": "string", "description": "中文提示", "example": "成功" }, "data": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "新用户编号" } } } }, "required": [ "code", "message", "data" ] } } } }, "401": { "description": "签名无效、时间戳过期或未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在或无权限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "重复请求或手机号已注册", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求媒体类型错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "参数校验失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求过于频繁", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "配置未就绪", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Register" } } } } } }, "/api/v1/auth/login": { "post": { "summary": "用户登录", "description": "", "tags": [ "用户认证" ], "security": [ { "AppId": [], "Timestamp": [], "Nonce": [], "Signature": [] } ], "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ], "description": "0表示成功" }, "message": { "type": "string", "description": "中文提示", "example": "成功" }, "data": { "type": "object", "properties": { "access_token": { "type": "string", "description": "随机Bearer令牌，仅此次返回" }, "token_type": { "type": "string", "description": "固定Bearer" }, "expires_at": { "type": "integer", "description": "到期时间，Unix秒" }, "user": { "$ref": "#/components/schemas/User" } } } }, "required": [ "code", "message", "data" ] } } } }, "401": { "description": "签名无效、时间戳过期或未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在或无权限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "重复请求或手机号已注册", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求媒体类型错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "参数校验失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求过于频繁", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "配置未就绪", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credentials" } } } } } }, "/api/v1/auth/me": { "post": { "summary": "获取当前用户", "description": "", "tags": [ "用户认证" ], "security": [ { "AppId": [], "Timestamp": [], "Nonce": [], "Signature": [], "BearerAuth": [] } ], "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ], "description": "0表示成功" }, "message": { "type": "string", "description": "中文提示", "example": "成功" }, "data": { "$ref": "#/components/schemas/User" } }, "required": [ "code", "message", "data" ] } } } }, "401": { "description": "签名无效、时间戳过期或未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在或无权限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "重复请求或手机号已注册", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求媒体类型错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "参数校验失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求过于频繁", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "配置未就绪", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/auth/logout": { "post": { "summary": "退出当前登录", "description": "立即撤销当前Bearer令牌，其他设备会话不受影响。", "tags": [ "用户认证" ], "security": [ { "AppId": [], "Timestamp": [], "Nonce": [], "Signature": [], "BearerAuth": [] } ], "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ], "description": "0表示成功" }, "message": { "type": "string", "description": "中文提示", "example": "成功" }, "data": { "nullable": true } }, "required": [ "code", "message", "data" ] } } } }, "401": { "description": "签名无效、时间戳过期或未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在或无权限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "重复请求或手机号已注册", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求媒体类型错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "参数校验失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求过于频繁", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "配置未就绪", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/categories": { "post": { "summary": "获取启用的一级服务类目", "description": "", "tags": [ "服务管理" ], "security": [ { "AppId": [], "Timestamp": [], "Nonce": [], "Signature": [] } ], "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ], "description": "0表示成功" }, "message": { "type": "string", "description": "中文提示", "example": "成功" }, "data": { "type": "array", "description": "类目列表", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "类目编号" }, "name": { "type": "string", "description": "类目名称" } } } } }, "required": [ "code", "message", "data" ] } } } }, "401": { "description": "签名无效、时间戳过期或未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在或无权限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "重复请求或手机号已注册", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求媒体类型错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "参数校验失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求过于频繁", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "配置未就绪", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/uploads/images": { "post": { "summary": "上传服务图片", "description": "原始二进制图片请求体，非multipart。支持JPEG、PNG、WebP，最大5MB、4000万像素。签名对原始图片字节计算SHA256。由UPLOAD_DRIVER切换本地或COS。", "tags": [ "图片上传" ], "security": [ { "AppId": [], "Timestamp": [], "Nonce": [], "Signature": [], "BearerAuth": [] } ], "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ], "description": "0表示成功" }, "message": { "type": "string", "description": "中文提示", "example": "成功" }, "data": { "$ref": "#/components/schemas/Upload" } }, "required": [ "code", "message", "data" ] } } } }, "401": { "description": "签名无效、时间戳过期或未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在或无权限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "重复请求或手机号已注册", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求媒体类型错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "参数校验失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求过于频繁", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "配置未就绪", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } } } } }, "/api/v1/services/list": { "post": { "summary": "查询在售服务列表", "description": "分页和筛选条件放入JSON请求体；不筛选时发送空对象{}。", "tags": [ "服务管理" ], "security": [ { "AppId": [], "Timestamp": [], "Nonce": [], "Signature": [] } ], "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ], "description": "0表示成功" }, "message": { "type": "string", "description": "中文提示", "example": "成功" }, "data": { "type": "object", "properties": { "list": { "type": "array", "description": "服务列表", "items": { "$ref": "#/components/schemas/Service" } }, "total": { "type": "integer", "description": "符合条件的总条数" }, "page": { "type": "integer", "description": "当前页码" }, "page_size": { "type": "integer", "description": "每页条数" }, "counts": { "type": "object", "properties": { "on_sale": { "type": "integer", "description": "在售数量" }, "off_sale": { "type": "integer", "description": "下架数量" }, "draft": { "type": "integer", "description": "草稿数量" } }, "nullable": true, "description": "仅我的服务返回状态统计；统计不受关键词及当前状态筛选影响" } } } }, "required": [ "code", "message", "data" ] } } } }, "401": { "description": "签名无效、时间戳过期或未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在或无权限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "重复请求或手机号已注册", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求媒体类型错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "参数校验失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求过于频繁", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "配置未就绪", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "type": "integer", "description": "页码", "minimum": 1, "maximum": 100000, "default": 1 }, "page_size": { "type": "integer", "description": "每页数量", "minimum": 1, "maximum": 100, "default": 20 }, "keyword": { "type": "string", "description": "服务名称关键词", "maxLength": 100 }, "category_id": { "type": "integer", "description": "一级类目编号", "minimum": 1 } } } } } } } }, "/api/v1/services/detail": { "post": { "summary": "获取在售服务详情", "description": "", "tags": [ "服务管理" ], "security": [ { "AppId": [], "Timestamp": [], "Nonce": [], "Signature": [] } ], "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ], "description": "0表示成功" }, "message": { "type": "string", "description": "中文提示", "example": "成功" }, "data": { "$ref": "#/components/schemas/Service" } }, "required": [ "code", "message", "data" ] } } } }, "401": { "description": "签名无效、时间戳过期或未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在或无权限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "重复请求或手机号已注册", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求媒体类型错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "参数校验失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求过于频繁", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "配置未就绪", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "服务编号，必须为正整数", "minimum": 1, "example": 1 } }, "required": [ "id" ] } } } } } }, "/api/v1/my/services/list": { "post": { "summary": "查询我的服务及各状态数量", "description": "", "tags": [ "服务管理" ], "security": [ { "AppId": [], "Timestamp": [], "Nonce": [], "Signature": [], "BearerAuth": [] } ], "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ], "description": "0表示成功" }, "message": { "type": "string", "description": "中文提示", "example": "成功" }, "data": { "type": "object", "properties": { "list": { "type": "array", "description": "服务列表", "items": { "$ref": "#/components/schemas/Service" } }, "total": { "type": "integer", "description": "符合条件的总条数" }, "page": { "type": "integer", "description": "当前页码" }, "page_size": { "type": "integer", "description": "每页条数" }, "counts": { "type": "object", "properties": { "on_sale": { "type": "integer", "description": "在售数量" }, "off_sale": { "type": "integer", "description": "下架数量" }, "draft": { "type": "integer", "description": "草稿数量" } }, "nullable": true, "description": "仅我的服务返回状态统计；统计不受关键词及当前状态筛选影响" } } } }, "required": [ "code", "message", "data" ] } } } }, "401": { "description": "签名无效、时间戳过期或未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在或无权限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "重复请求或手机号已注册", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求媒体类型错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "参数校验失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求过于频繁", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "配置未就绪", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "type": "integer", "description": "页码", "minimum": 1, "maximum": 100000, "default": 1 }, "page_size": { "type": "integer", "description": "每页数量", "minimum": 1, "maximum": 100, "default": 20 }, "keyword": { "type": "string", "description": "服务名称关键词", "maxLength": 100 }, "category_id": { "type": "integer", "description": "一级类目编号", "minimum": 1 }, "status": { "type": "string", "description": "状态，默认on_sale", "enum": [ "on_sale", "off_sale", "draft" ] } } } } } } } }, "/api/v1/my/services/detail": { "post": { "summary": "获取我的服务编辑详情", "description": "", "tags": [ "服务管理" ], "security": [ { "AppId": [], "Timestamp": [], "Nonce": [], "Signature": [], "BearerAuth": [] } ], "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ], "description": "0表示成功" }, "message": { "type": "string", "description": "中文提示", "example": "成功" }, "data": { "$ref": "#/components/schemas/Service" } }, "required": [ "code", "message", "data" ] } } } }, "401": { "description": "签名无效、时间戳过期或未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在或无权限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "重复请求或手机号已注册", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求媒体类型错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "参数校验失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求过于频繁", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "配置未就绪", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "服务编号，必须为正整数", "minimum": 1, "example": 1 } }, "required": [ "id" ] } } } } } }, "/api/v1/services/create": { "post": { "summary": "发布服务或保存草稿", "description": "", "tags": [ "服务管理" ], "security": [ { "AppId": [], "Timestamp": [], "Nonce": [], "Signature": [], "BearerAuth": [] } ], "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ], "description": "0表示成功" }, "message": { "type": "string", "description": "中文提示", "example": "成功" }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "服务编号" } } } }, "required": [ "code", "message", "data" ] } } } }, "401": { "description": "签名无效、时间戳过期或未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在或无权限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "重复请求或手机号已注册", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求媒体类型错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "参数校验失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求过于频繁", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "配置未就绪", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceInput" } } } } } }, "/api/v1/services/update": { "post": { "summary": "完整编辑本人服务", "description": "JSON请求体同时包含id及完整服务字段。完整替换，不是部分更新。缺省字段重置为默认值；status省略将保存为草稿。", "tags": [ "服务管理" ], "security": [ { "AppId": [], "Timestamp": [], "Nonce": [], "Signature": [], "BearerAuth": [] } ], "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ], "description": "0表示成功" }, "message": { "type": "string", "description": "中文提示", "example": "成功" }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "服务编号" } } } }, "required": [ "code", "message", "data" ] } } } }, "401": { "description": "签名无效、时间戳过期或未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在或无权限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "重复请求或手机号已注册", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求媒体类型错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "参数校验失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求过于频繁", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "配置未就绪", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "category_id": { "type": "integer", "description": "一级类目编号，来自类目接口；草稿可空", "nullable": true, "example": 1 }, "name": { "type": "string", "description": "服务名称，发布必填，最多20字", "maxLength": 20, "example": "精致洗车" }, "refund_policy": { "type": "string", "description": "保障，默认随时退", "enum": [ "anytime", "non_refundable" ] }, "service_modes": { "type": "array", "description": "服务方式，可多选：in_store车主到店、home_visit师傅上门、pickup上门取车", "items": { "type": "string", "description": "服务方式", "enum": [ "in_store", "home_visit", "pickup" ] }, "uniqueItems": true }, "requires_appointment": { "type": "boolean", "description": "true提前预约、false免预约；草稿可空", "nullable": true }, "price": { "type": "string", "description": "售价，单位元；金额必须为字符串，非负，最多两位小数，默认0.00", "pattern": "^(0|[1-9]\\d{0,6})(\\.\\d{1,2})?$", "example": "9.80" }, "image_ids": { "type": "array", "description": "已上传的本人主图编号，发布须1至6张，按数组顺序展示", "items": { "type": "integer", "description": "图片编号", "minimum": 1 }, "maxItems": 6, "uniqueItems": true }, "detail_text": { "type": "string", "description": "图文详情纯文字，和详情图片至少提供一项", "maxLength": 20000, "example": "内外清洁，含吸尘。" }, "detail_image_ids": { "type": "array", "description": "已上传的本人详情图片编号，最多3张", "items": { "type": "integer", "description": "图片编号", "minimum": 1 }, "maxItems": 3, "uniqueItems": true }, "items": { "type": "array", "description": "可选服务内容，最多50条", "items": { "type": "object", "properties": { "description": { "type": "string", "description": "服务内容说明", "minLength": 1, "maxLength": 1000 }, "quantity": { "type": "integer", "description": "数量", "minimum": 1, "maximum": 9999 } }, "required": [ "description", "quantity" ] }, "maxItems": 50 }, "availability": { "type": "object", "properties": { "weekdays": { "type": "array", "description": "每周可用星期：1周一至7周日", "items": { "type": "integer", "description": "星期", "minimum": 1, "maximum": 7 }, "uniqueItems": true, "maxItems": 7 }, "all_day": { "type": "boolean", "description": "是否24小时；为true时periods须为空" }, "periods": { "type": "array", "description": "自定义时间段，禁止重叠或跨日；非24小时模式发布至少一段", "items": { "type": "object", "properties": { "start": { "type": "string", "description": "开始时间（含）", "example": "09:00", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" }, "end": { "type": "string", "description": "结束时间（不含），须大于开始时间；禁止跨日", "example": "21:00", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" } }, "required": [ "start", "end" ] }, "maxItems": 12 } }, "required": [ "weekdays", "all_day", "periods" ] }, "status": { "type": "string", "description": "draft草稿、on_sale在售、off_sale下架；默认draft", "enum": [ "draft", "on_sale", "off_sale" ] }, "id": { "type": "integer", "description": "服务编号，必须为正整数", "minimum": 1, "example": 1 } }, "required": [ "id" ] } } } } } }, "/api/v1/services/status": { "post": { "summary": "上架或下架本人服务", "description": "草稿转上架须通过全部发布校验。不完整草稿不能直接下架。", "tags": [ "服务管理" ], "security": [ { "AppId": [], "Timestamp": [], "Nonce": [], "Signature": [], "BearerAuth": [] } ], "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ], "description": "0表示成功" }, "message": { "type": "string", "description": "中文提示", "example": "成功" }, "data": { "nullable": true } }, "required": [ "code", "message", "data" ] } } } }, "401": { "description": "签名无效、时间戳过期或未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在或无权限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "重复请求或手机号已注册", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求媒体类型错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "参数校验失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求过于频繁", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "配置未就绪", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "服务编号，必须为正整数", "minimum": 1, "example": 1 }, "status": { "type": "string", "description": "目标状态", "enum": [ "on_sale", "off_sale" ] } }, "required": [ "id", "status" ] } } } } } }, "/api/v1/services/delete": { "post": { "summary": "软删除本人服务", "description": "", "tags": [ "服务管理" ], "security": [ { "AppId": [], "Timestamp": [], "Nonce": [], "Signature": [], "BearerAuth": [] } ], "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ], "description": "0表示成功" }, "message": { "type": "string", "description": "中文提示", "example": "成功" }, "data": { "nullable": true } }, "required": [ "code", "message", "data" ] } } } }, "401": { "description": "签名无效、时间戳过期或未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在或无权限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "重复请求或手机号已注册", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求媒体类型错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "参数校验失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求过于频繁", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "配置未就绪", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "服务编号，必须为正整数", "minimum": 1, "example": 1 } }, "required": [ "id" ] } } } } } }, "/health": { "post": { "summary": "健康检查", "description": "检查数据库连接，不要求签名或登录。", "tags": [ "服务管理" ], "security": [], "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ], "description": "0表示成功" }, "message": { "type": "string", "description": "中文提示", "example": "成功" }, "data": { "type": "object", "properties": { "status": { "type": "string", "description": "运行状态", "example": "ok" } } } }, "required": [ "code", "message", "data" ] } } } }, "401": { "description": "签名无效、时间戳过期或未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在或无权限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "重复请求或手机号已注册", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求媒体类型错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "参数校验失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求过于频繁", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "配置未就绪", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "ServiceInput": { "type": "object", "properties": { "category_id": { "type": "integer", "description": "一级类目编号，来自类目接口；草稿可空", "nullable": true, "example": 1 }, "name": { "type": "string", "description": "服务名称，发布必填，最多20字", "maxLength": 20, "example": "精致洗车" }, "refund_policy": { "type": "string", "description": "保障，默认随时退", "enum": [ "anytime", "non_refundable" ] }, "service_modes": { "type": "array", "description": "服务方式，可多选：in_store车主到店、home_visit师傅上门、pickup上门取车", "items": { "type": "string", "description": "服务方式", "enum": [ "in_store", "home_visit", "pickup" ] }, "uniqueItems": true }, "requires_appointment": { "type": "boolean", "description": "true提前预约、false免预约；草稿可空", "nullable": true }, "price": { "type": "string", "description": "售价，单位元；金额必须为字符串，非负，最多两位小数，默认0.00", "pattern": "^(0|[1-9]\\d{0,6})(\\.\\d{1,2})?$", "example": "9.80" }, "image_ids": { "type": "array", "description": "已上传的本人主图编号，发布须1至6张，按数组顺序展示", "items": { "type": "integer", "description": "图片编号", "minimum": 1 }, "maxItems": 6, "uniqueItems": true }, "detail_text": { "type": "string", "description": "图文详情纯文字，和详情图片至少提供一项", "maxLength": 20000, "example": "内外清洁，含吸尘。" }, "detail_image_ids": { "type": "array", "description": "已上传的本人详情图片编号，最多3张", "items": { "type": "integer", "description": "图片编号", "minimum": 1 }, "maxItems": 3, "uniqueItems": true }, "items": { "type": "array", "description": "可选服务内容，最多50条", "items": { "type": "object", "properties": { "description": { "type": "string", "description": "服务内容说明", "minLength": 1, "maxLength": 1000 }, "quantity": { "type": "integer", "description": "数量", "minimum": 1, "maximum": 9999 } }, "required": [ "description", "quantity" ] }, "maxItems": 50 }, "availability": { "type": "object", "properties": { "weekdays": { "type": "array", "description": "每周可用星期：1周一至7周日", "items": { "type": "integer", "description": "星期", "minimum": 1, "maximum": 7 }, "uniqueItems": true, "maxItems": 7 }, "all_day": { "type": "boolean", "description": "是否24小时；为true时periods须为空" }, "periods": { "type": "array", "description": "自定义时间段，禁止重叠或跨日；非24小时模式发布至少一段", "items": { "type": "object", "properties": { "start": { "type": "string", "description": "开始时间（含）", "example": "09:00", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" }, "end": { "type": "string", "description": "结束时间（不含），须大于开始时间；禁止跨日", "example": "21:00", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" } }, "required": [ "start", "end" ] }, "maxItems": 12 } }, "required": [ "weekdays", "all_day", "periods" ] }, "status": { "type": "string", "description": "draft草稿、on_sale在售、off_sale下架；默认draft", "enum": [ "draft", "on_sale", "off_sale" ] } }, "description": "创建及编辑均为完整替换。草稿可省略字段；在售及下架须满足完整发布规则。主图、类目、名称、服务方式、预约选项、可用时间、图文详情必填；保障默认随时退。" }, "Credentials": { "type": "object", "properties": { "mobile": { "type": "string", "description": "中国大陆手机号；当前版本不进行短信验证码验证", "pattern": "^1[3-9]\\d{9}$", "example": "13800138000" }, "password": { "type": "string", "description": "密码，8至72字节", "minLength": 8, "maxLength": 72, "format": "password" } }, "required": [ "mobile", "password" ] }, "Register": { "type": "object", "properties": { "mobile": { "type": "string", "description": "中国大陆手机号", "pattern": "^1[3-9]\\d{9}$" }, "password": { "type": "string", "description": "密码，8至72字节", "minLength": 8, "maxLength": 72, "format": "password" }, "nickname": { "type": "string", "description": "昵称，选填", "minLength": 1, "maxLength": 40 } }, "required": [ "mobile", "password" ] }, "User": { "type": "object", "properties": { "id": { "type": "integer", "description": "用户编号" }, "mobile": { "type": "string", "description": "手机号" }, "nickname": { "type": "string", "description": "昵称" }, "created_at": { "type": "integer", "description": "注册时间，Unix秒" } } }, "Upload": { "type": "object", "properties": { "id": { "type": "integer", "description": "上传图片编号" }, "url": { "type": "string", "description": "访问地址；本地可能为相对路径" }, "size_bytes": { "type": "integer", "description": "文件大小，字节" } } }, "Error": { "type": "object", "properties": { "code": { "type": "integer", "description": "HTTP错误状态码" }, "message": { "type": "string", "description": "中文错误说明" }, "data": { "nullable": true } }, "required": [ "code", "message", "data" ] }, "Service": { "type": "object", "properties": { "category_id": { "type": "integer", "description": "一级类目编号，来自类目接口；草稿可空", "nullable": true, "example": 1 }, "name": { "type": "string", "description": "服务名称，发布必填，最多20字", "maxLength": 20, "example": "精致洗车" }, "refund_policy": { "type": "string", "description": "保障，默认随时退", "enum": [ "anytime", "non_refundable" ] }, "service_modes": { "type": "array", "description": "服务方式，可多选：in_store车主到店、home_visit师傅上门、pickup上门取车", "items": { "type": "string", "description": "服务方式", "enum": [ "in_store", "home_visit", "pickup" ] }, "uniqueItems": true }, "requires_appointment": { "type": "boolean", "description": "true提前预约、false免预约；草稿可空", "nullable": true }, "price": { "type": "string", "description": "售价，单位元；金额必须为字符串，非负，最多两位小数，默认0.00", "pattern": "^(0|[1-9]\\d{0,6})(\\.\\d{1,2})?$", "example": "9.80" }, "image_ids": { "type": "array", "description": "已上传的本人主图编号，发布须1至6张，按数组顺序展示", "items": { "type": "integer", "description": "图片编号", "minimum": 1 }, "maxItems": 6, "uniqueItems": true }, "detail_text": { "type": "string", "description": "图文详情纯文字，和详情图片至少提供一项", "maxLength": 20000, "example": "内外清洁，含吸尘。" }, "detail_image_ids": { "type": "array", "description": "已上传的本人详情图片编号，最多3张", "items": { "type": "integer", "description": "图片编号", "minimum": 1 }, "maxItems": 3, "uniqueItems": true }, "items": { "type": "array", "description": "可选服务内容，最多50条", "items": { "type": "object", "properties": { "description": { "type": "string", "description": "服务内容说明", "minLength": 1, "maxLength": 1000 }, "quantity": { "type": "integer", "description": "数量", "minimum": 1, "maximum": 9999 } }, "required": [ "description", "quantity" ] }, "maxItems": 50 }, "availability": { "type": "object", "properties": { "weekdays": { "type": "array", "description": "每周可用星期：1周一至7周日", "items": { "type": "integer", "description": "星期", "minimum": 1, "maximum": 7 }, "uniqueItems": true, "maxItems": 7 }, "all_day": { "type": "boolean", "description": "是否24小时；为true时periods须为空" }, "periods": { "type": "array", "description": "自定义时间段，禁止重叠或跨日；非24小时模式发布至少一段", "items": { "type": "object", "properties": { "start": { "type": "string", "description": "开始时间（含）", "example": "09:00", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" }, "end": { "type": "string", "description": "结束时间（不含），须大于开始时间；禁止跨日", "example": "21:00", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" } }, "required": [ "start", "end" ] }, "maxItems": 12 } }, "required": [ "weekdays", "all_day", "periods" ] }, "status": { "type": "string", "description": "draft草稿、on_sale在售、off_sale下架；默认draft", "enum": [ "draft", "on_sale", "off_sale" ] }, "id": { "type": "integer", "description": "服务编号" }, "user_id": { "type": "integer", "description": "发布者编号" }, "sold_count": { "type": "integer", "description": "已购买数量，客户端不可写" }, "images": { "type": "array", "description": "主图有序列表", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "图片编号" }, "url": { "type": "string", "description": "图片URL" } } } }, "detail_images": { "type": "array", "description": "详情图片有序列表", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "图片编号" }, "url": { "type": "string", "description": "图片URL" } } } }, "created_at": { "type": "integer", "description": "创建时间，Unix秒" }, "updated_at": { "type": "integer", "description": "更新时间，Unix秒" }, "deleted_at": { "type": "integer", "description": "软删除时间", "nullable": true } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "登录返回的随机令牌" }, "AppId": { "type": "apiKey", "in": "header", "name": "X-App-Id", "description": "应用ID" }, "Timestamp": { "type": "apiKey", "in": "header", "name": "X-Timestamp", "description": "Unix秒时间戳，误差最多300秒" }, "Nonce": { "type": "apiKey", "in": "header", "name": "X-Nonce", "description": "16至64位每次唯一随机串" }, "Signature": { "type": "apiKey", "in": "header", "name": "X-Signature", "description": "HMAC-SHA256小写十六进制签名" } } } }