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

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** 页面显示"本次读数未写入：采集队列未满"

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** 表单提示原因必填，不发请求

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** 页面提示请选择时间范围，不发请求

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** 列表同时显示成功与失败记录，失败记录有明显标识