{ "openapi": "3.0.3", "info": { "title": "真实出车与自有外接运营统计", "version": "1.0.0", "description": "仅实际departed_at非空车次；使用DEPART不可变快照，一车次计一次，跨客户或多目的地不重复。物理托盘去重；自有与外接箱数以BOUND外接实收归属核算，支持同排车/同托混货。全筛选汇总与分页同快照；sourceType筛选含该类货的整车，并非裁切另一类货物。from含、to不含，UTC，最多366天/5000车次。发车车牌/司机使用历史，货物结案状态使用当前事实。约定金额按币种分别累计，不是财务应收/实收；列表财务按需读取，未读取明确NOT_QUERIED；单车次财务仅按DEPART客户/排车核对唯一派送来源，Finance返回已审核有效应收与明确归属整车次账单的确认收款分配。混合来源、无收款分配或多车次归属不估算，显示待分配。应收额仍按Finance实际币种展示，不把外接约定金额当应收；成本只通过FleetTripCostService.summaries(Collection)按最多100车次一批读取，保持现有trip:list成本读权限。无权限为FORBIDDEN，既有车次无登记为NOT_RECORDED；可读汇总仅包含已登记直接成本，返回未登记及未能分摊车次数，未知分摊值为null。查询不跨服务逐行HTTP，不写执行状态。图表与分页共用全筛选快照：按UTC日展示实运托盘及外接约定金额，目的地按稳定键统计涉及车次。按托均价仅包含PALLET计价，用该币种约定总金额除确认计价标准托位，ORDER报价排除。里程mile、油耗L是授权补充事实，与车辆档案累计里程和直接成本独立。" }, "security": [ { "bearerAuth": [] } ], "paths": { "/api/platform/v1/last-leg/fleet/operations": { "get": { "description": "platform:fleet:operations:list；一次查询返回分页与全范围汇总", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 200 } }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "warehouseId", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, { "name": "keyword", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 } }, { "name": "sourceType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "OWN", "EXTERNAL" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "IN_TRANSIT", "COMPLETED" ] } } ], "responses": { "200": { "description": "业务响应；成功code为200，业务失败不代表写入成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "page": { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/Row" } }, "page": { "type": "integer", "minimum": 0 }, "size": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "pages": { "type": "integer", "minimum": 0 } }, "required": [ "records", "page", "size", "total", "pages" ] }, "summary": { "$ref": "#/components/schemas/Summary" }, "charts": { "$ref": "#/components/schemas/Charts" } }, "required": [ "page", "summary", "charts" ] } }, "required": [ "code", "message", "data" ] } } } } } } }, "/api/platform/v1/last-leg/fleet/operations/{tripNo}/record": { "parameters": [ { "name": "tripNo", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "description": "platform:fleet:operations:list；仅实际已发车车次；尚未登记返回版本0和空值，不伪造零里程/油耗", "responses": { "200": { "description": "业务响应，成功code为200", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/MeasuredRecord" } }, "required": [ "code", "message", "data" ] } } } } } }, "put": { "description": "platform:fleet:operations:edit；父车次行锁、版本与原操作人请求键校验，原请求返回原快照，更正追加不可变历史。空值区别零，说明选填。不修改主档里程、车次执行、库存或费用。；附件选填，最多20个，保存前验证平台0、FLEET_TRIP_OPERATION_EVIDENCE和本车trip.id归属；幂等键包含完整文件ID列表，成功重放返回原快照，移除当前引用保留历史。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recordVersion": { "type": "integer", "minimum": 0 }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 128 }, "details": { "$ref": "#/components/schemas/MeasuredInput" }, "reason": { "type": "string", "maxLength": 1000, "nullable": true } }, "required": [ "recordVersion", "idempotencyKey", "details", "reason" ] } } } }, "responses": { "200": { "description": "业务响应，成功code为200", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/MeasuredRecord" } }, "required": [ "code", "message", "data" ] } } } } } } }, "/api/platform/v1/last-leg/fleet/operations/{tripNo}/record/history": { "parameters": [ { "name": "tripNo", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "description": "platform:fleet:operations:list；实测更正历史，按版本倒序分页", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "业务响应，成功code为200", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/MeasuredHistory" } }, "page": { "type": "integer", "minimum": 0 }, "size": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "pages": { "type": "integer", "minimum": 0 } }, "required": [ "records", "page", "size", "total", "pages" ] } }, "required": [ "code", "message", "data" ] } } } } } } }, "/api/platform/v1/last-leg/fleet/operations/{tripNo}/record/files": { "parameters": [ { "name": "tripNo", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "上传选填实测凭证，不创建实测记录", "description": "platform:fleet:operations:edit；仅平台0，实际已发车车次；FLEET_TRIP_OPERATION_EVIDENCE+trip.id，PDF/JPG/PNG，非空且最大10MiB；上传失败不创建或重建记录。", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "统一响应data为可信文件信息", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "data": { "$ref": "#/components/schemas/OperationEvidenceFile" } } } } } } } } }, "/api/platform/v1/last-leg/fleet/operations/{tripNo}/record/files/{fileId}/content": { "parameters": [ { "name": "tripNo", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fileId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 } } ], "get": { "summary": "按需读取本车实测凭证，历史引用继续可读", "description": "platform:fleet:operations:list；仅已保存至本车当前或历史版本的引用可读；重验平台0/业务类型/车次内部ID/文件ID，no-store；不逐行预取。", "responses": { "200": { "description": "PDF或图片原始内容", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "文件不可用或归属不符" } } } }, "/api/platform/v1/last-leg/fleet/operations/{tripNo}/finance": { "get": { "description": "operations:list与platform:finance:customer-arap:list同时要求；实收及收款单据另要求platform:finance:receipt:view，否则receiptsVisible=false、实收null、documents空。按需一次跨服务读取，无列表逐行HTTP；不写状态/费用/分配。", "parameters": [ { "name": "tripNo", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "responses": { "200": { "description": "同车次财务归属结果；已确认部分与完整金额待分配分别标明", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "data": { "$ref": "#/components/schemas/TripFinance" } } } } } }, "403": { "description": "缺运营或应收权限" }, "404": { "description": "无实际发车记录" }, "503": { "description": "Finance不可查询，不能替换成零" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "Money": { "type": "object", "properties": { "currency": { "type": "string" }, "amount": { "type": "number", "minimum": 0 } }, "required": [ "currency", "amount" ] }, "Row": { "type": "object", "properties": { "tripNo": { "type": "string" }, "status": { "type": "string" }, "vehiclePlate": { "type": "string", "nullable": true }, "driverName": { "type": "string", "nullable": true }, "warehouseName": { "type": "string", "nullable": true }, "departedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "destinations": { "type": "array", "items": { "$ref": "#/components/schemas/Destination" } }, "physicalPallets": { "type": "integer", "minimum": 0 }, "palletSpaces": { "type": "integer", "minimum": 0 }, "ownPackages": { "type": "integer", "minimum": 0 }, "externalPackages": { "type": "integer", "minimum": 0 }, "externalAgreedAmounts": { "type": "array", "items": { "$ref": "#/components/schemas/Money" } }, "financeStatus": { "type": "string", "enum": [ "NOT_QUERIED" ] }, "costStatus": { "type": "string", "enum": [ "FORBIDDEN", "NOT_RECORDED", "AVAILABLE" ] }, "externalPalletRates": { "type": "array", "items": { "$ref": "#/components/schemas/PalletRate" } }, "measured": { "allOf": [ { "$ref": "#/components/schemas/Measured" } ], "nullable": true }, "costs": { "allOf": [ { "$ref": "./fleet-trip-costs-v1.yaml#/components/schemas/Summary" } ], "nullable": true } }, "required": [ "tripNo", "status", "vehiclePlate", "driverName", "warehouseName", "departedAt", "completedAt", "destinations", "physicalPallets", "palletSpaces", "ownPackages", "externalPackages", "externalAgreedAmounts", "financeStatus", "costStatus", "externalPalletRates", "measured", "costs" ] }, "Summary": { "type": "object", "properties": { "trips": { "type": "integer", "minimum": 0 }, "inTransit": { "type": "integer", "minimum": 0 }, "completed": { "type": "integer", "minimum": 0 }, "physicalPallets": { "type": "integer", "minimum": 0 }, "palletSpaces": { "type": "integer", "minimum": 0 }, "ownPackages": { "type": "integer", "minimum": 0 }, "externalPackages": { "type": "integer", "minimum": 0 }, "externalAgreedAmounts": { "type": "array", "items": { "$ref": "#/components/schemas/Money" } }, "costs": { "$ref": "#/components/schemas/CostSummary" } }, "required": [ "trips", "inTransit", "completed", "physicalPallets", "palletSpaces", "ownPackages", "externalPackages", "externalAgreedAmounts", "costs" ] }, "Measured": { "type": "object", "properties": { "actualDistanceMiles": { "type": "number", "minimum": 0, "nullable": true, "multipleOf": 0.1 }, "actualFuelLitres": { "type": "number", "minimum": 0, "nullable": true, "multipleOf": 0.1 }, "remark": { "type": "string", "nullable": true, "maxLength": 1000 }, "evidenceFiles": { "type": "array", "items": { "$ref": "#/components/schemas/OperationEvidenceFile" } } }, "required": [ "actualDistanceMiles", "actualFuelLitres", "remark", "evidenceFiles" ] }, "Destination": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ] }, "PalletRate": { "type": "object", "properties": { "currency": { "type": "string" }, "pricedPalletSpaces": { "type": "integer", "minimum": 0 }, "agreedAmount": { "type": "number", "minimum": 0 } }, "required": [ "currency", "pricedPalletSpaces", "agreedAmount" ] }, "Series": { "type": "object", "properties": { "label": { "type": "string" }, "unit": { "type": "string" }, "points": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "number", "minimum": 0 } }, "required": [ "label", "value" ] } } }, "required": [ "label", "unit", "points" ] }, "Charts": { "type": "object", "properties": { "physicalPallets": { "type": "array", "items": { "$ref": "#/components/schemas/Series" } }, "destinationTrips": { "type": "array", "items": { "$ref": "#/components/schemas/Series" } }, "externalAgreedAmounts": { "type": "array", "items": { "$ref": "#/components/schemas/Series" } }, "externalPalletRates": { "type": "array", "items": { "$ref": "#/components/schemas/Series" } } }, "required": [ "physicalPallets", "destinationTrips", "externalAgreedAmounts", "externalPalletRates" ] }, "MeasuredRecord": { "type": "object", "properties": { "tripNo": { "type": "string" }, "recordVersion": { "type": "integer", "format": "int64", "minimum": 0 }, "details": { "$ref": "#/components/schemas/Measured" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "tripNo", "recordVersion", "details", "updatedAt" ] }, "MeasuredHistory": { "type": "object", "properties": { "recordVersion": { "type": "integer", "minimum": 0 }, "reason": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "details": { "$ref": "#/components/schemas/Measured" } }, "required": [ "recordVersion", "reason", "occurredAt", "details" ] }, "CostTotal": { "type": "object", "properties": { "currency": { "type": "string" }, "directCost": { "type": "number", "minimum": 0 }, "ownCost": { "type": "number", "minimum": 0, "nullable": true }, "externalCost": { "type": "number", "minimum": 0, "nullable": true } }, "required": [ "currency", "directCost", "ownCost", "externalCost" ] }, "CostSummary": { "type": "object", "properties": { "visible": { "type": "boolean" }, "unrecordedTrips": { "type": "integer", "minimum": 0, "nullable": true }, "unallocatedTrips": { "type": "integer", "minimum": 0, "nullable": true }, "totals": { "type": "array", "items": { "$ref": "#/components/schemas/CostTotal" } } }, "required": [ "visible", "unrecordedTrips", "unallocatedTrips", "totals" ] }, "MeasuredInput": { "type": "object", "properties": { "actualDistanceMiles": { "type": "number", "minimum": 0, "nullable": true, "multipleOf": 0.1 }, "actualFuelLitres": { "type": "number", "minimum": 0, "nullable": true, "multipleOf": 0.1 }, "remark": { "type": "string", "nullable": true, "maxLength": 1000 }, "evidenceFileIds": { "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "type": "integer", "format": "int64", "minimum": 1 }, "description": "选填，空数组合法；只提交本车已上传文件ID，保存重新核验归属" } }, "required": [ "actualDistanceMiles", "actualFuelLitres", "remark" ] }, "OperationEvidenceFile": { "type": "object", "required": [ "fileId", "fileName", "contentType", "sizeBytes" ], "properties": { "fileId": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string", "enum": [ "application/pdf", "image/jpeg", "image/png" ] }, "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 10485760 } } }, "TripFinanceMoney": { "type": "object", "required": [ "currency", "receivableAmount", "receivedAmount" ], "properties": { "currency": { "type": "string" }, "receivableAmount": { "type": "number", "minimum": 0 }, "receivedAmount": { "type": "number", "minimum": 0, "nullable": true } } }, "TripFinanceSource": { "type": "object", "required": [ "customerId", "businessNo", "sourceNo", "feeItemName", "sourceVersion", "currency", "amount", "status" ], "properties": { "customerId": { "type": "string" }, "businessNo": { "type": "string" }, "sourceNo": { "type": "string", "nullable": true }, "feeItemName": { "type": "string" }, "sourceVersion": { "type": "integer", "minimum": 1 }, "currency": { "type": "string" }, "amount": { "type": "number", "minimum": 0 }, "status": { "type": "string" } } }, "TripFinanceDocument": { "type": "object", "required": [ "billNo", "currency", "receivedAmount", "allocationStatus", "reason" ], "properties": { "billNo": { "type": "string" }, "currency": { "type": "string" }, "receivedAmount": { "type": "number", "minimum": 0, "nullable": true }, "allocationStatus": { "type": "string", "enum": [ "ATTRIBUTED", "PENDING_ALLOCATION" ] }, "reason": { "type": "string" } } }, "TripFinanceAuthority": { "type": "object", "required": [ "status", "totals", "sources", "documents", "reason" ], "properties": { "status": { "type": "string", "enum": [ "AVAILABLE", "PENDING_ALLOCATION" ] }, "totals": { "type": "array", "items": { "$ref": "#/components/schemas/TripFinanceMoney" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/TripFinanceSource" } }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/TripFinanceDocument" } }, "reason": { "type": "string" } } }, "TripFinance": { "type": "object", "required": [ "tripNo", "dispatchNos", "receiptsVisible", "finance", "attributionStatus", "attributionReason" ], "properties": { "tripNo": { "type": "string" }, "dispatchNos": { "type": "array", "items": { "type": "string" } }, "receiptsVisible": { "type": "boolean" }, "finance": { "$ref": "#/components/schemas/TripFinanceAuthority" }, "attributionStatus": { "type": "string", "enum": [ "ATTRIBUTED", "PENDING_ALLOCATION" ] }, "attributionReason": { "type": "string" } } } } }, "x-integration-database": { "owner": "总控负责集成模块基线与海外统一初始化SQL，专项不执行SQL。新增权限platform:fleet:operations:edit。", "ddl": "CREATE TABLE ll_fleet_trip_operations_record (\n id BIGINT NOT NULL COMMENT '出车实测历史主键',\n trip_no VARCHAR(64) NOT NULL COMMENT '车次业务编号',\n record_version BIGINT NOT NULL COMMENT '实测记录版本从一递增',\n details_json JSON NOT NULL COMMENT '实际里程英里油耗升与备注快照',\n reason VARCHAR(1000) NOT NULL COMMENT '实测更正说明',\n operator_id VARCHAR(64) NOT NULL COMMENT '实测操作人标识',\n request_key VARCHAR(128) NOT NULL COMMENT '实测保存幂等键',\n request_hash CHAR(64) NOT NULL COMMENT '实测请求内容摘要',\n occurred_at DATETIME(3) NOT NULL COMMENT '实测保存时间UTC',\n PRIMARY KEY (id),\n UNIQUE KEY uk_fleet_operations_version (trip_no,record_version),\n UNIQUE KEY uk_fleet_operations_request (trip_no,operator_id,request_key)\n) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='车次里程油耗不可变更正记录';" } }