hectorzhao/lislgosms

Fork 0

Files

T

hectorzhao 9b8196ecab feat: build reporting workbench workflow

2026-09-02 14:30:15 +08:00

41 KiB

Raw Blame History

报备工作台、签名补资料与报备记录改造方案

日期：2026-09-02 状态：已按确认方案实施，待测试环境验收基线：main / cd824999f3b604155e09fbad1f5c6258cfe1d918

1. 改造目标

本轮保留现有资料进入待生成范围、批次生成、文件处理和通道报备状态模型，将现有“报备任务”重组为“报备工作台”，集中完成八项改造：

将“报备资料池、报备批次、通道报备明细、状态记录”拆成四个职责清晰的二级菜单。
重新设计报备批次，在批次列表增加批次详情入口，并在批次内查看、筛选和操作真实报备明细。
修复已有签名导入时把补资料误处理为整块覆盖的问题，避免未映射字段及用途被意外清空。
增强状态记录的查询、重置、分页和操作人展示，方便按业务主体和状态变化追溯。
增加单条通道报备明细的签名资料导出，按目标通道的真实字段配置生成一行报备文件。
优化“短信通道管理—报备详情”的分页、今日发送排序、查询、状态修改和报备资料查看体验。
企业签名新增或报备资料真实变化并提交成功后，提示用户前往报备资料池生成批次。
企业签名列表展示最新材料版本尚待生成批次的签名报备明细数。

本轮不改变短信发送、队列、计费、通道路由和供应商协议链路，不发送、补发、重投或重新入队短信。

2. 已确认的产品决策

2.1 保留待生成资料池现有逻辑

不新增资料池级“放弃/恢复”状态。
继续以 pendingReport=true 且审核通过作为进入待生成池的主要条件。
继续由现有材料版本、应用状态、应用路由、通道字段和重复批次检查决定是否可生成。
继续保留通道报备明细上的 abandoned 状态，不把它扩展为签名全局禁用状态。
本轮不修改新建签名、客户端审核和运营端自动审核的既有流程。

2.2 保留现有文件能力

保留 XLSX 解析、MinIO 原文件/图片存储、图片/文件字段映射和通道 XLSX 嵌图能力。
本轮不新增文件格式、文件清理、压缩包、批量下载或回执文件解析能力。
已生成批次详情只展示和下载现有 ReportExportFile，不改变文件生成与保存逻辑。

2.3 已有签名导入视为补资料

继续使用“企业 + 应用 + 完整签名名称 + 未删除”识别已有签名。
导入确认后仍先进入导入审核批次；审核通过前不修改真实签名。
审核通过已有签名时执行字段级补资料，而不是整块替换。
只有本次导入实际映射且单元格有值的字段参与更新：已有字段覆盖，新字段追加，未导入字段保留。
映射列为空时默认不清空旧值。本轮不增加“显式清空字段”语法；如后续需要，应单独设计清空标记和二次确认。
未映射“用途”时不得写入空字符串，也不得改变原用途。

3. 报备工作台信息架构

3.1 菜单与路由

原一级菜单“报备任务”更名为“报备工作台”，其下不再使用“待生成资料 / 已生成批次”页签承载不同业务对象，而是拆成四个二级菜单：

二级菜单	建议路由	页面主对象	核心职责
报备资料池	`/admin/report-materials`	已审核的签名/引流资料及材料版本	判断能否生成批次、选择资料并生成批次、查看各状态明细汇总
报备批次	`/admin/report-batches`	`ReportMaterialBatch`	查看批次进度、通道文件和本批次报备明细
通道报备明细	`/admin/report-tasks`	企业应用 × 签名/引流对象 × 通道 × 运营商	查看未报备及已落库任务、批量修改报备状态、进入详情
状态记录	`/admin/report-records`	`ChannelSignatureReportRecord`	查询每次状态变化、原因、入口、操作人和时间轨迹

权限点应按四页职责拆分或复用现有最接近的权限；实施前先核对当前菜单权限表和角色授权。为避免既有收藏和页面跳转失效，现有路由能复用的继续复用；原批次页签链接通过兼容跳转进入新的“报备批次”页面。

四个页面之间共享统一的业务标识和跳转条件：资料池可进入关联通道明细，批次可进入本批次明细，明细可进入状态记录，状态记录可回到对应明细。前端不得通过多个列表结果自行拼接关系，关联范围由后端返回的真实标识确定。

3.2 报备资料池

“待生成资料”更名为“报备资料池”。它仍沿用当前资料进入和批次生成规则，但页面不再只表达“有没有生成过文件”，还要呈现资料对应通道报备明细的汇总状态。

资料池维度明确为“企业应用 × 签名/引流对象 × 材料版本”，不是“企业应用 × 签名 × 通道”。通道及运营商属于该资料行下面的报备明细维度，由资料池做数量汇总和下钻；如果把通道作为资料池主维度，会与“通道报备明细”页面重复，并造成同一材料版本重复展示。

资料池主行仍以签名/引流资料及其材料版本为选择和生成单位。
默认视图突出当前可生成批次的资料；可切换查看全部、待生成、已生成、资料不完整等状态，避免生成后对象完全不可追踪。
每行显示关联通道明细总数及未报备、报备中、通过、失败、放弃数量。
通道报备状态发生变化后，资料池汇总随真实明细状态更新；不反向改写签名审核状态或材料版本。
abandoned 只排除对应的通道报备明细，不把整个签名从资料池永久移除；同一签名的其他通道/运营商明细仍可参与批次。
生成批次时只选择符合现有生成规则且未放弃的通道报备明细，并继续执行材料版本、路由、通道字段及重复生成校验。

这一步是页面查询与汇总语义调整，不要求签名创建时提前写入所有通道任务记录。

3.3 报备批次

“已生成批次”从资料页签中拆出，成为独立的批次级主列表，批次明细通过独立入口打开。

主列表建议字段：

字段	展示内容
报备批次号	`batchNo`，作为主要识别信息
生成时间	北京时间
生成范围	所选资料数、通道数、文件数
报备进度	报备总数、通过数、成功率
生成状态	生成中、生成完成、部分生成、生成失败
操作	“查看批次”主入口

现有逐文件下载链接从主列表移入批次详情，避免一行中出现大量链接并挤压进度信息。

3.4 批次详情工作台

点击“查看批次”打开大尺寸批次详情层。首版沿用平台现有 Modal 体系，不新增独立路由；如果真实批次规模导致弹层不可用，再升级为独立详情页。

详情分为三个区域：

批次摘要
- 批次号、生成时间、生成状态、所选资料数、通道数、文件数。
- 报备总数、通过数、成功率。
- 部分失败或失败时展示真实 errorMessage，不得用统一成功提示覆盖。
通道文件
- 按通道显示文件名、行数、生成状态和下载入口。
- 文件对象缺失时显示“文件不可用”，不渲染失效下载按钮。
报备明细
- 一行对应一个真实 ChannelSignatureReportTask。
- 展示签名/引流对象、企业、应用、通道、运营商、文件行号、资料版本、当前状态和更新时间。
- 支持按关键字、报备类型、状态和通道筛选，使用后端分页。
- 操作包含“查看报备资料”“导出报备资料”（签名明细）和“修改状态”。

3.5 通道报备明细

通道报备明细的业务粒度统一定义为：

企业应用 × 签名/引流对象 × 通道 × 运营商

页面同时展示两类行：

根据当前有效应用路由计算出的、尚未产生数据库任务的“未报备”明细；
已存在 ChannelSignatureReportTask 的报备中、通过、失败、放弃及历史明细。

实现采用“查询时补齐、首次业务操作时落库”的方式：未报备明细由后端基于真实签名、应用路由、通道和运营商计算，前端不得自行做笛卡尔积；当用户批量修改状态或生成批次时，再在事务内创建缺失任务。这样可以让未报备项可见、可选、可批量操作，同时避免签名新增或路由变化时提前制造大量无业务动作的任务记录。

页面能力包括：

按企业、应用、签名/引流对象、通道、运营商、状态和关键字筛选；
单选、跨当前页选择规则明确的批量选择、批量修改报备状态；
展示真实任务号；尚未落库的未报备行显示“首次操作后生成”，不得伪造任务号；
查看资料字段、材料版本、当前状态及状态轨迹；
从批次详情进入时限定当前批次，从资料池进入时限定当前资料对象；
状态更新后同步刷新本页、资料池汇总、批次汇总和状态记录。

批量操作必须由后端校验权限、租户、通道归属和允许的状态变化，并在同一事务中完成任务创建/更新及状态记录写入。局部失败不得静默吞错，应返回可定位到具体明细的结果。

3.6 明细详情与状态操作

复用报备明细页的详情字段、状态轨迹和 changeReportTaskStatuses 统一状态接口。
不在批次详情中复制新的报备状态保存逻辑。
修改成功后同时刷新：当前明细、批次通过数、成功率和报备记录。
状态原因保持选填；状态变化继续写 ChannelSignatureReportRecord，sourceEntry 使用 report_task。
企业签名页当前只保留“报备状态”入口；本轮不恢复旧的只读“报备详情”弹窗，避免形成第三套详情实现。

3.7 API 设计

报备资料池改为统一查询接口，返回资料本身、生成资格及通道明细汇总。现有待生成接口可暂时保留供兼容跳转或逐步迁移：

GET /api/admin/report-materials
  ?scope=all|pending|generated|incomplete
  &keyword=
  &page=
  &pageSize=

通道报备明细新增统一列表查询，响应需区分虚拟未报备行与已落库任务，并返回稳定的业务组合键：

GET /api/admin/report-details
  ?keyword=
  &enterpriseId=
  &applicationId=
  &signatureId=
  &channelId=
  &carrier=
  &status=
  &batchId=
  &page=
  &pageSize=

批量状态操作复用现有统一状态变更服务；接口须接受任务ID或完整业务组合键，后者在事务内按需创建缺失任务：

POST /api/admin/report-tasks/status-change

保留现有批次列表接口，新增批次详情查询：

GET /api/admin/report-materials/batches/:id

返回批次摘要及通道文件，不一次性返回全部明细。

新增批次明细分页接口：

GET /api/admin/report-materials/batches/:id/tasks
  ?keyword=
  &reportType=
  &status=
  &channelId=
  &page=
  &pageSize=

查询关系必须来自：

ReportMaterialBatch
  -> ReportMaterialBatchItem
  -> ReportExportFileItem
  -> ChannelSignatureReportTask

不得只按签名ID猜测批次归属，也不得用前端拼接现有多个列表结果冒充批次详情。

3.8 页面状态

批次列表和详情必须分别覆盖：

首次加载；
空批次；
批次生成中；
部分生成；
生成失败；
文件缺失；
明细为空；
请求失败；
修改状态进行中、成功和失败；
历史批次、历史通道级未拆分任务和已删除业务主体的兼容展示。

资料池和通道报备明细还必须覆盖：虚拟未报备行、无有效路由、部分通道放弃、状态变更后汇总刷新、批量操作部分失败以及历史任务与当前路由不一致等状态。

3.9 单条明细签名资料导出

“通道报备明细”和“短信通道管理—报备详情”均增加“导出报备资料”操作，首版仅针对单条签名报备明细，不等同于导出当前列表，也不生成新的批次。

导出口径如下：

一次导出一个“企业应用 × 签名 × 通道 × 运营商”明细，生成只有一条数据行的 XLSX。
字段只使用目标通道当前启用的签名报备字段，按 ChannelReportField.sortOrder ASC, createdAt ASC 排列；表头优先使用 exportName，否则使用字段名称。
从普通明细入口导出当前材料版本；从历史批次详情入口导出该批次冻结的材料快照，文件中及下载前均明确显示资料版本，避免把当前资料误当成历史批次资料。
复用现有通道批次导出的字段解析、转换、列宽和图片嵌入能力，不另写一套 XLSX 映射逻辑。
图片继续按现有能力嵌入 XLSX；其他文件类型维持现有文件字段处理规则，本轮不扩展压缩包或附件打包。
导出前执行通道字段和必填资料校验。缺失必填字段时不生成看似可交付的空白文件，返回具体缺失字段，并允许用户先进入“查看报备资料”定位问题。
导出动作写操作日志，记录操作者、租户、签名、通道、运营商、资料版本和结果；它不改变报备状态，不创建报备批次，不触发短信任务，也不把虚拟未报备明细强制落库。

为支持尚未落库的未报备明细，接口使用稳定业务组合键而不是只接受任务ID：

POST /api/admin/report-details/material-export
{
  "signatureId": "...",
  "channelId": "...",
  "carrier": "mobile|unicom|telecom",
  "materialVersion": 3,
  "batchItemId": "可选；从历史批次导出时传入"
}

后端必须重新校验当前用户权限、租户范围、签名与应用归属、通道及运营商组合；不能相信前端提交的企业名称、字段值或文件对象ID。

3.10 企业签名保存提示与待生成明细数

3.10.1 新增或资料变化后的引导弹窗

企业签名发生新增、修改或报备资料变化并成功提交后，前端根据后端返回的真实变更结果弹出引导，不使用前端表单脏状态猜测是否已经落库。

弹窗主文案为：

资料发生变化，如需提交至通道报备，请到“报备工作台—报备资料池”生成报备批次。

交互和边界如下：

提供“稍后处理”和“前往报备资料池”两个操作；前往资料池时自动携带当前企业、应用和签名筛选条件。
如果当前新增或修改仍需审核，补充提示“审核通过后将进入报备资料池”，不得暗示未审核资料已经可以生成批次。
只有签名新增成功，或签名名称、所属应用、用途、签名主体资料、动态报备字段及文件等会影响报备材料或通道目标的内容真实发生变化时提示。
仅打开后未修改、保存失败、后端事务回滚或与报备无关的展示字段未发生变化时不提示。
导入补资料在审核通过并真实应用到已有签名后，也应产生相同的资料变化标识；导入审核提交但尚未应用时不提前提示已可生成。
提示本身不自动生成批次、不创建通道任务、不改变报备状态，也不触发任何短信链路。

签名新增/修改接口的成功响应建议增加：

reportMaterialChanged: boolean
materialVersion: number
pendingReport: boolean
reportPoolAvailableAfter: "immediate" | "approval"

由后端在提交事务内判断材料是否变化并返回最终材料版本，前端只负责展示与跳转。

3.10.2 企业签名列表的待生成报备明细数

企业签名列表增加“待生成报备明细数”列。该数字按每个签名的最新材料版本计算，统计尚需进入报备批次的有效签名明细：

企业应用 × 签名 × 通道 × 运营商

计算规则：

从签名所属应用的当前有效路由获取目标通道，并按通道实际支持的运营商拆分组合。
只统计当前签名最新材料版本尚未生成对应报备批次的组合；旧版本生成过批次不能抵消新版本的待生成人数。
排除已删除或停用通道、不支持的运营商组合以及明确为 abandoned 的对应通道明细。
无有效应用路由时数量为 0，同时通过提示说明“暂无有效报备通道”，不能伪造待生成任务。
尚未审核通过、按现有规则不能进入资料池的签名数量为 0，并展示“审核通过后计算”或等价说明。
一个组合即使存在多条历史批次或状态记录，也只能计数一次。
数量必须由后端随签名分页列表批量计算并返回，禁止前端逐行请求或加载全量任务后统计。

建议企业签名分页响应每行增加：

pendingReportDetailCount: number
pendingReportMaterialVersion: number | null
pendingReportBlockedReason: string | null

点击数量进入“通道报备明细”，自动带入当前签名、最新材料版本及“待生成”范围；页面另提供“前往报备资料池”入口。数量为 0 时不伪装成可点击链接。

4. 已有签名补资料 Bug 修复

4.1 当前问题

当前导入暂存会把导入得到的动态字段整体写入 signatureReportValues。当导入表只包含部分字段时，原有但未导入的字段会丢失；未映射用途时还可能把原用途更新为空字符串。

4.2 目标合并规则

设现有资料为：

{
  "license": "old-license",
  "authorization": "old-authorization"
}

本次导入只有：

{
  "license": "new-license",
  "contact": "new-contact"
}

审核通过后的结果必须为：

{
  "license": "new-license",
  "authorization": "old-authorization",
  "contact": "new-contact"
}

具体规则：

签名名称继续是匹配和校验必填字段，不作为普通补资料字段清空。
purpose 只有映射且有值时才更新。
动态字段只收集已映射且有值的单元格。
合并顺序为“现有字段在前，本次有效导入字段在后”。
未映射字段和映射但为空的字段保留原值。
新增签名仍使用本次导入资料创建，不套用已有对象合并逻辑。
审核前继续保存 originalSnapshot，审核页应能区分新增、覆盖和保留字段。

4.3 实现调整

修改 mappedCoreValue 或新增可区分“未映射 / 已映射空值 / 已映射有值”的读取函数，避免用空字符串同时表示三种状态。
stageSignatureRow 生成字段补丁，不生成会清空旧字段的完整替换对象。
applyImportItem 对已有签名重新读取当前值后合并，避免导入审核等待期间被其他修改覆盖。
保留现有材料版本递增、pendingReport=true、审核记录和待生成池逻辑。
本修复不需要 Prisma schema migration。

4.4 并发与错误边界

审核应用时重新确认目标签名仍存在且未删除。
如导入审核期间签名名称、应用或资料发生变化，必须基于最新对象合并，不得用旧快照覆盖整份资料。
单行失败只把该导入明细标记为无效，不阻断同批其他行。
不吞并 MinIO 下载、字段校验或数据库更新错误。

5. 状态记录检索改造

5.1 查询条件

“报备记录”页面更名为“状态记录”，调整为以下服务端组合查询：

通用关键字：报备任务号、批次号、签名、引流 URL/号码、通道、动作和备注；
报备类型：签名、引流信息；
状态后：未报备、资料待补充、报备中、报备通过、报备失败、放弃报备；
动作：创建、生成批次、导出、人工修改、历史回执导入及系统动作；
修改入口：企业签名、报备任务、通道信息、系统、历史记录；
操作人；
记录时间范围。

中文状态和动作在前端转换为后端枚举值，不能要求用户输入数据库英文值。

5.2 列表与详情

列表补充批次号和操作人；历史无操作人的记录显示“系统/历史”。
保留真实任务号、通道、主体、动作、状态变化、原因和时间。
详情展示当前记录及所属任务的时间顺序状态轨迹；轨迹使用真实记录分页/查询结果，不把单条记录包装成“完整历史”。
从批次详情、报备明细详情进入报备记录时预填批次号或任务号。

5.3 React 查询状态

输入条件与已应用条件分离。
点击“查询”后应用条件并回到第一页。
点击“重置”后清空条件、回到第一页并立即请求默认列表。
翻页只使用已应用条件，不读取尚未查询的输入值。
使用请求序号或 AbortController 防止旧请求覆盖新条件结果。
分别展示加载、空数据和失败状态；失败不能保留旧列表并伪装为当前查询结果。

5.4 API 与索引

扩充现有接口：

GET /api/admin/report-records
  ?keyword=
  &batchNo=
  &reportType=
  &statusAfter=
  &action=
  &sourceEntry=
  &operatorKeyword=
  &createdAtFrom=
  &createdAtTo=
  &page=
  &pageSize=

功能实现先使用真实 PostgreSQL 查询。根据真实数据量执行 EXPLAIN (ANALYZE, BUFFERS)；若状态、动作、入口或操作人查询出现不可接受的全表扫描，再新增以下组合索引：

(statusAfter, createdAt)；
(action, createdAt)；
(sourceEntry, createdAt)；
(operatorId, createdAt)。

索引属于数据库 migration，只有查询计划证明需要时才纳入，不为小数据量预先增加全部索引。

6. “短信通道管理—报备详情”页面优化

6.1 当前问题与改造边界

当前页面一次性加载该通道全部报备任务，再在浏览器内按关键词和状态筛选；列表没有真实分页，默认按任务创建时间倒序。“今日发送”统计由另一套非分页查询补充，现有分页任务接口不支持按今日发送量排序。当前“查看详情”直接遍历资料 JSON，不能保证与该通道签名/引流信息字段配置顺序一致。

本次改造只调整通道报备管理、查询和资料导出，不改变今日发送数据口径，不发送、补发、重投或重新入队短信。

6.2 服务端分页与今日发送排序

页面改为真实服务端分页，默认每页 20 条，允许切换 20/50/100 条。
默认排序为“今日发送条数从大到小”；今日按北京时间 00:00:00 至次日 00:00:00 计算。
“今日发送条数”沿用当前真实提交记录口径，以该明细对应签名、通道及引流对象归集的总尝试条数为准，不把成功数或计费条数替代为发送条数。
排序必须在后端完成后再分页，不能先按创建时间分页，再对当前页做前端排序。
今日发送量相同时依次按任务更新时间倒序、任务ID倒序，保证翻页稳定且不重复、不漏行。
分页响应直接返回每条明细的今日发送统计和上次发送成功时间，页面不得再并行拉取全部任务后自行合并。
历史通道级未拆分任务和没有今日发送记录的任务仍保留，今日发送数按 0 排在后面。

建议扩充通道报备明细查询：

GET /api/admin/channels/:channelId/report-details
  ?keyword=
  &reportType=
  &tenantId=
  &applicationId=
  &signatureKeyword=
  &drainageKeyword=
  &carrier=
  &status=
  &todaySendMin=
  &todaySendMax=
  &submittedAtFrom=
  &submittedAtTo=
  &approvedAtFrom=
  &approvedAtTo=
  &sort=todaySendDesc
  &page=
  &pageSize=

先用真实 PostgreSQL 数据检查聚合、排序和分页查询计划。若在真实数据量下需要新索引或汇总结构，须单独说明迁移、写入成本、历史回填和部署风险，不能为了页面排序未经评估增加定时汇总或新表。

6.3 搜索条件细化

基础查询区保留高频条件，高级条件折叠展示，避免所有控件挤在一行：

基础条件：资料类型（签名/引流信息）、签名名称或引流 URL/号码、企业、企业应用、运营商、报备状态；
高级条件：今日发送条数区间、提交报备时间、报备通过时间、是否有缺失必填资料；
固定通道由当前页面上下文确定，不再重复提供通道选择器；
输入态与已应用查询态分离，点击查询后回到第一页；重置后立即加载默认条件；
翻页和修改页大小只使用已应用条件，旧请求不得覆盖新查询结果；
URL 保留已应用筛选和分页参数，便于从其他页面跳入、刷新和返回时保持上下文。

后端对各条件执行权限和类型校验，企业、应用和签名必须受当前用户租户范围限制。不能在前端拿到全量任务后做敏感数据筛选。

6.4 列表信息与操作

列表保留通道报备工作的核心信息，并减少单行视觉噪音：

主体：签名或引流 URL/号码、所属企业、企业应用；
维度：资料类型、运营商；
报备：当前状态、提交时间、通过时间；
发送：今日发送总数及成功、未知、回执失败、提交失败概览，上次发送成功时间；
操作：“查看报备资料”“导出报备资料”“修改状态”。

原“查看详情”统一更名为“查看报备资料”。状态轨迹不再混在资料字段中，需要时从弹层进入独立“状态记录”菜单并带入任务条件。

6.5 “查看报备资料”弹层

点击后展示该通道针对当前报备类型要求的真实资料，而不是无序遍历签名 JSON：

顶部摘要固定展示企业、应用、签名/引流对象、通道、运营商、资料版本、当前状态及更新时间。
签名明细按该通道启用的 signature 或 both 字段配置排序；引流明细按 drainage 或 both 字段配置排序。
排序规则固定为 sortOrder ASC, createdAt ASC，与通道报备 XLSX 的列顺序一致。
字段名称优先显示通道配置名称；值从对应资料快照按字段编码解析，并应用与导出一致的取值规则。
图片显示缩略图并支持查看原图；文件字段显示真实文件名和授权下载入口；对象缺失或无权限时显示明确错误，不渲染失效链接。
当前通道已取消配置但历史资料仍存在的字段，统一追加在“其他历史资料”区域，保持确定性顺序，不直接丢弃。
缺失的必填字段明确标红并显示“缺少资料”，普通空字段显示“-”；不能把默认值伪装成用户已提交资料。
弹层提供“导出报备资料”和“查看状态记录”入口，复用单条导出及状态记录能力。

6.6 “修改状态”弹层重设计

实施前先输出与现有后台设计系统一致的完整桌面及窄屏概念稿。新弹层采用清晰的任务上下文和状态变更结构：

顶部摘要：签名/引流对象、企业应用、通道和运营商，避免用户改错对象；
状态区：明显展示“当前状态 → 目标状态”，目标状态使用可读的单选项或状态卡，不使用拥挤的裸下拉框；
原因区：保留修改原因输入及字符提示；不擅自改变现有原因必填规则，如后续要求失败/放弃必须填写，应另行确认业务校验；
风险提示：对“放弃报备”等影响后续批次生成的状态展示明确说明；
操作区：取消与确认层级清晰，保存中禁止重复提交，关闭弹层不保留上一次任务的状态和原因；
失败时保留当前输入并显示后端真实错误；成功后关闭弹层并刷新当前页、资料池汇总、批次汇总和状态记录。

弹层只复用统一状态变更接口，不新增一套通道专用状态保存逻辑。

6.7 页面状态与响应式

必须验收首次加载、查询加载、空数据、请求失败、分页越界、任务被并发修改、文件缺失、无权限、历史任务及零发送量状态。桌面端保持可扫描的表格；窄屏优先保留主体、状态、今日发送和操作，其余信息进入行详情，不使用横向无限溢出的固定宽表格。

7. 数据模型与迁移判断

改造项	是否需要数据库迁移
一级菜单更名及四个二级页面拆分	否，优先复用现有菜单与权限配置能力
报备资料池汇总	否，基于现有资料、路由和任务查询
企业签名保存后的资料变化提示	否，由现有保存事务返回变化结果和材料版本
企业签名列表待生成报备明细数	默认否，基于现有应用路由、通道运营商、材料版本、批次项和任务状态计算
虚拟未报备明细及批量状态操作	否，首次操作时复用现有任务表按需落库
报备批次详情	否，复用现有批次、文件、明细关联
单条签名资料导出	否，复用现有字段配置、材料快照和 XLSX 导出能力
通道报备详情分页及今日发送排序	默认否；如真实查询计划证明需要索引或汇总结构，则需另行评估 migration
已有签名补资料合并	否，修复 JSON 合并和字段读取逻辑
状态记录新增筛选	默认否
状态记录性能索引	视真实查询计划决定，可能需要

本轮不修改 ChannelSignatureReportTask 状态集合和发送链路对 approved 的判断。

8. 实施顺序

阶段一：导入补资料 Bug 修复

固化字段合并规则。
修改导入暂存和审核应用逻辑。
增加已有签名、未映射用途、部分动态字段和并发修改回归。
真实 PostgreSQL 事务内验证后回滚验收数据。

阶段二：报备工作台查询与数据联动

增加资料池统一查询和通道明细统一查询，后端计算虚拟未报备行及资料状态汇总。
为企业签名分页列表批量计算最新材料版本的待生成报备明细数、版本和阻塞原因，避免逐行查询。
让签名新增、修改和导入补资料应用接口返回材料是否真实变化、最终材料版本及资料池可用时点。
扩充批量状态接口，使虚拟未报备行在首次操作时按需落库，并保证任务与状态记录事务一致。
验证状态变化可同步反映到资料池、企业签名计数、批次、通道明细和状态记录。
固化历史任务与当前路由变化、无路由、待审核和部分放弃的兼容规则。

阶段三：四菜单页面改造与报备批次重设计

先产出与现有运营端设计系统一致的完整桌面/窄屏概念稿，确认四菜单的信息层级、跨页跳转、批次详情、文件区和批量操作。
将一级菜单改为“报备工作台”，拆分报备资料池、报备批次、通道报备明细和状态记录四个二级页面，并配置权限与兼容跳转。
在企业签名保存成功后增加资料变化引导弹窗，并在企业签名列表展示待生成报备明细数及下钻入口。
新增批次详情和批次明细分页 API，实现主列表和批次详情组件。
复用报备明细详情及统一状态接口，不复制状态保存逻辑。
完成真实 API、PostgreSQL、MinIO 文件和浏览器交互验收。

阶段四：单条导出与通道报备详情优化

抽取并复用现有通道 XLSX 的字段解析、转换、图片嵌入和必填校验能力，增加单条签名资料导出接口。
将通道报备列表改为后端分页、后端今日发送聚合排序及稳定次级排序。
细化服务端搜索条件，完成输入态、已应用条件、分页和 URL 查询状态管理。
先确认“查看报备资料”和“修改状态”桌面/窄屏概念稿，再实现按通道字段顺序展示的资料弹层及新状态弹层。
使用真实 PostgreSQL 数据执行查询计划检查，使用真实 MinIO 文件验证图片、附件查看和单条 XLSX 下载。

阶段五：状态记录检索

扩充 API 查询参数和响应映射。
修复查询、重置、分页及旧请求覆盖。
增加批次号、状态、入口、操作人查询和展示。
用真实数据检查查询计划，决定是否增加索引 migration。

9. 测试与验收

9.1 导入补资料

已有字段被新值覆盖。
新字段被追加。
未映射字段保持原值。
映射但空白的字段保持原值。
未映射用途不被清空。
新增签名流程不受影响。
审核前业务表不变，审核通过后才落库。
同批单行失败不影响其他行。
材料版本、待生成标志和审核记录正确。

9.2 报备资料池与通道报备明细

报备资料池一行严格对应“企业应用 × 签名/引流对象 × 材料版本”，不因多个通道重复资料主行。
新建签名沿用当前规则进入资料范围，不额外批量预写任务。
有有效路由但尚无任务记录的组合以“未报备”显示。
无有效路由时不虚构通道报备明细，并明确展示不可生成原因。
企业、应用、签名/引流对象、通道、运营商组合键稳定且不重复。
单选和批量修改状态均使用真实后端接口；首次操作只创建一次任务。
通过、失败、放弃等状态变化实时反映到资料池汇总。
放弃只排除对应通道明细，不误伤同资料的其他通道/运营商。
批量操作校验权限和租户，失败项返回具体原因并写入正确状态记录。
历史任务保留可查，不因当前路由取消而丢失。

9.3 企业签名保存提示与待生成明细数

新建签名成功、报备相关字段真实修改成功、导入补资料审核通过并应用成功后，返回正确的资料变化标识和材料版本。
未改动直接保存、保存失败、事务回滚及导入仍待审核时不误提示已经可以生成批次。
待审核对象的弹窗明确提示审核通过后进入资料池；审核通过对象可直接带条件跳转资料池。
“稍后处理”和“前往报备资料池”行为正确，跳转后企业、应用和签名筛选条件准确。
企业签名列表的计数按最新材料版本及有效“通道 × 运营商”组合计算，不把同一组合重复计数。
新材料版本生成后重新计入，当前版本成功生成对应批次后扣减；放弃明细、无效通道及不支持运营商不计入。
无有效路由、待审核和无待生成明细均返回 0，并展示正确且可区分的阻塞原因。
分页列表由一次后端查询返回每行计数，不产生逐行 API 请求或明显的数据库 N+1 查询。
使用不同租户、角色和分页数据验证计数隔离，不能泄露其他租户的路由或任务数量。

9.4 单条明细签名资料导出

当前资料入口导出当前材料版本，历史批次入口导出该批次材料快照。
XLSX 只有当前签名明细一条数据行，不混入同签名其他通道或运营商。
列名、列顺序、默认值、转换、列宽及图片尺寸与目标通道字段配置一致。
图片来自真实 MinIO 对象并正确嵌入；对象缺失、格式不支持和下载失败返回明确错误。
缺少通道必填字段时列出缺失项，不生成可被误交付的空白文件。
导出校验租户、权限、通道和运营商，不能通过修改请求参数导出其他租户资料。
导出不创建批次、不改变任务状态、不创建虚拟任务、不触发短信链路，但写入真实操作日志。

9.5 报备批次

列表汇总与真实文件项和任务状态一致。
查看批次只返回当前批次明细，不串入同签名其他批次。
通道文件可下载且哈希与 MinIO 对象一致。
批次明细使用真实后端分页和筛选。
批次内修改状态后，任务、记录、通过数和成功率同步。
生成中、部分失败、失败、文件缺失和历史数据正确展示。

9.6 短信通道管理—报备详情

总数、页码和每页条数来自真实后端分页，直接访问后续页不依赖前端已有全量数据。
默认按北京时间今日发送总数全局倒序后分页；相同数量时顺序稳定。
抽取不同页样本核对今日发送统计与 SmsSubmitRecord、SmsMessageRecord 的真实归集结果。
企业、应用、签名/引流对象、运营商、状态、时间及今日发送区间可组合查询。
查询、重置、翻页和页大小变化发送正确参数，快速查询时旧响应不覆盖新结果。
“查看报备资料”分别按签名字段配置和引流信息字段配置顺序展示，历史未配置字段进入独立区域。
图片预览、原图/文件下载、缺失对象、空字段和必填字段缺失状态正确。
修改状态弹层展示正确任务上下文和当前状态，防重复提交，失败保留输入，成功刷新所有关联统计与记录。
桌面端及窄屏下表格、筛选区、资料弹层和状态弹层可操作，控制台无新增错误。

9.7 状态记录

中文条件正确映射到后端枚举。
任务号、批次号、签名、引流信息、通道、状态、动作、入口和操作人可组合查询。
查询、重置、翻页只发送一次正确请求。
快速连续查询时旧响应不能覆盖新结果。
操作人、修改入口和状态轨迹来自真实 PostgreSQL 数据。

9.8 菜单、权限与页面联动

一级菜单显示“报备工作台”，包含且仅包含本方案确定的四个二级入口。
四个入口分别打开独立页面，刷新和直接访问路由均有效。
原有页签或收藏链接通过兼容跳转落到正确页面。
无权限用户不显示入口，直接访问也由后端/路由守卫拒绝。
资料池、批次和通道明细进入状态记录时自动带入正确查询条件。
桌面端及窄屏下菜单、表格、批量操作条和详情弹层可用。

9.9 门禁

报备材料、通道报备、短信配置定向单元测试。
API 全量回归、TypeScript 正式构建和 Prisma validate。
前端组件测试、TypeScript 检查和 Vite 生产构建。
桌面端及窄屏真实页面检查。
浏览器控制台、加载、空数据、失败、权限和历史数据状态。
git diff --check、staged diff 精确核对。

自动化测试替身只用于隔离回归；最终功能验收必须使用真实 API、PostgreSQL、MinIO 文件和浏览器交互证据。

10. 发布与回滚边界

方案确认后默认只修改代码、测试和文档，不提交、不推送、不部署。
如最终没有数据库索引 migration，回滚为前后端代码及文档回退。
如增加索引 migration，发布前必须评估建索引锁和耗时，优先使用适合当前 PostgreSQL 版本的低影响方式；回滚不得删除业务数据。
不修改预生产 fstab、数据盘 UUID、绑定挂载、存储保护脚本或 systemd drop-in。
未经单独授权不访问或修改预生产，不发布测试环境。

11. 需在实施前锁定的验收口径

本方案已采用以下默认口径，如需调整应在编码前修改方案：

导入补资料时，空白单元格不清空旧值。
一级菜单使用“报备工作台”，其下固定为“报备资料池、报备批次、通道报备明细、状态记录”四个二级菜单。
报备资料池保留当前资料进入和批次生成规则，但补充所有相关通道明细的状态汇总，生成后仍可追踪。
未报备通道明细采用查询时计算、首次业务操作时落库，不在新建签名时批量预写任务。
报备批次详情首版使用大尺寸弹层，不新增批次详情路由。
批次主列表不直接铺开全部文件下载链接，文件统一进入批次详情。
企业签名页不恢复旧的只读报备详情弹窗，批次和通道报备明细共用一套详情能力。
单条签名资料导出为目标通道格式的一行 XLSX；普通入口导出当前材料版本，历史批次入口导出批次快照。
短信通道报备详情默认按北京时间今日发送总数全局倒序，排序完成后再分页。
“查看报备资料”严格按当前通道的签名或引流字段配置顺序展示，历史剩余字段放在独立区域。
修改状态弹层只重做信息层级和交互，不新增状态枚举，不擅自改变原因必填规则。
企业签名新增或报备资料真实变化并成功提交后显示引导弹窗，目标页面固定为“报备工作台—报备资料池”；待审核对象必须说明审核前不可生成。
企业签名列表展示的是最新材料版本尚待生成批次的“通道 × 运营商”明细数，不是签名数，也不是历史任务总数。
状态记录性能索引、今日发送排序及待生成明细计数所需索引均以真实查询计划为准，不预先创建无证据索引或汇总表。

41 KiB Raw Blame History Unescape Escape