feat: add historical data management
This commit is contained in:
wangxuming
211
docs/history-data-management-plan.md
Normal file
211
docs/history-data-management-plan.md
Normal file
@@ -0,0 +1,211 @@
|
||||
# 后台历史数据管理功能规划
|
||||
|
||||
## 1. 目标
|
||||
|
||||
在现有管理端增加“历史数据”模块，用于查询过去营业日的排队记录、叫号记录和运营统计，支持问题追溯、现场复盘和受控导出。
|
||||
|
||||
首期定位为“历史数据查询与分析”，不把历史记录当成可直接编辑的业务表，也不引入独立历史数据库或复杂数据中台。
|
||||
|
||||
## 2. 当前系统基础
|
||||
|
||||
- 管理端已有运营概览、项目管理、账号管理和大屏中心；管理端接口统一使用 `/api/admin/*`，要求管理员登录。
|
||||
- 数据库已有 `queue_sessions`、`queue_tickets`、`call_batches`、`call_batch_tickets` 和 `audit_entries`，可以用“项目 + 营业日”定位历史数据。
|
||||
- `queue_tickets` 已记录取号、叫号、到场、完成、过号、取消等时间和状态，并保存同行人数。
|
||||
- 个人关联数据已有定时清理机制：终态号码到期后清除手机号、姓氏和称谓；历史维护任务对超过 90 天的记录再次兜底清除未处理的个人字段，清理后仍保留号码和运营统计。
|
||||
- 当前 `ADMIN` 可跨项目查看管理数据，员工账号不能进入管理端；后续若增加项目级管理员，历史查询必须复用服务端项目授权校验。
|
||||
|
||||
## 3. 推荐的信息架构
|
||||
|
||||
在管理端侧边栏新增：
|
||||
|
||||
`历史数据`
|
||||
|
||||
页面内部采用三个视图，避免拆成过多导航：
|
||||
|
||||
1. **排队记录**：按营业日、项目、号码和状态查询单号明细。
|
||||
2. **叫号记录**：按营业日、项目和操作人查询每次叫号及其号码成员。
|
||||
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. 数据生命周期与隐私
|
||||
|
||||
### 推荐口径
|
||||
|
||||
1. **0–30 天**：可查询业务明细；手机号/姓氏只在管理员权限范围内可见，列表默认脱敏。
|
||||
2. **个人信息清理后**：号码、同行人数、状态、时间和批次关系仍可用于历史分析；手机号和姓氏显示“已匿名化”，不可再按手机号查询。
|
||||
3. **90 天以后**：保留匿名业务明细和运营统计；手机号、姓氏等个人关联信息不可恢复，且不可再按手机号检索。
|
||||
4. **审计记录**：沿用现有 1 年留存和定时清理机制；历史模块的查看明文、导出、筛选敏感字段都要写入审计。
|
||||
|
||||
实现口径已确认：历史维护任务对超过 90 天的记录物理清除手机号、姓氏、称谓和检索摘要，并写入匿名化时间；业务号码、状态、时间、批次关系和统计字段继续保留，之后不可按手机号检索或恢复个人关联。
|
||||
|
||||
## 6. 权限与安全
|
||||
|
||||
- 所有历史接口只允许管理端账号访问，游客、员工、大屏令牌不能访问。
|
||||
- 服务端按项目授权过滤，不能信任前端传入的项目 ID；跨项目查询仅对全局管理员开放。
|
||||
- 列表默认手机号脱敏；查看完整手机号、按手机号查询和导出完整手机号均记录审计。
|
||||
- 过滤条件和分页参数必须有上限，避免全表扫描；手机号不进入 URL、普通日志或前端埋点。
|
||||
- 历史记录只读。若出现业务纠错需求，另建“纠正申请/调整记录”，保留原始值、调整值、原因、审批人和时间，不直接覆盖原始事实。
|
||||
|
||||
## 7. 后端接口建议
|
||||
|
||||
```text
|
||||
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 周可完成首版，实际取决于历史数据量和隐私口径确认。
|
||||
Reference in New Issue
Block a user