water/server/docs/openapi/water-mini-v1.json

{
  "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/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": "以服务器返回值决定是否开放入口"
              },
              "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"
            }
          }
        }
      }
    }
  }
}