优化

三期/货柜管理全链验收矩阵-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`、内容长度及资源归属复核。
 

独立任务协作登记.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接入与全量验收 | 接入运单、应收和在途柜量三项统计，按原型实现客户详情卡片、权限状态、前端测试与全量验收脚本 |
 
 ## 规则
 

财务管理/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'}}}