java-project/baiyue-firstleg
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(firstleg): resolve loading list lifecycle by plan

Browse Source
This commit is contained in:
ouyangxq
2026-08-31 15:26:47 +08:00
parent 0122ad314b
commit c9792b1f63
7 changed files with 137 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
firstleg/src/main/java/com/baiyue/firstleg/controller/PlatformLoadingListController.java
+12
View File
@@ -12,6 +12,7 @@ import com.baiyue.firstleg.dto.LoadingListDtos.PreloadSummary;
import com.baiyue.firstleg.dto.LoadingListDtos.ConfirmPreloadRequest;
import com.baiyue.firstleg.dto.LoadingListDtos.PreloadConfirmationResponse;
import com.baiyue.firstleg.dto.LoadingListDtos.TransportUpdateRequest;
import com.baiyue.firstleg.dto.LoadingListDtos.LifecycleResolution;
import com.baiyue.firstleg.service.FirstlegScopeGuard;
import com.baiyue.firstleg.service.LoadingListService;
import io.swagger.v3.oas.annotations.Operation;
@@ -60,6 +61,17 @@ public class PlatformLoadingListController {
return ApiResponse.success(service.preloadDetail(planId, warehouseId));
}
@Operation(summary = "解析装柜计划当前详情阶段",
description = "按稳定 planId 返回 PRELOAD 或 LOADING_LIST，供页面在计划完成后受控切换详情接口。")
@GetMapping("/loading-plans/{planId}/lifecycle")
@PreAuthorize("hasAuthority('platform:firstleg:preload:list')")
public ApiResponse<LifecycleResolution> lifecycle(
@AuthenticationPrincipal AuthenticatedUser user, @PathVariable @Positive long planId,
@RequestParam @Positive long warehouseId) {
FirstlegScopeGuard.platform(user);
return ApiResponse.success(service.lifecycle(planId, warehouseId));
}
@Operation(summary = "修改装柜运输字段", description = "已推送且仍为 EDITING 的预装清单可补录或修改集装箱号与航次；LOADING 阶段按稳定柜次身份规则维护，不能清空已创建 PDA 任务的柜号。")
@PatchMapping("/loading-plans/{planId}/transport")
@PreAuthorize("hasAuthority('platform:firstleg:preload:edit')")
firstleg/src/main/java/com/baiyue/firstleg/dto/LoadingListDtos.java
+11
View File
@@ -115,6 +115,17 @@ public final class LoadingListDtos {
) {
}
public record LifecycleResolution(
Long planId,
Long containerBookingId,
Long warehouseId,
String planNo,
String planStatus,
String detailResource,
String requiredPermission
) {
}
public record PreloadSummary(
Long planId,
Long containerBookingId,
firstleg/src/main/java/com/baiyue/firstleg/service/LoadingListService.java
+22 -3
View File
@@ -16,6 +16,7 @@ import com.baiyue.firstleg.dto.LoadingListDtos.TransportUpdateRequest;
import com.baiyue.firstleg.dto.LoadingListDtos.BusinessDocument;
import com.baiyue.firstleg.dto.LoadingListDtos.DocumentAttachRequest;
import com.baiyue.firstleg.dto.LoadingListDtos.DocumentCompleteRequest;
import com.baiyue.firstleg.dto.LoadingListDtos.LifecycleResolution;
import com.baiyue.firstleg.client.LoadingDocumentFileClient;
import com.baiyue.firstleg.entity.ContainerDocumentEntity;
import com.baiyue.firstleg.mapper.LoadingListQueryMapper.AggregateRow;
@@ -97,20 +98,38 @@ public class LoadingListService {
AggregateRow row = requirePlan(planId);
requireWarehouse(row, warehouseId);
if (!PRELOAD_STATUSES.contains(row.getPlanStatus())) {
throw notFound("预装清单不存在");
throw conflict("装柜计划已离开预装详情阶段");
}
return repository.preloadDetail(row);
}
public LifecycleResolution lifecycle(long planId, long warehouseId) {
AggregateRow row = requirePlan(planId);
requireWarehouse(row, warehouseId);
if (PRELOAD_STATUSES.contains(row.getPlanStatus())) {
return lifecycle(row, "PRELOAD", "platform:firstleg:preload:list");
}
if ("COMPLETED".equals(row.getPlanStatus())) {
return lifecycle(row, "LOADING_LIST", "platform:firstleg:loading-list:list");
}
throw conflict("装柜计划处于未知生命周期阶段");
}
public ConfirmedDetail confirmedDetail(long planId, long warehouseId) {
AggregateRow row = requirePlan(planId);
requireWarehouse(row, warehouseId);
if (!"COMPLETED".equals(row.getPlanStatus())) {
throw notFound("装柜清单不存在");
throw conflict("装柜计划尚未进入正式装柜清单阶段");
}
return repository.confirmedDetail(row);
}
private static LifecycleResolution lifecycle(AggregateRow row, String resource,
String permission) {
return new LifecycleResolution(row.getPlanId(), row.getContainerBookingId(),
row.getWarehouseId(), row.getPlanNo(), row.getPlanStatus(), resource, permission);
}
public BusinessDocument containerClearance(long bookingId) {
requireBookingPlan(bookingId);
return document(repository.document(bookingId, DESTINATION_CLEARANCE));
@@ -554,7 +573,7 @@ public class LoadingListService {
throw badRequest("warehouseId必须大于0");
}
if (!java.util.Objects.equals(row.getWarehouseId(), warehouseId)) {
throw notFound("装柜计划不属于当前仓库");
throw new BizException(ResultCode.FORBIDDEN, "装柜计划不属于当前仓库");
}
}
firstleg/src/main/resources/openapi/loading-lists-v1.yaml
+38
View File
@@ -31,6 +31,20 @@ paths:
parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/WarehouseId'}]
responses:
'200': {$ref: '#/components/responses/PreloadDetailResponse'}
'409': {description: 计划已离开预装阶段；先查询 lifecycle 获取当前正式详情资源}
/api/platform/v1/first-leg/loading-plans/{planId}/lifecycle:
get:
summary: 解析装柜计划当前详情阶段
description: >-
需要 platform:firstleg:preload:list 权限。同一 planId 从 EDITING、LOADING 到 COMPLETED 永久稳定；
EDITING/LOADING 返回 PRELOAD，COMPLETED 返回 LOADING_LIST 及其独立读取权限。
页面据此选择预装详情或正式装柜清单详情，不得以错误文案或 A0404 猜测阶段。
x-permission: platform:firstleg:preload:list
parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/WarehouseId'}]
responses:
'200': {$ref: '#/components/responses/LifecycleResolutionResponse'}
'403': {description: planId 不属于请求仓库或缺少平台读取权限}
'404': {description: planId 真实不存在}
/api/platform/v1/first-leg/loading-plans/{planId}/transport:
patch:
summary: 修改预装运输信息
@@ -83,6 +97,7 @@ paths:
parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/WarehouseId'}]
responses:
'200': {$ref: '#/components/responses/ConfirmedDetailResponse'}
'409': {description: 计划尚未进入 COMPLETED 正式装柜清单阶段}
components:
parameters:
PlanId:
@@ -156,6 +171,9 @@ components:
ConfirmedDetailResponse:
description: 装柜清单详情查询或确认成功，也可能返回业务失败
content: {application/json: {schema: {$ref: '#/components/schemas/ConfirmedDetailEnvelope'}}}
LifecycleResolutionResponse:
description: 装柜计划生命周期解析成功或业务失败
content: {application/json: {schema: {$ref: '#/components/schemas/LifecycleResolutionEnvelope'}}}
schemas:
LongId:
type: string
@@ -214,6 +232,14 @@ components:
data:
allOf: [{$ref: '#/components/schemas/ConfirmedDetail'}]
nullable: true
LifecycleResolutionEnvelope:
allOf:
- {$ref: '#/components/schemas/ApiEnvelope'}
- type: object
properties:
data:
allOf: [{$ref: '#/components/schemas/LifecycleResolution'}]
nullable: true
PreloadPage:
type: object
required: [records, page, size, total, pages]
@@ -238,6 +264,18 @@ components:
properties:
accountId: {$ref: '#/components/schemas/LongId'}
customerName: {type: string, nullable: true, description: 客户名称}
LifecycleResolution:
type: object
additionalProperties: false
required: [planId, containerBookingId, warehouseId, planNo, planStatus, detailResource, requiredPermission]
properties:
planId: {$ref: '#/components/schemas/LongId'}
containerBookingId: {$ref: '#/components/schemas/LongId'}
warehouseId: {$ref: '#/components/schemas/LongId'}
planNo: {type: string, description: 预装与正式装柜清单沿用的稳定业务号}
planStatus: {type: string, enum: [EDITING, LOADING, COMPLETED]}
detailResource: {type: string, enum: [PRELOAD, LOADING_LIST], description: 当前应读取的唯一详情资源}
requiredPermission: {type: string, enum: ['platform:firstleg:preload:list', 'platform:firstleg:loading-list:list']}
PreloadSummary:
type: object
required: [planId, containerBookingId, preloadNo, customers, status, skuCount, totalPackageCount, totalVolumeCbm, totalGrossWeightKg, createdAt, version, readiness]
firstleg/src/test/java/com/baiyue/firstleg/controller/LoadingListControllerContractTest.java
+9 -1
View File
@@ -29,6 +29,7 @@ class LoadingListControllerContractTest {
void permissionsMatch() throws Exception {
authority("preloadPage", "platform:firstleg:preload:list", AuthenticatedUser.class, PreloadQuery.class);
authority("preloadDetail", "platform:firstleg:preload:list", AuthenticatedUser.class, long.class, long.class);
authority("lifecycle", "platform:firstleg:preload:list", AuthenticatedUser.class, long.class, long.class);
authority("updateTransport", "platform:firstleg:preload:edit", AuthenticatedUser.class,
long.class, long.class, String.class, TransportUpdateRequest.class);
authority("confirmPreload", "platform:firstleg:preload:edit", AuthenticatedUser.class,
@@ -72,6 +73,8 @@ class LoadingListControllerContractTest {
.contains("校验ISO 6346结构、设备类别和校验位")
.contains("PDA任务尚未领取且无任何物理作业事实")
.contains("/loading-plans/{planId}/confirm")
.contains("/loading-plans/{planId}/lifecycle")
.contains("不得以错误文案或 A0404 猜测阶段")
.contains("confirmationStatus")
.contains("canConfirm")
.contains("blockingReasons")
@@ -116,6 +119,7 @@ class LoadingListControllerContractTest {
assertThat(paths).containsOnlyKeys(
"/api/platform/v1/first-leg/loading-plans",
"/api/platform/v1/first-leg/loading-plans/{planId}",
"/api/platform/v1/first-leg/loading-plans/{planId}/lifecycle",
"/api/platform/v1/first-leg/loading-plans/{planId}/transport",
"/api/platform/v1/first-leg/loading-plans/{planId}/confirm",
"/api/platform/v1/first-leg/loading-lists",
@@ -126,7 +130,11 @@ class LoadingListControllerContractTest {
"LongId", "PreloadPage", "ConfirmedPage", "Customer", "PreloadSummary",
"ConfirmedSummary", "LoadingItem", "OperationHistory", "PreloadDetail",
"ConfirmedDetail", "TransportUpdateRequest", "PreloadReadiness",
"ConfirmPreloadRequest", "PreloadConfirmation", "PreloadConfirmationEnvelope");
"ConfirmPreloadRequest", "PreloadConfirmation", "PreloadConfirmationEnvelope",
"LifecycleResolution", "LifecycleResolutionEnvelope");
assertThat(properties(schemas, "LifecycleResolution")).containsOnlyKeys(
"planId", "containerBookingId", "warehouseId", "planNo", "planStatus",
"detailResource", "requiredPermission");
assertThat(paths)
.doesNotContainKey("/api/platform/v1/first-leg/loading-plans/{planId}/complete");
assertThat(stringMap(schemas.get("LongId"))).containsEntry("type", "string");
firstleg/src/test/java/com/baiyue/firstleg/repository/LoadingListQueryMapperContractTest.java
+9
View File
@@ -67,6 +67,15 @@ class LoadingListQueryMapperContractTest {
.contains("i.deleted = 0");
}
@Test
void lifecycleAggregateKeepsTheSamePlanIdAcrossEveryStatus() throws Exception {
String aggregate = sql("selectAggregate", Select.class);
assertThat(aggregate)
.contains("WHERE p.id = #{planId}")
.contains("p.plan_status")
.doesNotContain("plan_status = 'COMPLETED'", "plan_status IN ('EDITING', 'LOADING')");
}
@Test
void mutationsShouldUseStatusAndOptimisticVersionConditions() throws Exception {
String touch = sql("touchEditable", Update.class);
firstleg/src/test/java/com/baiyue/firstleg/service/LoadingListServiceTest.java
+36 -1
View File
@@ -361,7 +361,42 @@ class LoadingListServiceTest {
assertThatThrownBy(() -> service.preloadDetail(10L, 200L))
.isInstanceOf(BizException.class)
.extracting(error -> ((BizException) error).getResultCode())
.isEqualTo(ResultCode.NOT_FOUND);
.isEqualTo(ResultCode.FORBIDDEN);
}
@Test
void resolvesStablePlanIdToPreloadOrCompletedLoadingListWithoutGuessingFrom404() {
when(repository.aggregate(10L)).thenReturn(row("LOADING", 2), row("COMPLETED", 3));
var preload = service.lifecycle(10L, 100L);
var completed = service.lifecycle(10L, 100L);
assertThat(preload.planId()).isEqualTo(10L);
assertThat(preload.planStatus()).isEqualTo("LOADING");
assertThat(preload.detailResource()).isEqualTo("PRELOAD");
assertThat(preload.requiredPermission()).isEqualTo("platform:firstleg:preload:list");
assertThat(completed.planId()).isEqualTo(10L);
assertThat(completed.planStatus()).isEqualTo("COMPLETED");
assertThat(completed.detailResource()).isEqualTo("LOADING_LIST");
assertThat(completed.requiredPermission()).isEqualTo("platform:firstleg:loading-list:list");
}
@Test
void stageMismatchIsConflictAndOnlyMissingPlanIsNotFound() {
when(repository.aggregate(10L)).thenReturn(row("COMPLETED", 3));
assertThatThrownBy(() -> service.preloadDetail(10L, 100L))
.isInstanceOfSatisfying(BizException.class, error ->
assertThat(error.getResultCode()).isEqualTo(ResultCode.CONFLICT));
when(repository.aggregate(11L)).thenReturn(row("LOADING", 2));
assertThatThrownBy(() -> service.confirmedDetail(11L, 100L))
.isInstanceOfSatisfying(BizException.class, error ->
assertThat(error.getResultCode()).isEqualTo(ResultCode.CONFLICT));
when(repository.aggregate(12L)).thenReturn(null);
assertThatThrownBy(() -> service.lifecycle(12L, 100L))
.isInstanceOfSatisfying(BizException.class, error ->
assertThat(error.getResultCode()).isEqualTo(ResultCode.NOT_FOUND));
}
@Test