{ "openapi": "3.0.0", "info": { "title": "小袋鼠绿通服务 · 陪诊师端 API", "description": "陪诊师端小程序接口文档（与 `陪诊师端/api/*.js` 一一对应）。\n\n当前工程处于 Mock 模式（`api/request.js` 中 `USE_MOCK = true`），所有接口数据由前端 `mock/` 层返回，页面无感知。\n\n## 统一返回格式\n\n所有接口返回统一结构：\n\n```json\n{ \"code\": 200, \"message\": \"ok\", \"data\": { ... } }\n```\n\n- `code`：200 表示成功，非 200 为业务失败（由 request 层 Toast 提示并 reject）。\n- `message`：提示信息。\n- `data`：业务数据，即本文档中各接口的 `Response` 结构。\n\n## 通用枚举\n\n- 认证状态 `cert`：`none`（未认证）/ `reviewing`（审核中）/ `rejected`（未通过）/ `approved`（已认证）\n- 订单状态 `status`：`assigned`（已分配，待开始服务）/ `serving`（服务中）/ `done`（已完成）\n- 接单开关 `active`：`true` 接单中 / `false` 停止接单", "version": "1.0.0", "contact": { "name": "小袋鼠绿通服务" } }, "servers": [ { "url": "https://api.example.com", "description": "Mock 模式占位地址（USE_MOCK = true 时实际数据由前端 mock 层返回）" } ], "tags": [ { "name": "首页", "description": "首页运营数据" }, { "name": "认证与接单", "description": "陪诊师认证、审核、接单开关、登录态" }, { "name": "订单", "description": "接单列表、历史订单、订单详情与服务流程" }, { "name": "个人中心", "description": "个人信息与数据统计" }, { "name": "公共", "description": "省市定位等公共数据" } ], "paths": { "/escort/home": { "get": { "tags": [ "首页" ], "summary": "获取首页数据", "description": "返回定位城市、运营轮播图、服务入口 4 宫格、宣传卡片 2x2。", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/HomeData" } } } } } } } } }, "/escort/auth/status": { "get": { "tags": [ "认证与接单" ], "summary": "获取认证与接单状态", "description": "返回认证状态、接单开关、被拒原因与认证资料。页面进入接单工作台时调用。", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/AuthStatus" } } } } } } } } }, "/escort/auth/submit": { "post": { "tags": [ "认证与接单" ], "summary": "提交认证资料", "description": "提交真实姓名、身份证号、省市、性别、手机号与图形验证码，提交后认证状态变为 `reviewing`。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "idNo", "provinceId", "cityId", "phone", "code", "gender" ], "properties": { "name": { "type": "string", "description": "真实姓名", "example": "李陪诊" }, "idNo": { "type": "string", "description": "身份证号码", "example": "350104199001012034" }, "provinceId": { "type": "integer", "description": "省份 id（省市弹层选中项）", "example": 13 }, "cityId": { "type": "integer", "description": "城市 id（省市弹层选中项）", "example": 3501 }, "phone": { "type": "string", "description": "手机号码", "example": "13800008866" }, "code": { "type": "string", "description": "图形验证码（4 位随机数字，页面本地 canvas 生成并校验）", "example": "4826" }, "gender": { "type": "string", "description": "性别（必选）", "enum": [ "男", "女" ], "example": "女" } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "cert": { "type": "string", "enum": [ "none", "reviewing", "rejected", "approved" ], "example": "reviewing" } } } } } } } } } } }, "/escort/auth/review": { "post": { "tags": [ "认证与接单" ], "summary": "模拟平台审核结果（演示辅助）", "description": "仅用于演示：传入是否通过，将认证状态置为 `approved` 或 `rejected`。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pass" ], "properties": { "pass": { "type": "boolean", "description": "是否审核通过", "example": true } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "cert": { "type": "string", "enum": [ "none", "reviewing", "rejected", "approved" ], "example": "approved" }, "active": { "type": "boolean", "description": "接单开关（审核后重置为 false）", "example": false } } } } } } } } } } }, "/escort/auth/city": { "post": { "tags": [ "认证与接单" ], "summary": "更新常驻城市", "description": "认证资料中仅「常驻城市」支持修改。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "city" ], "properties": { "city": { "type": "string", "description": "新的常驻城市（省 市）", "example": "福建省 厦门市" } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "city": { "type": "string", "description": "更新后的常驻城市", "example": "福建省 厦门市" } } } } } } } } } } }, "/escort/logout": { "post": { "tags": [ "认证与接单" ], "summary": "退出登录", "description": "清除登录态，认证状态重置为 `none`、接单开关关闭。", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "cert": { "type": "string", "enum": [ "none", "reviewing", "rejected", "approved" ], "example": "none" }, "active": { "type": "boolean", "example": false } } } } } } } } } } }, "/escort/receive": { "post": { "tags": [ "认证与接单" ], "summary": "切换接单开关", "description": "开启/停止接单。开启后系统匹配附近订单，停止后不再接收新派单（不影响已接订单）。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "active" ], "properties": { "active": { "type": "boolean", "description": "目标接单状态", "example": true } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "active": { "type": "boolean", "example": true } } } } } } } } } } }, "/escort/orders": { "get": { "tags": [ "订单" ], "summary": "获取已派单订单", "description": "返回当前已分配的全部订单列表（接单工作台使用）。", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } } } } } } } } } } }, "/escort/orders/history": { "get": { "tags": [ "订单" ], "summary": "获取历史订单", "description": "返回已完成的历史订单列表（按时间倒序）。", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "history": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryOrder" } } } } } } } } } } } }, "/escort/orders/simulate": { "post": { "tags": [ "订单" ], "summary": "模拟收到新订单（演示辅助）", "description": "仅用于演示：向已派单列表追加一条新订单。", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Order" } } } } } } } } }, "/escort/orders/{id}": { "get": { "tags": [ "订单" ], "summary": "获取订单详情", "description": "按订单号获取订单完整信息（含服务进度时间线、追加服务、就诊用户虚拟号）。订单不存在时 data 为 null。", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "订单号", "schema": { "type": "string", "example": "PT20260818D11" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "ok" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/Order" }, { "type": "null" } ] } } } } } } } } }, "/escort/orders/{id}/start": { "post": { "tags": [ "订单" ], "summary": "开始服务", "description": "开始服务后订单状态变为 `serving`，按 `durationHours` 启动服务计时（endTime = 当前时间 + 时长）。", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "订单号", "schema": { "type": "string", "example": "PT20260818D11" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Order" } } } } } } } } }, "/escort/orders/{id}/progress": { "post": { "tags": [ "订单" ], "summary": "上传服务进度", "description": "追加一条服务进度记录（可含现场照片标记与定位），返回更新后的订单。", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "订单号", "schema": { "type": "string", "example": "PT20260818D11" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "进度说明", "example": "已到达医院，正在陪同取号" }, "photo": { "type": "boolean", "description": "是否附带现场照片", "example": true }, "loc": { "type": "string", "description": "定位信息", "example": "福建省福州市鼓楼区" } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Order" } } } } } } } } }, "/escort/orders/{id}/addon": { "post": { "tags": [ "订单" ], "summary": "模拟用户追加时长（演示辅助）", "description": "仅用于演示：追加「延长服务1小时」服务项（提成 +¥40），并顺延服务计时。", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "订单号", "schema": { "type": "string", "example": "PT20260818D11" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Order" } } } } } } } } }, "/escort/orders/{id}/end-timer": { "post": { "tags": [ "订单" ], "summary": "快进倒计时结束（演示辅助）", "description": "仅用于演示：将服务计时置为结束，订单状态变为 `done`（可执行结束订单）。", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "订单号", "schema": { "type": "string", "example": "PT20260818D11" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Order" } } } } } } } } }, "/escort/orders/{id}/complete": { "post": { "tags": [ "订单" ], "summary": "结束订单", "description": "订单服务完成：从已派单列表移除并进入历史订单。返回 success 与订单信息。", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "订单号", "schema": { "type": "string", "example": "PT20260818D11" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "order": { "$ref": "#/components/schemas/Order" } } } } } } } } } } }, "/escort/profile": { "get": { "tags": [ "个人中心" ], "summary": "获取个人信息", "description": "返回昵称、手机号（脱敏）、身份证号（脱敏）。", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Profile" } } } } } } } } }, "/escort/stats": { "get": { "tags": [ "个人中心" ], "summary": "获取数据统计", "description": "返回今日接单数、本月接单数。", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "ok" }, "data": { "$ref": "#/components/schemas/Stats" } } } } } } } } }, "/region/provinces": { "get": { "tags": [ "公共" ], "summary": "获取省市数据", "description": "返回全国省市映射（省份 → 城市数组），用于常驻城市选择弹层。", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "provinces": { "type": "object", "description": "省份 → 城市数组", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "福建省": [ "福州市", "厦门市", "莆田市" ], "广东省": [ "广州市", "深圳市", "珠海市" ] } } } } } } } } } } } } }, "components": { "schemas": { "HomeData": { "type": "object", "description": "首页数据", "properties": { "city": { "type": "string", "description": "当前定位城市", "example": "北京市" }, "banners": { "type": "array", "description": "运营轮播图", "items": { "$ref": "#/components/schemas/Banner" } }, "services": { "type": "array", "description": "服务入口 4 宫格", "items": { "$ref": "#/components/schemas/ServiceEntry" } }, "promos": { "type": "array", "description": "宣传卡片", "items": { "$ref": "#/components/schemas/PromoCard" } } } }, "Banner": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "tag": { "type": "string", "example": "限时特惠" }, "title": { "type": "string", "example": "开通黄金会员" }, "sub": { "type": "string", "example": "全年享 9 折优惠" }, "emoji": { "type": "string", "example": "👑" }, "bg": { "type": "string", "description": "渐变色背景", "example": "linear-gradient(135deg,#F39C12,#E74C3C)" } } }, "ServiceEntry": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "培训考证" }, "emoji": { "type": "string", "example": "📚" }, "bg": { "type": "string", "description": "图标圆底颜色", "example": "rgba(62,180,137,0.1)" }, "toast": { "type": "string", "description": "点击提示文案", "example": "培训考证功能开发中" } } }, "PromoCard": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "emoji": { "type": "string", "example": "🛡️" }, "title": { "type": "string", "example": "平台保障" }, "desc": { "type": "string", "example": "实名认证陪诊师，服务全程平台监管，安全更放心。" } } }, "AuthStatus": { "type": "object", "description": "认证与接单状态", "properties": { "cert": { "type": "string", "enum": [ "none", "reviewing", "rejected", "approved" ], "description": "认证状态" }, "active": { "type": "boolean", "description": "是否接单中" }, "rejectReason": { "type": "string", "description": "认证被拒原因（cert=rejected 时有效）", "example": "您提交的身份证照片不清晰，请重新上传。" }, "certData": { "$ref": "#/components/schemas/CertData" } } }, "CertData": { "type": "object", "description": "认证资料", "properties": { "name": { "type": "string", "example": "李陪诊" }, "idNo": { "type": "string", "example": "350104199001012034" }, "phone": { "type": "string", "example": "13800008866" }, "city": { "type": "string", "description": "常驻城市（省 市）", "example": "福建省 福州市" }, "gender": { "type": "string", "description": "性别", "enum": [ "男", "女" ], "example": "女" } } }, "Order": { "type": "object", "description": "已派单订单（订单详情）", "required": [ "id", "service", "time", "address", "commission", "status" ], "properties": { "id": { "type": "string", "description": "订单号", "example": "PT20260818D11" }, "service": { "type": "string", "description": "服务名称", "example": "2小时陪诊" }, "time": { "type": "string", "description": "预约时间 yyyy-MM-dd HH:mm", "example": "2026-08-19 15:00" }, "address": { "type": "string", "description": "预约地点", "example": "福建省福州市晋安区 鼓山镇福马路18号 福州市中医院" }, "commission": { "type": "number", "description": "本单基础提成（元）", "example": 80 }, "durationHours": { "type": "number", "description": "服务时长（小时）", "example": 2 }, "status": { "type": "string", "enum": [ "assigned", "serving", "done" ], "description": "订单状态" }, "note": { "type": "string", "description": "订单备注" }, "user": { "type": "object", "description": "就诊用户（虚拟号）", "properties": { "name": { "type": "string", "example": "张先生" }, "virtualPhone": { "type": "string", "example": "138****8888" } } }, "progress": { "type": "array", "description": "服务进度时间线（倒序展示）", "items": { "$ref": "#/components/schemas/ProgressItem" } }, "startTime": { "type": [ "integer", "null" ], "description": "开始服务时间戳（ms），未开始为 null" }, "endTime": { "type": [ "integer", "null" ], "description": "服务结束时间戳（ms），未开始为 null" }, "timerEnded": { "type": "boolean", "description": "服务计时是否已结束" }, "addons": { "type": "array", "description": "追加服务项", "items": { "$ref": "#/components/schemas/Addon" } } } }, "HistoryOrder": { "type": "object", "description": "历史订单", "properties": { "id": { "type": "string", "example": "PT20260815X03" }, "service": { "type": "string", "example": "2小时陪诊" }, "time": { "type": "string", "example": "2026-08-15 10:00" }, "address": { "type": "string", "example": "福建省福州市仓山区 上三路32号 福州市第二医院" }, "commission": { "type": "number", "example": 80 }, "status": { "type": "string", "enum": [ "assigned", "serving", "done" ], "example": "done" }, "note": { "type": "string", "example": "已完成服务，用户评价良好。" } } }, "ProgressItem": { "type": "object", "description": "服务进度记录", "properties": { "time": { "type": "string", "description": "进度时间 yyyy-MM-dd HH:mm", "example": "2026-08-19 15:02" }, "text": { "type": "string", "description": "进度说明", "example": "已开始服务，服务计时启动" }, "photo": { "type": "boolean", "description": "是否含现场照片" }, "loc": { "type": "string", "description": "定位信息（photo=true 时有效）" } } }, "Addon": { "type": "object", "description": "追加服务项", "properties": { "name": { "type": "string", "example": "延长服务1小时" }, "commission": { "type": "number", "description": "追加提成（元）", "example": 40 } } }, "Profile": { "type": "object", "description": "个人信息（脱敏）", "properties": { "name": { "type": "string", "example": "李陪诊" }, "phone": { "type": "string", "example": "138****8866" }, "id": { "type": "string", "example": "3101**********2034" } } }, "Stats": { "type": "object", "description": "数据统计", "properties": { "today": { "type": "integer", "description": "今日接单数", "example": 3 }, "month": { "type": "integer", "description": "本月接单数", "example": 28 } } } } } }