diff --git a/三期/货柜履约原型字段验收矩阵-2026-08-17.md b/三期/货柜履约原型字段验收矩阵-2026-08-17.md new file mode 100644 index 0000000..e5c870f --- /dev/null +++ b/三期/货柜履约原型字段验收矩阵-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 仅在测试环境重新部署且当前对话明确授权后执行。 diff --git a/三期/货柜管理全链验收矩阵-2026-08-13.md b/三期/货柜管理全链验收矩阵-2026-08-13.md index 2e1dea6..cd7e61d 100644 --- a/三期/货柜管理全链验收矩阵-2026-08-13.md +++ b/三期/货柜管理全链验收矩阵-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 伪造或用其他字段代填。 ## 状态数据目录 diff --git a/财务管理/openapi/finance-phase1-five-pages-v1.yaml b/财务管理/openapi/finance-phase1-five-pages-v1.yaml index 52f6e78..d1aad5f 100644 --- a/财务管理/openapi/finance-phase1-five-pages-v1.yaml +++ b/财务管理/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 客户对账单详情。