feat(fleet): integrate costs quotes operations and in-transit handovers

This commit is contained in:
2026-10-03 12:38:04 +08:00
parent 274ecac474
commit cb6c54ffe5
107 changed files with 7304 additions and 42 deletions
@@ -0,0 +1,928 @@
{
"openapi": "3.0.3",
"info": {
"title": "真实出车与自有外接运营统计",
"version": "1.0.0",
"description": "仅实际departed_at非空车次;使用DEPART不可变快照,一车次计一次,跨客户或多目的地不重复。物理托盘去重;自有与外接箱数以BOUND外接实收归属核算,支持同排车/同托混货。全筛选汇总与分页同快照;sourceType筛选含该类货的整车,并非裁切另一类货物。from含、to不含,UTC,最多366天/5000车次。发车车牌/司机使用历史,货物结案状态使用当前事实。约定金额按币种分别累计,不是财务应收/实收;财务未查询明确NOT_QUERIED;成本只通过FleetTripCostService.summaries(Collection<String>)按最多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/export": {
"get": {
"description": "platform:fleet:operations:export;同筛选同事实来源的CSV",
"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": "UTF-8 BOM CSV",
"content": {
"text/csv": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
}
}
}
},
"/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;父车次行锁、版本与原操作人请求键校验,原请求返回原快照,更正追加不可变历史。空值区别零,说明选填。不修改主档里程、车次执行、库存或费用。",
"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/Measured"
},
"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"
]
}
}
}
}
}
}
}
},
"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
}
},
"required": [
"actualDistanceMiles",
"actualFuelLitres",
"remark"
]
},
"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"
]
}
}
},
"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='车次里程油耗不可变更正记录';"
}
}