From 0171c791bd3123d65fd2b4ba2e72b67861a3d737 Mon Sep 17 00:00:00 2001 From: ouyangxq <775153912@qq.com> Date: Fri, 14 Aug 2026 19:59:30 +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 --- README.md | 1 + 三期/货柜管理全链验收矩阵-2026-08-13.md | 17 ++- 首页数据看板真实化与统计策略规划.md | 151 ++++++++++++++++++++++++ 3 files changed, 168 insertions(+), 1 deletion(-) create mode 100644 首页数据看板真实化与统计策略规划.md diff --git a/README.md b/README.md index 50b3a4c..a156669 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ - [财务管理闭环盘点与范围建议](财务管理/README.md)：基于当前入库计费、财务原型和现有代码盘点财务闭环、缺口及建议的首期应收边界。 - [墨家设备测量上传接口说明 V3](墨家设备测量上传接口说明-V3.md)：墨家测量设备经 Gateway 上传箱码、尺寸、重量和图片的开放接口契约。 - [统一订单主状态与操作契约](统一订单主状态与操作契约.md)：统一订单七状态、操作编码、内部状态兼容映射，以及与三期一致的 `LOADED` 硬门禁和 `DELIVERED` 可信回传边界。 +- [首页数据看板真实化与统计策略规划](首页数据看板真实化与统计策略规划.md)：记录首页看板当前数据能力、实时/缓存边界、指标口径和后续实施顺序。 - [Admin/Client 前端原型还原验收规则](Admin-Client前端原型还原验收规则.md)：已确认原型页面的逐操作承载方式、视觉还原、响应式检查和验收证据要求。 - [数据库中文注释维护规范](数据库注释维护规范.md)：数据库注释口径、职责、迁移流程、自动门禁与实值验收要求。 - [测试环境 Jenkins 部署指南](测试环境Jenkins部署指南.md)：测试环境持续部署授权、Job 参数、执行边界、健康检查与失败处理。 diff --git a/三期/货柜管理全链验收矩阵-2026-08-13.md b/三期/货柜管理全链验收矩阵-2026-08-13.md index a4c41ba..6525c2c 100644 --- a/三期/货柜管理全链验收矩阵-2026-08-13.md +++ b/三期/货柜管理全链验收矩阵-2026-08-13.md @@ -101,7 +101,6 @@ | 阻断 | 影响 | 解除条件 | |---|---|---| -| Admin 入口与动作承载尚未由 Admin 任务回传 | 无法固定人工点击路径与 UI 断言 | Admin 任务给出路由、状态动作和构建/测试结果 | | 测试环境未获得部署授权且本任务禁止部署 | 无法验证环境是否已包含依赖实现 | 人工部署明确提交后，再执行获授权的验收轮次 | | 未提供测试环境凭据和两组隔离身份 | 无法执行跨客户/跨仓库/下载鉴权负向用例 | 由总控提供临时验收身份或既有安全注入方式 | @@ -129,3 +128,19 @@ | 双有效渠道 fixture | 跨渠道负向必须使用同一起运仓下两个真实有效渠道；只有一个有效渠道时输出 `BLOCKED_FIXTURE`，禁止派生 `-OTHER` 伪渠道 | 脚本门禁与正式渠道生产者已落地；待环境数据验证是否存在双渠道 | | 船公司与物流渠道独立 | `shippingCompanyId/shippingCompanyName` 与渠道选择分别建模，不用船公司字段代替渠道字段 | `LANDED`：Admin 与写请求模型分别承载船公司和物流渠道，静态合同已转绿 | | `CONFIRMED` 柜次继承渠道 | 订舱确认生成柜次后，货柜详情 `channelCode` 必须等于所选有效渠道；异渠道入库单不能分配到该柜次 | 既有 HTTP 断言保留；异渠道负向已移除伪渠道来源；写 DTO 不再发送服务端拥有的 `channelName` | + +## 订舱资料字段与可选客户增量 + +事实来源：原型 `prototype-src/modules/06-containers.html`、P3-Q14、`OceanBookingDtos.DraftData`、`ocean-bookings-v1.yaml`、Admin `OceanBookingDetailView.vue` 与 `OceanBookingDraftData`。 + +| 字段/链路 | 原型与阶段时序 | 自动化断言 | 当前结论 | +|---|---|---|---| +| `serviceTerm` | 原型第 516 行以 `*` 标记主要运输条款必填；P3-Q14 未删除该业务快照 | Admin 必填自由文本；Java `@NotBlank`；OpenAPI `required` 且非 nullable；模块基线和统一 SQL 均为 `NOT NULL`；不保留无来源的 `CY-DOOR/DOOR-CY/DOOR-DOOR` 自造字典；验收 fixture 使用原型展示值 `CY-CY` | `LANDED` | +| `freightTerm` | 原型第 518 行以 `*` 标记运费条款必填；示例值为 `NINGBO`，不构成枚举事实来源 | Admin 必填自由文本；Java `@NotBlank`；OpenAPI `required` 且非 nullable；模块基线和统一 SQL 均为 `NOT NULL`；不保留无来源的 `PREPAID/COLLECT` 自造字典；验收 fixture 使用原型展示值 `NINGBO` | `LANDED` | +| 可选客户 | 原型第 527 行“客户/公司名称”无必填标记；当前产品确认允许平台先建订舱后关联客户 | Admin 可清空选择；前端类型、Java DTO 与 OpenAPI 均允许 `customerId/customerName` 同时为空，单边填写必须拒绝 | `LANDED` | +| 无客户 HTTP fixture | 不以历史客户或占位 ID/名称替代可空契约 | `ocean-bookings` 使用本轮 marker、正式渠道和仓库创建无客户订舱，详情回读真实 `bookingNo` 后按订舱号查询列表，断言空客户快照、`CONFIRMED` 及稳定柜次；发布 `createdResources.oceanBookingUnassignedCustomer` | 已准备，待部署后 HTTP 验收 | +| 指定客户隔离链 | 保留来自本轮入库单的正式客户范围 | `phase3-container-loading` 与既有订舱主链继续断言客户、仓库、渠道一致和跨渠道拒绝，不借历史资源 | 已准备，待部署后 HTTP 验收 | +| 提单号、船名、航次、ETD、ETA | 原型存在相关展示/录入字段，但 P3-Q14 明确真实运输数据在 `RELEASE` 补录，阶段时序覆盖草稿直接编辑方式 | 草稿页面仅只读展示，`OceanBookingDraftData` 和保存 payload 不含五字段；确认放舱弹框与 `ReleaseRequest` 必须完整携带五字段 | `LANDED` | +| 单证号 | 原型第 529 行存在“单证号”，但当前阶段 DTO/OpenAPI 未冻结对应写字段 | 不猜字段名或复用提单号；本轮不扩展写契约 | 非本轮能力，不标记接口阻断 | + +离线合同：`ocean-booking-prototype-contract.test.mjs` 锁定原型证据、跨端可选客户、条款字段、草稿/放舱时序；`ocean-booking-fixture-contract.test.mjs` 与 `full-regression-entry-contract.test.mjs` 锁定无客户/指定客户双链和默认编排。 diff --git a/首页数据看板真实化与统计策略规划.md b/首页数据看板真实化与统计策略规划.md new file mode 100644 index 0000000..dbdd941 --- /dev/null +++ b/首页数据看板真实化与统计策略规划.md @@ -0,0 +1,151 @@ +# 首页数据看板真实化与统计策略规划 + +## 1. 文档定位 + +本文用于记录 Admin 首页数据看板从原型静态数据接入真实业务数据时的技术规划。本文是后续开发的边界和决策输入，不代表接口、缓存或预聚合已经实现。 + +适用页面：`apps/admin-web/src/modules/dashboard/`。 + +## 2. 当前状态 + +### 2.1 前端 + +当前首页仍是原型占位页面，指标、趋势、状态分布、TOP10 航线、收入构成和待办事项均由页面常量提供，页面明确标记为“静态演示数据”。当前 Dashboard 模块没有正式 API、store 或后端 DTO。 + +### 2.2 后端已有能力 + +| 领域 | 当前已有能力 | 当前查询特征 | +| --- | --- | --- | +| 订单 | 客户累计及本月已提交运单统计；订单列表和正式状态 | 请求到达时直接查询 `ord_order`，暂无平台首页聚合 | +| 货柜/在途 | 单客户在途柜量和 TEU 统计 | 直接查询货柜、订舱、装柜计划并去重 | +| 财务 | 单客户正式结算汇总 | 直接查询 `fin_settlement`；缺正式表时存在零值保护回退 | +| 客户 | 客户分页和状态查询 | 没有首页级客户活跃度聚合 | +| 清关 | 货柜和清关资料/状态业务数据 | 没有首页级待清关聚合 | +| 待办 | 各业务模块分别存在列表或待处理状态 | 没有统一待办汇总 | + +### 2.3 缓存和预聚合现状 + +当前公共配置提供 Redis，但代码中的 Redis 主要用于登录会话、Token 校验和防重放。未发现 Dashboard 业务缓存、`@Cacheable`、业务 `CacheManager`、Caffeine、指标快照表或统计定时刷新任务。 + +现有 `@Scheduled` 任务主要用于 Outbox、通知、文件、审计等投递，不属于数据看板统计机制。 + +因此，当前真实统计能力应描述为“已有部分请求时实时 SQL 聚合”，不能描述为“已有缓存统计”。 + +## 3. 目标架构 + +Dashboard 不应让浏览器循环调用客户列表、订单列表和财务列表再自行计算。建议提供一个面向页面的只读聚合接口： + +```http +GET /api/platform/v1/dashboard/overview?zoneId=Asia/Shanghai&days=30 +``` + +聚合层负责并行调用各领域的内部统计能力，不能跨服务直接 Join 其他服务数据库。响应需要返回统一的 `asOf`、各区块数据、模块状态和 `partialFailures`，让单个领域暂时不可用时其他区块仍可展示。 + +建议分层： + +```text +Admin Dashboard + | + v +Dashboard 聚合接口 + +-- Order 统计 + +-- Firstleg 货柜/清关统计 + +-- Finance 财务统计 + +-- IAM 客户统计 + +-- 待办统计 +``` + +## 4. 实时、短缓存和预聚合边界 + +### 4.1 第一阶段优先实时查询 + +以下数据需要较新状态，且可以通过时间/状态索引控制查询成本： + +- 今日新运单； +- 当前运单状态分布； +- 待清关柜量； +- 待办数量。 + +实时的定义是请求时读取业务数据库的已提交事务数据，不承诺跨服务事件已经在同一毫秒内收敛。 + +### 4.2 第一阶段短时缓存 + +以下数据变化频率较低，适合按 `platform + zoneId + days` 做 30 秒至 2 分钟的 Redis 短缓存： + +- 在途柜量和 TEU； +- 近 30 天趋势； +- 活跃客户数； +- 海运 TOP10 航线。 + +缓存必须携带生成时间和口径版本。业务状态发生重大变更时可主动删除相关 key，但不能把缓存当作业务事实源。 + +### 4.3 短缓存或定时预聚合 + +以下数据跨领域聚合成本较高，建议先短缓存；只有在查询耗时、并发或数据规模验证不满足要求时，再设计按日/按月预聚合： + +- 本月财务金额； +- 收入构成； +- 跨服务综合看板快照。 + +当前不直接引入永久指标表、数据仓库或复杂 MQ 指标链路。是否预聚合必须有实际查询耗时和并发证据。 + +## 5. 指标口径初稿 + +以下是技术实现前需要冻结的口径，不冻结前不得把原型文案直接当成正式指标： + +| 页面指标 | 建议口径 | 需要确认 | +| --- | --- | --- | +| 今日新运单 | `submittedAt` 按 `Asia/Shanghai` 自然日统计；对比昨日完整自然日 | 是，确认是否只统计 MASTER 根运单 | +| 在途柜量 | 沿用已确认的柜次去重和 TEU 规则；未知箱型单独返回 | 是，确认是否要求实际开船后才算在途 | +| 本月营收 | 必须指定应收结算、实际回款或已发布费用来源之一 | 是，未确认前不得继续使用“营收”文案 | +| 活跃客户 | 建议为近 30 天有已提交运单的去重客户数 | 是，不能用前端拉客户列表后估算 | +| 待清关 | 建议改为“待清关柜量”，统计真实柜次且清关未完成 | 是，确认“即将超期”的截止字段 | +| 30 天趋势 | 服务端按天返回完整日期序列，无数据日期补零；按运输方式聚合 | 是，确认是否拆分海运 FCL/LCL | +| 状态分布 | 使用统一订单正式状态，不沿用旧原型混合节点 | 是，确认展示映射文案 | +| TOP10 航线 | 第一版只做海运，使用稳定起运港/目的港快照并按 TEU 排序 | 是 | +| 收入构成 | 与金额卡片使用同一财务事实源和时间口径，未分类单列其他 | 是 | +| 待办 | 只返回已有业务事实和固定页面路由，不返回任意前端 URL | 是 | + +## 6. 建议响应结构 + +```json +{ + "asOf": "2026-08-14T10:00:00+08:00", + "zoneId": "Asia/Shanghai", + "metrics": {}, + "orderTrend": [], + "orderStatusDistribution": [], + "topRoutes": [], + "revenueComposition": [], + "todoSummary": [], + "partialFailures": [] +} +``` + +每个区块应能表达 `loading`、`empty`、`unavailable` 和 `forbidden`。Finance 缺表或查询异常不能静默显示为真实的零金额，应区分“真实零值”和“数据源不可用”。 + +## 7. 实施顺序 + +1. 冻结指标口径、时区、权限和 Dashboard DTO。 +2. 为 Order、Firstleg、Finance、IAM 分别补充领域内部聚合接口，保持服务数据库边界。 +3. 实现 Dashboard 聚合层，先实时查询，加入部分失败和 `asOf`。 +4. 仅对经查询耗时验证的区块增加 Redis 短缓存。 +5. Admin API/store/page 接入，删除静态常量和演示文案。 +6. 增加契约测试、聚合测试、缓存失效测试和真实只读验收。 +7. 只有性能证据显示短缓存仍不足时，才另立预聚合方案。 + +## 8. 验收要求 + +- 页面不再出现静态演示数据、演示快照或“待接入”按钮。 +- 每个区块能单独展示真实数据、空态、错误态、无权限态。 +- 响应返回 `asOf` 和统计口径版本，缓存命中不能改变数据归属。 +- 同一请求不会让前端循环调用所有客户详情接口。 +- 缓存命中、过期、主动失效和服务不可用均有可追踪日志。 +- Finance 缺表、模块超时和部分失败不能伪装成零值成功。 +- 首页真实验收保留请求、响应、业务码、`requestId`、`traceId` 和数据断言。 + +## 9. 暂不纳入 + +- 不在本规划中修改全局导航、权限初始化 SQL 或统一增量 SQL。 +- 不在没有数据规模和性能证据前新增统计数据仓库、永久快照表或复杂实时指标平台。 +- 不把原型中的旧状态名称、营收口径或超期规则直接视为正式业务契约。