[!WARNING]
渠道管理新增的“快照有效优先级”是基于已保存配置、响应节点策略和所读取 Redis 状态计算的只读观察值。节点配置、缓存阶段或请求候选条件不一致时，它可能与实际选路不同；不能用来还原历史请求，也不能作为上游健康或全局一致性的保证。

Redis 读取失败时，界面显示未知；选路仍可能使用有效缓存，或回退到配置优先级。超时禁用到达最早检查时间，也不代表已经恢复。请先在目标部署验证这些行为，再依赖页面进行运维判断。

[!NOTE]
v2.0.0-smartops.pre5 聚焦渠道运行态的可观测性与编辑一致性：将配置优先级和快照有效优先级分开展示，补充降权、暂停路由与恢复条件，并保护刷新过程中的未保存输入。同时在用户管理列表展示邮箱，便于管理员核对账户并使用既有批量状态管理流程。

本次更新延续既有渠道健康治理机制，新增管理界面的运行态快照展示，不改变配置优先级、运行态处罚规则或选路算法。前后端须成套构建和部署；快照适用范围与升级要求见下文。

MAX API 2.0 SmartOps pre5

GitHub 地址

v2.0.0-smartops.pre5

Compatibility Notes

• 配置值与运行态分离：priority 继续表示可编辑、可持久保存的配置优先级。超时降权不覆盖该字段；新增展示说明既有运行态限制。例如配置为 10、活动惩罚为 2 时，快照可显示 8，配置仍为 10。运行态快照基于已保存配置，不计算未保存草稿的选路结果。
• 管理 API 增量字段：现有渠道列表、搜索和详情响应中的渠道对象新增只读 routing_health，当前 schema_version 为 1，原响应包裹及配置字段保持。自定义客户端需容忍新增字段，并正确区分数字 0、false 与 null。创建、更新渠道时仍只提交配置，不能通过回写该对象调整惩罚或恢复状态。
• 严格展示读取与选路回退不同：管理投影直接严格读取 Redis，既有选路读取仍使用节点缓存及容错规则。策略启用但 Redis 未配置、读取失败、状态损坏或投影预算不足时，相应快照显示未知，不将其伪装为无惩罚或优先级 0；配置查询仍可成功。Redis 成功读到不存在的运行态 hash，才按已确认的空状态处理。
• 单次查询有预算：运行态投影共享 100ms 读取期限，每批最多 200 个去重渠道，最多读取 1000 个渠道；已经成功读取的批次可保留，无法确认的部分单独标记未知。大规模查询的运行态并非跨渠道原子快照，也不承诺覆盖全部结果。
• 快照的解释范围：仅在节点配置、策略、运行态缓存和计算时点相符时，用于解释常规优先级选路。分组、模型、重试、权重及其他候选筛选仍会影响最终选择。“无运行态限制”不代表上游健康，“策略未启用”不代表 Redis 没有历史限制记录。
• 时间与恢复语义：evaluated_at 是响应节点完成投影时的计算时间，不是 Redis 写入版本或跨节点排序依据。惩罚到期后页面等待新快照确认；自动禁用的截止时间表示最早恢复检查时刻，仍须满足探测条件，人工模式继续等待人工恢复。跨节点恢复水位的时间比较仍要求可比的时间基准。
• 新旧版本组合：新前端遇到缺少快照字段的旧接口，明确提示不支持运行态展示；未知版本、损坏数据和已知但不可确认的状态分别降级，不阻断配置读写。已验证的历史前端读写模块可消费新增字段并提交原配置载荷；保证限于固定历史源码及相同依赖，不推广为任意旧客户端或真实混部兼容承诺。
• 用户邮箱展示范围：邮箱列复用现有管理员列表及搜索接口的 email 字段，无需新增数据库字段或迁移。它反映账户当前登记邮箱，不是不可变的原始注册邮箱，也不表示邮箱已验证。该列用于人工核对，后续批量禁用仍遵循既有权限、账户保护和确认流程。
• 升级与回退范围：相对 v2.0.0-smartops.pre4，本次未新增数据库迁移、运行时依赖、Redis 运行态存储格式或选路算法变更。前后端应成套构建和部署；仅更新前端无法让旧后端产生快照。从更早版本升级仍需执行所跨版本的迁移和备份要求，不能仅依据本次增量判断可直接降级。

Known Issues

• 快照与选路存在可复现的差异窗口：管理接口可已读到新惩罚，而节点仍在使用约 1 秒的旧运行态缓存；SQL 配置已更新但节点配置缓存未刷新，也可产生不同候选结果。刷新页面不会强制同步全部节点的选路缓存。
• 异常状态不构成路由结论：管理投影未知时，真实选路可能继续使用缓存或配置值。界面不提供历史请求决策追踪，也未提供可比较全部节点的全局状态版本。
• 目标环境仍需独立验收：真实浏览器的视觉、键盘及窄屏交互尚未执行；正式 MySQL/PostgreSQL、实际 HTTP/认证链路、真实 Redis 重启或网络分区、持久化恢复、跨主机时钟偏差和部署回滚仍待验证。同机双进程与 miniredis 故障注入不替代这些检查。
• 历史版本兼容范围有限：兼容测试覆盖固定历史控制器、前端 schema/API 模块及相同共享依赖，未覆盖完整历史应用构建或两套真实 HTTP 服务混部。自定义客户端与滚动部署仍需按实际版本验证。

Highlights

• 解释运行态降权：渠道列表并列展示“配置优先级”和“快照有效优先级”，可以直接观察配置未变而路由受到惩罚的情况。
• 恢复条件更明确：区分超时降权、暂停路由、策略关闭与未知状态，展示快照时间、惩罚记录和恢复要求，避免把截止时间理解为恢复承诺。
• 刷新与编辑相互隔离：运行态可独立刷新，配置草稿不随轮询重置；列表在编辑或确认期间暂停自动刷新，并提供失败和陈旧提示。
• 用户邮箱直接可见：用户列表默认显示当前登记邮箱，结合现有邮箱关键字搜索和批量禁用流程，便于管理员直接在列表中核对账户。
• 兼容边界可验证：补充单节点链路、双进程缓存差异及历史模块兼容夹具，使用实际控制器响应与序列化保存载荷检查读写契约。

New Features

• 渠道列表运行态列：新增只读“快照有效优先级”，支持展开查看配置基值、记录惩罚、最近运行态事件、计算时间与适用范围。已知有效值 0 正常显示，运行态禁用和不可确认状态不填充为 0；该列不提供排序。
• 编辑面板路由快照卡片：已有渠道的编辑面板新增独立只读区域，支持手动刷新运行态并跳转至渠道健康设置。卡片明确以已保存配置为依据，刷新不提交表单，也不触发运行态恢复。
• 版本化管理投影：在现有渠道列表、搜索及详情接口中加入 routing_health，提供 normal、penalized、runtime_disabled、policy_off、unknown 状态，以及数据来源、活动惩罚、恢复模式、时间与不可用原因。投影不进入持久模型或选路缓存。
• 标签维度摘要：标签聚合行根据当前查询结果中的子渠道，展示降权、暂停和未知数量；存在不同有效值时显示多个有效优先级。摘要不代表标签的全库统计，也不借用第一个子渠道的快照。
• 用户管理邮箱列：在“用户名”后新增默认可见的“邮箱”列，可通过列视图菜单控制显隐；空邮箱显示 —，长地址沿用桌面悬停／移动端展开查看方式。复用六种语言的已有邮箱翻译，该列不提供排序；现有搜索、勾选和批量禁用流程继续使用原接口。

Improvements

• 按页面可见性刷新：可见页面约每 30 秒获取新快照，回到前台和达到快照中的截止时间时请求确认；后台页面暂停自动请求，前台事件去重，组件卸载后清理定时器和监听。截止计时只触发读取，不在客户端推算或改写有效优先级。
• 保护进行中的修改：列表在编辑面板、相关对话框、批量操作，以及优先级／权重编辑、确认和保存期间暂停自动刷新，并取消进行中的列表读取。编辑面板的运行态轮询使用独立缓存，不重新初始化配置表单。
• 统一配置变更后的刷新：渠道保存、行内修改及标签编辑后，同时使相关列表、详情与运行态缓存失效，减少配置已更新而卡片继续展示旧基值的情况。
• 明确失败与陈旧状态：刷新失败保留此前成功快照并提示可能过期；切换查询条件时，上一批结果中的运行态数值暂时隐藏。初次配置详情读取失败可重试，在配置尚未完成初始化前禁止保存。
• 多语言与窄屏布局：补充中、英、法、俄、日、越六种语言的状态和恢复提示；配置与快照两列纳入窄屏布局，长文案支持换行。源码和组件回归不替代真实设备视觉验收。

Bug Fixes

• 修复渠道管理只显示持久配置值、难以解释既有超时降权的问题；保留配置编辑语义，并单独呈现运行态观察值。
• 修复编辑期间详情重新读取或缓存失效可能重置未保存表单的问题；每个渠道的每次打开会话只初始化一次，重新打开或切换渠道时重新读取配置。
• 修复配置详情与运行态轮询交错时，较早发出的迟到响应可能覆盖较新观察值的问题；卡片同时保护初始数据写入和查询完成路径，按浏览器本地请求顺序接纳响应，不按跨节点时间戳判断新旧。这不保证响应来自全局最新状态。
• 修复将合法 0、字段缺失、不支持版本及损坏状态混为同一展示的问题；成功收到旧接口响应时清除此前运行态数值，失败刷新则保留旧快照并明确提示，二者分别处理。
• 修复运行态读取失败原因分类不准确的问题；管理投影分别返回 Redis 读取超时、请求取消和其他读取失败原因，避免将不同故障统一标记为普通读取失败。无法确认的状态继续显示未知，已成功读取的批次仍可保留。
• 修复标签配置优先级聚合使用 -1 作为初始化标记，导致合法负优先级与混合值判断冲突的问题；按子项顺序初始化，配置值不一致时显示“多个配置优先级”。
• 修复恢复提示直接依赖浏览器与服务端墙上时间一致的前提；改用快照内时间差与浏览器接收后的单调时钟经过时长安排提示和确认请求，防止仅因浏览器时钟偏差过早宣告到期。该修复不解决服务节点之间的时钟同步。

Verification

本说明以 v2.0.0-smartops.pre4 为比较基线，对应已提交源码 502171aca1828c54278d7760cc1ffb9b759c808f。增量集中于管理投影、渠道前端、用户邮箱列及相关回归测试；不包含本地未提交改动。

验证范围	已记录结果及适用边界
Linux CI	对应上述源码的 CI 40641969548 已通过：59 个有测试 Go 包通过、36 个包无测试；前端 602 项通过、0 失败、1 项跳过。go vet、JSON wrapper 检查、TypeScript 类型检查、前端生产构建及 Tailwind 检查通过。跳过项不计为通过。
单节点保存与选路链路	临时 SQLite 与 miniredis 下，通过真实控制器保存配置和超时评估写入惩罚，检查管理投影、数据库及缓存候选路径；配置 10、惩罚 2 得到快照 8，候选中配置 9 的渠道优先。管理读取及配置保存不清除运行态。
同机双进程与故障注入	覆盖新 Redis 状态与旧缓存、SQL 与节点配置缓存、节点策略差异、Redis 错误及到期／探测恢复。当前 CI 显式执行双进程集成测试并通过；结果以同机可比时钟及模拟 Redis 为前提。
历史版本兼容	本地隔离验收已通过固定历史控制器与前端模块的交叉读写；配置保存为 20、Redis 惩罚保持 2，新接口读回 18。覆盖缺字段、版本变化、未知、合法 0、失败刷新及草稿保护；仅证明固定源码与相同依赖下的隔离契约。该历史前端夹具在上述 CI 中跳过，不计为 CI 通过。
用户邮箱列与批量管理	已有专项通过目标文件 ESLint／格式检查、类型检查、生产构建与 Tailwind 检查；既有批量状态纯逻辑 11 项和 JSDOM 交互 9 项通过。用户邮箱列已包含在当前 CI 源码中；专项不替代真实浏览器验收。
Windows 本地回归边界	此前完整前端回归曾在渠道刷新测试长时间无结果后中止，本次未重跑；历史时序问题未据此归因或关闭。当前 Linux CI 的通过结果不等同于 Windows 本地问题已解决。
真实环境与发行制品	本次未执行真实浏览器、正式数据库、跨主机故障、实际部署及回退验收，也未核验最终镜像或二进制。构建、组件与隔离测试不替代目标环境验收。

本次增量未引入 RelayKit、Task Plugin 或协议转换同步，不据此宣称与最新上游能力一致。

升级检查清单

1. 确认升级范围：记录实际部署提交、前后端制品来源与回退起点。由 v2.0.0-smartops.pre4 升级时按本说明检查；从更早版本升级时，另查所跨版本的迁移、备份与回退要求。
2. 成套构建部署：源码部署先使用 Bun 构建 web/default，再使用 Go 1.26.10 构建后端，确保内嵌页面与接口配套。确认渠道列表、搜索和详情均来自预期版本；多节点应检查各节点策略、数据库配置与缓存更新情况，避免把不同节点观察值当成统一版本。
3. 检查接口兼容与故障提示：验证新增只读字段不破坏自定义客户端；覆盖合法 0、旧接口缺字段、未知版本、Redis 不可用及部分状态损坏，确认配置仍可读取和编辑，未知不会被当作健康或禁用结论。
4. 验证编辑和恢复流程：在存在未保存输入时触发手动刷新、后台切换、查询失败及延迟响应，确认草稿与保存载荷正确；检查到期后等待新快照、探测或人工恢复的提示符合所选策略。
5. 在实际环境核对选路并验收回退：固定分组、模型、重试、权重和候选条件，比对请求节点实际候选结果与管理快照；分别检查缓存过渡期、Redis 失效和恢复。回退后快照缺失应显示不支持，不能保留旧数值误导操作；真实混部与部署回滚仍须单独验收。
6. 核对用户邮箱展示及批量操作：在目标浏览器与窄屏布局下，确认邮箱列默认可见、空值与长地址可正确查看；搜索邮箱关键字后核对具体账户，再按既有确认流程变更状态。勿将当前登记邮箱当作不可变注册记录。

Full Changelog

查看自 v2.0.0-smartops.pre4 以来的完整变更