优化
This commit is contained in:
@@ -14,6 +14,7 @@
|
||||
- [财务管理闭环盘点与范围建议](财务管理/README.md)：基于当前入库计费、财务原型和现有代码盘点财务闭环、缺口及建议的首期应收边界。
|
||||
- [墨家设备测量上传接口说明 V3](墨家设备测量上传接口说明-V3.md)：墨家测量设备经 Gateway 上传箱码、尺寸、重量和图片的开放接口契约。
|
||||
- [统一订单主状态与操作契约](统一订单主状态与操作契约.md)：统一订单七状态、操作编码、内部状态兼容映射，以及与三期一致的 `LOADED` 硬门禁和 `DELIVERED` 可信回传边界。
|
||||
- [首页数据看板真实化与统计策略规划](首页数据看板真实化与统计策略规划.md)：记录首页看板当前数据能力、实时/缓存边界、指标口径和后续实施顺序。
|
||||
- [Admin/Client 前端原型还原验收规则](Admin-Client前端原型还原验收规则.md)：已确认原型页面的逐操作承载方式、视觉还原、响应式检查和验收证据要求。
|
||||
- [数据库中文注释维护规范](数据库注释维护规范.md)：数据库注释口径、职责、迁移流程、自动门禁与实值验收要求。
|
||||
- [测试环境 Jenkins 部署指南](测试环境Jenkins部署指南.md)：测试环境持续部署授权、Job 参数、执行边界、健康检查与失败处理。
|
||||
|
||||
@@ -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` 锁定无客户/指定客户双链和默认编排。
|
||||
|
||||
@@ -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。
|
||||
- 不在没有数据规模和性能证据前新增统计数据仓库、永久快照表或复杂实时指标平台。
|
||||
- 不把原型中的旧状态名称、营收口径或超期规则直接视为正式业务契约。
|
||||
Reference in New Issue
Block a user