docs: 新增流量记录查询、人工冲正与退款资产后处理提案 add-traffic-records-and-refund-post-processing

2026-11-07 11:29:33 +09:00
parent d24506ab54
commit 49a4d32eab
8 changed files with 371 additions and 0 deletions
--- a/openspec/changes/add-traffic-records-and-refund-post-processing/.openspec.yaml
+++ b/openspec/changes/add-traffic-records-and-refund-post-processing/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-11-07
--- a/openspec/changes/add-traffic-records-and-refund-post-processing/design.md
+++ b/openspec/changes/add-traffic-records-and-refund-post-processing/design.md
@@ -0,0 +1,141 @@
+## 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）是否沿用此清单，还是由后端统一定名后回填前端常量？默认先用此清单。
+- 记录查询菜单是否放在"资产管理 → 记录管理"，还是放到"轮询管理"下与停复机记录并列？默认放"记录管理"。
--- a/openspec/changes/add-traffic-records-and-refund-post-processing/proposal.md
+++ b/openspec/changes/add-traffic-records-and-refund-post-processing/proposal.md
@@ -0,0 +1,34 @@
+## Why
+
+后端 8-11 迭代在 11-05 新增了流量采集记录分表与记录查询接口、套餐流量人工冲正、退款资产后处理逐次尝试与重试上限，10-29 起资产刷新接口还会返回本次读数是否入账（`traffic_refresh`）。管理后台目前都没有接上：运营看不到采集成功/失败记录和卡日流量，无法人工冲正套餐流量；退款后处理失败到达重试上限后，后台既看不到状态也不能人工重试。依据 `junhong_cmp_fiber/docs/2026-11-06-测试环境8-11新功能前端对接与权限现状.md` 第 2.9、2.11、2.12、5.2 节补齐管理后台。
+
+本变更基于 `iteration/8-11` 分支，只部署测试环境。
+
+## What Changes
+
+- 新增 6 个记录查询列表页：运营商流量采集成功记录、采集失败记录、卡日流量、套餐日流量详单、套餐流量冲正流水、退款资产后处理尝试记录。
+- 资产详情新增"采集记录"（按卡，可包含失败记录）。
+- 资产详情套餐列表新增"冲正记录"查看与"人工冲正"（正数补扣、负数退回，原因必填）。
+- 退款列表、详情展示资产后处理状态、已尝试次数、最后错误、下次自动重试时间；列表支持按后处理状态筛选；"需人工处理"的退款单提供"人工重试"按钮与尝试记录入口。
+- 可选：资产"同步"成功后展示本次读数、读数结果、是否写入、写入判断、增量。
+- 新增上述页面与按钮的前端权限码常量，并整理清单供测试库补权限数据。
+- 不改停复机逻辑：人工冲正、人工重试会由后端按规则触发停复机判断，前端只调用接口；测试环境资产已全部在网关只读表中，不会真实停复机。
+
+## Capabilities
+
+### New Capabilities
+- `traffic-record-query`：采集成功/失败记录、卡日流量、套餐日流量详单、冲正流水 4 类全局查询页，以及资产详情中的卡采集记录。
+- `package-traffic-adjustment`：资产详情中按套餐查看冲正流水与提交人工冲正。
+- `refund-asset-post-processing`：退款后处理状态展示与筛选、人工重试、后处理尝试记录查询页。
+- `asset-refresh-traffic-result`：资产同步后展示 `traffic_refresh` 入账结果（可选）。
+
+### Modified Capabilities
+（无。本仓库 `openspec/specs/` 下没有已有规格。）
+
+## Impact
+
+- 接口模块：新增 `src/api/modules/trafficRecords.ts`；`refund.ts` 增加人工重试与尝试记录；`asset.ts` 增加采集记录、冲正查询与提交，`AssetRefreshResponse` 类型增加 `traffic_refresh`。
+- 类型：`src/types/api/refund.ts` 的 `Refund` 与 `RefundQueryParams` 增加 `asset_post_*` 字段；新增记录查询类型。
+- 页面：新增记录查询页（`src/views/asset-management/record-management/*`、`src/views/finance/refund-post-attempts`）；修改 `src/views/finance/refund/index.vue`、`detail.vue`、`src/views/asset-management/asset-information`（采集记录、冲正）。
+- 路由与权限：`src/router/routes/asyncRoutes.ts`、`routesAlias.ts`，新增权限常量文件；菜单与按钮权限码需在测试库 `tb_permission` 补数据，否则只有超级管理员可见。
+- 后端接口（8-11 已提供，不改）：`/api/admin/traffic-collections`、`/traffic-collection-failures`、`/card-daily-usages`、`/package-usage-daily-records`、`/package-traffic-adjustments`、`/refund-post-process-attempts`、`/assets/{identifier}/traffic-collections`、`/assets/{identifier}/packages/{package_usage_id}/traffic-adjustments`（GET/POST）、`POST /refunds/{id}/asset-post-processing/retry`、`POST /assets/{identifier}/refresh`。
--- a/openspec/changes/add-traffic-records-and-refund-post-processing/specs/asset-refresh-traffic-result/spec.md
+++ b/openspec/changes/add-traffic-records-and-refund-post-processing/specs/asset-refresh-traffic-result/spec.md
@@ -0,0 +1,13 @@
+## ADDED Requirements
+
+### Requirement: 同步后展示流量入账结果
+
+资产详情点击"同步"成功后，若响应包含 `traffic_refresh`，系统 SHALL 在成功提示中或提示下方展示本次流量入账结果：读数结果（中文名称）、本次运营商读数 `reading_mb`（为空时显示"未返回读数"）、是否写入 `written`、写入判断 `decision`（中文名称）、本次增量 `delta_mb`。响应不含 `traffic_refresh` 时 MUST 保持现有"刷新成功"提示不变。本需求为可选项，不实现不影响现有功能。
+
+#### Scenario: 读数已写入
+- **WHEN** 同步返回 `traffic_refresh = { result: ok, reading_mb: 1200, written: true, decision: written, delta_mb: 15 }`
+- **THEN** 页面显示"本次读数 1200 MB，已写入，增量 15 MB"
+
+#### Scenario: 读数未写入
+- **WHEN** 同步返回 `written = false`、`decision = queue_not_full`
+- **THEN** 页面显示"本次读数未写入：采集队列未满"
--- a/openspec/changes/add-traffic-records-and-refund-post-processing/specs/package-traffic-adjustment/spec.md
+++ b/openspec/changes/add-traffic-records-and-refund-post-processing/specs/package-traffic-adjustment/spec.md
@@ -0,0 +1,25 @@
+## ADDED Requirements
+
+### Requirement: 查看套餐冲正流水
+
+资产详情套餐列表中每笔套餐 SHALL 提供"冲正记录"入口，弹窗调用 `GET /api/admin/assets/{identifier}/packages/{package_usage_id}/traffic-adjustments` 分页展示该套餐的冲正流水：冲正时间、调整量、调整前后已用量、调整前后套餐状态、原因、操作人、关联流量事件 ID 与采集 ID。企业账号 MUST NOT 显示该入口。
+
+#### Scenario: 查看冲正记录
+- **WHEN** 运营在资产详情某笔套餐上点击"冲正记录"
+- **THEN** 弹窗按时间倒序显示该套餐的冲正流水，无记录时显示空状态
+
+### Requirement: 提交人工冲正
+
+有冲正按钮权限的账号 SHALL 能在资产详情套餐上提交人工冲正，调用 `POST /api/admin/assets/{identifier}/packages/{package_usage_id}/traffic-adjustments`。表单字段：调整方向（补扣 / 退回）、调整量 MB（正整数，提交时按方向转为正数或负数 `delta_mb`）、原因（必填，去首尾空格后不能为空）、关联采集 ID 与关联流量事件 ID（选填）。提交前 SHALL 二次确认，确认框展示当前已用量、调整量与预计调整后已用量，并提示"提交后系统会按规则重新判断停复机"。退回量大于当前已用量时 SHALL 提示调整后不能小于 0 并阻止提交。提交中 MUST 防重复。成功后 SHALL 提示调整前后已用量，并刷新套餐列表与冲正记录。
+
+#### Scenario: 补扣
+- **WHEN** 运营对已用 500 MB 的套餐选择补扣 100 MB、填写原因并确认
+- **THEN** 系统提交 `delta_mb = 100`，成功后提示已用量 500 MB → 600 MB，套餐列表刷新
+
+#### Scenario: 退回超过已用量
+- **WHEN** 运营对已用 50 MB 的套餐选择退回 80 MB
+- **THEN** 页面提示调整后已用量不能小于 0，不提交
+
+#### Scenario: 原因为空
+- **WHEN** 运营未填写原因直接提交
+- **THEN** 表单提示原因必填，不发请求
--- a/openspec/changes/add-traffic-records-and-refund-post-processing/specs/refund-asset-post-processing/spec.md
+++ b/openspec/changes/add-traffic-records-and-refund-post-processing/specs/refund-asset-post-processing/spec.md
@@ -0,0 +1,45 @@
+## ADDED Requirements
+
+### Requirement: 退款后处理状态展示
+
+退款列表与退款详情 SHALL 展示资产后处理状态 `asset_post_status`（0 未开始、1 待重试、2 已完成、3 需人工处理），列表用标签展示，"需人工处理"用警示色。详情 SHALL 另外展示已尝试次数 `asset_post_attempts`（注明自动重试上限 10 次）、最后一次错误 `asset_post_last_error`、下次自动重试时间 `asset_post_next_at`（仅待重试时有值）。字段缺失时显示"-"，不影响现有展示。
+
+#### Scenario: 待重试
+- **WHEN** 一笔退款 `asset_post_status = 1`、已尝试 3 次、下次重试时间为 10:30
+- **THEN** 详情显示"待重试"、已尝试 3/10 次、最后错误与下次重试时间 10:30
+
+### Requirement: 按后处理状态筛选
+
+退款列表 SHALL 增加"资产后处理状态"筛选项，选中后请求带 `asset_post_status`；清空时不传该参数。
+
+#### Scenario: 筛选需人工处理
+- **WHEN** 运营选择"需人工处理"并查询
+- **THEN** 请求带 `asset_post_status = 3`，列表只显示需人工处理的退款单
+
+### Requirement: 人工重试后处理
+
+退款单 `asset_post_status = 3` 且当前账号为平台账号或超级管理员、并有人工重试按钮权限时，退款列表操作列与详情页 SHALL 显示"人工重试"按钮；其他状态或账号类型 MUST NOT 显示。点击后 SHALL 二次确认，提示"重试会重新执行退款后的资产处理（可能包括停机），确认继续？"。调用 `POST /api/admin/refunds/{id}/asset-post-processing/retry`，提交中 MUST 防重复。成功时 SHALL 用返回的最新退款详情刷新当前行或详情；失败时 SHALL 显示后端错误信息（如"资产后处理仍未完成：…"），并重新加载该退款单以展示最新尝试次数与错误。
+
+#### Scenario: 重试成功
+- **WHEN** 运营对需人工处理的退款单点击"人工重试"并确认，后端返回成功
+- **THEN** 页面提示重试成功，该退款单后处理状态显示"已完成"，按钮消失
+
+#### Scenario: 重试仍失败
+- **WHEN** 后端返回"资产后处理仍未完成：停机失败"
+- **THEN** 页面显示该错误，重新加载后仍显示"需人工处理"和最新错误
+
+#### Scenario: 非需人工处理
+- **WHEN** 退款单后处理状态为"待重试"
+- **THEN** 不显示"人工重试"按钮
+
+### Requirement: 后处理尝试记录查询
+
+系统 SHALL 提供"退款后处理尝试记录"列表页，调用 `GET /api/admin/refund-post-process-attempts`，仅平台账号与超级管理员可用。筛选条件：时间范围（必填，跨度不超过 31 天）、退款单 ID 或单号、资产标识、处理步骤 `step`、结果 `result`、错误码、触发方式 `trigger`（自动 / 人工）。列表 SHALL 展示记录时间、退款单号、资产类型与 ICCID、第几次尝试、步骤、结果、错误码与错误信息、触发方式、耗时；步骤、结果、触发方式显示中文名称。退款详情 SHALL 提供"后处理尝试记录"入口，打开该列表并自动带上退款单 ID。
+
+#### Scenario: 从退款详情查看
+- **WHEN** 运营在退款详情点击"后处理尝试记录"
+- **THEN** 打开尝试记录列表，已按该退款单 ID 筛选，时间范围为最近 31 天
+
+#### Scenario: 时间范围必填
+- **WHEN** 运营清空时间范围后查询
+- **THEN** 页面提示请选择时间范围，不发请求
--- a/openspec/changes/add-traffic-records-and-refund-post-processing/specs/traffic-record-query/spec.md
+++ b/openspec/changes/add-traffic-records-and-refund-post-processing/specs/traffic-record-query/spec.md
@@ -0,0 +1,65 @@
+## ADDED Requirements
+
+### Requirement: 采集成功记录查询
+
+系统 SHALL 提供"流量采集成功记录"列表页，调用 `GET /api/admin/traffic-collections`。筛选条件：资产标识、时间范围（`start_time`～`end_time`，结束时间不含）、运营商账户、写入判断 `decision`、来源 `source`、场景 `scene`、是否有增量 `has_delta`、是否触发重置日防旧值 `stale_guarded`。列表 SHALL 展示采集时间、ICCID 或卡 ID、运营商账户、来源、场景、运营商原始读数、本月累计、本次增量、写入判断、防旧值、网关 code 与 trace_id、网关尝试次数，并可展开查看采集队列 `queue_points`、原始请求 `raw_request`、原始响应 `raw_response` / `raw_response_text`（截断时标注）。写入判断、来源、读数结果 SHALL 显示中文名称。分页每页默认 20、最大 100。
+
+#### Scenario: 默认查询
+- **WHEN** 运营打开采集成功记录页
+- **THEN** 默认时间范围为最近 1 天，按采集时间倒序展示第一页
+
+#### Scenario: 查看原始数据
+- **WHEN** 运营展开一条 `raw_truncated = true` 的记录
+- **THEN** 页面显示 `raw_response_text` 并标注"原始响应已截断"
+
+### Requirement: 采集失败记录查询
+
+系统 SHALL 提供"流量采集失败记录"列表页，调用 `GET /api/admin/traffic-collection-failures`。筛选条件：资产标识、时间范围、运营商账户、失败类型 `result`、错误类别 `error_category`、上游返回码 `provider_code`、来源、场景。列表 SHALL 展示采集时间、ICCID、运营商账户、失败类型、错误类别、HTTP 状态、上游返回码与信息、网关 code/msg/trace_id、耗时、尝试次数，并可展开原始请求与响应。
+
+#### Scenario: 按失败类型筛选
+- **WHEN** 运营选择失败类型"限流"并查询
+- **THEN** 列表只显示 `result = rate_limited` 的记录
+
+### Requirement: 卡日流量查询
+
+系统 SHALL 提供"卡日流量"列表页，调用 `GET /api/admin/card-daily-usages`。筛选条件：资产标识、日期范围（`start_date`～`end_date`，含首尾）、运营商账户、当日用量下限 `min_usage_mb`。列表 SHALL 展示日期、ICCID、运营商账户、当日用量 `settled_mb`、当日结束时本月累计、最后一次运营商原始读数、当天写入次数 `obs_count`、是否触发防旧值、更新时间。
+
+#### Scenario: 排查异常大流量
+- **WHEN** 运营输入当日用量下限 1024 MB 并查询
+- **THEN** 列表只显示当日用量不低于 1024 MB 的卡日记录
+
+### Requirement: 套餐日流量详单查询
+
+系统 SHALL 提供"套餐日流量详单"列表页，调用 `GET /api/admin/package-usage-daily-records`。筛选条件：资产标识、日期范围、套餐使用记录 ID、套餐 ID、运营商账户。列表 SHALL 展示日期、套餐使用记录 ID、套餐 ID、卡 ID 或设备 ID、当日流量、截止当日累计、更新时间。
+
+#### Scenario: 按套餐使用记录查询
+- **WHEN** 运营输入套餐使用记录 ID 并查询
+- **THEN** 列表只显示该套餐的日流量
+
+### Requirement: 冲正流水查询
+
+系统 SHALL 提供"套餐流量冲正流水"列表页，调用 `GET /api/admin/package-traffic-adjustments`。筛选条件：资产标识、时间范围、套餐使用记录 ID、操作人账号 ID、调整方向 `direction`（补扣 / 退回）。列表 SHALL 展示冲正时间、套餐使用记录 ID、卡 ID 或设备 ID、调整量（正数补扣、负数退回）、调整前后已用量、调整前后套餐状态、原因、操作人、关联流量事件 ID 与采集 ID。
+
+#### Scenario: 只看退回
+- **WHEN** 运营选择调整方向"退回"
+- **THEN** 列表只显示调整量为负数的流水
+
+### Requirement: 查询范围与账号限制
+
+所有记录查询页的时间或日期跨度 MUST NOT 超过 31 天，超出时 SHALL 在提交前提示并阻止查询。不填资产标识查询全部只允许平台账号与超级管理员：其他账号类型 SHALL 要求填写资产标识后才能查询。后端返回无权限时 SHALL 显示后端提示。
+
+#### Scenario: 跨度超限
+- **WHEN** 运营选择 2026-10-01 至 2026-11-06 并查询
+- **THEN** 页面提示时间跨度不能超过 31 天，不发请求
+
+#### Scenario: 代理账号不填资产
+- **WHEN** 代理账号不填资产标识直接查询
+- **THEN** 页面提示请先输入资产标识
+
+### Requirement: 资产详情采集记录
+
+资产详情 SHALL 为卡（含设备绑定的卡）提供"采集记录"入口，弹窗调用 `GET /api/admin/assets/{identifier}/traffic-collections`，默认最近 1 天、每页 50、不含失败记录；可勾选"包含失败记录"（`include_failures = true`），并可按写入判断、来源、场景筛选。列表 SHALL 用 `record_kind` 区分成功与失败记录，成功记录展示读数、累计、增量、写入判断，失败记录展示失败类型、错误类别与上游返回；均可展开原始数据。企业账号 MUST NOT 显示该入口。
+
+#### Scenario: 包含失败记录
+- **WHEN** 运营在卡详情打开采集记录并勾选"包含失败记录"
+- **THEN** 列表同时显示成功与失败记录，失败记录有明显标识
--- a/openspec/changes/add-traffic-records-and-refund-post-processing/tasks.md
+++ b/openspec/changes/add-traffic-records-and-refund-post-processing/tasks.md
@@ -0,0 +1,46 @@
+## 1. 类型、接口与常量
+
+- [ ] 1.1 新增记录查询类型（采集成功/失败记录、卡日流量、套餐日流量详单、冲正流水、后处理尝试记录、`traffic_refresh`）
+- [ ] 1.2 `types/api/refund.ts`：`Refund` 增加 `asset_post_status`、`asset_post_attempts`、`asset_post_last_error`、`asset_post_next_at`；`RefundQueryParams` 增加 `asset_post_status`
+- [ ] 1.3 新增 `api/modules/trafficRecords.ts`（6 个全局查询接口），在 `api/modules/index.ts` 导出
+- [ ] 1.4 `api/modules/asset.ts` 增加资产采集记录、套餐冲正查询与提交；`AssetRefreshResponse` 增加 `traffic_refresh`
+- [ ] 1.5 `api/modules/refund.ts` 增加人工重试接口
+- [ ] 1.6 新增 `config/constants/trafficRecords.ts`：权限码（design D3）、枚举中文名（D5）、31 天跨度校验工具
+
+## 2. 可复用记录组件
+
+- [ ] 2.1 原始数据展开组件：格式化 JSON、截断标注、复制
+- [ ] 2.2 `TrafficCollectionRecords.vue`（成功 / 失败两种模式，支持固定 identifier、include_failures）
+- [ ] 2.3 `CardDailyUsages.vue`
+- [ ] 2.4 `PackageUsageDailyRecords.vue`
+- [ ] 2.5 `PackageTrafficAdjustments.vue`（支持固定 identifier + package_usage_id）
+- [ ] 2.6 `RefundPostProcessAttempts.vue`（支持固定 refund_id，时间范围必填）
+- [ ] 2.7 组件统一处理：默认时间范围、31 天校验、非平台账号必须填资产标识、分页
+
+## 3. 页面与路由
+
+- [ ] 3.1 新增 5 个记录查询页（资产管理 → 记录管理）与退款后处理尝试记录页（财务管理），注册 `routesAlias.ts` 与 `asyncRoutes.ts`，配置 `meta.permissions`
+- [ ] 3.2 菜单多语言文案（`locales`）
+
+## 4. 资产详情
+
+- [ ] 4.1 `BasicInfoCard` 为卡与设备绑定卡增加"采集记录"按钮（权限 + 非企业账号），弹窗嵌入 `TrafficCollectionRecords`
+- [ ] 4.2 `PackageListCard` 每笔套餐增加"冲正记录"，弹窗嵌入 `PackageTrafficAdjustments`
+- [ ] 4.3 新增人工冲正弹窗：方向 + 正整数 MB + 原因必填 + 选填关联 ID；二次确认展示预计结果；退回不得小于 0；提交防重复；成功后刷新套餐列表
+- [ ] 4.4 （可选）同步成功后展示 `traffic_refresh` 入账结果
+
+## 5. 退款
+
+- [ ] 5.1 退款列表增加后处理状态列与筛选项
+- [ ] 5.2 退款详情增加后处理状态、尝试次数（/10）、最后错误、下次重试时间
+- [ ] 5.3 列表操作列与详情增加"人工重试"（需人工处理 + 平台账号 + 权限），二次确认、防重复，成功替换数据、失败显示错误并重新加载
+- [ ] 5.4 退款详情增加"后处理尝试记录"入口，按退款单 ID 打开尝试记录
+
+## 6. 验证与发布
+
+- [ ] 6.1 `vue-tsc --noEmit` 与 `build:development` 通过
+- [ ] 6.2 整理 D3 权限码清单给后端，在测试库 `tb_permission` 补数据并分配测试角色
+- [ ] 6.3 超级管理员验证：6 个列表页筛选与原始数据、资产详情采集记录、冲正记录与人工冲正、退款后处理展示与筛选、人工重试
+- [ ] 6.4 普通运营账号验证菜单与按钮权限；代理账号验证必须填资产标识、看不到人工重试
+- [ ] 6.5 人工冲正、人工重试后确认停复机调用被网关只读拦截（worker 日志），不以上游卡状态为准
+- [ ] 6.6 推送 `iteration/8-11` 部署测试环境（先 `docker login registry.boss160.cn`，时间由你安排）