java-project/baiyue-firstleg
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3b5454fb9944bdae421d1d364c891d487bb20ed5
baiyue-firstleg/lastleg-service/src/main/resources/openapi/fleet-operations-v1.yaml
T

1231 lines
34 KiB
YAML
Raw Normal View History

feat(fleet): integrate costs quotes operations and in-transit handovers
2026-10-03 12:38:04 +08:00
{
"openapi": "3.0.3",
"info": {
"title": "真实出车与自有外接运营统计",
"version": "1.0.0",
feat(fleet): read attributable trip receivables and receipts from finance
2026-10-05 11:51:47 +08:00
"description": "仅实际departed_at非空车次；使用DEPART不可变快照，一车次计一次，跨客户或多目的地不重复。物理托盘去重；自有与外接箱数以BOUND外接实收归属核算，支持同排车/同托混货。全筛选汇总与分页同快照；sourceType筛选含该类货的整车，并非裁切另一类货物。from含、to不含，UTC，最多366天/5000车次。发车车牌/司机使用历史，货物结案状态使用当前事实。约定金额按币种分别累计，不是财务应收/实收；列表财务按需读取，未读取明确NOT_QUERIED；单车次财务仅按DEPART客户/排车核对唯一派送来源，Finance返回已审核有效应收与明确归属整车次账单的确认收款分配。混合来源、无收款分配或多车次归属不估算，显示待分配。应收额仍按Finance实际币种展示，不把外接约定金额当应收；成本只通过FleetTripCostService.summaries(Collection<String>)按最多100车次一批读取，保持现有trip:list成本读权限。无权限为FORBIDDEN，既有车次无登记为NOT_RECORDED；可读汇总仅包含已登记直接成本，返回未登记及未能分摊车次数，未知分摊值为null。查询不跨服务逐行HTTP，不写执行状态。 图表与分页共用全筛选快照：按UTC日展示实运托盘及外接约定金额，目的地按稳定键统计涉及车次。按托均价仅包含PALLET计价，用该币种约定总金额除确认计价标准托位，ORDER报价排除。里程mile、油耗L是授权补充事实，与车辆档案累计里程和直接成本独立。"
feat(fleet): integrate costs quotes operations and in-transit handovers
2026-10-03 12:38:04 +08:00
},
"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": {
feat(fleet): attach scoped evidence to measured trip records
2026-10-03 16:38:37 +08:00
"description": "platform:fleet:operations:edit；父车次行锁、版本与原操作人请求键校验，原请求返回原快照，更正追加不可变历史。空值区别零，说明选填。不修改主档里程、车次执行、库存或费用。；附件选填，最多20个，保存前验证平台0、FLEET_TRIP_OPERATION_EVIDENCE和本车trip.id归属；幂等键包含完整文件ID列表，成功重放返回原快照，移除当前引用保留历史。",
feat(fleet): integrate costs quotes operations and in-transit handovers
2026-10-03 12:38:04 +08:00
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"recordVersion": {
"type": "integer",
"minimum": 0
},
"idempotencyKey": {
"type": "string",
"minLength": 8,
"maxLength": 128
},
"details": {
feat(fleet): attach scoped evidence to measured trip records
2026-10-03 16:38:37 +08:00
"$ref": "#/components/schemas/MeasuredInput"
feat(fleet): integrate costs quotes operations and in-transit handovers
2026-10-03 12:38:04 +08:00
},
"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"
]
}
}
}
}
}
}
feat(fleet): attach scoped evidence to measured trip records
2026-10-03 16:38:37 +08:00
},
"/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": "文件不可用或归属不符"
}
}
}
feat(fleet): read attributable trip receivables and receipts from finance
2026-10-05 11:51:47 +08:00
},
"/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不可查询，不能替换成零"
}
}
}
feat(fleet): integrate costs quotes operations and in-transit handovers
2026-10-03 12:38:04 +08:00
}
},
"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
feat(fleet): attach scoped evidence to measured trip records
2026-10-03 16:38:37 +08:00
},
"evidenceFiles": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OperationEvidenceFile"
}
feat(fleet): integrate costs quotes operations and in-transit handovers
2026-10-03 12:38:04 +08:00
}
},
"required": [
"actualDistanceMiles",
"actualFuelLitres",
feat(fleet): attach scoped evidence to measured trip records
2026-10-03 16:38:37 +08:00
"remark",
"evidenceFiles"
feat(fleet): integrate costs quotes operations and in-transit handovers
2026-10-03 12:38:04 +08:00
]
},
"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"
]
feat(fleet): attach scoped evidence to measured trip records
2026-10-03 16:38:37 +08:00
},
"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
}
}
feat(fleet): read attributable trip receivables and receipts from finance
2026-10-05 11:51:47 +08:00
},
"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"
}
}
feat(fleet): integrate costs quotes operations and in-transit handovers
2026-10-03 12:38:04 +08:00
}
}
},
"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='车次里程油耗不可变更正记录';"
}
}
Reference in New Issue Copy Permalink