one-pipe-system/openspec/changes/update-carrier-polling-scheduler-integration/proposal.md

Change: 按最新运营商账户限流契约补齐调度、告警与轮询开关管理

Why

docs/2026-10-26-轮询按运营商账户限流-前端接口变更说明.md 是前两轮简化文档之后的完整变更契约，包含 46 个新增接口与 16 个改动接口。当前前端已实现其中的网关管理和轮询配置扩展基础，但仍缺少账户调度、失败告警、演练、单卡排查、批量开关及导入清单，并存在必须升级的持久化配置和已废弃保护期字段。

本次以该日期文档为准做增量接入，不重复建设前两轮已有页面，不把文档中所有“新增”理解为当前项目均未实现。

What Changes

1. 轮询配置保存升级：创建/编辑/列表/详情支持 asset_status、package_state、pre_reset_window、pre_reset_carddata_interval；四项检查间隔支持 null 继承、0 禁用、正数间隔。编辑清空显式使用 clear_fields，保存成功展示 warnings；移除 protect_check_interval。更新草稿、匹配预览和拖拽优先级，保留既有预览、进度及统计权限。
2. 保护期退场：移除后台相关输入与展示，不再请求/保存保护期间隔；兼容后端仍返回但废弃的 device_protect_status，不影响其他资产功能。
3. 现有网关页面增量：错误分类支持 terminal 类别专属 auto_disable_polling 与测试结果；限流组展示真实 observe/enforce 模式；网关调用统计按已补全 DTO 展示账户/操作汇总、失败分类、豁免来源和趋势，不再保留“字段未定义”的临时限制。成功率按 0–1 显示，p95=-1 显示超出最大桶，不伪造精确耗时。
4. 轮询管理新增「运营商账户调度参数」「请求检查场景」「失败告警」「账户队列监控」「停复机规则演练」「不轮询清单」「轮询开关导入」。失败告警使用普通列表、账户汇总、停机被拒三个视图；单卡轮询状态放入现有单卡及设备绑定卡入口，不新建一级菜单。
5. 调度参数、场景修改严格仅超级管理员；规则演练、文件导入、不轮询清单、告警批量关闭及指定导出严格仅平台账号（user_type=1/2）。普通权限不得越过账号身份边界。
6. 卡/设备列表补齐 enable_polling 筛选、列和最多 500 项的批量开关。批量提交前取 impact 文案并确认、要求原因；展示成功/跳过/失败/无权限逐项结果，部分成功不回滚。设备级联语义保持后端决定；风险停机/已销户不提供强制开启。
7. 单资产开关改为展示接口 impact 确认文案并处理拒绝响应；订单或有效期变动后读取后端实际状态，不在前端模拟自动恢复。
8. 导入复用预签名上传：purpose=polling_status_import、CSV 表头与首列标识符、最多 50000 行、file_key 前缀校验，提交后列表与逐行结果按真实状态显示。长 ICCID 保持字符串，不转数字；上传失败不得创建任务，异步轮询要清理。
9. 导出复用统一任务，增加 polling_pause、polling_stop_refused_alert、stop_resume_rule_dry_run 场景、列表/详情/下载权限和必要菜单路由；卡/设备导出携带 enable_polling，客户端不重写旧历史文件。
10. 系统配置支持 polling 模块和文档中的 string/int/bool/json 配置，以服务器返回校验规则和错误为准；轮询并发页提示仅 legacy 调度生效，并链接账户参数。运营商实名管控 0→1 改为展示后端返回的实际影响说明，确认后带 realname_control_confirm 重提，不先擅自确认。
11. 延续 UI 标准：店铺列表和详情组件、统一 formatDateTime、运营商账户名称搜索、日期范围按临期资产样式、搜索条件 >=4 才显示展开。普通账号交付清单只列实际新增/变更菜单、URL、父菜单及 xxx:xxx 权限；保留旧配置、不列仅超级管理员专属项。

Impact

• Affected specs: carrier-polling-scheduler-integration（新增综合接入规范）。当前无已归档 specs；前两轮 add-gateway-rate-limit-management、add-polling-config-preview-and-statistics 已完成，不更改其既有路由 URL 与权限编码。
• Affected code: pollingConfig / gateway / asset / card / device / carrier / storage / exportTask / systemConfig 的 API、类型与界面，相关路由、权限、上传组件、导出场景配置及测试。
• 不执行后端限流调度算法或数据迁移，不在真实环境触发批量操作、导入、调序、重算、配置修改、Git 推送或生产部署。测试写操作只使用本地 mock。
• 保留工作区已有未提交的轮询配置实现与其他用户修改。

Scope boundaries and contract risks

• 文档要求的 C 端资产详情不在当前后台仓库：检索未发现独立 C 端工程。本次只落实本仓库可定位的后台部分，C 端保护期下线在交付中明确列为外部同步项，不声称已经修改。
• 本文 46 个新增接口中，前两轮已经建立 24 个方法，预计补齐剩余 22 个；实施前按路径与方法逐项核对，不以数量替代验收。附录已给出多数新 DTO，旧接口的完整 OpenAPI 未随本文提供时，不猜测未定义字段或清空规则。
• 网关统计内部字段已经补全，覆盖前一提案的“未知字段动态展示”临时约定。轮询配置新持久化字段已经明确，覆盖上一提案“新增字段仅用于预览”的暂定边界。旧说明与回归测试需同步升级。
• warnings 未定义固定结构时以实际字符串/对象安全展示，不假设固定业务键；clear_fields 仅使用文档支持的可空字段，不任意清除配置。
• 演练 page_size 特例最大 500，其余文档分页最大 100；演练结果筛选只影响明细不影响汇总，导出接口没有 result 参数时不擅自加入。假设实名管控 on/off 账户集合不得重叠。
• 停机被拒视图仅发送文档支持的五类筛选；切换视图清除忽略项及旧勾选。账户级告警 card_id=0 不得当作有效单卡 ID 请求历史或轮询状态。

Delivery

先实现配置/保护期和公共契约，再接调度与排查，随后接批量/导入/导出，最后完成权限矩阵、mock 浏览器和回归验证。普通菜单与按钮配置写入 docs/权限.md 并在最终回复给出增量清单；现有菜单和权限不重复要求用户新增。

用户于 2026-10-26 批准执行，并明确仅修改后台前端；交付时另列 C 端同步事项，不修改 C 端代码。