{ "openapi": "3.0.3", "info": { "title": "云泉智配小程序 API", "version": "1.0.0", "description": "按实际 /api/mini/v1 路由整理。金额为人民币整数分，时间为Asia/Shanghai的YYYY-MM-DD HH:mm:ss（非RFC3339）。POST JSON；未知业务字段拒绝。普通请求≤65536字节，照片≤3000000。GET/POST成功统一code/message/data/request_id，照片和HEAD除外。业务身份必须后台绑定，后台JWT不能用于本API。所有资源权限由服务器复核。购水订单仅给客户成交时直接归属代理按后台当前比例计提佣金，默认一级10%、二级5%、三级2%，当前待结算；微信支付、佣金结算与提现、奖励与设备绑定尚未开放，以capabilities为准。OPTIONS由边界中间件返回204（浏览器Origin须在白名单）；health/session的POST/PUT/PATCH/DELETE返回40501，不作为业务操作列入。" }, "servers": [ { "url": "http://127.0.0.1:8787/api/mini/v1", "description": "本机调试；真机替换为已配置的HTTPS合法域名" } ], "security": [ { "MiniBearer": [] } ], "tags": [ { "name": "公共与登录" }, { "name": "套餐" }, { "name": "企业" }, { "name": "司机" }, { "name": "代理" }, { "name": "照片" } ], "paths": { "/health": { "get": { "tags": [ "公共与登录" ], "summary": "服务状态", "operationId": "get_health", "description": "仅表示 API 服务可响应，不代表支付、微信凭据或全部基础设施可用。", "parameters": [], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Health" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [] }, "head": { "tags": [ "公共与登录" ], "summary": "服务状态（无响应体）", "operationId": "head_health", "description": "服务状态（无响应体）", "parameters": [], "responses": { "200": { "description": "成功，无响应体" }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [] } }, "/config": { "get": { "tags": [ "公共与登录" ], "summary": "前端配置与能力开关", "operationId": "get_config", "description": "前端配置与能力开关", "parameters": [], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Config" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [] } }, "/auth/wechat": { "post": { "tags": [ "公共与登录" ], "summary": "微信 code 登录", "operationId": "post_auth_wechat", "description": "wx.login 获取 code 后提交。未绑定业务身份时 identities=[]；需后台明确授权。未配置微信凭据返回50301，不能伪造用户登录。", "parameters": [], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Login" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" }, "example": { "code": "replace-with-wx-login-code" } } } } } }, "/auth/logout": { "post": { "tags": [ "公共与登录" ], "summary": "退出登录", "operationId": "post_auth_logout", "description": "撤销当前令牌；无必填请求体，可发送 {}。", "parameters": [], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "logged_out": { "type": "boolean" } }, "required": [ "logged_out" ] }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/session": { "get": { "tags": [ "公共与登录" ], "summary": "会话主体", "operationId": "get_session", "description": "会话主体", "parameters": [], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "user_id": { "type": "string" } }, "required": [ "user_id" ] }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "head": { "tags": [ "公共与登录" ], "summary": "检查会话（无响应体）", "operationId": "head_session", "description": "检查会话（无响应体）", "parameters": [], "responses": { "200": { "description": "令牌有效，无响应体" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/packages": { "get": { "tags": [ "套餐" ], "summary": "套餐列表", "operationId": "get_packages", "description": "套餐列表", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 1000000, "default": 1 } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "keyword", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all" ] } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/PackagePage" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [] } }, "/packages/{id}": { "get": { "tags": [ "套餐" ], "summary": "套餐详情", "operationId": "get_packages_id", "description": "套餐详情", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Package" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [] } }, "/me": { "get": { "tags": [ "公共与登录" ], "summary": "当前用户与业务身份", "operationId": "get_me", "description": "当前用户与业务身份", "parameters": [ { "name": "enterprise_id", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "description": "选填；传入时返回该企业信息和权益汇总并校验权限" } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Profile" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/addresses": { "get": { "tags": [ "公共与登录" ], "summary": "可访问的企业地址列表", "operationId": "get_addresses", "description": "可访问的企业地址列表", "parameters": [], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Addresses" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/enterprises/{enterprise}/home": { "get": { "tags": [ "企业" ], "summary": "企业首页", "operationId": "get_enterprises_enterprise_home", "description": "企业管理员或成员可读。权益按企业+SKU汇总；没有消息数据时 unread_messages=null。", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Home" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/enterprises/{enterprise}/rights": { "get": { "tags": [ "企业" ], "summary": "权益与现场库存", "operationId": "get_enterprises_enterprise_rights", "description": "企业管理员或成员可读。不是按购买订单拆分的水卡，不提供虚构的有效期。", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Rights" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/enterprises/{enterprise}/ledger": { "get": { "tags": [ "企业" ], "summary": "权益相关流水", "operationId": "get_enterprises_enterprise_ledger", "description": "企业管理员或成员可读。quantity 是操作桶数；预约是冻结、取消是释放，不能直接将流水数量全部求和作为余额。", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 1000000, "default": 1 } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/LedgerPage" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/enterprises/{enterprise}/orders": { "get": { "tags": [ "企业" ], "summary": "企业订单列表", "operationId": "get_enterprises_enterprise_orders", "description": "企业管理员或成员可读。按 kind 选择三种独立数据结构；这些订单 ID 不通用。", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 1000000, "default": 1 } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "purchases", "deliveries", "checkouts" ], "default": "deliveries" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "pending", "transit", "completed", "cancelled", "exception" ], "default": "all" }, "description": "仅 kind=deliveries 生效；pending 包含 pending/assigned；exception 对应 returning/returned" } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/EnterpriseOrderPage" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/enterprises/{enterprise}/devices": { "get": { "tags": [ "企业" ], "summary": "企业设备列表", "operationId": "get_enterprises_enterprise_devices", "description": "企业设备列表", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 1000000, "default": 1 } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/DevicePage" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/enterprises/{enterprise}/devices/{id}": { "get": { "tags": [ "企业" ], "summary": "设备详情与七日用量", "operationId": "get_enterprises_enterprise_devices_id", "description": "设备详情与七日用量", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/DeviceDetail" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/enterprises/{enterprise}/rewards": { "get": { "tags": [ "企业" ], "summary": "推广奖励能力", "operationId": "get_enterprises_enterprise_rewards", "description": "企业管理员或成员读取真实邀请及赠水记录。现金字段恒为null；每页20条，total为邀请总数。活动关闭仍可读取历史；测试展示数据不再作为奖励返回。付款凭据、金额、配送ID及内部核实说明不向邀请企业公开。", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Rewards" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/enterprises/{enterprise}/deliveries/{id}": { "get": { "tags": [ "企业" ], "summary": "配送跟踪", "operationId": "get_enterprises_enterprise_deliveries_id", "description": "企业管理员或成员可读。无实时司机GPS或承诺到达时间。", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Tracking" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/enterprises/{enterprise}/address": { "get": { "tags": [ "企业" ], "summary": "编辑用地址详情", "operationId": "get_enterprises_enterprise_address", "description": "仅企业管理员，返回完整联系电话和 revision。", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/EditableAddress" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "企业" ], "summary": "修改供水地址", "operationId": "post_enterprises_enterprise_address", "description": "仅企业管理员。版本变化40901；存在未结束配送40902（含并发创建的任务）。地址变化会清空坐标，需要后台重新定位。", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/AddressResult" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressRequest" }, "example": { "request_key": "address-20260918-0001", "revision": "replace-with-current-revision", "address": "深圳市示例配送地址", "contact": "张先生", "phone": "138-1234-5678" } } } } } }, "/enterprises/{enterprise}/deliveries": { "post": { "tags": [ "企业" ], "summary": "预约配送", "operationId": "post_enterprises_enterprise_deliveries", "description": "仅企业管理员。使用已购权益和库存并冻结数量；不接受客户端预约时段或调度日期。", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/CommandResult" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingRequest" }, "example": { "request_key": "booking-20260918-0001", "sku_id": 2, "quantity": 8 } } } } } }, "/enterprises/{enterprise}/deliveries/{id}/cancel": { "post": { "tags": [ "企业" ], "summary": "取消未派单配送", "operationId": "post_enterprises_enterprise_deliveries_id_cancel", "description": "仅企业管理员；只允许 pending/cancelled，已派单由后台处理。", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/CommandResult" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandRequest" } } } } } }, "/enterprises/{enterprise}/checkout/quote": { "post": { "tags": [ "企业" ], "summary": "计算套餐报价", "operationId": "post_enterprises_enterprise_checkout_quote", "description": "仅企业管理员；服务器计算价格，不扣款、不产生订单或权益。", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Quote" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" }, "example": { "items": [ { "package_id": 3, "quantity": 2 } ] } } } } } }, "/enterprises/{enterprise}/checkouts": { "post": { "tags": [ "企业" ], "summary": "创建待支付意向", "operationId": "post_enterprises_enterprise_checkouts", "description": "仅企业管理员；expected_amount_cents 必须等于报价，变化返回40904。意向30分钟有效；不扣款、不发权益、不代表真实收款或开票。", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Checkout" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutRequest" }, "example": { "request_key": "checkout-20260918-0001", "items": [ { "package_id": 3, "quantity": 2 } ], "expected_amount_cents": 139800, "agreement_accepted": true } } } } } }, "/enterprises/{enterprise}/checkouts/{id}": { "get": { "tags": [ "企业" ], "summary": "待支付意向详情", "operationId": "get_enterprises_enterprise_checkouts_id", "description": "待支付意向详情", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/CheckoutDetail" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/enterprises/{enterprise}/checkouts/{id}/cancel": { "post": { "tags": [ "企业" ], "summary": "取消待支付意向", "operationId": "post_enterprises_enterprise_checkouts_id_cancel", "description": "仅企业管理员；取消pending或已取消的意向，不处理真实收款退款。", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Checkout" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandRequest" } } } } } }, "/enterprises/{enterprise}/checkouts/{id}/pay": { "post": { "tags": [ "企业" ], "summary": "支付订单", "operationId": "post_enterprises_enterprise_checkouts_id_pay", "description": "企业余额支付按创建订单时保存的价格、SKU、桶数快照扣款并发放权益，30分钟内有效。套餐修改、下架、删除不影响已有有效订单；原商品规格或企业停用时拒绝支付。扣款、收款记录和权益同事务提交。微信支付尚未接入，返回50303。", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "余额支付成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Checkout" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayRequest" }, "example": { "request_key": "pay-20260924-0001", "payment_method": "balance" } } } } } }, "/drivers/{driver}/dashboard": { "get": { "tags": [ "司机" ], "summary": "司机工作台", "operationId": "get_drivers_driver_dashboard", "description": "必须有该司机身份；今日班次、任务和未结算路线。", "parameters": [ { "name": "driver", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/DriverDashboard" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/drivers/{driver}/tasks": { "get": { "tags": [ "司机" ], "summary": "司机任务列表", "operationId": "get_drivers_driver_tasks", "description": "司机任务列表", "parameters": [ { "name": "driver", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 1000000, "default": 1 } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "pending", "transit", "completed", "exception" ], "default": "all" }, "description": "pending=assigned；exception=returning/returned；全部状态只限分配给本司机的任务" } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/TaskPage" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/drivers/{driver}/routes": { "get": { "tags": [ "司机" ], "summary": "司机未结算路线", "operationId": "get_drivers_driver_routes", "description": "最多50条，返回 data 数组，不分页；每条 stops 按 stop_order/id 排序。", "parameters": [ { "name": "driver", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Route" } }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/drivers/{driver}/tasks/{id}": { "get": { "tags": [ "司机" ], "summary": "司机任务详情", "operationId": "get_drivers_driver_tasks_id", "description": "司机任务详情", "parameters": [ { "name": "driver", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/TaskDetail" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/drivers/{driver}/tasks/{id}/start": { "post": { "tags": [ "司机" ], "summary": "出发配送", "operationId": "post_drivers_driver_tasks_id_start", "description": "本人任务从 assigned 出发进入 transit；使用既有库存出库事务。", "parameters": [ { "name": "driver", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/CommandResult" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandRequest" } } } } } }, "/drivers/{driver}/tasks/{id}/checkin": { "post": { "tags": [ "司机" ], "summary": "到达打卡", "operationId": "post_drivers_driver_tasks_id_checkin", "description": "仅 transit；wx.getLocation({type:\"gcj02\"}) 上报数值坐标。只记录客户端坐标，location_verified=false。", "parameters": [ { "name": "driver", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/CheckinResult" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckinRequest" }, "example": { "request_key": "checkin-20260918-0001", "latitude": 22.522806, "longitude": 113.92414 } } } } } }, "/drivers/{driver}/tasks/{id}/draft": { "post": { "tags": [ "司机" ], "summary": "暂存履约记录", "operationId": "post_drivers_driver_tasks_id_draft", "description": "仅 transit；保存草稿，不扣权益、不完成配送。可不传照片或 confirmed。", "parameters": [ { "name": "driver", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/DraftResult" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftRequest" } } } } } }, "/drivers/{driver}/tasks/{id}/complete": { "post": { "tags": [ "司机" ], "summary": "确认实际签收", "operationId": "post_drivers_driver_tasks_id_complete", "description": "仅 transit；当前用户必须先打卡。照片须属于本任务，1–4张，不重复。accepted_qty不能超过计划数；部分/全部拒收须reason。按实际签收扣权益；有余货进入returning，交后台退货结算。", "parameters": [ { "name": "driver", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/CommandResult" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteRequest" }, "example": { "request_key": "complete-20260918-0001", "accepted_qty": 8, "empty_returned": 0, "receiver": "张先生", "reason": "", "photo_ids": [ 12 ], "confirmed": true } } } } } }, "/drivers/{driver}/tasks/{id}/exception": { "post": { "tags": [ "司机" ], "summary": "上报配送异常", "operationId": "post_drivers_driver_tasks_id_exception", "description": "仅 transit；仅记录异常，不自动取消或完成任务，不改变库存权益。", "parameters": [ { "name": "driver", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/ExceptionResult" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExceptionRequest" } } } } } }, "/drivers/{driver}/tasks/{id}/photos": { "post": { "tags": [ "司机" ], "summary": "上传履约照片", "operationId": "post_drivers_driver_tasks_id_photos", "description": "仅 transit；最多20张/任务。JSON请求≤3,000,000字节；原图≤2MiB，JPEG/PNG。服务端重编码JPEG并叠加服务器时间及上报坐标。", "parameters": [ { "name": "driver", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/PhotoResult" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoRequest" } } } } } }, "/drivers/{driver}/tasks/{id}/device-check": { "get": { "tags": [ "司机" ], "summary": "查询当前企业设备登记状态", "operationId": "get_drivers_driver_tasks_id_device_check", "description": "仅查已绑定该任务企业的设备；不执行绑定，不把登记当成联网测试成功。", "parameters": [ { "name": "driver", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "sn", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": "设备序列号" } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/DeviceCheck" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/photos/{id}": { "get": { "tags": [ "照片" ], "summary": "读取私有履约照片", "operationId": "get_photos_id", "description": "携带Bearer并校验该照片对应任务归属；成功直接返回JPEG字节，无JSON包装。微信端使用wx.downloadFile的header传令牌，获得临时路径后展示。", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "scope", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "enterprise", "driver" ] }, "description": "访问业务身份" }, { "name": "resource_id", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "description": "企业或司机ID，与scope对应" } ], "responses": { "200": { "description": "JPEG照片；Cache-Control:no-store", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agents/{agent}/dashboard": { "get": { "tags": [ "代理" ], "summary": "代理经营看板", "operationId": "get_agents_agent_dashboard", "description": "本代理及有效下级企业，按企业当前归属统计真实收款；历史订单可能随企业归属变化，不是佣金账本。", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/AgentDashboard" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agents/{agent}/customers": { "get": { "tags": [ "代理" ], "summary": "代理客户列表", "operationId": "get_agents_agent_customers", "description": "new=本月新增；unpaid=截至当前时间无收款。summary不随关键词/分页/筛选变化。金额排除未来日期记录。", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 1000000, "default": 1 } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "keyword", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "name": "filter", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "new", "unpaid" ], "default": "all" } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/CustomerPage" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agents/{agent}/orders": { "get": { "tags": [ "代理" ], "summary": "代理范围内已收款订单", "operationId": "get_agents_agent_orders", "description": "不含小程序待支付意向；排除未来日期记录。", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 1000000, "default": 1 } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "enterprise_id", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "description": "仅缩小当前代理范围；不在范围返回空列表" } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/AgentOrderPage" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agents/{agent}/commissions": { "get": { "tags": [ "代理" ], "summary": "代理佣金计提明细", "operationId": "get_agents_agent_commissions", "description": "正式订单仅给成交时客户直接归属代理按后台当前比例计提，默认一级10%、二级5%、三级2%。新佣金状态为pending，提现未开放。历史订单不补记；调整比例不重算历史佣金；source=demo仅返回本地演示数据。", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "all", "pending", "settled", "adjustment", "withdrawn" ], "default": "all" } }, { "name": "source", "in": "query", "description": "默认正式佣金账本；demo仅用于本地测试夹具", "schema": { "type": "string", "enum": [ "regular", "demo" ], "default": "regular" } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Commissions" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agents/{agent}/withdrawals": { "post": { "tags": [ "代理" ], "summary": "佣金提现（尚未开通）", "operationId": "post_agents_agent_withdrawals", "description": "校验代理身份后返回 HTTP503/code50303，不创建提现申请，无提现请求参数。可发送 {}。", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/auth/send-sms": { "post": { "tags": [ "公共与登录" ], "summary": "下发短信登录验证码", "operationId": "post_auth_send_sms", "description": "需开启 MINI_SMS_LOGIN 且配置短信宝账号。手机号必须先在后台绑定到已有小程序账号，否则不会真正下发短信。为防止枚举注册手机号，已绑定与未绑定返回完全一致的成功响应，未绑定时不发送也不落库。服务端限流：同号 60 秒内不可重发、同号每日上限、单 IP 每小时上限；超限返回 42901。验证码 6 位、2 分钟（120秒）过期、仅存哈希、单次有效、重发即作废旧码、连续错误 5 次作废。发送失败统一 50302，不透出短信宝返回码。", "parameters": [], "responses": { "200": { "description": "成功；JSON 业务码 code=0。无论手机号是否绑定均返回此结构。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "sent": { "type": "boolean", "example": true }, "expires_in": { "type": "integer", "example": 120 } }, "required": [ "sent", "expires_in" ] }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "phone" ], "properties": { "phone": { "type": "string", "pattern": "^1[3-9][0-9]{9}$" } } }, "example": { "phone": "13800138000" } } } } } }, "/auth/phone-login": { "post": { "tags": [ "公共与登录" ], "summary": "短信验证码登录", "operationId": "post_auth_phone_login", "description": "需开启 MINI_SMS_LOGIN。校验通过后登录到该手机号所绑定的小程序账号，user_id、身份与权限与同一账号的微信登录完全一致；验证码消费后立即作废，重复提交返回 40102。手机号未绑定或账号已停用时同样返回 40102，不透露账号是否存在。验证码错误累计 5 次后该验证码作废，需重新获取。", "parameters": [], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Login" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "phone", "code" ], "properties": { "phone": { "type": "string", "pattern": "^1[3-9][0-9]{9}$" }, "code": { "type": "string", "pattern": "^[0-9]{6}$" } } }, "example": { "phone": "13800138000", "code": "123456" } } } } } }, "/auth/test-phone": { "post": { "tags": [ "公共与登录" ], "summary": "本地测试手机号登录", "operationId": "post_auth_test_phone", "description": "仅 APP_ENV=local 且 MINI_TEST_PHONE_LOGIN=true 开启，要求连接来源为本机回环地址（不信任代理头）。固定测试身份，与微信及真实手机身份隔离；账号须预先初始化，仅获得已绑定权限。关闭开关后既有测试会话失效。非短信验证接口，禁止正式部署启用。", "parameters": [], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Login" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "phone", "code" ], "properties": { "phone": { "type": "string", "enum": [ "13012345678" ] }, "code": { "type": "string", "enum": [ "66666" ] } } }, "example": { "phone": "13012345678", "code": "66666" } } } } } }, "/enterprises/{enterprise}/addresses": { "post": { "tags": [ "企业" ], "summary": "新增配送地址", "operationId": "post_enterprises_enterprise_addresses", "description": "仅企业管理员。首个地址自动设为默认；写入使用请求标识保证幂等。", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/DeliveryAddressResult" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryAddressCreate" }, "example": { "request_key": "address-create-20261008-0001", "label": "办公楼", "address": "深圳市示例地址", "contact": "张先生", "phone": "13812345678", "is_default": true } } } } } }, "/enterprises/{enterprise}/addresses/{address}": { "get": { "tags": [ "企业" ], "summary": "读取配送地址详情", "operationId": "get_enterprises_enterprise_addresses_address", "description": "仅企业管理员。按企业和配送地址 ID 校验归属，返回编辑资料与版本。", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/EditableAddress" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "企业" ], "summary": "修改配送地址", "operationId": "post_enterprises_enterprise_addresses_address", "description": "仅企业管理员。校验地址归属及 revision；该地址存在有效配送时禁止修改位置。", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/DeliveryAddressResult" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryAddressUpdate" }, "example": { "request_key": "address-create-20261008-0001", "label": "办公楼", "address": "深圳市示例地址", "contact": "张先生", "phone": "13812345678", "is_default": true, "revision": "replace-with-current-revision" } } } } } }, "/enterprises/{enterprise}/promotion/code": { "post": { "tags": [ "企业" ], "summary": "获取专属企业邀请码", "operationId": "post_enterprises_enterprise_promotion_code", "description": "仅企业管理员；复用request_key幂等、撤权复核及审计。活动开启后生成企业唯一随机邀请码。", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/PromotionCodeResult" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionCodeRequest" }, "example": { "request_key": "promotion-code-20261019" } } } } } }, "/enterprises/{enterprise}/promotion/bind": { "post": { "tags": [ "企业" ], "summary": "首购前绑定企业邀请人", "operationId": "post_enterprises_enterprise_promotion_bind", "description": "仅企业管理员；复用request_key幂等、撤权复核及审计。活动开启且从未购水的企业仅可绑定一次；禁止自邀、共用管理员及循环邀请，规则在绑定时快照。", "parameters": [ { "name": "enterprise", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "成功；JSON 业务码 code=0", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/CommandResult" }, "request_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionBindRequest" }, "example": { "request_key": "promotion-bind-20261019", "invite_code": "AABBCCDDEEFF00112233" } } } } } } }, "components": { "securitySchemes": { "MiniBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "Opaque token", "description": "POST /auth/wechat 返回的 access_token；非后台JWT" } }, "schemas": { "Error": { "type": "object", "properties": { "code": { "type": "integer", "format": "int64", "description": "业务错误码" }, "message": { "type": "string", "description": "适合向用户展示的说明" }, "data": { "type": "object", "properties": { "fields": { "type": "object", "additionalProperties": { "type": "string", "description": "字段错误说明" } } }, "nullable": true }, "request_id": { "type": "string", "description": "排障时提供此编号", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "code", "message", "data", "request_id" ] }, "Identity": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "enterprise_admin", "enterprise_member", "driver", "agent" ] }, "resource_id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "name": { "type": "string" } }, "required": [ "role", "resource_id", "name" ] }, "Login": { "type": "object", "properties": { "access_token": { "type": "string", "description": "随机不透明令牌，前端不要解析", "minLength": 64, "maxLength": 64 }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_at": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00" }, "user_id": { "type": "string", "description": "用户 ID 是字符串" }, "identities": { "type": "array", "items": { "$ref": "#/components/schemas/Identity" } } }, "required": [ "access_token", "token_type", "expires_at", "user_id", "identities" ] }, "Enterprise": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "name": { "type": "string" }, "contact": { "type": "string" }, "phone": { "type": "string", "description": "脱敏电话；无号码为空串，无法识别的历史格式返回 ****" }, "address": { "type": "string" }, "region": { "type": "string" }, "longitude": { "type": "number", "nullable": true }, "latitude": { "type": "number", "nullable": true }, "employee_count": { "type": "integer", "format": "int64", "nullable": true }, "revision": { "type": "string", "description": "编辑地址时原样提交的版本", "minLength": 64, "maxLength": 64 } }, "required": [ "id", "name", "contact", "phone", "address", "region", "longitude", "latitude", "employee_count", "revision" ] }, "EditableAddress": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 0, "maximum": 2147483647 }, "name": { "type": "string" }, "contact": { "type": "string" }, "phone": { "type": "string", "description": "仅企业管理员可读完整号码；表单应使用此接口，不能使用脱敏列表" }, "address": { "type": "string" }, "region": { "type": "string" }, "longitude": { "type": "number", "nullable": true }, "latitude": { "type": "number", "nullable": true }, "employee_count": { "type": "integer", "format": "int64", "nullable": true }, "revision": { "type": "string", "description": "编辑地址时原样提交的版本", "minLength": 64, "maxLength": 64 }, "enterprise_id": { "type": "integer", "minimum": 1 }, "label": { "type": "string" }, "is_default": { "type": "boolean" }, "status": { "type": "integer" } }, "required": [ "id", "name", "contact", "phone", "address", "region", "longitude", "latitude", "employee_count", "revision" ] }, "Package": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "name": { "type": "string" }, "sku_id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "sku_name": { "type": "string", "nullable": true }, "liters": { "type": "number", "nullable": true }, "buckets": { "type": "integer", "format": "int64", "description": "套餐总桶数" }, "price_cents": { "type": "integer", "format": "int64", "description": "人民币整数分", "minimum": 0 }, "unit_price_cents": { "type": "integer", "format": "int64", "description": "每桶参考单价，四舍五入为整数分" }, "category": { "type": "string", "nullable": true, "description": "当前为 null，尚无可用数据" }, "valid_months": { "type": "integer", "nullable": true, "description": "当前为 null，尚无可用数据" }, "includes_device": { "type": "boolean", "nullable": true, "description": "当前为 null，尚无可用数据" } }, "required": [ "id", "name", "sku_id", "sku_name", "liters", "buckets", "price_cents", "unit_price_cents", "category", "valid_months", "includes_device" ] }, "PackagePage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Package" } }, "total": { "type": "integer", "format": "int64" }, "page": { "type": "integer", "format": "int64" }, "page_size": { "type": "integer", "format": "int64" }, "has_more": { "type": "boolean" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "all" ] }, "label": { "type": "string" } }, "required": [ "value", "label" ] } }, "capabilities": { "type": "object", "properties": { "category_filter": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" } }, "required": [ "category_filter" ] } }, "required": [ "items", "total", "page", "page_size", "has_more", "categories", "capabilities" ] }, "RightsSummary": { "type": "object", "properties": { "remaining": { "type": "integer", "format": "int64", "description": "剩余权益（含冻结）" }, "available": { "type": "integer", "format": "int64", "description": "可用权益" }, "frozen": { "type": "integer", "format": "int64", "description": "已预约冻结" }, "full_qty": { "type": "integer", "format": "int64", "description": "现场满桶" }, "purchased": { "type": "integer", "format": "int64", "description": "历史购买桶数" }, "delivered": { "type": "integer", "format": "int64", "description": "历史实收桶数" } }, "required": [ "remaining", "available", "frozen", "full_qty", "purchased", "delivered" ] }, "Rights": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "sku_id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "sku_name": { "type": "string", "nullable": true }, "liters": { "type": "number", "nullable": true }, "remaining": { "type": "integer", "format": "int64" }, "frozen": { "type": "integer", "format": "int64" }, "available": { "type": "integer", "format": "int64" }, "full_qty": { "type": "integer", "format": "int64" }, "empty_qty": { "type": "integer", "format": "int64" }, "days_left": { "type": "number", "description": "预计可用天数", "nullable": true }, "severity": { "type": "string", "enum": [ "healthy", "normal", "urgent" ] }, "expires_at": { "type": "string", "nullable": true, "description": "当前为 null，尚无可用数据" } }, "required": [ "id", "sku_id", "sku_name", "liters", "remaining", "frozen", "available", "full_qty", "empty_qty", "days_left", "severity", "expires_at" ] } }, "summary": { "$ref": "#/components/schemas/RightsSummary" }, "policy": { "type": "object", "properties": { "alert_qty": { "type": "integer", "format": "int64" }, "days_per_barrel": { "type": "integer", "format": "int64" }, "urgent_qty": { "type": "integer", "format": "int64" }, "revision": { "type": "integer", "format": "int64" }, "updated_at": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00" }, "comparison": { "type": "string", "enum": [ "lt" ] }, "accuracy_available": { "type": "boolean" } }, "required": [ "alert_qty", "days_per_barrel", "urgent_qty", "revision", "updated_at", "comparison", "accuracy_available" ] }, "accounting": { "type": "string", "enum": [ "enterprise_sku" ] }, "capabilities": { "type": "object", "properties": { "individual_package_cards": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "expiry_deduction": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" } }, "required": [ "individual_package_cards", "expiry_deduction" ] } }, "required": [ "items", "summary", "policy", "accounting", "capabilities" ] }, "Profile": { "type": "object", "properties": { "user_id": { "type": "string" }, "identities": { "type": "array", "items": { "$ref": "#/components/schemas/Identity" } }, "balance_cents": { "type": "integer", "nullable": true, "description": "当前企业可用余额，人民币整数分" }, "reward_cents": { "type": "integer", "nullable": true, "description": "当前为 null，尚无可用数据" }, "capabilities": { "type": "object", "properties": { "balance_payment": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "rewards": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "withdrawals": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" } }, "required": [ "balance_payment", "rewards", "withdrawals" ] }, "enterprise": { "$ref": "#/components/schemas/Enterprise" }, "rights": { "$ref": "#/components/schemas/RightsSummary" }, "reward_buckets": { "type": "integer", "nullable": true, "description": "累计已发放的推广赠水桶数，非现金、非剩余权益" } }, "required": [ "user_id", "identities", "balance_cents", "reward_cents", "capabilities", "reward_buckets" ] }, "Addresses": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryAddress" } }, "capabilities": { "type": "object", "properties": { "multiple_sites_per_enterprise": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "self_create_enterprise": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" } }, "required": [ "multiple_sites_per_enterprise", "self_create_enterprise" ] }, "service_hours": { "type": "string", "nullable": true, "description": "当前为 null，尚无可用数据" }, "coverage_verified": { "type": "boolean" } }, "required": [ "items", "capabilities", "service_hours", "coverage_verified" ] }, "Delivery": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "code": { "type": "string", "description": "展示配送号，例如 DS123" }, "sku_id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "sku_name": { "type": "string", "nullable": true }, "quantity": { "type": "integer", "format": "int64", "description": "计划配送桶数" }, "status": { "type": "string", "enum": [ "pending", "assigned", "transit", "completed", "cancelled", "returning", "returned" ] }, "delivered_qty": { "type": "integer", "format": "int64", "description": "实际签收桶数" }, "empty_returned": { "type": "integer", "format": "int64" }, "address": { "type": "string" }, "scheduled_date": { "type": "string", "format": "date", "nullable": true }, "deadline_at": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00", "nullable": true }, "driver_name": { "type": "string" }, "driver_phone": { "type": "string", "description": "脱敏电话；无号码为空串，无法识别的历史格式返回 ****" }, "created_at": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00" }, "received_at": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00", "nullable": true }, "completed_at": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00", "nullable": true } }, "required": [ "id", "code", "sku_id", "sku_name", "quantity", "status", "delivered_qty", "empty_returned", "address", "scheduled_date", "deadline_at", "driver_name", "driver_phone", "created_at", "received_at", "completed_at" ] }, "PhotoMeta": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "created_at": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00" } }, "required": [ "id", "created_at" ] }, "Tracking": { "allOf": [ { "$ref": "#/components/schemas/Delivery" }, { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string", "description": "后台履约动作或 depart/checkin/exception" }, "created_at": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00" } }, "required": [ "action", "created_at" ] } }, "photos": { "type": "array", "items": { "$ref": "#/components/schemas/PhotoMeta" } }, "eta": { "type": "string", "nullable": true, "description": "当前为 null，尚无可用数据" }, "distance_km": { "type": "number", "nullable": true, "description": "当前为 null，尚无可用数据" }, "capabilities": { "type": "object", "properties": { "live_gps": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" } }, "required": [ "live_gps" ] } }, "required": [ "events", "photos", "eta", "distance_km", "capabilities" ] } ] }, "Device": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "name": { "type": "string" }, "sn": { "type": "string" }, "sku_id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "state": { "type": "string", "enum": [ "fault", "unconnected", "offline", "online" ] }, "last_seen": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00", "nullable": true }, "today_liters": { "type": "number", "description": "无当日遥测时 null，不能显示成 0", "nullable": true }, "fault": { "type": "string" } }, "required": [ "id", "name", "sn", "sku_id", "state", "last_seen", "today_liters", "fault" ] }, "DevicePage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Device" } }, "total": { "type": "integer", "format": "int64" }, "page": { "type": "integer", "format": "int64" }, "page_size": { "type": "integer", "format": "int64" }, "has_more": { "type": "boolean" } }, "required": [ "items", "total", "page", "page_size", "has_more" ] }, "DeviceDetail": { "allOf": [ { "$ref": "#/components/schemas/Device" }, { "type": "object", "properties": { "trend": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "format": "date" }, "liters": { "type": "number", "nullable": true } }, "required": [ "day", "liters" ] } }, "rights": { "$ref": "#/components/schemas/Rights" }, "automatic_delivery": { "type": "boolean" } }, "required": [ "trend", "rights", "automatic_delivery" ] } ] }, "Banner": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "title": { "type": "string" }, "image_url": { "type": "string" }, "target_url": { "type": "string" }, "audience": { "type": "string", "enum": [ "all", "new", "purchased", "enterprise_admin" ] }, "region": { "type": "string", "nullable": true }, "starts_at": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00", "nullable": true }, "ends_at": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00", "nullable": true }, "sort": { "type": "integer", "format": "int64" }, "status": { "type": "integer", "format": "int64" }, "created_at": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00" }, "updated_at": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00" }, "delivery_status": { "type": "string" }, "status_label": { "type": "string" } }, "required": [ "id", "title", "image_url", "target_url", "audience", "region", "starts_at", "ends_at", "sort", "status", "created_at", "updated_at", "delivery_status", "status_label" ] }, "Home": { "type": "object", "properties": { "enterprise": { "$ref": "#/components/schemas/Enterprise" }, "banners": { "type": "array", "items": { "$ref": "#/components/schemas/Banner" } }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/Package" } }, "rights": { "$ref": "#/components/schemas/Rights" }, "devices": { "$ref": "#/components/schemas/DevicePage" }, "unread_messages": { "type": "integer", "nullable": true, "description": "当前为 null，尚无可用数据" }, "capabilities": { "type": "object", "properties": { "coupon": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "messages": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "automatic_delivery": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" } }, "required": [ "coupon", "messages", "automatic_delivery" ] } }, "required": [ "enterprise", "banners", "packages", "rights", "devices", "unread_messages", "capabilities" ] }, "LedgerPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "sku_id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "kind": { "type": "string", "enum": [ "purchase", "reserve", "cancel", "complete", "partial_receive", "delivery_return" ] }, "quantity": { "type": "integer", "format": "int64" }, "reference": { "type": "string" }, "created_at": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00" } }, "required": [ "id", "sku_id", "kind", "quantity", "reference", "created_at" ] } }, "total": { "type": "integer", "format": "int64" }, "page": { "type": "integer", "format": "int64" }, "page_size": { "type": "integer", "format": "int64" }, "has_more": { "type": "boolean" }, "quantity_semantics": { "type": "string", "description": "操作桶数不等于权益扣减数" } }, "required": [ "items", "total", "page", "page_size", "has_more", "quantity_semantics" ] }, "Purchase": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "package_name": { "type": "string" }, "sku_id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "buckets": { "type": "integer", "format": "int64" }, "amount_cents": { "type": "integer", "format": "int64", "description": "人民币整数分", "minimum": 0 }, "created_at": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00" } }, "required": [ "id", "package_name", "sku_id", "buckets", "amount_cents", "created_at" ] }, "QuoteItem": { "type": "object", "properties": { "package_id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "name": { "type": "string" }, "sku_id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "quantity": { "type": "integer", "format": "int64", "description": "套餐份数" }, "buckets": { "type": "integer", "format": "int64", "description": "本行总桶数" }, "unit_price_cents": { "type": "integer", "format": "int64", "description": "每份套餐价；与套餐详情的每桶单价语义不同" }, "amount_cents": { "type": "integer", "format": "int64", "description": "人民币整数分", "minimum": 0 } }, "required": [ "package_id", "name", "sku_id", "quantity", "buckets", "unit_price_cents", "amount_cents" ] }, "Quote": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteItem" } }, "subtotal_cents": { "type": "integer", "format": "int64", "description": "人民币整数分", "minimum": 0 }, "discount_cents": { "type": "integer", "format": "int64", "description": "人民币整数分", "minimum": 0 }, "amount_cents": { "type": "integer", "format": "int64", "description": "人民币整数分", "minimum": 0 }, "payment_methods": { "type": "array", "items": { "type": "string" } }, "capabilities": { "type": "object", "properties": { "payment": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "balance": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "first_purchase_discount": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "invoice_issuance": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" } }, "required": [ "payment", "balance", "first_purchase_discount", "invoice_issuance" ] }, "agreement_url": { "type": "string", "nullable": true }, "balance_cents": { "type": "integer", "format": "int64", "minimum": 0, "description": "当前企业可用余额，人民币整数分" }, "quote_revision": { "type": "string", "minLength": 64, "maxLength": 64, "description": "服务器对套餐价格、名称、规格和桶数生成的报价版本；下单原样提交，变更返回40904" } }, "required": [ "items", "subtotal_cents", "discount_cents", "amount_cents", "payment_methods", "capabilities", "agreement_url", "balance_cents", "quote_revision" ] }, "Checkout": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "code": { "type": "string", "description": "MP 开头的意向单号" }, "enterprise_id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "status": { "type": "string", "enum": [ "pending", "cancelled", "expired", "paid" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteItem" } }, "amount_cents": { "type": "integer", "format": "int64", "description": "人民币整数分", "minimum": 0 }, "created_at": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00" }, "expires_at": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00" }, "payment_enabled": { "type": "boolean" }, "replayed": { "type": "boolean", "description": "同 key 重试时才出现" }, "payment_method": { "type": "string", "enum": [ "balance", "wechat" ], "nullable": true }, "paid_at": { "type": "string", "nullable": true, "description": "支付完成时间" }, "balance_cents": { "type": "integer", "format": "int64", "minimum": 0, "description": "当前企业可用余额，人民币整数分" } }, "required": [ "id", "code", "enterprise_id", "status", "items", "amount_cents", "created_at", "expires_at", "payment_enabled", "balance_cents" ] }, "CheckoutDetail": { "allOf": [ { "$ref": "#/components/schemas/Checkout" }, { "type": "object", "properties": { "address": { "type": "object", "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "region": { "type": "string" }, "contact": { "type": "string" }, "phone": { "type": "string", "description": "脱敏电话；无号码为空串，无法识别的历史格式返回 ****" } }, "required": [ "name", "address", "region", "contact", "phone" ] } }, "required": [ "address" ] } ] }, "EnterpriseOrderPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/Delivery" }, { "$ref": "#/components/schemas/Purchase" }, { "$ref": "#/components/schemas/Checkout" } ] } }, "total": { "type": "integer", "format": "int64" }, "page": { "type": "integer", "format": "int64" }, "page_size": { "type": "integer", "format": "int64" }, "has_more": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "deliveries", "purchases", "checkouts" ] } }, "required": [ "items", "total", "page", "page_size", "has_more", "kind" ] }, "Rewards": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "reason": { "type": "string" }, "reward_type": { "type": "string", "enum": [ "water" ] }, "total_cents": { "type": "integer", "nullable": true }, "withdrawable_cents": { "type": "integer", "nullable": true }, "demo": { "type": "boolean", "enum": [ false ] }, "invite_code": { "type": "string", "nullable": true }, "total_buckets": { "type": "integer" }, "successful_invites": { "type": "integer" }, "first_order_enterprises": { "type": "integer" }, "bound": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PromotionRecord" } ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PromotionRecord" } }, "total": { "type": "integer" }, "policy": { "$ref": "#/components/schemas/PromotionPolicy" } }, "required": [ "enabled", "reason", "reward_type", "total_cents", "withdrawable_cents", "demo", "invite_code", "total_buckets", "successful_invites", "first_order_enterprises", "bound", "items", "total", "policy" ] }, "TaskListItem": { "allOf": [ { "$ref": "#/components/schemas/Delivery" }, { "type": "object", "properties": { "enterprise_name": { "type": "string", "nullable": true }, "route_id": { "type": "integer", "format": "int64", "nullable": true }, "stop_order": { "type": "integer", "format": "int64" } }, "required": [ "enterprise_name", "route_id", "stop_order" ] } ] }, "TaskPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TaskListItem" } }, "total": { "type": "integer", "format": "int64" }, "page": { "type": "integer", "format": "int64" }, "page_size": { "type": "integer", "format": "int64" }, "has_more": { "type": "boolean" } }, "required": [ "items", "total", "page", "page_size", "has_more" ] }, "TaskRecord": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "kind": { "type": "string", "enum": [ "depart", "checkin", "exception", "draft", "complete" ] }, "data": { "oneOf": [ { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "coordinate_system": { "type": "string" }, "source": { "type": "string" }, "reason": { "type": "string" }, "accepted_qty": { "type": "integer", "format": "int64" }, "empty_returned": { "type": "integer", "format": "int64" }, "receiver": { "type": "string" }, "photo_ids": { "type": "array", "items": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 } } } }, { "type": "array", "items": {}, "maxItems": 0 } ], "description": "按 kind 区分。depart 为 []；checkin 为坐标；exception 为 reason；draft/complete 为履约内容" }, "created_at": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00" } }, "required": [ "id", "kind", "data", "created_at" ] }, "TaskDetail": { "allOf": [ { "$ref": "#/components/schemas/Delivery" }, { "type": "object", "properties": { "enterprise_name": { "type": "string", "nullable": true }, "contact": { "type": "string", "nullable": true }, "phone": { "type": "string", "description": "脱敏电话；无号码为空串，无法识别的历史格式返回 ****", "nullable": true }, "contact_phone": { "type": "string", "description": "仅本人 assigned/transit/returning 任务提供完整拨号号码，完成后 null", "nullable": true }, "longitude": { "anyOf": [ { "type": "number", "nullable": true }, { "type": "string", "description": "数据库 DECIMAL 原值" } ], "description": "历史接口坐标可为数值、数字字符串或 null；前端使用前转换 Number" }, "latitude": { "anyOf": [ { "type": "number", "nullable": true }, { "type": "string", "description": "数据库 DECIMAL 原值" } ], "description": "历史接口坐标可为数值、数字字符串或 null；前端使用前转换 Number" }, "route_id": { "type": "integer", "format": "int64", "nullable": true }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/TaskRecord" } }, "photos": { "type": "array", "items": { "$ref": "#/components/schemas/PhotoMeta" } }, "capabilities": { "type": "object", "properties": { "checkin": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "photos": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "fulfillment": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "device_binding": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" } }, "required": [ "checkin", "photos", "fulfillment", "device_binding" ] } }, "required": [ "enterprise_name", "contact", "phone", "contact_phone", "longitude", "latitude", "route_id", "records", "photos", "capabilities" ] } ] }, "Route": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "code": { "type": "string" }, "work_date": { "type": "string", "format": "date" }, "region": { "type": "string" }, "optimization": { "type": "object", "nullable": true, "description": "后台路线规划元数据，可能为 null；展示站点请使用 stops，不能据此承诺实时 ETA", "additionalProperties": true }, "stops": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "address": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "assigned", "transit", "completed", "cancelled", "returning", "returned" ] }, "quantity": { "type": "integer", "format": "int64" }, "longitude": { "anyOf": [ { "type": "number", "nullable": true }, { "type": "string", "description": "数据库 DECIMAL 原值" } ], "description": "历史接口坐标可为数值、数字字符串或 null；前端使用前转换 Number" }, "latitude": { "anyOf": [ { "type": "number", "nullable": true }, { "type": "string", "description": "数据库 DECIMAL 原值" } ], "description": "历史接口坐标可为数值、数字字符串或 null；前端使用前转换 Number" }, "origin_address": { "type": "string" }, "origin_longitude": { "anyOf": [ { "type": "number", "nullable": true }, { "type": "string", "description": "数据库 DECIMAL 原值" } ], "description": "历史接口坐标可为数值、数字字符串或 null；前端使用前转换 Number" }, "origin_latitude": { "anyOf": [ { "type": "number", "nullable": true }, { "type": "string", "description": "数据库 DECIMAL 原值" } ], "description": "历史接口坐标可为数值、数字字符串或 null；前端使用前转换 Number" }, "stop_order": { "type": "integer", "format": "int64" } }, "required": [ "id", "address", "status", "quantity", "longitude", "latitude", "origin_address", "origin_longitude", "origin_latitude", "stop_order" ] } } }, "required": [ "id", "code", "work_date", "region", "optimization", "stops" ] }, "DriverDashboard": { "type": "object", "properties": { "driver": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "name": { "type": "string" }, "vehicle": { "type": "string" } }, "required": [ "id", "name", "vehicle" ] }, "shift": { "type": "string", "description": "今日班次；未设置为 null", "nullable": true }, "summary": { "type": "object", "properties": { "pending": { "type": "integer", "format": "int64" }, "transit": { "type": "integer", "format": "int64" }, "completed_today": { "type": "integer", "format": "int64" } }, "required": [ "pending", "transit", "completed_today" ] }, "tasks": { "$ref": "#/components/schemas/TaskPage" }, "routes": { "type": "array", "items": { "$ref": "#/components/schemas/Route" } }, "capabilities": { "type": "object", "properties": { "live_gps": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "self_accept_unassigned": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" } }, "required": [ "live_gps", "self_accept_unassigned" ] } }, "required": [ "driver", "shift", "summary", "tasks", "routes", "capabilities" ] }, "DeviceCheck": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "sn": { "type": "string" }, "last_seen": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00", "nullable": true }, "online": { "type": "boolean", "description": "按最近15分钟心跳与故障标记判断" }, "network_test_passed": { "type": "boolean", "nullable": true, "description": "当前为 null，尚无可用数据" }, "binding_enabled": { "type": "boolean" } }, "required": [ "id", "sn", "last_seen", "online", "network_test_passed", "binding_enabled" ] }, "AgentDashboard": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "name": { "type": "string" }, "region": { "type": "string" } }, "required": [ "id", "name", "region" ] }, "summary": { "type": "object", "properties": { "month_amount_cents": { "type": "integer", "format": "int64", "description": "人民币整数分", "minimum": 0 }, "previous_month_amount_cents": { "type": "integer", "format": "int64", "description": "人民币整数分", "minimum": 0 }, "growth_percent": { "type": "number", "description": "上月为0时 null", "nullable": true }, "customer_count": { "type": "integer", "format": "int64" }, "new_customers": { "type": "integer", "format": "int64" }, "team_count": { "type": "integer", "format": "int64" }, "estimated_commission_cents": { "type": "integer", "nullable": true, "description": "当前代理自己的待结算佣金，单位分；旧订单不补记" }, "withdrawable_cents": { "type": "integer", "nullable": true, "description": "提现尚未开放，当前为0" }, "pending_commission_cents": { "type": "integer", "nullable": true, "description": "当前代理自己的待结算佣金，单位分" } }, "required": [ "month_amount_cents", "previous_month_amount_cents", "growth_percent", "customer_count", "new_customers", "team_count", "estimated_commission_cents", "withdrawable_cents", "pending_commission_cents" ] }, "trend": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "format": "date" }, "amount_cents": { "type": "integer", "format": "int64", "description": "人民币整数分", "minimum": 0 } }, "required": [ "day", "amount_cents" ] } }, "attribution": { "type": "string", "enum": [ "current_enterprise_agent" ] }, "capabilities": { "type": "object", "properties": { "commission": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "withdrawal": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" } }, "required": [ "commission", "withdrawal" ] } }, "required": [ "agent", "summary", "trend", "attribution", "capabilities" ] }, "Customer": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "name": { "type": "string" }, "contact": { "type": "string" }, "phone": { "type": "string", "description": "脱敏电话；无号码为空串，无法识别的历史格式返回 ****" }, "region": { "type": "string" }, "created_at": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00" }, "amount_cents": { "type": "integer", "format": "int64", "description": "人民币整数分", "minimum": 0 }, "last_purchase_at": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00", "nullable": true }, "has_purchased": { "type": "boolean" }, "device_count": { "type": "integer", "format": "int64" } }, "required": [ "id", "name", "contact", "phone", "region", "created_at", "amount_cents", "last_purchase_at", "has_purchased", "device_count" ] }, "CustomerPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "total": { "type": "integer", "format": "int64" }, "page": { "type": "integer", "format": "int64" }, "page_size": { "type": "integer", "format": "int64" }, "has_more": { "type": "boolean" }, "summary": { "type": "object", "properties": { "all": { "type": "integer", "format": "int64" }, "new": { "type": "integer", "format": "int64", "description": "本月新增" }, "unpaid": { "type": "integer", "format": "int64", "description": "无已发生收款" } }, "required": [ "all", "new", "unpaid" ] } }, "required": [ "items", "total", "page", "page_size", "has_more", "summary" ] }, "AgentOrderPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "enterprise_id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "package_name": { "type": "string" }, "buckets": { "type": "integer", "format": "int64" }, "amount_cents": { "type": "integer", "format": "int64", "description": "人民币整数分", "minimum": 0 }, "created_at": { "type": "string", "description": "Asia/Shanghai 时间，格式 YYYY-MM-DD HH:mm:ss", "example": "2026-09-18 10:30:00" } }, "required": [ "id", "enterprise_id", "package_name", "buckets", "amount_cents", "created_at" ] } }, "total": { "type": "integer", "format": "int64" }, "page": { "type": "integer", "format": "int64" }, "page_size": { "type": "integer", "format": "int64" }, "has_more": { "type": "boolean" } }, "required": [ "items", "total", "page", "page_size", "has_more" ] }, "Commissions": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "reason": { "type": "string" }, "withdrawable_cents": { "type": "integer", "nullable": true, "description": "正式佣金账本当前为0，提现尚未开放；演示模式可为null" }, "pending_cents": { "type": "integer", "nullable": true, "description": "当前代理自己的待结算佣金，单位分；演示模式可为null" }, "total_cents": { "type": "integer", "nullable": true, "description": "当前代理自己的累计计提金额，单位分；演示模式可为null" }, "withdrawn_cents": { "type": "integer", "nullable": true, "description": "正式佣金账本当前为0，提现尚未开放；演示模式可为null" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "customer_name": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "settled", "pending", "withdrawn", "adjustment" ] }, "status_text": { "type": "string" }, "amount_cents": { "type": "integer" }, "created_at": { "type": "string" } }, "required": [ "id", "customer_name", "title", "status", "status_text", "amount_cents", "created_at" ] } }, "demo": { "type": "boolean", "description": "本地测试展示数据，不可兑现" }, "total": { "type": "integer" }, "page": { "type": "integer" }, "page_size": { "type": "integer" }, "has_more": { "type": "boolean" } }, "required": [ "enabled", "reason", "withdrawable_cents", "pending_cents", "total_cents", "withdrawn_cents", "items", "total", "page", "page_size", "has_more" ] }, "Config": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "CNY" ] }, "money_unit": { "type": "string", "enum": [ "cent" ] }, "timezone": { "type": "string", "enum": [ "Asia/Shanghai" ] }, "support_phone": { "type": "string", "nullable": true }, "privacy_url": { "type": "string", "nullable": true }, "purchase_agreement_url": { "type": "string", "nullable": true }, "capabilities": { "type": "object", "properties": { "wechat_login": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "sms_login": { "type": "boolean", "description": "短信登录总开关；关闭时不下发验证码，也不接受验证码登录" }, "enterprise": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "driver": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "agent": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "payment": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "balance_payment": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "commissions": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "withdrawal": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "rewards": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "individual_package_cards": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "multiple_sites_per_enterprise": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "device_binding": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "test_phone_login": { "type": "boolean", "description": "仅本机测试手机号入口是否启用，非正式短信能力" } }, "required": [ "wechat_login", "enterprise", "driver", "agent", "payment", "balance_payment", "commissions", "withdrawal", "rewards", "individual_package_cards", "multiple_sites_per_enterprise", "device_binding", "test_phone_login" ] }, "setup_messages": { "type": "object", "description": "运营配置指引。能力未开启时给出在 server/.env 写入与重启的步骤；不会泄露密钥或具体配置值", "additionalProperties": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "configure", "optional" ] }, "summary": { "type": "string" }, "steps": { "type": "array", "items": { "type": "string" } } }, "required": [ "action", "summary", "steps" ], "additionalProperties": false } }, "admin_binding": { "type": "object", "description": "后台管理员绑定小程序账号流程所需端点与角色清单。仅在 capabilities 指定管理员 ID 上调用", "properties": { "route_users": { "type": "string" }, "route_grants": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "enterprise_admin", "enterprise_member", "driver", "agent" ] } }, "note": { "type": "string" } }, "required": [ "route_users", "route_grants", "roles", "note" ], "additionalProperties": false } }, "required": [ "currency", "money_unit", "timezone", "support_phone", "privacy_url", "purchase_agreement_url", "capabilities", "setup_messages", "admin_binding" ] }, "Health": { "type": "object", "properties": { "service": { "type": "string", "enum": [ "water-mini-api" ] }, "version": { "type": "string", "enum": [ "v1" ] }, "status": { "type": "string", "enum": [ "ok" ] }, "capabilities": { "type": "object", "properties": { "login": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "business": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "wechat_payment": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "balance_payment": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "commissions": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" }, "withdrawals": { "type": "boolean", "description": "以服务器返回值决定是否开放入口" } }, "required": [ "login", "business", "wechat_payment", "balance_payment", "commissions", "withdrawals" ] } }, "required": [ "service", "version", "status", "capabilities" ] }, "CommandRequest": { "type": "object", "properties": { "request_key": { "type": "string", "description": "同一次提交及网络重试使用同一 key 和原始请求内容；修改内容必须生成新 key", "minLength": 8, "maxLength": 80, "pattern": "^[A-Za-z0-9_-]{8,80}$", "example": "mini-20260918-0001" } }, "required": [ "request_key" ], "additionalProperties": false }, "LoginRequest": { "type": "object", "properties": { "code": { "type": "string", "description": "wx.login 返回的一次性 code", "minLength": 1, "maxLength": 512 } }, "required": [ "code" ], "additionalProperties": false }, "AddressRequest": { "type": "object", "properties": { "request_key": { "type": "string", "description": "同一次提交及网络重试使用同一 key 和原始请求内容；修改内容必须生成新 key", "minLength": 8, "maxLength": 80, "pattern": "^[A-Za-z0-9_-]{8,80}$", "example": "mini-20260918-0001" }, "revision": { "type": "string", "description": "GET address 返回的 revision 原样提交", "minLength": 1, "maxLength": 64 }, "address": { "type": "string", "minLength": 1, "maxLength": 255 }, "contact": { "type": "string", "minLength": 1, "maxLength": 60 }, "phone": { "type": "string", "description": "7–15位数字；允许前置+、空格、短横线、成对括号。保存时规范化；拒绝掩码和纯符号。格式校验不代表号码已验证", "minLength": 7, "maxLength": 30, "example": "+86 138 1234 5678" } }, "required": [ "request_key", "revision", "address", "contact", "phone" ], "additionalProperties": false }, "BookingRequest": { "type": "object", "properties": { "request_key": { "type": "string", "description": "同一次提交及网络重试使用同一 key 和原始请求内容；修改内容必须生成新 key", "minLength": 8, "maxLength": 80, "pattern": "^[A-Za-z0-9_-]{8,80}$", "example": "mini-20260918-0001" }, "sku_id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "quantity": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 10000 }, "address_id": { "type": "integer", "minimum": 0, "description": "配送地址 ID；省略或 0 使用默认地址" } }, "required": [ "request_key", "sku_id", "quantity" ], "additionalProperties": false }, "QuoteRequest": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "package_id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "quantity": { "type": "integer", "format": "int64", "description": "套餐份数", "minimum": 1, "maximum": 100 } }, "required": [ "package_id", "quantity" ], "additionalProperties": false }, "minItems": 1, "maxItems": 20, "description": "同一套餐不能重复，不能提交客户端单价" } }, "required": [ "items" ], "additionalProperties": false }, "Invoice": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "tax_number": { "type": "string", "minLength": 1, "maxLength": 30 }, "email": { "type": "string", "format": "email", "maxLength": 120 } }, "required": [ "title", "tax_number", "email" ], "additionalProperties": false }, "CheckoutRequest": { "type": "object", "properties": { "request_key": { "type": "string", "description": "同一次提交及网络重试使用同一 key 和原始请求内容；修改内容必须生成新 key", "minLength": 8, "maxLength": 80, "pattern": "^[A-Za-z0-9_-]{8,80}$", "example": "mini-20260918-0001" }, "items": { "type": "array", "items": { "type": "object", "properties": { "package_id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "quantity": { "type": "integer", "format": "int64", "description": "套餐份数", "minimum": 1, "maximum": 100 } }, "required": [ "package_id", "quantity" ], "additionalProperties": false }, "minItems": 1, "maxItems": 20, "description": "同一套餐不能重复，不能提交客户端单价" }, "expected_amount_cents": { "type": "integer", "format": "int64", "description": "人民币整数分", "minimum": 0 }, "agreement_accepted": { "type": "boolean", "enum": [ true ] }, "invoice": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "tax_number": { "type": "string", "minLength": 1, "maxLength": 30 }, "email": { "type": "string", "format": "email", "maxLength": 120 } }, "required": [ "title", "tax_number", "email" ], "additionalProperties": false, "nullable": true }, "quote_revision": { "type": "string", "minLength": 64, "maxLength": 64, "description": "服务器对套餐价格、名称、规格和桶数生成的报价版本；下单原样提交，变更返回40904；兼容旧客户端允许省略，新客户端应提交" } }, "required": [ "request_key", "items", "expected_amount_cents", "agreement_accepted" ], "additionalProperties": false }, "CheckinRequest": { "type": "object", "properties": { "request_key": { "type": "string", "description": "同一次提交及网络重试使用同一 key 和原始请求内容；修改内容必须生成新 key", "minLength": 8, "maxLength": 80, "pattern": "^[A-Za-z0-9_-]{8,80}$", "example": "mini-20260918-0001" }, "latitude": { "type": "number", "description": "GCJ-02 纬度，须为 JSON 数值", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "description": "GCJ-02 经度，须为 JSON 数值", "minimum": -180, "maximum": 180 } }, "required": [ "request_key", "latitude", "longitude" ], "additionalProperties": false }, "PhotoRequest": { "type": "object", "properties": { "request_key": { "type": "string", "description": "同一次提交及网络重试使用同一 key 和原始请求内容；修改内容必须生成新 key", "minLength": 8, "maxLength": 80, "pattern": "^[A-Za-z0-9_-]{8,80}$", "example": "mini-20260918-0001" }, "image_base64": { "type": "string", "description": "纯 base64，无 data: 前缀；JPEG/PNG ≤2MiB，最长边4096、总像素≤800万", "maxLength": 2800000 }, "latitude": { "type": "number", "description": "GCJ-02 纬度，须为 JSON 数值", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "description": "GCJ-02 经度，须为 JSON 数值", "minimum": -180, "maximum": 180 } }, "required": [ "request_key", "image_base64", "latitude", "longitude" ], "additionalProperties": false }, "ExceptionRequest": { "type": "object", "properties": { "request_key": { "type": "string", "description": "同一次提交及网络重试使用同一 key 和原始请求内容；修改内容必须生成新 key", "minLength": 8, "maxLength": 80, "pattern": "^[A-Za-z0-9_-]{8,80}$", "example": "mini-20260918-0001" }, "reason": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "request_key", "reason" ], "additionalProperties": false }, "DraftRequest": { "type": "object", "properties": { "request_key": { "type": "string", "description": "同一次提交及网络重试使用同一 key 和原始请求内容；修改内容必须生成新 key", "minLength": 8, "maxLength": 80, "pattern": "^[A-Za-z0-9_-]{8,80}$", "example": "mini-20260918-0001" }, "accepted_qty": { "type": "integer", "format": "int64", "description": "0至任务计划桶数", "minimum": 0 }, "empty_returned": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 10000000, "default": 0 }, "receiver": { "type": "string", "minLength": 1, "maxLength": 60 }, "reason": { "type": "string", "description": "部分/全部拒收时必填", "maxLength": 255 }, "photo_ids": { "type": "array", "items": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "maxItems": 4, "uniqueItems": true }, "confirmed": { "type": "boolean" } }, "required": [ "request_key", "accepted_qty", "receiver" ], "additionalProperties": false }, "CompleteRequest": { "type": "object", "properties": { "request_key": { "type": "string", "description": "同一次提交及网络重试使用同一 key 和原始请求内容；修改内容必须生成新 key", "minLength": 8, "maxLength": 80, "pattern": "^[A-Za-z0-9_-]{8,80}$", "example": "mini-20260918-0001" }, "accepted_qty": { "type": "integer", "format": "int64", "description": "0至任务计划桶数", "minimum": 0 }, "empty_returned": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 10000000, "default": 0 }, "receiver": { "type": "string", "minLength": 1, "maxLength": 60 }, "reason": { "type": "string", "description": "部分/全部拒收时必填", "maxLength": 255 }, "photo_ids": { "type": "array", "items": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "maxItems": 4, "uniqueItems": true, "minItems": 1 }, "confirmed": { "type": "boolean", "enum": [ true ] } }, "required": [ "request_key", "accepted_qty", "receiver", "photo_ids", "confirmed" ], "additionalProperties": false }, "CommandResult": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "status": { "type": "string", "enum": [ "pending", "assigned", "transit", "completed", "cancelled", "returning", "returned" ] }, "replayed": { "type": "boolean", "description": "可能仅有 id/replayed，无 status；需要当前状态时重新取详情" } }, "required": [ "id" ] }, "AddressResult": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "revision": { "type": "string" }, "replayed": { "type": "boolean" } }, "required": [ "id", "revision" ] }, "CheckinResult": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "checked_in": { "type": "boolean" }, "location_verified": { "type": "boolean" }, "replayed": { "type": "boolean" } }, "required": [ "id", "checked_in", "location_verified" ] }, "DraftResult": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "saved": { "type": "boolean" }, "replayed": { "type": "boolean" } }, "required": [ "id", "saved" ] }, "ExceptionResult": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "reported": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "assigned", "transit", "completed", "cancelled", "returning", "returned" ] }, "replayed": { "type": "boolean" } }, "required": [ "id", "reported", "status" ] }, "PhotoResult": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "delivery_id": { "type": "integer", "format": "int64", "description": "正整数资源 ID", "minimum": 1, "maximum": 2147483647 }, "location_verified": { "type": "boolean" }, "watermark": { "type": "string", "enum": [ "server_time_and_client_location" ] }, "replayed": { "type": "boolean" } }, "required": [ "id", "delivery_id", "location_verified", "watermark" ] }, "PayRequest": { "type": "object", "properties": { "request_key": { "type": "string", "description": "同一次提交及网络重试使用同一 key 和原始请求内容；修改内容必须生成新 key", "minLength": 8, "maxLength": 80, "pattern": "^[A-Za-z0-9_-]{8,80}$", "example": "mini-20260918-0001" }, "payment_method": { "type": "string", "enum": [ "balance", "wechat" ], "description": "balance 已开通；wechat 预留" } }, "required": [ "request_key", "payment_method" ], "additionalProperties": false }, "DeliveryAddress": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "配送地址 ID；0 表示尚未建立独立地址档案的企业主地址", "minimum": 0, "maximum": 2147483647 }, "name": { "type": "string" }, "contact": { "type": "string" }, "phone": { "type": "string", "description": "脱敏电话；无号码为空串，无法识别的历史格式返回 ****" }, "address": { "type": "string" }, "region": { "type": "string" }, "longitude": { "type": "number", "nullable": true }, "latitude": { "type": "number", "nullable": true }, "employee_count": { "type": "integer", "format": "int64", "nullable": true }, "revision": { "type": "string", "description": "编辑地址时原样提交的版本", "minLength": 64, "maxLength": 64 }, "enterprise_id": { "type": "integer", "minimum": 1 }, "label": { "type": "string" }, "is_default": { "type": "boolean" }, "status": { "type": "integer" } }, "required": [ "id", "name", "contact", "phone", "address", "region", "longitude", "latitude", "employee_count", "revision", "enterprise_id", "label", "is_default", "status" ] }, "DeliveryAddressUpdate": { "type": "object", "properties": { "request_key": { "type": "string", "description": "同一次提交及网络重试使用同一 key 和原始请求内容；修改内容必须生成新 key", "minLength": 8, "maxLength": 80, "pattern": "^[A-Za-z0-9_-]{8,80}$", "example": "mini-20260918-0001" }, "revision": { "type": "string", "description": "修改时原样提交配送地址详情的 revision", "minLength": 1, "maxLength": 64 }, "address": { "type": "string", "minLength": 1, "maxLength": 255 }, "contact": { "type": "string", "minLength": 1, "maxLength": 60 }, "phone": { "type": "string", "description": "7–15位数字；允许前置+、空格、短横线、成对括号。保存时规范化；拒绝掩码和纯符号。格式校验不代表号码已验证", "minLength": 7, "maxLength": 30, "example": "+86 138 1234 5678" }, "label": { "type": "string", "maxLength": 80 }, "region": { "type": "string", "maxLength": 80 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "is_default": { "type": "boolean" } }, "required": [ "request_key", "revision", "address", "contact", "phone" ], "additionalProperties": false }, "DeliveryAddressCreate": { "type": "object", "properties": { "request_key": { "type": "string", "description": "同一次提交及网络重试使用同一 key 和原始请求内容；修改内容必须生成新 key", "minLength": 8, "maxLength": 80, "pattern": "^[A-Za-z0-9_-]{8,80}$", "example": "mini-20260918-0001" }, "address": { "type": "string", "minLength": 1, "maxLength": 255 }, "contact": { "type": "string", "minLength": 1, "maxLength": 60 }, "phone": { "type": "string", "description": "7–15位数字；允许前置+、空格、短横线、成对括号。保存时规范化；拒绝掩码和纯符号。格式校验不代表号码已验证", "minLength": 7, "maxLength": 30, "example": "+86 138 1234 5678" }, "label": { "type": "string", "maxLength": 80 }, "region": { "type": "string", "maxLength": 80 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "is_default": { "type": "boolean" } }, "required": [ "request_key", "address", "contact", "phone" ], "additionalProperties": false }, "DeliveryAddressResult": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "revision": { "type": "string" }, "is_default": { "type": "boolean" }, "replayed": { "type": "boolean" } }, "required": [ "id", "is_default" ] }, "PromotionPolicy": { "type": "object", "properties": { "initialized": { "type": "boolean" }, "enabled": { "type": "boolean" }, "sku_id": { "type": "integer", "nullable": true }, "sku_name": { "type": "string", "nullable": true }, "quantity": { "type": "integer" }, "min_amount_cents": { "type": "integer" }, "revision": { "type": "integer" }, "rules": { "type": "string" } }, "required": [ "initialized", "enabled", "sku_id", "sku_name", "quantity", "min_amount_cents", "revision", "rules" ] }, "PromotionRecord": { "type": "object", "properties": { "id": { "type": "integer" }, "inviter_name": { "type": "string" }, "enterprise_name": { "type": "string" }, "sku_name": { "type": "string" }, "quantity": { "type": "integer" }, "status": { "type": "string", "enum": [ "bound", "pending", "issued", "rejected" ] }, "status_text": { "type": "string" }, "order_id": { "type": "integer", "nullable": true }, "reference": { "type": "string", "nullable": true }, "amount_cents": { "type": "integer", "nullable": true }, "created_at": { "type": "string" }, "qualified_at": { "type": "string", "nullable": true }, "reviewed_at": { "type": "string", "nullable": true }, "review_note": { "type": "string" }, "delivery_id": { "type": "integer", "nullable": true }, "revision": { "type": "integer" } }, "required": [ "id", "inviter_name", "enterprise_name", "sku_name", "quantity", "status", "status_text", "order_id", "reference", "amount_cents", "created_at", "qualified_at", "reviewed_at", "review_note", "delivery_id", "revision" ] }, "PromotionCodeRequest": { "type": "object", "properties": { "request_key": { "type": "string", "minLength": 8, "maxLength": 80, "pattern": "^[A-Za-z0-9_-]{8,80}$" } }, "required": [ "request_key" ] }, "PromotionBindRequest": { "type": "object", "properties": { "request_key": { "type": "string", "minLength": 8, "maxLength": 80, "pattern": "^[A-Za-z0-9_-]{8,80}$" }, "invite_code": { "type": "string", "pattern": "^[A-Fa-f0-9]{20}$" } }, "required": [ "request_key", "invite_code" ] }, "PromotionCodeResult": { "type": "object", "properties": { "invite_code": { "type": "string", "pattern": "^[A-F0-9]{20}$" }, "replayed": { "type": "boolean" } }, "required": [ "invite_code" ] } }, "responses": { "Error": { "description": "失败。根据HTTP状态与code分支；40101登录过期，40301业务权限不足，40901幂等/版本冲突，40902状态冲突，40904价格变化，42201参数错误，50301登录未配置，50302外部服务暂不可用，50303能力未开通；data可能为null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 42201, "message": "参数校验失败", "data": { "fields": { "phone": "请填写完整有效的联系电话" } }, "request_id": "0123456789abcdef0123456789abcdef" } } } } } } }