218 lines
28 KiB
Markdown
218 lines
28 KiB
Markdown
# 首页运营数据整改方案与 UI V1
|
||
|
||
## 2026-09-17 实施规格（优先于下方设计历史）
|
||
|
||
用户已授权实施、提交及推送；不部署。采用V2一行三块紧凑布局，营业区标题“今日营业状况”。保留今日企业消费排行原排序、余额、详情和导出入口，在消费后增加“今日返还金额（元）”列，详情/导出同步包含返还。此前“不增返还列”被本次要求替代。
|
||
|
||
实现将三个逻辑投影合为业务消息版本事实 `HomeMessageFact`：包含原提交日、有效回执日集合、唯一成功日及金额快照；用 `HomeProjectionState`、`HomeProjectionDirty` 和 `HomeSnapshot` 保存游标、耐久工作及发布版本。源表事务触发器仅登记待投影消息，不改发送/账务；投影按500条批次，事务级 advisory lock 和工作行锁认领，事实版本和工作删除同事务，进程故障整批回滚。旧版本事实按有效版本区间保留供快照读取；完成初始化前不发布，增量积压显示处理状态。源变化触发耐久重算，消除只用updatedAt水位漏掉晚提交事务的风险。API快照绑定平台用户与日期，15分钟有效，明细只在点击后聚合。
|
||
|
||
当前权限模型只有平台管理员/企业管理员，未发现独立财务角色；本次在全部新接口重新校验平台管理员角色及有效用户，不新增角色体系。客户端会话不能调用。钱使用整数万分之一元，服务层越出JS安全整数范围明确报错，不静默舍入。原排行只列未删除企业，返还列遵循同一企业范围；不再另设平台返还总额，保持现有排行语义。
|
||
|
||
新增统计表/触发器随迁移创建，开关 `HOME_DASHBOARD_ENABLED=false` 可暂停后台投影；页面首次无可读快照提示初始化中，保留重试入口。只在API进程后台消费；测试通过显式调用投影方法控制进度，不启动短信消费者。错误写入投影状态并记录日志，旧已发布版本可读并提示数据滞后。数据库回退保留统计资产，不回写原账務。
|
||
|
||
> **2026-09-17 用户修订：以UI V2为当前版本。** 顶部“今日业务”“今日回执”“今日营业状况”改为一行三块紧凑布局，整体占用压缩至V1约三分之一；“今日回执收益”更名为“今日营业状况”。**今日企业消费排行保持原样**：排名、企业名称、今日消费（元）、可用余额、余额状态、查看详情及导出排行保留，不替换为返还区域、不增返还列。运营状态保留。下文V1关于替换消费排行、返还区域及三排大卡布局的描述已被本修订替代；其他统计规则和按需查询保持。当前[UI V2](designs/homepage-20260917/homepage-v2.png)，[修订提示词](designs/homepage-20260917/prompt-v2.txt)。仅改设计，未改业务代码。
|
||
|
||
日期：2026-09-17。状态：**设计稿，待实施**。本轮交付方案及效果图，不修改业务代码，不提交、推送或部署。
|
||
|
||
## 1. 范围与现状证据
|
||
|
||
适用运营端首页，不改变客户端首页、计费动作、供应商协议、短信发送或补发规则。实现涉及运营查询、回执统计事实及首页展示；如需增加投影表及索引，按迁移执行，不能直接在线补写业务状态。
|
||
|
||
核验本地 main：`627fa7ec97a656731244f5d1a7fa93b27806cd16`；实际远端 main：`4eb7b16d122da14f921093716d4ca1ed390d9e4c`，本地领先两次提交，暂存区为空。已有版本、metrics、发布工具、部署脚本和文档草稿继续保护。本轮未连接目标环境或查询线上数据库，以下是当前源码证据，不能视为线上字段覆盖率证明。
|
||
|
||
| 当前实现 | 与本次要求的差异 |
|
||
| --- | --- |
|
||
| [首页](../src/apps/admin/AdminHome.tsx)同时请求 dashboard 和 sendQuality，显示10项指标、发送趋势、审核速度、消费排行、运营状态 | 改为9项主指标、返还区域、运营状态；删除无需展示的数据及对应首页请求 |
|
||
| [dashboard查询](../api/src/operations/queries/dashboard.queries.ts)按 `SmsMessageRecord.queuedAt` 限定今日业务短信 | 收到回执的当天和原提交日期必须分开，不可继续用今日提交条件过滤所有指标 |
|
||
| 总体成功率为今日业务消息 `status=delivered` 数量 / 今日业务消息总量，保留1位小数，零分母为0 | 按用户要求保持现有口径，不改为分片成功率或全历史成功率 |
|
||
| 分片成功直接统计 `SmsMessageSegmentAudit` 成功行数 | 部分成功、跨尝试重复及缺片不满足本次业务短信整体成功口径 |
|
||
| 今日计收按今日提交且最终成功消息的 `billingUnits × unitPrice`；成本按 accepted 尝试成功分片和成本快照统计 | 新收益按今日完整成功回执归属，需要跨提交日统计并防止重复确认收入 |
|
||
| `clientDashboard()`复用旧 `dashboard()` | 不宜原地破坏旧接口；运营首页另建明确契约，客户端继续保持原行为 |
|
||
|
||
设计入口：[设计开发规范](design-development-guidelines.md)、[UI规范](ui-design-guidelines.md)、[CSS规范](css-development-guidelines.md)、[测试计划](testing-plan.md)。此方案实施后，替代运营首页旧的10指标顺序、到达率、活跃签名、消费/计收卡、两张趋势图及消费排行展示；不替代其他页面、历史测试记录和底层账务规则。与[签名质量方案](signature-quality-optimization-plan-20260917.md)共用时间/长短信约定，但不能直接复用按提交日生成的签名日报来冒充今日回执数据。
|
||
|
||
## 2. 首页信息结构
|
||
|
||
| 区域 | 保留内容 | 交互 |
|
||
| --- | --- | --- |
|
||
| 今日业务 | 今日业务短信数量、今日发送成功数量、总体成功率 | 3列，单位为条、条、% |
|
||
| 今日回执 | 今日回执分片总数、今日回执成功分片数、今日回执成功率 | 成功分片数以绿色和较大字号突出；“按提交日查看”按需展开 |
|
||
| 今日回执收益 | 今日营收金额、今日利润、今日利润率 | 单位元、元、%；独立的“按提交日查看” |
|
||
| 今日返还金额 | 今日返还总额，企业返还明细入口 | 暂按替换整个消费排行区域设计，不保留消费、余额和排行列；这是第6点的设计解释，待用户反馈可局部调整 |
|
||
| 运营状态 | 原企业认证待审、短信审核待审、模板待审、签名待审、引流信息待审、平均等待、下游投递告警 | 保留原入口和统计，不借本次任务修改规则 |
|
||
|
||
代码中“平均等待”实际上显示批量任务总数，本次按“运营状态保留”维持，同时显示“批量任务总数”说明；这是已发现的命名遗留问题，不冒称等待时长。
|
||
|
||
删除今日消息分片数、今日到达率、今日活跃签名、今日消费、今日计收等旧卡，以及今日发送趋势、审核处理速度。首页不再为了活跃签名调用全量发送质量查询。全局导航、通知、权限保留；图中导航只示意，实施不删实际菜单。
|
||
|
||
## 3. 时间、去重与分片口径
|
||
|
||
### 3.1 三个不同的时间
|
||
|
||
- T为服务器当前上海自然日，所有窗口使用 `[当日00:00, 次日00:00)`，统一 `Asia/Shanghai`，不是滚动24/72小时。
|
||
- 原提交日期沿用旧“发送总量”的 `SmsMessageRecord.queuedAt`，即业务短信进入平台的日期；不以补发时间、最新 `submittedAt` 或供应商 Submit 日期重新归组。
|
||
- 回执日期优先取 `UpstreamReceiptInbox.gatewayReceivedAt`。当前 [Gateway](../gateway/internal/upstream/deliver.go)生产事件的 `DeliveredAt` 为网关当时 `time.Now().UTC()`，[intake](../api/src/send-chain/send-receipt.service.ts)将其原样存入 `gatewayReceivedAt`。不能仅凭字段名把它当运营商实际送达时刻，也不能用业务记录 `updatedAt` 代替接收时间。
|
||
- Inbox `receivedAt` 是API持久接收时间；`SmsReceiptRecord.createdAt` 是后续处理入库时间。发生积压或跨午夜处理时，二者不一定是网关接收日。旧记录缺网关时间时允许显式标注 `timeSource=inbox_received/legacy_created` 的近似兼容，不混称精确；无可靠关联/时间记录列入覆盖缺口。正式上线前只读核验各入口和历史覆盖率，不能静默默认0。
|
||
- 同一响应带 `businessDate`、`asOf`、`dataThrough`、`timeSourceCoverage`、`definitionVersion`。`asOf` 是查询快照时刻，`dataThrough` 才是已处理到的进度，不能将二者混淆。
|
||
|
||
### 3.2 总数：计的是业务分片当量，不是原始回执包数
|
||
|
||
先选择：原提交日期位于 T-3～T、在T收到至少一次**新的、有效关联到该业务消息的回执**。按 `messageRecordId` 去重，一条业务短信在同一天只贡献一次分母，不按手机号、通道、供应商 Msg_Id 或发送尝试计多次。
|
||
|
||
每条业务短信贡献的分片数 N 使用其冻结的 `SmsMessageRecord.billingUnits`。这是业务短信计费分片单位，与“业务短信维度去重”的要求一致，不能求和多次补发的分片。`SmsMessageSegmentAudit.segmentTotal`、`segmentIndex` 用于核对对应发送尝试的物理分段和完整性，不能用收到的行数替代预期总量。若不同通道实际分片数不同，首页保持业务分片当量N，成本按该尝试真实分片；两者不要混用。
|
||
|
||
历史 N 无效或与证据明显矛盾时，按真实发送时的分段记录核对并登记缺口，不能用当前正文重新分片后伪装历史事实。正常 N=3 的长短信，即使只回一个失败片，分母也加3；无需伪造剩余2片的原始回执或修改业务状态。界面说明为“按业务短信去重，包含应计未回分片”。
|
||
|
||
### 3.3 成功：整条业务短信完成成功后才计入
|
||
|
||
某条业务短信首次形成可信的整条成功结论，且其形成成功结论所需的最后一条有效回执于T被网关收到，才在T贡献N个成功分片。成功判定沿用可靠的发送尝试级收尾结果，并核对该成功尝试的全部预期分段；不能跨通道/尝试拼接成功片，不能因为 `message.status` 当前成功就把它计到每个曾收到回执的日期。
|
||
|
||
- 3片中2成功1失败，或2成功1未回：成功分片为0。
|
||
- 昨天2片成功，今天最后1片成功：今天分母3、成功3；昨天不因今天成功而补增“昨天成功分片”。
|
||
- 通道约定整条回执 `message_level`：仅在现有明确协议及 `supplier_message_level_receipt` 补偿证据支持整条成功时计N；普通分片通道单条成功不得推断其余成功。
|
||
- 首次失败后补发全成功：同一天分母只计N，成功也只计N；客户收入只确认一次。采用既有有效收尾结果，不由统计代码触发补发。
|
||
- 输送重放、同一分片相同状态重复包应全局幂等去重，不能因重新入库或重试跨日再次贡献分母。需结合原事件键、尝试、分段和状态迁移，不能只依赖含不同接收时刻的包键。
|
||
- 已最终成功后，无效的旧尝试迟到失败、重复成功只作审计，不再增加业务回执数量或撤回历史收入；真实冲突交由既有异常处理机制，禁止统计模块自行决定业务终态。
|
||
|
||
“有新有效回执的日分母”允许一条跨日长短信在两个不同接收日分别进入分母，因此**各天分母不能相加称为不重复短信总量**。成功及收入只在首次形成整条成功的接收日确认一次。页面今日比率 = 今日成功分片 / 今日总分片，禁止超过100%；零分母显示0%，提示“今日暂无有效回执”。这是对跨日未回齐场景的明确建议规则，实施测试必须覆盖。
|
||
|
||
## 4. 九项指标及财务规则
|
||
|
||
| 指标 | 计算 |
|
||
| --- | --- |
|
||
| 今日业务短信数量 | `queuedAt` 属于T的唯一业务短信数量，沿用旧 `today.sent` |
|
||
| 今日发送成功数量 | 上述消息中，首次整条成功的回执接收日也为T的消息数；不是分片数 |
|
||
| 总体成功率 | 保持旧 `today.successRate`：今日业务消息当前 `status=delivered` / 今日业务消息总数，不改精度与零分母规则 |
|
||
| 今日回执分片总数 | 第3节今日有效回执消息集合的N之和，仅T-3～T提交 |
|
||
| 今日回执成功分片数 | 第3节今日首次整条成功集合的N之和，仅T-3～T提交 |
|
||
| 今日回执成功率 | 成功分片数 / 回执分片总数 ×100% |
|
||
| 今日营收金额 | 今日首次整条成功集合的 `billingUnits × unitPrice` 快照之和；只计一次，不取充值、不按现行应用单价重算 |
|
||
| 今日利润 | 上述成功消息收入减其对应已发生通道计费成本，包括该消息此前尝试已产生的计费成本，不因只看最后成功尝试漏成本 |
|
||
| 今日利润率 | 今日利润 / 今日营收 ×100%；营收为0时显示0%及无营收说明，负利润正常显示负数 |
|
||
|
||
成本兼容现有“成功分片计费”口径：同一业务消息下所有 accepted 尝试，按各自成功的唯一物理分片乘其 `SmsSubmitRecord.costUnitPrice` 快照；失败尝试中已成功且需要付费的片也计入成本。`costAmountCents` 不能未核验语义就当最终结算金额；不能以客户N乘最后一次通道价概括多次尝试。缺审计的旧尝试，只能按明确关联的整条成功回执及可证明的分片数兼容，不以相同供应商ID跨通道串联。
|
||
|
||
本区是**今日成功回执对应的短信毛利**，不是公司净利润，也不是今日账户现金流；不包括尚未整体成功的其他业务短信亏损。若实际通道存在按提交收费等不同结算规则，应复用已有真实成本事实并扩大相关验收，不擅自修改结算方式。后续发现成功消息有额外真实费用，应有可追溯的更正版本，不能重复确认收入或无记录覆盖冻结成本。
|
||
|
||
金额内部用整数万分之一元（虽字段名为Cents，实际1元=10000单位），API使用十进制字符串或既有有界安全金额契约，禁止浮点累计；展示复用 `MoneyText/formatAmount` 最多4位、去尾零。比例在汇总后计算，不平均各行比例。
|
||
|
||
### 今日返还金额
|
||
|
||
沿用真实 `AccountTransaction` 返还语义：`refunded`，以及 `released AND relatedType=sms_message_record`，追加严格的今日上界与租户权限条件。按唯一流水统计，不同时再叠加账单状态推算退款；若同一业务退款与解冻代表两笔实际不同资金动作，以账务证据为准，不按消息ID盲目去掉一笔。
|
||
|
||
返还依今日流水日期，**不限制原短信必须在最近4天提交**；不将历史返还移到今天。总额与明细分别按相同过滤规则读取。移除消费排行后拟展示企业名称、今日返还金额及返还流水入口；企业归档/删除不得使实际返还从平台总额消失，名称使用可追溯快照或历史企业标记。保留“返还”称谓，避免把解冻全部称作已扣费退款。该模块不重复扣减成功回执营收。
|
||
|
||
## 5. 按需展开与文案
|
||
|
||
两个按钮相互独立。首次进入不请求、不预取、不后台生成这两组按提交日期的响应数据；点击才查。主卡总值仍需聚合，同源总值不等于提前查询并隐藏四行明细。
|
||
|
||
回执展开标题：**今日回执 · 按原提交日期查看**。说明：“以下只统计今天收到的回执，按短信最初提交日期分组。”
|
||
|
||
| 原提交日期 | 今日回执分片总数 | 今日回执成功分片数 | 今日回执成功率 |
|
||
| --- | ---: | ---: | ---: |
|
||
| 09-17 提交 → 今日回执（T） | 180000 | 162000 | 90.0% |
|
||
| 09-16 提交 → 今日回执（T-1） | 40000 | 36000 | 90.0% |
|
||
| 09-15 提交 → 今日回执（T-2） | 15000 | 13500 | 90.0% |
|
||
| 09-14 提交 → 今日回执（T-3） | 5000 | 4500 | 90.0% |
|
||
|
||
收益展开标题：**今日回执收益 · 按原提交日期查看**。说明：“以下是这些批次今天成功回执带来的收益，不是对应提交日的全天营业额。”
|
||
|
||
| 原提交日期 | 今日回执归属营收 | 今日回执归属利润 | 对应利润率 |
|
||
| --- | ---: | ---: | ---: |
|
||
| 09-17 提交 → 今日成功回执（T） | ¥8100 | ¥1620 | 20.0% |
|
||
| 09-16 提交 → 今日成功回执（T-1） | ¥1800 | ¥360 | 20.0% |
|
||
| 09-15 提交 → 今日成功回执（T-2） | ¥675 | ¥135 | 20.0% |
|
||
| 09-14 提交 → 今日成功回执（T-3） | ¥225 | ¥45 | 20.0% |
|
||
|
||
以上均为示例，与图中总数一致。每表4行、每行3指标，共12数据，不新增其他指标；分母和金额各行合计应等于同一快照主卡。比例依总分子/总分母计算。T-4及以前不混入这两个模块。
|
||
|
||
默认收起，展开处分别有加载、空态、失败重试与显式收起按钮。一次请求失败不清空其他区域；成功缓存限当前会话内存，保留时间标签，刷新失败展示“上次成功数据，更新失败”，不能回退假数据。跨午夜将旧数标为昨日，重新取当天总值；已收起明细失效但不发请求。页面刷新重新收起；快速点击去重在途请求，离开页面取消/忽略旧响应。
|
||
|
||
## 6. 建议实现
|
||
|
||
### 6.1 API与一致性
|
||
|
||
建议新增运营专用 `GET /operations/home/summary`、`GET /operations/home/receipt-breakdown`、`GET /operations/home/revenue-breakdown`，路径在实现时按既有控制器风格落地；不改变旧 dashboard/clientDashboard。总览只返回本页需要的三个汇总组、返还和运营状态。两个明细接口一次返回4行，不循环发4个请求。
|
||
|
||
明细请求携带总览签发的 `snapshotToken`；token绑定服务端日期、投影版本、数据截止时间、查询租户范围及权限，不接受前端任意扩大租户。主卡聚合及延迟查询都读同一发布版本；版本失效返回明确刷新要求，先刷新主卡再查明细，避免不同时间查询后四行与卡片不一致。不能只传 `asOf` 却查询可变的当前终态。
|
||
|
||
认证和运营财务权限分别校验；无财务权限返回不可见状态，不返回金额并仅前端隐藏。匿名401、越权403、非法日期/token400或明确失效状态；响应不暴露号码、短信内容、凭据。客户端不能通过复用接口取得其他企业数据。
|
||
|
||
### 6.2 耐久统计事实与性能
|
||
|
||
现有表足以找到原始字段，但缺少专门表达“某日首次形成完整成功及其金额版本”的稳定首页事实。建议增加只读用途的投影，而不是每次首页扫描全部历史发送/回执并依当前状态推断历史。
|
||
|
||
建议逻辑模型（均为待新增，不是当前已存在功能）：
|
||
|
||
1. `HomeReceiptMessageDay`：接收日期、业务消息ID、原提交日期、租户、N快照、首次有效事件、成功认定事件、接收时间来源、revision；唯一键为接收日+业务消息ID。
|
||
2. `HomeMessageSuccessFact`：业务消息ID唯一、成功尝试ID、完成成功所需最后回执接收时间、收入/成本快照及更正版本；解决跨日收入一次确认。
|
||
3. `HomeProjectionRun/Version`：发布版本、截止游标、覆盖缺口、租约/fence/失败状态。分批投影更新先写不可变版本或版本化事实，完整提交后原子发布；保留页面token有效期覆盖的版本，不能用单行可变upsert假冒一致快照。
|
||
|
||
消费既有持久回执/收尾事件增量生成事实，按业务消息串行化或revision比较，事务中写事实与消费游标。崩溃重试不重复计入；并发worker需要租约/fence；成功事实必须在整条收尾提交后才能发布。投影消费者只写统计表，不发送短信、不改变收尾、账务、通知行为。乱序先按事件时间和可靠收尾结果重建该业务消息，不能直接累加包数。
|
||
|
||
迟到处理保持原网关接收日，源事件先到而发送关联后到需可重试；pending/unmatched、缺时间、缺分段不能静默当0。汇总元数据提示“统计处理中/部分数据待核对”，不额外增加用户未要求的首页业务KPI。
|
||
|
||
建议索引以真实EXPLAIN决定：Inbox网关接收时间+状态+关联消息，消息queuedAt范围，投影接收日+租户+原提交日，成功事实唯一业务消息与接收日。现有Inbox按receivedAt索引不等于按gatewayReceivedAt过滤可直接高效命中。避免OR大范围扫描，旧时间来源分支可UNION ALL后去重。生产建索引需评估写放大与并发索引迁移，不未经现场测量宣称提速。
|
||
|
||
默认总值和两个展开分别缓存、按日期/租户/定义版本隔离；投影可以生成业务事实，但不得预执行四行明细聚合。初步目标为代表性四日数据下首页API p95≤1秒、展开p95≤1秒，具体SLA以真实数据基线确定；测试同时记录CPU、扫描行数、内存、队列延迟，不只报告一个平均耗时。
|
||
|
||
### 6.3 历史与恢复
|
||
|
||
上线前先只读核验4日范围内时间字段覆盖、分段/计费单位差异、协议整条回执比例和补发成本，再使用分页、限流、可暂停的投影补建。无历史完整证据须标注覆盖缺口，不追造网关时间或假装完整成功。用旧/新查询影子对账解释差异，不能要求新口径总值强行等于旧口径。
|
||
|
||
新增表为可重建统计资产，原始收尾、Inbox及账务不可改写。功能开关默认保持旧首页，迁移与补建完整验收后切换；回退只回退读路径并保留投影，不删数据、不回滚客户账务。发布、补建执行及真实短信验收遵循独立授权。
|
||
|
||
## 7. UI设计稿与适配
|
||
|
||
|
||
|
||
图为默认收起状态。白色侧栏、浅灰底、三组横向指标；成功回执使用浅绿背景和绿色数字，其余金额沿用普通深色，负利润用红色。金额不采用整数/小数两种字号。页头显示上海日期、刷新入口与数据截止提示；设计图示例标识只用于设计交付，不作为上线UI固定文案。
|
||
|
||
实施复用现有Breadcrumb、Button、Table、MoneyText及原AppShell；页面CSS仅归 `AdminHome.css` 且限定页面根类。图中间距/字体为视觉意向，实施严格采用现有字号、8px圆角及248px侧栏规范。1600×1000三列；1366×768允许内容纵向滚动；390×844侧栏折叠、指标单列、两张明细表各自横向滚动，不允许整个页面横向溢出。
|
||
|
||
生成方式：内置imagegen，主提示词见 [UI提示词](designs/homepage-20260917/prompt.txt)。本轮仅视觉设计审阅，不是浏览器或真实API验收。
|
||
|
||
## 8. 实施顺序、验证与交付边界
|
||
|
||
1. 字段覆盖和真实四日数据只读基线；确认旧成本与通道协议事实。
|
||
2. 时间/去重/完整成功纯规则及投影迁移、恢复机制；真实PG校验后再接查询。
|
||
3. 运营专用API与快照token，四日数据独立对账；客户端回归。
|
||
4. 首页9项指标、返还区域、两个按需展开；删除多余查询，保留运营状态。
|
||
5. 真实后端页面三尺寸与网络断言、定向及全量回归、类型/生产构建/格式/样式/安全等现有门禁；如改Gateway，补Go测试和vet。
|
||
|
||
验证成本主要在跨日长短信、重复/补发、价格快照、迟到与故障恢复，而不是卡片布局。实现需完整覆盖下列验收，并同步需求/测试进度；发送/补发测试须另有明确环境、数据和负载授权，本方案本身不授权触发短信。
|
||
|
||
| 用例 | 待验证预期 |
|
||
| --- | --- |
|
||
| HOME0917-01 | T短信、T-1～T-3短信的今日回执纳入；T-4排除；北京时间午夜边界正确 |
|
||
| HOME0917-02 | 3片仅一个失败回执：总3、成功0；2成功1未回仍成功0 |
|
||
| HOME0917-03 | 全3片成功才成功3；message_level有协议证据才计整条成功；不同尝试不得拼片 |
|
||
| HOME0917-04 | 同日重复包/乱序/重放/补发按业务去重；只确认一次成功和收入 |
|
||
| HOME0917-05 | 昨日2成功、今日末片成功，今日计总3成功3，昨日成功不追增；已成功后的重复包不再计入 |
|
||
| HOME0917-06 | 网关23:59接收、API次日处理仍归原接收日；缺时间字段显示覆盖说明 |
|
||
| HOME0917-07 | 今日发送成功限今日提交且今日形成成功；总体成功率旧公式保持 |
|
||
| HOME0917-08 | 收入使用历史价格，成本包含对应消息之前尝试已计费成功片；多通道成本、负利润、零营收、万分之一元精度正确 |
|
||
| HOME0917-09 | 返还按今日唯一流水，与企业明细汇总一致；历史提交退款可纳入，已删除企业不漏账 |
|
||
| HOME0917-10 | 首屏零明细请求；单击仅请求所属组，四行12值，同一版本与总卡勾稽；缓存/快速点击/午夜失效正确 |
|
||
| HOME0917-11 | API错误保留带时标的真实旧值，首次失败不显示假0；登录和财务/租户权限隔离 |
|
||
| HOME0917-12 | 投影并发、崩溃、重试、过期worker、乱序与补建完整性；发布半成品不可见，token过期不混版本 |
|
||
| HOME0917-13 | 三尺寸、刷新/跨路由、展开表格、键盘焦点、空态/失败及控制台；删除旧模块但保留运营状态和客户端行为 |
|
||
| HOME0917-14 | 代表性数据EXPLAIN、p50/p95、CPU/内存与队列影响；索引/迁移/回退只读路径验证 |
|
||
|
||
当前完成：代码字段核查、规则方案、UI图和文档一致性检查。未完成：业务代码、迁移、真实API/PG验收、浏览器三尺寸、性能基线、提交、推送、测试部署及预生产部署。
|
||
|
||
|
||
## 9. 2026-09-17 实施与验收结果
|
||
|
||
当前实现已完成V2紧凑三栏、9指标及独立按需明细；保留原企业消费排行，新增今日返还金额列，详情和CSV同步。入口为运营专用 `/admin/operations/home/*`，客户端旧dashboard不变。四个投影表、两项迁移、源变化事务触发器和500条批次投影已实现；重关联同步失效新旧消息，版本事实/消费确认同事务。首次未就绪返回初始化状态，增量/未匹配回执/失败/时间近似均明确提示。已使用快照绑定用户、日期和15分钟期限；总览创建与版本回收通过数据库读写锁协调，明细读取不可变版本。仅过期首页快照和不被活跃快照使用的投影版本限量回收，源短信/回执/账务不删除。
|
||
|
||
实际截图：[桌面完整页面](designs/homepage-20260917/homepage-implemented.png)、[营业明细展开](designs/homepage-20260917/homepage-implemented-expanded.png)、[窄屏](designs/homepage-20260917/homepage-implemented-mobile.png)。来自本机真实Nest API、独立PostgreSQL16与隔离Redis中的验收数据，不是设计图或线上数据。Browser插件技能未提供，按既有授权使用Edge/Playwright。三尺寸1600×1000、1366×768、390×844及1600×1120完整截图通过；首次无明细请求、不调用旧dashboard/send-quality；分别点击才加载、刷新收起、错误保留真值、详情及含返还列CSV通过，页面异常0。
|
||
|
||
自动测试API79套854项、前端35文件163项通过；API覆盖率67.89%/53.10%/68.77%/70.65%，增量87.98%/77.03%/95.91%/91.22%，前端88.48%/85.09%/84%/88.19%，均通过各自门槛。类型、生产构建、定向ESLint、全量CSS样式、CSS治理及结构/包体检查通过。后续微调已补定向真实验收；不以历史测试数字冒充线上发布证据。
|
||
|
||
真实PG验收见 `tools/testing/verify-home-dashboard.mjs`，新库110项迁移通过；四日、缺片、重复、跨日、快照旧值、退款边界、归属/失效、事务回滚和认领已验收。附加真实故障注入确认投影写失败整批回滚、重试恢复，源更新与确认竞态不丢待处理记录。1/2/3/4片及旧无审计、整条协议回执、补发之前已成功片成本有定向规则测试。副作用测试仅在本地隔离库，不发送短信或向供应商/客户投递。
|
||
|
||
本地2020消息、增加6000片样本：2000条增量投影约4915ms，总览p50约46.8ms/p95约54.5ms，展开p95约20.1ms。未验证线上四日大数据、持续吞吐、整机CPU/峰值内存和外部供应商链路；HOME0917-14生产规模部分保留待验证，不作为容量承诺。初次数据库端口、Redis旧RDB格式以及浏览器关闭按钮/窄屏隐藏表头定位失败均留日志，修正后通过。Redis5.0版本建议保留，未改依赖。
|
||
|
||
本轮授权为提交、推送；不部署。两项迁移及首次投影初始化需在后续授权发布时执行，线上仍是旧首页。原始日志在忽略目录 `.local-data/homepage-implementation-20260917/`，不含密码、令牌或浏览器认证状态。
|