From 44999e44b00fc24249b68b6b4c7b49500507b34f Mon Sep 17 00:00:00 2001 From: ouyangxq <775153912@qq.com> Date: Thu, 13 Aug 2026 12:22:36 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 三期/货柜管理全链验收矩阵-2026-08-13.md | 6 +-- 独立任务协作登记.md | 4 ++ .../openapi/finance-phase1-five-pages-v1.yaml | 41 +++++++++++++++++++ 3 files changed, 48 insertions(+), 3 deletions(-) diff --git a/三期/货柜管理全链验收矩阵-2026-08-13.md b/三期/货柜管理全链验收矩阵-2026-08-13.md index 3778c20..3b02cc6 100644 --- a/三期/货柜管理全链验收矩阵-2026-08-13.md +++ b/三期/货柜管理全链验收矩阵-2026-08-13.md @@ -71,10 +71,10 @@ | 能力标识 | 冻结路径与字段 | 权限/并发 | 状态 | |---|---|---|---| -| `container-overview` | `GET /api/platform/v1/containers/{id}/overview`；聚合 container、loadingPlanId、PDA 摘要、documents、exception/history、timeline | `platform:firstleg:container:view` | 已冻结 | +| `container-overview` | `GET /api/platform/v1/containers/{id}/overview`；聚合 container、loadingPlanId、PDA 摘要、documents、exception/history、timeline | `platform:firstleg:container:list`；旧 `container:view` 已移除 | 已冻结 | | `pda-progress-exception-summary` | PDA 任务 ID/状态/版本、明细计数、`photoCounts`、`photos`（含 fileId/status/downloadPath）及异常原因 | 随 overview 查看权限 | 已冻结 | | `container-abnormal-history` | `POST/DELETE /api/platform/v1/containers/{id}/exception`；请求使用 overview 返回的 container.version、必填原因和幂等键 | `platform:firstleg:container:edit`；版本冲突 fail-closed | 已冻结 | -| `container-documents` | 通用查询、multipart 上传和受控文件下载仅支持 DO/PU；下载透传已校验 Content-Type，非法类型回退 `application/octet-stream`，并返回 UTF-8 文件名、`no-store` 和内容长度 | 查看/下载用 container list/view，上传用 edit；下载校验柜次、类型、文件 ID 及文件服务 tenant/business 归属 | 已冻结 | +| `container-documents` | 通用查询、multipart 上传和受控文件下载仅支持 DO/PU；下载透传已校验 Content-Type，非法类型回退 `application/octet-stream`，并返回 UTF-8 文件名、`no-store` 和内容长度 | 查询/下载用 `platform:firstleg:container:list`，上传用 `platform:firstleg:container:edit`；旧 `container:view` 已移除；下载校验柜次、类型、文件 ID 及文件服务 tenant/business 归属 | 已冻结 | | `do-pu` | `DELIVERY_ORDER`、`PICKUP_ORDER` 通用查询/上传/下载 | 同 `container-documents` | 已冻结 | | `transport-trajectory-log` | overview timeline 的事件类型、详情、操作者、发生时间；服务端升序 | 随 overview 查看权限 | 已冻结 | @@ -82,7 +82,7 @@ 1. overview 与通用 documents 只覆盖 `DELIVERY_ORDER`、`PICKUP_ORDER`，不得向通用路径传清关或报关类型。 2. 目的港清关使用 `/api/platform/v1/containers/{id}/clearance` 及其专用上传、完成动作，权限为 `platform:firstleg:customs:manage`。 -3. 出口报关使用 `/api/platform/v1/first-leg/loading-lists/{planId}/customs` 及其专用上传、完成动作；查询使用 loading-list list/view，写入使用 customs manage。 +3. 出口报关使用 `/api/platform/v1/first-leg/loading-lists/{planId}/customs` 及其专用上传、完成动作；查询使用 `platform:firstleg:loading-list:list`，旧 `loading-list:view` 已移除，写入使用 `platform:firstleg:customs:manage`。 4. 清关和出口报关分别验证完成态禁止替换，不能用 DO/PU 通用上传替代。 5. 下载允许透传经校验的 Content-Type，非法值回退二进制类型；同时必须保留 UTF-8 文件名、`no-store`、内容长度及资源归属复核。 diff --git a/独立任务协作登记.md b/独立任务协作登记.md index b0a471b..ee68849 100644 --- a/独立任务协作登记.md +++ b/独立任务协作登记.md @@ -36,6 +36,10 @@ | `019ff90b-9b45-7191-b68f-c3b52567e3e4` | `019ff600-f9f1-78f1-a357-7c80c13e574e` | 货柜管理后端扩展契约 | 补齐清关报关与 DO/PU 文件查看下载、货柜异常及历史、运输轨迹日志和柜次 PDA 作业摘要的后端契约、权限、OpenAPI、SQL 与测试 | | `019ff90b-a037-79b0-b945-8f88bdbde9c5` | `019ff600-f9f1-78f1-a357-7c80c13e574e` | 货柜管理 Admin 功能补齐 | 补齐货柜与装柜清单的文件闭环、异常处理、更多操作、运输轨迹日志、PDA 摘要和必要列表字段，不含柜态看板 | | `019ff90b-a72d-7000-abdf-e5363357a564` | `019ff600-f9f1-78f1-a357-7c80c13e574e` | 货柜管理全链验收与状态数据 | 维护货柜管理全流程契约测试、真实验收脚本、各状态人工可点击数据矩阵和验收证据，不修改业务源码 | +| `019ff946-fe30-7a53-9b2d-293224f311fd` | `019ff600-e924-7902-b00e-fa1ee1658e08` | 客户详情统计-运单聚合后端 | 按已提交主运单口径提供客户累计运单与本月运单聚合契约、索引、OpenAPI 和测试 | +| `019ff947-0478-7690-998f-91b545353d06` | `019ff600-e924-7902-b00e-fa1ee1658e08` | 客户详情统计-正式应收聚合 | 基于正式应收结算模型提供客户累计应收、已收、未结清及相关派生指标契约和测试 | +| `019ff947-0c7b-7b60-9031-54201e8ca79f` | `019ff600-e924-7902-b00e-fa1ee1658e08` | 客户详情统计-在途柜量TEU | 按实际开船未到仓口径提供客户在途柜数、TEU、未知柜型聚合契约和测试 | +| `019ff947-1182-79e1-9054-ac11b70891d4` | `019ff600-e924-7902-b00e-fa1ee1658e08` | 客户详情统计-Admin接入与全量验收 | 接入运单、应收和在途柜量三项统计，按原型实现客户详情卡片、权限状态、前端测试与全量验收脚本 | ## 规则 diff --git a/财务管理/openapi/finance-phase1-five-pages-v1.yaml b/财务管理/openapi/finance-phase1-five-pages-v1.yaml index ada1888..772f85d 100644 --- a/财务管理/openapi/finance-phase1-five-pages-v1.yaml +++ b/财务管理/openapi/finance-phase1-five-pages-v1.yaml @@ -130,6 +130,22 @@ paths: responses: '200': {$ref: '#/components/responses/CustomerAccountReadResponse'} '404': {$ref: '#/components/responses/BusinessError'} + /platform/finance/v1/customer-accounts/{customerId}/summary: + get: + operationId: getCustomerAccountSummary + summary: 查询客户正式结算口径财务汇总 + description: >- + 固定 CNY。累计应收、已收和未结清仅聚合本客户非 VOIDED 的正式 RECEIVABLE + fin_settlement；待出账仅聚合合格且尚未进入非 VOIDED 对账单的应收费用来源； + 未结应付仅聚合本客户非 VOIDED 的正式 PAYABLE fin_settlement。 + x-permission: platform:finance:customer-account:list + x-customer-isolation: 所有聚合子查询都必须使用 customerId 约束，空客户返回零值。 + parameters: + - $ref: '#/components/parameters/CustomerId' + responses: + '200': {$ref: '#/components/responses/CustomerAccountSummaryResponse'} + '400': {$ref: '#/components/responses/BusinessError'} + '403': {$ref: '#/components/responses/BusinessError'} /platform/finance/v1/accounts/{customerId}/ledger: get: operationId: listDerivedCustomerAccountLedger @@ -687,6 +703,19 @@ components: entries: type: array items: {$ref: '#/components/schemas/AccountEntryRead'} + CustomerAccountSummary: + type: object + required: [customerId, currency, totalReceivable, receivedAmount, outstandingReceivable, pendingBilling, outstandingPayable, asOf, lastChangedAt] + properties: + customerId: {$ref: '#/components/schemas/Id'} + currency: {type: string, enum: [CNY]} + totalReceivable: {$ref: '#/components/schemas/Money'} + receivedAmount: {$ref: '#/components/schemas/Money'} + outstandingReceivable: {$ref: '#/components/schemas/Money'} + pendingBilling: {$ref: '#/components/schemas/Money'} + outstandingPayable: {$ref: '#/components/schemas/Money'} + asOf: {type: string, format: date-time} + lastChangedAt: {type: string, format: date-time} AccountEntryRead: type: object required: [entryType, resourceId, resourceNo, occurredAt, debitAmount, creditAmount, currency, status] @@ -1277,6 +1306,15 @@ components: code: {type: string, example: '200'} message: {type: string} data: {$ref: '#/components/schemas/CustomerAccountRead'} + CustomerAccountSummaryEnvelope: + allOf: + - $ref: '#/components/schemas/TraceMeta' + - type: object + required: [code, message, data] + properties: + code: {type: string, example: '200'} + message: {type: string} + data: {$ref: '#/components/schemas/CustomerAccountSummary'} FeePoolReadEnvelope: allOf: - $ref: '#/components/schemas/TraceMeta' @@ -1380,6 +1418,9 @@ components: CustomerAccountReadResponse: description: 当前固定 DTO 客户账户及流水。 content: {application/json: {schema: {$ref: '#/components/schemas/CustomerAccountReadEnvelope'}}} + CustomerAccountSummaryResponse: + description: 客户正式结算口径财务汇总。 + content: {application/json: {schema: {$ref: '#/components/schemas/CustomerAccountSummaryEnvelope'}}} FeePoolReadResponse: description: 当前固定 DTO 客户应收应付费用池。 content: {application/json: {schema: {$ref: '#/components/schemas/FeePoolReadEnvelope'}}}