优化

三期/货柜履约原型字段验收矩阵-2026-08-17.md

@@ -0,0 +1,43 @@
+# 货柜履约原型字段验收矩阵
+
+> 更新时间：2026-08-17
+> 范围：货柜、预装/装柜清单、订舱、船期、拖车、报关协同与国内出仓列表。
+> 口径：原型只提供字段与交互参考；当前确认契约、后端 DTO/OpenAPI 和已落地 Admin 优先。`UNKNOWN` 不生成假值、不改名借用其他字段，也不以空值通过验收。
+
+## 跨列表统一门禁
+
+- 操作列必须是第一业务列并固定左侧；原型中拖车、预装把操作列放在末尾的布局由当前统一表格规则覆盖。
+- `柜号/cabinetNo` 是平台稳定柜次编号，`集装箱号/containerNo` 是真实物理柜号，两者不得互换。模拟柜可以没有 `containerNo`，真实柜、完成装柜清单和国内出仓聚合必须有。
+- 客户、仓库、渠道、船公司、订舱/拖车/报关供应商名称只能来自服务端冻结快照或正式主数据，不由 fixture 自造名称。
+- ID 使用正整数；数量、重量和体积为非负数；关键时间必须可按 ISO-8601 解析；有供应商 ID 时名称必须非空，无 ID 时不得伪造名称。
+- 文件、异常、轨迹只在正式聚合提供摘要时断言；原型出现但 DTO 未提供的摘要登记为 `UNKNOWN`。
+
+## 列表逐字段矩阵
+
+| 列表 | 原型字段 | Admin 当前列 | 后端事实字段 | 真实 fixture 来源 | 结论 |
+|---|---|---|---|---|---|
+| 货柜 | 操作、集装箱号、装柜清单号、状态、异常、柜号、清关/DO/PU、车队、仓库、提单、船名航次、箱型、船公司、港口、容量、装柜/开船/到港时间 | 操作第一且左固定；柜号、订舱、集装箱号、状态、仓库、车队、提单、航线、箱型、容量、船名航次、船公司及关键时间 | `ContainerBookingEntity` 的稳定身份、来源/记录状态、客户/仓库/渠道、订舱、规格、运输及 `planId/planStatus`；overview 承载异常、单证、轨迹 | `phase3-container-loading` 本轮模拟柜合并真实订舱柜后的 ACTIVE 唯一行 | `LANDED`；清关/DO/PU、异常、轨迹摘要不在列表 DTO，见 UNKNOWN |
+| 预装清单 | 预装单号、集装箱号、柜号、客户、仓库、船名航次、箱型、状态、SKU数、总件数、体积、重量、创建时间、操作 | 操作第一且左固定；其余列与原型一致 | `PreloadSummary` 全部对应字段及 readiness/version | 同 marker 智能排货、push-preload、真实柜合并和计划级确认 | `LANDED`；“总件数”按当前契约解释为 `totalPackageCount` |
+| 装柜清单 | 操作、仓库、清单号、集装箱号、柜号、状态、总箱/毛重/净重/体积/数量、备注、创建人/时间 | 操作第一且左固定；字段与原型一致 | `ConfirmedSummary` 及 `ConfirmedDetail.items/histories` | 同一计划 PDA 完成后生成的 COMPLETED 清单 | `LANDED` |
+| 订舱 | 委托单位、主票号、放舱、MB/L 当事方、港口、箱量、船公司、截关、ETD/ATD/ATA、船名航次、订舱代理、退仓、单号、操作员、状态 | 操作第一且左固定；订舱号、客户、船公司、代理、船名航次、港口、ETD/ETA、状态、更新时间 | `OceanBookingDtos.Detail`：`oceanBooking/parties/containers/histories`，创建必填五项运输快照和逐柜 `containers[]` | `ocean-bookings` 本轮一单两真实柜，创建即 CONFIRMED，随后 RELEASED | `LANDED`；截关/ATD/ATA、退仓公司、操作员未进入当前列表，见 UNKNOWN |
+| 船期 | 原型订舱区域提供船名、航次、港口和关键时间 | 操作第一且左固定；船期号、来源、船名航次、港口、ETD/ETA、观测/更新时间、过期 | `ScheduleView.schedule+expired`，含来源、港口、ETD/ETA、截单/截关/截港、观测和过期时间 | `phase3-port-schedules` 本轮正式订舱关联观测 | `LANDED` |
+| 拖车 | 派车单号、运输公司、司机、车头号、门店、应付/应收、预计装箱、状态、附件、操作 | 操作第一且左固定；预约号、柜号、客户、运输公司、司机、车辆、门店、计划装货、状态、附件、更新时间 | `TruckAppointmentEntity` 及附件端点；订舱/柜次/计划/仓库/客户和供应商快照 | `truck-appointments` 复用同 marker 订舱详情身份并上传正式附件 | `LANDED`；附件列来自独立附件接口，不伪造实体字段 |
+| 报关协同 | 模块 13 的传统报关/清关表包含订单、客户、状态、资料与时间等历史字段 | 操作第一且左固定；报关编号、订单/入库关联、资料清单及版本、状态、更新时间 | `CustomsCaseEntity` 与聚合详情的 documents/supplements/submissions/receipts/histories | `phase3-customs` 本轮实际订单、入库、柜次及不可变清单版本 | `LANDED_WITH_OVERRIDE`：当前“报关协同”模型覆盖历史原型；客户名和文件摘要见 UNKNOWN |
+| 国内出仓 | 模块 04 为海外末端派送原型，非当前国内出仓门禁模型 | 操作第一且左固定；入库单、客户、柜号、订舱/拖车/PDA 状态、出仓状态、门禁 | `OutboundDispatchDtos.Aggregate/Detail` 的订单、入库、客户、柜次、计划、PDA、订舱、拖车、状态、版本和 gate/timeline | `phase3-outbound-dispatch` 同 marker LOADED 柜次聚合 | `LANDED_WITH_OVERRIDE`：当前确认契约优先；Admin“柜号”列实际绑定 `containerNo`，建议文案校准 |
+
+## UNKNOWN 登记
+
+| 批次 | 字段/摘要 | 当前缺口 | 验收处理 |
+|---|---|---|---|
+| U1 | 货柜列表清关、DO、PU、异常、轨迹摘要 | overview/专项详情有事实，但货柜列表 DTO 未冻结对应摘要字段 | 不向列表脚本注入假摘要；专项 overview 继续验文件下载、异常历史和轨迹 |
+| U1 | 订舱列表截关、ATD、ATA、退仓公司、操作员 | 原型存在，当前列表与 `OceanBookingDtos` 未全部公开 | 不复用 ETA/更新时间代替；待产品确认是否进入列表 |
+| U1 | 报关列表客户名称、文件/补件/回执摘要 | 实体仅有隔离键，聚合详情有文件事实，列表聚合未冻结这些摘要 | 只断言订单/入库/柜次和清单版本；待列表 DTO 冻结 |
+| U2 | 国内出仓“柜号”展示语义 | Admin 列标题为“柜号”，绑定的是物理 `containerNo` | 合同按 `containerNo` 验值；建议 Admin 文案改为“集装箱号”或同时展示 `cabinetNo` |
+| U2 | 清关列表 | 当前目的港清关走货柜 `/clearance` 专项权限/路径，没有独立、已冻结的清关列表 DTO | 继续详情级验收，不猜独立列表接口 |
+
+## 自动化接入
+
+- `fulfillment-list-field-contract.mjs` 提供八类正式响应的非空、ID、数值与时间格式投影；可选字段使用成对约束，不把 UNKNOWN 强制为必填。
+- `phase3-container-loading` 对 ACTIVE 货柜、预装清单和完成装柜清单执行字段断言。
+- `ocean-bookings`、`phase3-port-schedules`、`truck-appointments`、`phase3-customs`、`phase3-outbound-dispatch` 在既有本轮资源响应上执行字段断言，不增加历史查询或伪造回退。
+- 默认 Admin 全量入口已包含上述生产模块；真实 HTTP 仅在测试环境重新部署且当前对话明确授权后执行。

三期/货柜管理全链验收矩阵-2026-08-13.md

@@ -1,9 +1,9 @@
 # 货柜管理全链验收矩阵
 
-> 更新时间：2026-08-15  
-> 当前任务：`019ff90b-a72d-7000-abdf-e5363357a564`  
-> 父任务：`019ff600-f9f1-78f1-a357-7c80c13e574e`  
-> 依赖任务：后端主链 `019ff90b-9b45-7191-b68f-c3b52567e3e4`、动态增量后端 `01a00e91-2124-7960-95d6-e0d0f81959f9`、Admin `019ff90b-a037-79b0-b945-8f88bdbde9c5`  
+> 更新时间：2026-08-17
+> 当前任务：`019ff90b-a72d-7000-abdf-e5363357a564`
+> 父任务：`019ff600-f9f1-78f1-a357-7c80c13e574e`
+> 依赖任务：后端主链 `019ff90b-9b45-7191-b68f-c3b52567e3e4`、动态增量后端 `01a00e91-2124-7960-95d6-e0d0f81959f9`、Admin `019ff90b-a037-79b0-b945-8f88bdbde9c5`
 > 边界：只维护根目录脚本、验收文档和测试矩阵；不修改 Admin 或 Java 业务源码，不部署、不触发 Jenkins、不写测试环境数据库。
 
 ## 验收口径
@@ -13,6 +13,7 @@
 - 自动化必须通过业务 API 生成数据；人工验收必须能从 Admin/PDA 可见入口点击到对应状态。不得以数据库直写、mock、原型或前端本地假状态代替。
 - 每次真实 HTTP 验收记录请求用途、响应状态、业务码、`requestId`、`traceId`、关键资源 ID 和清理/保留策略；敏感凭据不得写入报告。
 - 柜态看板不纳入本轮。
+- 列表逐字段来源、格式门禁与 `UNKNOWN` 登记见《货柜履约原型字段验收矩阵-2026-08-17》；任何未冻结字段不得由 fixture 伪造或用其他字段代填。
 
 ## 状态数据目录
 

财务管理/openapi/finance-phase1-five-pages-v1.yaml

@@ -217,15 +217,58 @@ paths:
         '400': {$ref: '#/components/responses/BusinessError'}
         '403': {$ref: '#/components/responses/BusinessError'}
         '404': {$ref: '#/components/responses/BusinessError'}
-  /platform/finance/v1/fee-pool:
+  /platform/finance/v1/fee-sources:
     get:
       operationId: listFinanceFeeSources
-      summary: 查询客户应收应付费用来源池
+      summary: 分页查询客户应收应付费用来源
+      x-permission: platform:finance:customer-arap:list
+      parameters:
+        - name: page
+          in: query
+          schema: {type: integer, minimum: 1, default: 1}
+        - name: pageSize
+          in: query
+          schema: {type: integer, minimum: 1, maximum: 200, default: 20}
+        - name: customerId
+          in: query
+          schema: {$ref: '#/components/schemas/Id'}
+        - name: direction
+          in: query
+          schema: {$ref: '#/components/schemas/FeeDirection'}
+        - name: status
+          in: query
+          schema: {type: string, enum: [AVAILABLE, LOCKED, BILLED, VOIDED, SUPERSEDED]}
+        - name: reviewStatus
+          in: query
+          schema: {$ref: '#/components/schemas/ReviewStatus'}
+        - name: settlementIncluded
+          in: query
+          schema: {type: boolean}
+        - name: statementGenerated
+          in: query
+          schema: {type: boolean}
+        - name: businessDateFrom
+          in: query
+          schema: {type: string, format: date}
+        - name: businessDateTo
+          in: query
+          schema: {type: string, format: date}
+        - name: keyword
+          in: query
+          schema: {type: string, maxLength: 200}
+      responses:
+        '200': {$ref: '#/components/responses/FeeSourcePageResponse'}
+        '400': {$ref: '#/components/responses/BusinessError'}
+        '403': {$ref: '#/components/responses/BusinessError'}
+  /platform/finance/v1/fee-pool:
+    get:
+      operationId: listLegacyFinanceFeePool
+      summary: 查询旧版费用池（非五页事实源）
+      deprecated: true
       x-permission: platform:finance:customer-arap:list
       parameters:
         - name: customerId
           in: query
-          required: true
           schema: {$ref: '#/components/schemas/Id'}
         - name: direction
           in: query
@@ -316,7 +359,7 @@ paths:
       parameters:
         - name: customerId
           in: query
-          required: true
+          required: false
           schema: {$ref: '#/components/schemas/Id'}
       responses:
         '200': {$ref: '#/components/responses/StatementListReadResponse'}
@@ -726,7 +769,8 @@ components:
       enum: [RECEIVABLE, PAYABLE]
     FeeSourceType:
       type: string
-      enum: [INBOUND_FEE, CONTAINER_FEE]
+      minLength: 1
+      description: 来源系统定义的费用来源类型；Finance 原样保留，当前已知 INBOUND_FEE、CONTAINER_FEE，后续可接入海外仓等来源类型
     ReviewStatus:
       type: string
       enum: [PENDING, APPROVED, REJECTED]
@@ -833,10 +877,12 @@ components:
         remark: {type: string}
     FeeSource:
       type: object
-      required: [feeSourceId, sourceType, sourceFeeId, sourceVersion, direction, customerId, businessDate, feeItemName, amount, currency, reviewStatus, settlementIncluded, sourceStatus, statementGenerated]
+      required: [feeSourceId, sourceSystem, sourceType, sourceFeeId, sourceVersion, direction, customerId, businessDate, feeItemName, amount, currency, reviewStatus, settlementIncluded, sourceStatus, statementGenerated]
       properties:
         feeSourceId: {$ref: '#/components/schemas/Id'}
+        sourceSystem: {type: string, minLength: 1}
         sourceType: {$ref: '#/components/schemas/FeeSourceType'}
+        sourceBusinessId: {type: string, description: 来源系统内可展示的正式业务标识；不得用 Finance 技术主键替代}
         sourceFeeId: {$ref: '#/components/schemas/Id'}
         sourceVersion: {type: integer, minimum: 1}
         direction: {$ref: '#/components/schemas/FeeDirection'}
@@ -844,6 +890,7 @@ components:
         customerName: {type: string}
         supplierId: {$ref: '#/components/schemas/Id'}
         supplierName: {type: string}
+        orderId: {$ref: '#/components/schemas/Id'}
         inboundId: {$ref: '#/components/schemas/Id'}
         inboundCode: {type: string}
         containerId: {$ref: '#/components/schemas/Id'}
@@ -911,7 +958,7 @@ components:
         expectedVersion: {type: integer, minimum: 0}
     ReconciliationSummary:
       type: object
-      required: [statementId, statementNo, customerId, customerName, periodStart, periodEnd, creditDays, currency, totalReceivable, receivedAmount, outstandingAmount, settled, status, version, createdBy, createdAt, updatedBy, updatedAt]
+      required: [statementId, statementNo, customerId, customerName, periodStart, periodEnd, creditDays, currency, lineCount, sourceCount, sourceAmount, adjustmentAmount, totalReceivable, receivedAmount, outstandingAmount, settled, status, version, createdBy, createdAt, updatedBy, updatedAt]
       properties:
         statementId: {$ref: '#/components/schemas/Id'}
         statementNo: {type: string}
@@ -921,10 +968,17 @@ components:
         periodEnd: {type: string, format: date}
         creditDays: {type: integer, minimum: 0}
         currency: {type: string, enum: [CNY]}
+        lineCount: {type: integer, minimum: 0, description: 对账单费用明细数量}
+        sourceCount: {type: integer, minimum: 0, description: 去重后的费用来源数量}
+        sourceAmount: {$ref: '#/components/schemas/Money'}
+        adjustmentAmount: {$ref: '#/components/schemas/Money'}
         totalReceivable: {$ref: '#/components/schemas/Money'}
         receivedAmount: {$ref: '#/components/schemas/Money'}
         outstandingAmount: {$ref: '#/components/schemas/Money'}
         lastReceiptAt: {type: string, format: date-time}
+        submittedAt: {type: string, format: date-time}
+        reviewedAt: {type: string, format: date-time}
+        issuedAt: {type: string, format: date-time}
         settled: {type: boolean}
         status: {$ref: '#/components/schemas/ReconciliationStatus'}
         version: {type: integer, minimum: 0}
@@ -934,6 +988,7 @@ components:
         updatedBy: {$ref: '#/components/schemas/Id'}
         updatedByName: {type: string, description: 最后修改时操作人名称快照；历史数据可能为空}
         updatedAt: {type: string, format: date-time}
+        remark: {type: string}
     ReconciliationDetail:
       allOf:
         - $ref: '#/components/schemas/ReconciliationSummary'
@@ -952,14 +1007,23 @@ components:
               items: {$ref: '#/components/schemas/ReconciliationRevision'}
     ReconciliationLine:
       type: object
-      required: [statementLineId, feeSourceId, sourceVersion, feeItemName, sourceAmount, statementAmount, currency]
+      required: [statementLineId, feeSourceId, sourceVersion, direction, sourceType, feeItemName, sourceAmount, statementAmount, currency]
       properties:
         statementLineId: {$ref: '#/components/schemas/Id'}
         feeSourceId: {$ref: '#/components/schemas/Id'}
         sourceVersion: {type: integer, minimum: 1}
         sourceHash: {type: string}
+        direction: {type: string, enum: [RECEIVABLE, PAYABLE]}
+        sourceType: {type: string, enum: [INBOUND_FEE, CONTAINER_FEE]}
+        sourceNo: {type: string}
+        orderId: {$ref: '#/components/schemas/Id'}
         inboundId: {$ref: '#/components/schemas/Id'}
         containerId: {$ref: '#/components/schemas/Id'}
+        inboundCode: {type: string}
+        containerNo: {type: string}
+        businessDate: {type: string, format: date}
+        quantity: {$ref: '#/components/schemas/Money'}
+        unitPrice: {$ref: '#/components/schemas/Money'}
         feeItemName: {type: string}
         sourceAmount: {$ref: '#/components/schemas/Money'}
         statementAmount: {$ref: '#/components/schemas/Money'}
@@ -1435,7 +1499,7 @@ components:
           properties:
             code: {type: string, example: '200'}
             message: {type: string}
-            data: {type: array, items: {$ref: '#/components/schemas/StatementRead'}}
+            data: {type: array, items: {$ref: '#/components/schemas/ReconciliationSummary'}}
     StatementDetailReadEnvelope:
       allOf:
         - $ref: '#/components/schemas/TraceMeta'
@@ -1528,7 +1592,7 @@ components:
       description: 当前固定 DTO 客户应收应付费用池。
       content: {application/json: {schema: {$ref: '#/components/schemas/FeePoolReadEnvelope'}}}
     StatementListReadResponse:
-      description: 当前固定 DTO 客户对账单列表。
+      description: 客户对账单业务摘要列表，包含期间、金额、来源数量和流程时间。
       content: {application/json: {schema: {$ref: '#/components/schemas/StatementListReadEnvelope'}}}
     StatementDetailReadResponse:
       description: 当前固定 DTO 客户对账单详情。