wangxuming/XQKqueue

Fork 0

Files

wangxuming c6044d972c feat: add historical data management

2026-07-22 10:18:49 +08:00

10 KiB

Raw Blame History

后台历史数据管理功能规划

1. 目标

在现有管理端增加“历史数据”模块，用于查询过去营业日的排队记录、叫号记录和运营统计，支持问题追溯、现场复盘和受控导出。

首期定位为“历史数据查询与分析”，不把历史记录当成可直接编辑的业务表，也不引入独立历史数据库或复杂数据中台。

2. 当前系统基础

管理端已有运营概览、项目管理、账号管理和大屏中心；管理端接口统一使用 /api/admin/*，要求管理员登录。
数据库已有 queue_sessions、queue_tickets、call_batches、call_batch_tickets 和 audit_entries，可以用“项目 + 营业日”定位历史数据。
queue_tickets 已记录取号、叫号、到场、完成、过号、取消等时间和状态，并保存同行人数。
个人关联数据已有定时清理机制：终态号码到期后清除手机号、姓氏和称谓；历史维护任务对超过 90 天的记录再次兜底清除未处理的个人字段，清理后仍保留号码和运营统计。
当前 ADMIN 可跨项目查看管理数据，员工账号不能进入管理端；后续若增加项目级管理员，历史查询必须复用服务端项目授权校验。

3. 推荐的信息架构

在管理端侧边栏新增：

历史数据

页面内部采用三个视图，避免拆成过多导航：

排队记录：按营业日、项目、号码和状态查询单号明细。
叫号记录：按营业日、项目和操作人查询每次叫号及其号码成员。
运营统计：按日/项目查看数量、等待时长、完成率和过号率。

“操作审计”可作为后续第四个视图，复用已有 audit_entries，不要和业务历史记录混在一张表里。

默认进入“排队记录”，默认日期为最近 7 天，默认只显示已结束营业日；当前运行中的队列继续由运营概览负责。

4. 首期功能范围

4.1 排队记录列表

筛选条件：

项目：全部项目或单个项目；
营业日期：起止日期，默认最近 7 天，单次最多 31 天；
号码：支持完整号码或号码范围；
状态：全部、等待、已叫、已到场、已完成、过号、已取消；
可选：手机号精确查询，仅对仍在个人数据留存期内的记录生效。

列表字段：

字段	说明
项目/营业日	明确数据归属，避免多项目混淆
号码	显示业务号码，不暴露内部 UUID
同行人数	号码绑定人数
状态	使用现有状态颜色和中文文案
取号时间	`joined_at`
叫号时间	`called_at`，未叫号显示“—”
完成/终态时间	根据状态显示对应时间
实际等待时长	`called_at - joined_at`，未叫号显示“—”
联系信息	列表默认脱敏；已清理显示“已匿名化”

点击行打开详情抽屉，展示状态时间线、所属叫号批次、操作人和数据清理状态。历史详情只读，不提供直接修改状态、号码或同行人数的按钮。

4.2 叫号记录

列表字段：

项目、营业日、叫号序号；
叫号方式：按号码/按人数；
请求数量、实际号码数、实际人数；
号码区间或号码列表；
操作人、叫号时间、完成时间、批次状态。

点击后展示批次成员及每个成员的最终状态。批次记录必须以 call_batches 和 call_batch_tickets 为准，不从当前队列快照反推。

4.3 运营统计

运营统计按经营复盘看板组织，首期提供四层信息：

核心指标：取号号码/人数、完成率、平均/最长等待、过号率和取消率；
每日趋势：按营业日查看取号量、完成量和完成率变化；
项目对比：按取号量排序，联动完成率、过号率和平均等待，支持下钻到排队记录；
状态与时段节奏：展示号码状态、取号/叫号峰值时段和小时分布，并支持从项目对比下钻到排队记录。

基础业务指标包括：

取号总数、取号总人数；
已叫号码数/人数、已完成号码数/人数；
过号率、取消率、完成率；
平均等待时长、最长等待时长、按小时取号/叫号量。

统计口径固定为：

等待时长 = called_at - joined_at；
叫号吞吐按 called_at 计入小时；
完成率 = 已完成号码数 / 已取号号码数；
过号率、取消率均以已取号号码数为分母；
没有时间戳的数据不补估，统计中明确标记为缺失。

首期使用数据库聚合查询，不提前建设复杂报表引擎。若单表规模或查询 P95 超过目标，再增加按项目/营业日的汇总表。

4.4 导出

首期支持 CSV，编码采用 UTF-8 BOM，方便中文表格软件直接打开；
导出内容跟随当前筛选条件，不允许绕过项目范围；
默认导出脱敏手机号，完整手机号需要二次确认并记录审计；
单次最多导出 10,000 行，超出时提示缩小日期范围；
导出记录包含项目、营业日、筛选条件、操作人、时间和行数；
暂不做 Excel、定时邮件、外部链接和自动下载中心。

5. 数据生命周期与隐私

6. 权限与安全

所有历史接口只允许管理端账号访问，游客、员工、大屏令牌不能访问。
服务端按项目授权过滤，不能信任前端传入的项目 ID；跨项目查询仅对全局管理员开放。
列表默认手机号脱敏；查看完整手机号、按手机号查询和导出完整手机号均记录审计。
过滤条件和分页参数必须有上限，避免全表扫描；手机号不进入 URL、普通日志或前端埋点。
历史记录只读。若出现业务纠错需求，另建“纠正申请/调整记录”，保留原始值、调整值、原因、审批人和时间，不直接覆盖原始事实。

7. 后端接口建议

GET  /api/admin/history/sessions
GET  /api/admin/history/tickets
GET  /api/admin/history/tickets/{id}
GET  /api/admin/history/batches
GET  /api/admin/history/batches/{id}
GET  /api/admin/history/summary
GET  /api/admin/history/export.csv

公共查询参数建议统一为：project_id、from、to、status、page、page_size、query。

接口约束：

日期按项目时区解释，数据库仍统一存储 UTC 时间；
列表接口返回 items、page、page_size、total 和 filters；
详情接口返回只读时间线和关联批次；
汇总接口同时返回指标值和数据更新时间；
导出接口复用同一套筛选和授权逻辑，不另写一套查询条件。

8. 数据库与性能建议

首期直接复用现有事实表，补充必要索引：

queue_sessions(project_id, business_date DESC)；
queue_tickets(queue_session_id, status, ticket_number)；
queue_tickets(project_id, called_at)；
call_batches(queue_session_id, called_at DESC)；
如保留手机号查询，使用现有 phone_hmac 索引，不对密文做模糊搜索。

建议验收基线：最近 31 天、10 万条号码记录内，列表首屏 P95 ≤ 800ms；统计接口 P95 ≤ 1.5s；导出超过 10,000 行时先拒绝并提示缩小范围。达到规模后再评估日汇总表或异步导出任务。

9. 分阶段实施

P0：可用的历史查询

新增历史数据导航和页面骨架；
营业日/项目/状态/号码筛选；
排队记录列表、详情抽屉；
叫号批次列表与详情；
项目隔离、脱敏和只读限制；
后端分页、索引和接口测试。

P1：分析与受控导出

运营统计卡片、趋势图和按小时分布；
CSV 导出与导出审计；
明文查看审计；
历史数据新鲜度和匿名化状态提示；
性能压测与大数据量空状态/错误状态。

P2：治理能力

操作审计查询视图；
可配置留存策略和执行记录；
大范围导出的异步任务；
匿名化/纠正申请工作流；
冷数据归档和恢复演练。

10. 明确不做

不允许在历史列表直接“改状态”“改号码”“改同行人数”；
不把当前运营概览改造成全量历史报表；
不首期引入独立数据仓库、消息队列或复杂 BI 平台；
不首期支持任意字段模糊搜索、全库无限期明文查询和无审计导出；
不把个人手机号作为长期统计维度。

11. 验收标准

管理员可按项目、营业日、状态和号码分页查询历史记录；
查询结果不会混入当前运行队列之外的错误项目数据；
排队单详情能还原取号、叫号、到场、完成/过号/取消时间线；
叫号批次详情能展示实际号码数、实际人数和成员状态；
统计口径与列表数据一致，缺失时间不被伪造为 0；
已清理个人信息的记录不可通过手机号搜回，页面显示匿名化状态；
导出与明文查看均产生审计记录，且导出遵循同样的项目权限；
历史页面不提供改变事实数据的入口；
31 天范围内的列表和统计达到性能基线；
跨项目、未登录、员工账号和伪造项目参数的访问全部被拒绝并留痕。

12. 推荐决策

建议先按 P0 + P1 建设：先把“查得到、看得懂、导得出、可追责”做完整；暂不把人工修正、冷归档和可配置留存放进首期。按当前技术栈，预计 1 名前端、1 名后端和 1 名测试/产品协作，约 2–3 周可完成首版，实际取决于历史数据量和隐私口径确认。

10 KiB Raw Blame History Unescape Escape