{"openapi": "3.0.3", "info": {"title": "Golden Eagle 金鹰维修订单 API", "version": "0.12.0", "description": "开发参考版本。独立订单与客户后台；出库指回填寄回快递运单。无需ERP、无库存。真实微信支付尚未实现。所有金额使用人民币分；时间采用UTC ISO 8601。"}, "servers": [{"url": "http://127.0.0.1:8765", "description": "本地开发，请勿作生产环境"}], "security": [{"BearerAuth": []}], "paths": {"/health": {"get": {"operationId": "health", "summary": "环境和支付可用状态", "description": "", "x-allowed-roles": ["customer", "admin", "agent"], "parameters": [], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "demo": {"type": "boolean"}, "payment_ready": {"type": "boolean", "enum": [false]}}, "required": []}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "security": []}}, "/v1/catalog": {"get": {"operationId": "getCatalog", "summary": "获取维修商品、维修地址、快递公司", "description": "", "x-allowed-roles": ["customer", "admin", "agent"], "parameters": [], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object"}, "request_id": {"type": "string", "description": ""}}, "required": ["data", "request_id"]}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "security": []}}, "/v1/auth/wechat": {"post": {"operationId": "loginWithWechat", "summary": "微信code换取客户会话", "description": "非演示环境调用微信code2Session；演示环境固定合成客户，不可用于真实客户。", "x-allowed-roles": ["public"], "parameters": [], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object", "properties": {"token": {"type": "string", "description": ""}, "expires_in": {"type": "integer"}, "demo": {"type": "boolean"}}, "required": []}, "request_id": {"type": "string", "description": ""}}, "required": ["data", "request_id"]}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "security": [], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"code": {"type": "string", "description": "wx.login返回的code"}}, "required": []}}}}}}, "/v1/me": {"get": {"operationId": "getCurrentIdentity", "summary": "查询当前客户资料或后台角色", "description": "", "x-allowed-roles": ["customer", "admin", "agent"], "parameters": [], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object"}, "request_id": {"type": "string", "description": ""}}, "required": ["data", "request_id"]}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "patch": {"operationId": "updateMyContact", "summary": "保存自己的联系方式", "description": "不修改历史订单的收件快照。", "x-allowed-roles": ["customer"], "parameters": [{"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{8,128}$"}}], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/Customer"}, "request_id": {"type": "string", "description": ""}}, "required": ["data", "request_id"]}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Contact"}}}}}}, "/v1/orders": {"get": {"operationId": "listOrders", "summary": "获取订单，客户仅自己的订单", "description": "AI待出库查询：payment_status=paid&fulfillment_status=unshipped；按创建时间降序分页。", "x-allowed-roles": ["customer", "admin", "agent"], "parameters": [{"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}}, {"name": "offset", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 0, "default": 0}}, {"name": "payment_status", "in": "query", "required": false, "schema": {"type": "string", "enum": ["pending", "paid"]}}, {"name": "fulfillment_status", "in": "query", "required": false, "schema": {"type": "string", "enum": ["unshipped", "shipped"]}}, {"name": "q", "in": "query", "required": false, "schema": {"type": "string", "maxLength": 120}}], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object", "properties": {"items": {"type": "array", "items": {"$ref": "#/components/schemas/Order"}}, "total": {"type": "integer"}, "limit": {"type": "integer"}, "offset": {"type": "integer"}}, "required": []}, "request_id": {"type": "string", "description": ""}}, "required": ["data", "request_id"]}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "post": {"operationId": "createRepairFeeOrder", "summary": "创建待付款维修费订单", "description": "新客户端提交amount_fen整数分，联系电话、姓名、寄回地址必填，设备型号和寄修单号选填。禁止同时提交amount_fen和quantity。", "x-allowed-roles": ["customer"], "parameters": [{"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{8,128}$"}}], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/Order"}, "request_id": {"type": "string", "description": ""}}, "required": ["data", "request_id"]}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateOrder"}}}}}}, "/v1/orders/{order_id}": {"get": {"operationId": "getOrder", "summary": "获取订单和状态时间线", "description": "", "x-allowed-roles": ["customer", "admin", "agent"], "parameters": [{"name": "order_id", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/Order"}, "request_id": {"type": "string", "description": ""}}, "required": ["data", "request_id"]}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "delete": {"operationId": "deleteOwnOrder", "summary": "删除自己的未付款订单", "description": "仅pending且unshipped可删除；软删除后不能继续付款/出库，列表与客户详情不再显示。若关联寄修记录，解除有效订单占用，之后可重新创建。", "x-allowed-roles": ["customer"], "parameters": [{"name": "order_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 8, "maxLength": 128}}], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object", "properties": {"id": {"type": "string"}, "deleted": {"type": "boolean"}, "deleted_at": {"type": "string", "format": "date-time"}}}, "request_id": {"type": "string", "description": ""}}, "required": ["data", "request_id"]}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/v1/orders/{order_id}/payment": {"post": {"operationId": "startWechatPayment", "summary": "发起真实微信支付（尚未实现）", "description": "当前固定返回503 PAYMENT_NOT_CONFIGURED，不能用于真实收款。需接入微信支付v3下单、签名、通知验签解密和主动查单后开放。", "x-allowed-roles": ["customer"], "parameters": [{"name": "order_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{8,128}$"}}], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object"}, "request_id": {"type": "string", "description": ""}}, "required": ["data", "request_id"]}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/v1/orders/{order_id}/ship": {"post": {"operationId": "shipOrder", "summary": "回填快递公司和运单号并出库", "description": "订单必须paid且unshipped。相同幂等键重试返回同一结果；不同键覆盖已发货运单返回409。不会在打单软件创建运单。 已通过repair_id关联的付款订单与寄修记录在任一入口保存寄回运单后，同事务双向同步状态和运单；关联订单未付款或两边运单冲突时拒绝并回滚。 有 pending、approved 或 processing 退款的订单禁止出库（REFUND_IN_PROGRESS），已全额退款也不能出库。寄修进度寄回入口同样受限。", "x-allowed-roles": ["admin", "agent"], "parameters": [{"name": "order_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{8,128}$"}}], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/Order"}, "request_id": {"type": "string", "description": ""}}, "required": ["data", "request_id"]}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Shipment"}}}}}}, "/v1/orders/{order_id}/demo-pay": {"post": {"operationId": "simulatePayment", "summary": "仅本地演示：模拟付款", "description": "仅GE_DEMO=1可用。不代表真实支付。agent不能调用。", "x-allowed-roles": ["admin"], "parameters": [{"name": "order_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{8,128}$"}}], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/Order"}, "request_id": {"type": "string", "description": ""}}, "required": ["data", "request_id"]}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/v1/customers": {"get": {"operationId": "listCustomers", "summary": "后台查询客户联系资料", "description": "", "x-allowed-roles": ["admin", "agent"], "parameters": [{"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}}, {"name": "offset", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 0, "default": 0}}], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object", "properties": {"items": {"type": "array", "items": {"$ref": "#/components/schemas/Customer"}}, "total": {"type": "integer"}, "limit": {"type": "integer"}, "offset": {"type": "integer"}}, "required": []}, "request_id": {"type": "string", "description": ""}}, "required": ["data", "request_id"]}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/v1/repairs": {"get": {"operationId": "listRepairs", "summary": "查询寄修资料，客户仅自己的资料", "description": "", "x-allowed-roles": ["customer", "admin", "agent"], "parameters": [{"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}}, {"name": "offset", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 0, "default": 0}}, {"name": "repair_status", "in": "query", "required": false, "schema": {"type": "string", "enum": ["in_transit", "received", "inspecting", "quoted", "repairing", "returned"]}}, {"name": "q", "in": "query", "required": false, "schema": {"type": "string", "maxLength": 120}}, {"name": "repair_stage", "in": "query", "schema": {"type": "string", "enum": ["pending", "quoted", "returned"]}, "description": "寄修处理阶段：待确认检测费、检测费已确认但未寄回、已寄回。不传表示全部；兼容历史状态，费用0元属于已确认。"}], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object", "properties": {"items": {"type": "array", "items": {"$ref": "#/components/schemas/Repair"}}, "total": {"type": "integer"}, "limit": {"type": "integer"}, "offset": {"type": "integer"}}, "required": []}, "request_id": {"type": "string", "description": ""}}, "required": ["data", "request_id"]}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "post": {"operationId": "submitRepair", "summary": "提交自助寄修表单", "description": "", "x-allowed-roles": ["customer"], "parameters": [{"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{8,128}$"}}], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object"}, "request_id": {"type": "string", "description": ""}}, "required": ["data", "request_id"]}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RepairCreate"}}}}}}, "/v1/repairs/{repair_id}/evidence": {"get": {"operationId": "getRepairEvidence", "summary": "后台读取购买凭证", "description": "返回evidence_base64和evidence_type，仅供授权后台查看。", "x-allowed-roles": ["admin", "agent"], "parameters": [{"name": "repair_id", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object"}, "request_id": {"type": "string", "description": ""}}, "required": ["data", "request_id"]}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/v1/events": {"get": {"operationId": "pollOrderEvents", "summary": "按游标读取订单事件", "description": "每次最多100条。处理完再保存next_cursor。用于轮询，尚无推送Webhook。", "x-allowed-roles": ["admin", "agent"], "parameters": [{"name": "after", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 0, "default": 0}}], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object", "properties": {"items": {"type": "array", "items": {"$ref": "#/components/schemas/Event"}}, "next_cursor": {"type": "integer"}}, "required": []}, "request_id": {"type": "string", "description": ""}}, "required": ["data", "request_id"]}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/v1/repairs/{repair_id}": {"get": {"operationId": "getRepairProgress", "summary": "客户查询自己的寄修详情、状态、费用、寄回运单和历史进度", "x-allowed-roles": ["customer", "admin", "agent"], "parameters": [{"name": "repair_id", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/RepairDetail"}, "request_id": {"type": "string"}}}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "delete": {"operationId": "deleteOwnRepair", "summary": "删除填写错误的寄修记录", "x-allowed-roles": ["customer", "admin"], "parameters": [{"name": "repair_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 8, "maxLength": 128}}], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object", "properties": {"id": {"type": "string"}, "deleted": {"type": "boolean"}, "deleted_at": {"type": "string", "format": "date-time"}}}, "request_id": {"type": "string"}}}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "管理员可删除尚未寄回、未付款的寄修记录，包括已确认检测费记录；如有关联未付款订单，在同一事务软关闭。已付款或已寄回禁止删除。客户自助删除限制不变。"}}, "/v1/repairs/{repair_id}/progress": {"post": {"operationId": "updateRepairProgress", "summary": "后台或智能体更新维修进度", "description": "仅admin/agent。起始in_transit，先received，再检测/报价/维修，最后returned。quoted与repairing可按实际流程先后出现。返回新状态及时间线；写入事务与幂等响应原子提交。returned后禁止覆盖寄回单号。 已通过repair_id关联的付款订单与寄修记录在任一入口保存寄回运单后，同事务双向同步状态和运单；关联订单未付款或两边运单冲突时拒绝并回滚。 未付款时可重新确认检测费，关联待付款订单同步改价；改为0元关闭待付款订单。已付款禁止直接改价。", "x-allowed-roles": ["admin", "agent"], "parameters": [{"name": "repair_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{8,128}$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RepairProgress"}}}}, "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/RepairDetail"}, "request_id": {"type": "string"}}}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/v1/auth/admin": {"post": {"operationId": "loginAdministrator", "summary": "管理员账号密码登录", "security": [], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["username", "password"], "properties": {"username": {"type": "string", "maxLength": 100}, "password": {"type": "string", "maxLength": 200, "writeOnly": true}}}}}}, "responses": {"200": {"description": "返回 data.token、expires_in=28800 和 role=admin"}, "401": {"description": "账号或密码不正确"}, "429": {"description": "连续失败尝试过多，请稍后再试"}}}}, "/v1/auth/admin/logout": {"post": {"operationId": "logoutAdministrator", "summary": "退出并撤销管理员会话", "x-allowed-roles": ["admin"], "responses": {"200": {"description": "当前会话已撤销"}}}}, "/v1/admin-entry": {"get": {"operationId": "getMiniAdminEntry", "summary": "已授权微信账号获取一次性免密码后台入口", "x-allowed-roles": ["customer"], "responses": {"200": {"description": "data.url 为带60秒有效一次性票据片段的后台地址；禁止记录分享。"}, "403": {"description": "当前微信账号无后台入口授权"}, "503": {"description": "正式后台HTTPS地址未配置"}}}}, "/v1/auth/admin-entry": {"post": {"operationId": "exchangeMiniAdminTicket", "summary": "后台页面消费一次性入口票据并取得管理员会话", "security": [], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["ticket"], "properties": {"ticket": {"type": "string", "writeOnly": true}}}}}}, "responses": {"200": {"description": "data.token、role=admin和expires_in=28800"}, "401": {"description": "票据无效、已消费、过期或权限已取消"}}}}, "/v1/customers/{customer_id}/mini-admin": {"post": {"operationId": "setMiniAdminAccess", "summary": "管理员授权或取消微信账号后台入口", "x-allowed-roles": ["admin"], "parameters": [{"name": "customer_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["enabled"], "properties": {"enabled": {"type": "boolean"}}}}}}, "responses": {"200": {"description": "data.customer_id、data.can_manage"}, "403": {"description": "仅后台管理员可授权"}, "404": {"description": "客户账号不存在"}}}}, "/v1/orders/{order_id}/refunds": {"post": {"operationId": "requestRefund", "summary": "客户提交全额或部分退款申请", "description": "退款需管理员审核。审核通过不代表到账；当前退款通道尚未接通，approved 保持待退款。客户或智能体不能审核。", "x-allowed-roles": ["customer"], "parameters": [{"name": "order_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{8,128}$"}}], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/Refund"}, "request_id": {"type": "string", "description": ""}}, "required": ["data", "request_id"]}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amount_fen": {"type": "integer", "minimum": 1}, "reason": {"type": "string", "minLength": 1, "maxLength": 500}}, "required": ["amount_fen", "reason"], "additionalProperties": false}}}}}}, "/v1/refunds/{refund_id}/review": {"post": {"operationId": "reviewRefund", "summary": "管理员同意或拒绝退款申请", "description": "退款需管理员审核。审核通过不代表到账；当前退款通道尚未接通，approved 保持待退款。客户或智能体不能审核。", "x-allowed-roles": ["admin"], "parameters": [{"name": "refund_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{8,128}$"}}], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/Refund"}, "request_id": {"type": "string", "description": ""}}, "required": ["data", "request_id"]}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"decision": {"type": "string", "enum": ["approve", "reject"]}, "review_note": {"type": "string", "maxLength": 500, "description": "拒绝必填，客户可见"}}, "required": ["decision"], "additionalProperties": false}}}}}}, "/v1/refunds": {"get": {"operationId": "listRefunds", "summary": "仅管理员获取退款审核列表", "description": "默认全部，可按 status 筛选。", "x-allowed-roles": ["admin"], "parameters": [{"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}}, {"name": "offset", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 0, "default": 0}}, {"name": "status", "in": "query", "schema": {"type": "string", "enum": ["pending", "approved", "rejected", "processing", "succeeded", "failed"]}}], "responses": {"200": {"description": "成功", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object", "properties": {"items": {"type": "array", "items": {"$ref": "#/components/schemas/Refund"}}, "total": {"type": "integer"}, "limit": {"type": "integer"}, "offset": {"type": "integer"}}, "required": []}, "request_id": {"type": "string", "description": ""}}, "required": ["data", "request_id"]}}}}, "400": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "请求错误，参见error.code", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}}, "components": {"securitySchemes": {"BearerAuth": {"type": "http", "scheme": "bearer", "description": "客户会话或独立后台/agent令牌。后台令牌禁止放入小程序。"}}, "schemas": {"CreateOrder": {"type": "object", "properties": {"recipient_name": {"type": "string", "description": "寄回收件人", "maxLength": 60}, "recipient_phone": {"type": "string", "description": "联系电话", "maxLength": 30}, "recipient_address": {"type": "string", "description": "寄回完整地址", "maxLength": 500}, "product_id": {"type": "string", "enum": ["repair-fee"]}, "quantity": {"type": "integer", "minimum": 1, "maximum": 10000, "description": "仅兼容旧版10元商品客户端，新客户端不要传。", "deprecated": true}, "device_model": {"type": "string", "description": "设备型号，选填", "maxLength": 120}, "repair_reference": {"type": "string", "description": "客户付款时选填的寄入维修部快递单号；为空时显示留白。与系统寄修关联ID repair_id 分开，不自动替换为内部编号。", "maxLength": 120}, "note": {"type": "string", "description": "买家留言", "maxLength": 1000}, "save_contact": {"type": "boolean", "enum": [true], "description": "客户同意保存收件资料用于售后"}, "amount_fen": {"type": "integer", "minimum": 1, "maximum": 10000000, "description": "客户填写的维修金额，单位人民币分。99.50元传9950；无需是10元倍数。"}, "repair_id": {"type": "string", "nullable": false, "description": "客户确认关联的自助寄修ID，选填。仅允许本人寄修单；同一寄修单重复提交返回同一订单，包含已付款订单。repair_reference为自由文本，不作为去重依据。"}}, "required": ["recipient_name", "recipient_phone", "recipient_address", "product_id", "save_contact"], "oneOf": [{"required": ["amount_fen"], "not": {"required": ["quantity"]}}, {"required": ["quantity"], "not": {"required": ["amount_fen"]}}]}, "Contact": {"type": "object", "properties": {"recipient_name": {"type": "string", "description": "寄回收件人", "maxLength": 60}, "recipient_phone": {"type": "string", "description": "联系电话", "maxLength": 30}, "recipient_address": {"type": "string", "description": "寄回完整地址", "maxLength": 500}}, "required": ["recipient_name", "recipient_phone", "recipient_address"]}, "Shipment": {"type": "object", "properties": {"carrier": {"type": "string", "description": "快递公司", "enum": ["申通快递", "德邦快递", "顺丰速运", "其他", "无需物流"]}, "tracking_number": {"type": "string", "description": "打单软件产生的真实运单号", "pattern": "^[A-Za-z0-9-]{6,64}$"}, "carrier_name": {"type": "string", "maxLength": 40, "description": "选其他时必填实际快递公司名称。"}, "delivery_method": {"type": "string", "enum": ["courier", "no_logistics"], "description": "courier为快递寄回；no_logistics无需物流，不填写运单。"}}, "required": [], "anyOf": [{"required": ["carrier", "tracking_number"], "properties": {"carrier": {"enum": ["申通快递", "德邦快递", "顺丰速运"]}}}, {"required": ["carrier", "carrier_name", "tracking_number"], "properties": {"carrier": {"enum": ["其他"]}, "carrier_name": {"minLength": 1}}}, {"required": ["carrier"], "properties": {"carrier": {"enum": ["无需物流"]}}}, {"required": ["delivery_method"], "properties": {"delivery_method": {"enum": ["no_logistics"]}}}], "description": "其他需手填carrier_name；无需物流不需要公司或单号，不能同时提交冲突的快递信息。"}, "Order": {"type": "object", "properties": {"recipient_name": {"type": "string", "description": "寄回收件人", "maxLength": 60}, "recipient_phone": {"type": "string", "description": "联系电话", "maxLength": 30}, "recipient_address": {"type": "string", "description": "寄回完整地址", "maxLength": 500}, "id": {"type": "string", "description": "唯一订单ID"}, "customer_id": {"type": "string", "description": "客户ID"}, "quantity": {"type": "integer", "description": "兼容历史订单。custom_amount订单固定1，不参与新客户端计价。"}, "amount_fen": {"type": "integer", "description": "人民币分，10元=1000分"}, "payment_status": {"type": "string", "enum": ["pending", "paid"]}, "fulfillment_status": {"type": "string", "enum": ["unshipped", "shipped"]}, "carrier": {"type": "string", "nullable": true}, "tracking_number": {"type": "string", "nullable": true}, "device_model": {"type": "string", "description": ""}, "repair_reference": {"type": "string", "description": "客户付款时选填的寄入维修部快递单号；为空时显示留白。与系统寄修关联ID repair_id 分开，不自动替换为内部编号。"}, "note": {"type": "string", "description": ""}, "created_at": {"type": "string", "description": "", "format": "date-time"}, "paid_at": {"type": "string", "format": "date-time", "nullable": true}, "shipped_at": {"type": "string", "format": "date-time", "nullable": true}, "pricing_mode": {"type": "string", "enum": ["custom_amount", "legacy_quantity"]}, "repair_id": {"type": "string", "nullable": true, "description": "客户确认关联的自助寄修ID，选填。仅允许本人寄修单；同一寄修单重复提交返回同一订单，包含已付款订单。repair_reference为自由文本，不作为去重依据。"}, "deleted_at": {"type": "string", "nullable": true, "format": "date-time", "description": "删除时间。客户列表与详情不返回已删除记录；后台按原ID读取可核查。"}, "delivery_method": {"type": "string", "enum": ["courier", "no_logistics"], "description": "courier为快递寄回；no_logistics无需物流，不填写运单。", "nullable": true}, "refunds": {"type": "array", "items": {"$ref": "#/components/schemas/Refund"}}, "refund_status": {"type": "string", "nullable": true}, "refund_status_label": {"type": "string"}, "refunded_amount_fen": {"type": "integer"}, "refundable_amount_fen": {"type": "integer"}, "can_request_refund": {"type": "boolean"}}, "required": []}, "Customer": {"type": "object", "properties": {"id": {"type": "string", "description": ""}, "name": {"type": "string", "description": ""}, "phone": {"type": "string", "description": ""}, "address": {"type": "string", "description": ""}, "created_at": {"type": "string", "description": "", "format": "date-time"}, "updated_at": {"type": "string", "description": "", "format": "date-time"}, "can_manage": {"type": "boolean", "readOnly": true, "description": "此微信账号有后台入口授权，不由手机号推断。"}}, "required": []}, "Error": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "description": ""}, "message": {"type": "string", "description": ""}}, "required": ["code", "message"]}, "request_id": {"type": "string", "description": ""}}, "required": ["error", "request_id"]}, "RepairCreate": {"type": "object", "properties": {"phone": {"type": "string", "description": "", "maxLength": 30}, "return_address": {"type": "string", "description": "", "maxLength": 500}, "inbound_tracking_number": {"type": "string", "description": "", "pattern": "^[A-Za-z0-9-]{6,64}$"}, "device_description": {"type": "string", "description": "型号和数量", "maxLength": 200}, "fault_description": {"type": "string", "description": "", "maxLength": 1000}, "save_contact": {"type": "boolean", "enum": [true]}, "evidence_base64": {"type": "string", "description": "可选JPG/PNG购买凭证，不含data URI前缀，解码后最多1MB", "maxLength": 1500000}, "evidence_type": {"type": "string", "description": "", "enum": ["image/jpeg", "image/png"]}}, "required": ["phone", "return_address", "inbound_tracking_number", "device_description", "save_contact"]}, "Repair": {"type": "object", "properties": {"id": {"type": "string", "description": ""}, "customer_id": {"type": "string", "description": ""}, "phone": {"type": "string", "description": ""}, "return_address": {"type": "string", "description": ""}, "inbound_tracking_number": {"type": "string", "description": ""}, "device_description": {"type": "string", "description": ""}, "fault_description": {"type": "string", "description": ""}, "evidence_type": {"type": "string", "description": ""}, "created_at": {"type": "string", "description": "", "format": "date-time"}, "repair_status": {"type": "string", "enum": ["in_transit", "received", "inspecting", "quoted", "repairing", "returned"]}, "status_label": {"type": "string"}, "quoted_amount_fen": {"type": "integer", "nullable": true, "minimum": 0, "description": "检测维修费用，单位人民币分。null表示未确认，0表示免费。"}, "progress_note": {"type": "string"}, "return_carrier": {"type": "string", "nullable": true}, "return_tracking_number": {"type": "string", "nullable": true, "description": "维修后寄回的运单，与寄入运单分开。"}, "updated_at": {"type": "string", "format": "date-time"}, "payment_status": {"type": "string", "enum": ["unpaid", "pending", "paid"]}, "payment_order_id": {"type": "string", "nullable": true}, "payment_amount_fen": {"type": "integer", "nullable": true, "description": "关联订单金额，单位分"}, "deleted_at": {"type": "string", "nullable": true, "format": "date-time", "description": "删除时间。客户列表与详情不返回已删除记录；后台按原ID读取可核查。"}, "delivery_method": {"type": "string", "enum": ["courier", "no_logistics"], "description": "courier为快递寄回；no_logistics无需物流，不填写运单。", "nullable": true}}, "required": []}, "Event": {"type": "object", "properties": {"sequence": {"type": "integer"}, "type": {"type": "string", "enum": ["order.created", "order.paid", "order.shipped"]}, "order_id": {"type": "string", "description": ""}, "actor": {"type": "string", "description": ""}, "payload": {"type": "object"}, "created_at": {"type": "string", "description": "", "format": "date-time"}}, "required": []}, "RepairUpdate": {"type": "object", "properties": {"sequence": {"type": "integer"}, "status": {"type": "string", "enum": ["in_transit", "received", "inspecting", "quoted", "repairing", "returned"]}, "status_label": {"type": "string"}, "note": {"type": "string"}, "quoted_amount_fen": {"type": "integer", "nullable": true}, "return_carrier": {"type": "string", "nullable": true}, "return_tracking_number": {"type": "string", "nullable": true}, "created_at": {"type": "string", "format": "date-time"}}}, "RepairDetail": {"allOf": [{"$ref": "#/components/schemas/Repair"}, {"type": "object", "properties": {"timeline": {"type": "array", "items": {"$ref": "#/components/schemas/RepairUpdate"}}}}]}, "RepairProgress": {"type": "object", "required": ["repair_status"], "properties": {"repair_status": {"type": "string", "enum": ["in_transit", "received", "inspecting", "quoted", "repairing", "returned"]}, "note": {"type": "string", "maxLength": 1000}, "quoted_amount_fen": {"type": "integer", "minimum": 0, "maximum": 100000000, "description": "费用确认时必填，以人民币分计价，其他阶段不能传。"}, "return_carrier": {"type": "string", "description": "寄回阶段必填，取catalog中的carrier列表"}, "return_tracking_number": {"type": "string", "pattern": "^[A-Za-z0-9-]{6,64}$", "description": "寄回阶段必填"}, "return_carrier_name": {"type": "string", "maxLength": 40, "description": "选其他时必填实际快递公司名称。"}, "delivery_method": {"type": "string", "enum": ["courier", "no_logistics"], "description": "courier为快递寄回；no_logistics无需物流，不填写运单。"}}, "description": "新后台流程只使用 quoted（检测费已确认）和 returned（已寄回）。其余状态仅兼容历史客户端。"}, "Refund": {"type": "object", "properties": {"id": {"type": "string"}, "order_id": {"type": "string"}, "amount_fen": {"type": "integer", "minimum": 1, "description": "整数分"}, "reason": {"type": "string"}, "status": {"type": "string", "enum": ["pending", "approved", "rejected", "processing", "succeeded", "failed"]}, "status_label": {"type": "string"}, "review_note": {"type": "string"}, "created_at": {"type": "string"}, "updated_at": {"type": "string"}, "reviewed_at": {"type": "string", "nullable": true}, "reviewed_by": {"type": "string", "nullable": true}}}}}}