142 lines
8.6 KiB
Markdown
142 lines
8.6 KiB
Markdown
## Context
|
||
|
||
- **后端（8-11，不改）**：接口和字段见 `junhong_cmp_fiber/docs/2026-11-06-测试环境8-11新功能前端对接与权限现状.md` 第 2.9、2.11、2.12 节，以 8-11 生成的 `admin-openapi.yaml` 为准。
|
||
- **账号类型限制**（后端只按账号类型校验，没有对应权限码）：
|
||
- 记录查询接口不传资产标识时查全部，仅平台账号可用。
|
||
- 资产详情的采集记录、冲正查询与提交，企业账号无权调用。
|
||
- 退款后处理人工重试、尝试记录查询，仅平台账号（含超级管理员）可用。
|
||
- 人工重试只接受 `asset_post_status = 3`（需人工处理）且资产后处理未完成的退款单。
|
||
- **管理后台现状（`iteration/8-11`）**：
|
||
- 菜单为静态路由（`src/router/routes/asyncRoutes.ts`），用 `meta.permissions` 过滤；按钮用 `useAuth().hasAuth()`；超级管理员不受限。
|
||
- 列表页通用组件：`ArtSearchBar`、`ArtTableHeader`、`ArtTableFullScreen`。
|
||
- 可复用的模式是 `components/business/gateway/StopResumeRecords.vue`：同一个组件既作为独立页（`views/polling-management/stop-resume-records`），也嵌在资产详情里（传入卡 ID）。
|
||
- 资产详情：
|
||
- `views/asset-management/asset-information` 用 `BasicInfoCard` 触发停复机记录、`PackageListCard` 触发日流量详单（`DailyRecordsDialog`）。
|
||
- 同步按钮走 `useAssetInfo.refreshAsset`，目前忽略响应体。
|
||
- 退款：`views/finance/refund/index.vue`、`detail.vue`，接口在 `api/modules/refund.ts`，类型在 `types/api/refund.ts`。
|
||
- **约束**：基于 `iteration/8-11`，只部署测试环境；不改停复机逻辑；网关只读开关保持开启。
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
- 运营能在后台查清楚"一张卡的流量读数从采集到入账"的全过程，并能人工冲正。
|
||
- 退款后处理卡住时，运营能看到原因并人工重试。
|
||
- 新页面和按钮有明确的权限码，可以分配给非超级管理员角色。
|
||
|
||
**Non-Goals:**
|
||
- 后端接口或权限校验改动。
|
||
- 采集记录导出、归档文件下载（后端未提供）。
|
||
- 生产发布与生产权限数据。
|
||
|
||
## Decisions
|
||
|
||
### D1 记录列表做成可复用组件，页面只是壳
|
||
|
||
参照 `StopResumeRecords.vue`，在 `src/components/business/traffic-records/` 下新建组件：
|
||
|
||
- `TrafficCollectionRecords.vue`：成功记录；传 `failures` 时切到失败记录。
|
||
- `CardDailyUsages.vue`
|
||
- `PackageUsageDailyRecords.vue`
|
||
- `PackageTrafficAdjustments.vue`
|
||
- `RefundPostProcessAttempts.vue`
|
||
|
||
每个组件接受可选的固定筛选项，例如 `identifier`、`packageUsageId`、`refundId`。独立页面不传，资产详情和退款详情传入，复用同一套列表与原始数据展开。
|
||
|
||
**备选**：页面与弹窗各写一套。**拒绝原因**：字段多（约 30 个），两套容易不一致。
|
||
|
||
### D2 菜单位置
|
||
|
||
| 页面 | 菜单位置 |
|
||
|---|---|
|
||
| 流量采集成功记录、流量采集失败记录、卡日流量、套餐日流量详单、套餐流量冲正流水 | 资产管理 → 记录管理（与"资产分配""授权记录"并列） |
|
||
| 退款后处理尝试记录 | 财务管理（紧跟"退款管理"） |
|
||
|
||
路由别名在 `routesAlias.ts` 注册，页面目录分别为 `views/asset-management/record-management/<name>/index.vue` 与 `views/finance/refund-post-attempts/index.vue`。
|
||
|
||
### D3 权限码
|
||
|
||
后端没有这些权限码，前端新增常量文件 `src/config/constants/trafficRecords.ts`：
|
||
|
||
| 用途 | 权限码 |
|
||
|---|---|
|
||
| 采集成功记录页 | `traffic_collection_record:page` |
|
||
| 采集失败记录页 | `traffic_collection_failure:page` |
|
||
| 卡日流量页 | `card_daily_usage:page` |
|
||
| 套餐日流量详单页 | `package_usage_daily_record:page` |
|
||
| 冲正流水页 | `package_traffic_adjustment:page` |
|
||
| 退款后处理尝试记录页 | `refund_post_process_attempt:page` |
|
||
| 资产详情 · 采集记录（卡 / 设备绑定卡） | `iot_info:traffic_collections`、`device_info:traffic_collections` |
|
||
| 资产详情 · 冲正记录 | `package_usage:traffic_adjustments` |
|
||
| 资产详情 · 人工冲正 | `package_usage:traffic_adjust` |
|
||
| 退款 · 人工重试 | `refund:asset_post_retry` |
|
||
|
||
- 菜单用 `meta.permissions`，按钮用 `hasAuth`。
|
||
- 前端还要按账号类型隐藏后端会拒绝的入口：企业账号不显示资产详情的采集记录和冲正；非平台账号不显示人工重试和尝试记录页。
|
||
- 清单交后端写入测试库 `tb_permission` 并挂到对应菜单。权限码命名最终以写入测试库的数据为准。
|
||
|
||
### D4 时间范围与默认值
|
||
|
||
- 所有列表默认最近 1 天（日期类默认最近 7 天）。
|
||
- 选择器限制跨度 ≤ 31 天，提交前再校验一次。
|
||
- 时间参数按上海时间 `YYYY-MM-DD HH:mm:ss` 传，后端同时接受 RFC3339。
|
||
- 结束时间按"不含"处理，日期类按"含首尾"处理，筛选栏旁用文字说明。
|
||
|
||
### D5 枚举中文名
|
||
|
||
在 `src/config/constants/trafficRecords.ts` 统一维护以下中文名，未知值原样显示：
|
||
|
||
| 枚举 | 中文名 |
|
||
|---|---|
|
||
| `decision` | written 已写入、baseline 建立基线、queue_not_full 采集队列未满、slope_negative 读数回落、out_of_order 采集乱序、settled_existing 已结算 |
|
||
| `result` | ok 正常、failed 失败、rate_limited 限流、invalid_payload 响应无效、no_reading 无读数、invalid_reading 读数无效 |
|
||
| `source` | polling 轮询、manual_sync 人工同步、business_event 业务事件 |
|
||
| 退款后处理 `step` | load 加载、invalidate 失效套餐、activate 激活、check_main 检查主套餐、stop 停机、mark 标记完成、done 完成 |
|
||
| 退款后处理 `trigger` | outbox 自动、manual 人工 |
|
||
| `asset_post_status` | 0 未开始、1 待重试、2 已完成、3 需人工处理 |
|
||
|
||
### D6 原始数据展示
|
||
|
||
- 表格行展开后，用只读 JSON 块（`<pre>` 格式化）展示 `queue_points`、`raw_request`、`raw_response`。
|
||
- `raw_response` 为空、`raw_response_text` 有值时，显示文本并标注"已截断"。
|
||
- 每块提供"复制"按钮，方便贴给网关方排查。
|
||
|
||
### D7 人工冲正交互
|
||
|
||
- 表单只让运营填正整数加方向，由前端换算 `delta_mb` 的正负，避免运营手输负号出错。
|
||
- 确认框展示当前已用量（取套餐行的已用量）、调整量与预计结果。
|
||
- 退回不能使结果小于 0。
|
||
- 成功后刷新套餐列表，并展示返回的 `before_usage_mb → after_usage_mb`。
|
||
- 提示文案说明"提交后系统会按规则重新判断停复机"，前端不调用任何停复机接口。
|
||
|
||
### D8 人工重试交互
|
||
|
||
- 按钮只在"需人工处理 + 平台账号 + 有权限"时出现。
|
||
- 成功时接口返回最新退款详情，直接替换当前行或详情数据。
|
||
- 失败时显示后端 `msg`，并重新拉取该退款单，更新尝试次数和最后错误。
|
||
|
||
### D9 同步结果（可选）
|
||
|
||
- `AssetService.refreshAsset` 的响应类型增加 `traffic_refresh`。
|
||
- `useAssetInfo.refreshAsset` 在成功提示里附加一行入账结果，或用 `ElNotification` 展示。
|
||
- 不改同步按钮的限流和刷新逻辑。
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- **[权限码未入库，非超级管理员看不到新功能]** → 测试先用超级管理员验证。按 D3 清单补测试库后，再用普通运营账号验证。
|
||
- **[人工冲正、人工重试会触发后端停复机判断]** → 测试环境资产已全部在网关只读表，停复机调用会被拦截，不会改上游卡状态。验证只看停复机指令和拦截日志，不看上游卡状态。
|
||
- **[采集记录字段多，表格过宽]** → 默认只显示关键列，其余列通过 `ArtTableHeader` 列设置打开；原始数据放展开行。
|
||
- **[采集记录只保留当月加最近 2 个整月，资产详情采集记录保留 90 天]** → 筛选栏说明保留期，超出保留期查询为空属正常。
|
||
|
||
## Migration Plan
|
||
|
||
1. 在 `iteration/8-11` 实现。本地 `build:development`（接测试后端）通过类型检查与构建。
|
||
2. 后端在测试库补 D3 权限码，并分配给测试角色。
|
||
3. 推送 `iteration/8-11` 部署测试环境。管理后台 CI 要求推送前在本机构建镜像并推送到 `registry.boss160.cn`，需先 `docker login`；部署时间由你安排。
|
||
4. 用超级管理员和普通运营账号分别验证。
|
||
5. 回退：回滚对应提交重新部署；新增页面不影响现有页面。
|
||
|
||
## Open Questions
|
||
|
||
- 权限码命名（D3）是否沿用此清单，还是由后端统一定名后回填前端常量？默认先用此清单。
|
||
- 记录查询菜单是否放在"资产管理 → 记录管理"，还是放到"轮询管理"下与停复机记录并列？默认放"记录管理"。
|