fix(api): 修复节点流量限额共享统计与父子显隐联动

统一节点流量统计与限额展示口径，节点详情新增昨日流量，
并让今日、昨日和本月使用清晰的半开时间窗口聚合

同 machine_id 或同 host 的节点现在共享当前账期已用流量，
管理端优先使用后端 traffic_limit_snapshot 展示月额度状态，
mi-node 下发的 current_used 也改为共享账期统计

新增 parent_auto_hidden 标记与父节点显隐联动服务，父节点
因自动上线或流量限额变为不可展示时会隐藏当前显示的子节点，
恢复时只恢复这批自动隐藏的子节点，避免覆盖手动操作

.helloagents/modules/_index.md

@@ -2,11 +2,11 @@
 
 | 模块名 | 说明 | 最近更新 |
 |--------|------|----------|
-| [admin-frontend](admin-frontend.md) | 管理端前端登录、布局、仪表盘、用户管理、节点管理与管理 API 封装 | 2026-04-28 |
+| [admin-frontend](admin-frontend.md) | 管理端前端登录、布局、仪表盘、用户管理、节点管理与管理 API 封装 | 2026-04-29 |
 | [ci-workflows](ci-workflows.md) | GitHub Actions 镜像发布工作流、路径触发规则与前后端镜像发布边界 | 2026-04-28 |
 | [deploy](deploy.md) | 可复制到服务器的 Xboard Compose 部署模板、环境变量模板和运维脚本 | 2026-04-28 |
 | [node-gfw-check](node-gfw-check.md) | 节点墙状态检测任务、父/子节点继承规则、mi-node 检测上报链路 | 2026-04-28 |
-| [node-traffic-limit](node-traffic-limit.md) | 节点月流量限额配置、重置调度、metrics 状态回写与 mi-node 强制下线协作 | 2026-04-28 |
+| [node-traffic-limit](node-traffic-limit.md) | 节点月流量限额配置、共享账期用量、重置调度、metrics 状态回写与 mi-node 强制下线协作 | 2026-04-29 |
 | [order-payment](order-payment.md) | 订单支付成功快照、第三方回调元信息透传与后台支付成功信息展示 | 2026-04-25 |
 | [queue-mail](queue-mail.md) | 邮件发送队列、SMTP 运行时配置、Horizon 超时与失败重试边界 | 2026-04-28 |
 | [subscription-protocols](subscription-protocols.md) | 用户订阅导出入口、协议适配器与 Stash / Clash 系列兼容过滤 | 2026-04-24 |

.helloagents/modules/admin-frontend.md

@@ -46,9 +46,9 @@
 - 节点管理页现支持墙状态展示、墙状态筛选与关键词搜索；父节点可通过行级或批量操作发起检测，子节点不单独检测并显示“随父节点”的继承状态
 - 节点管理页现支持“墙检测托管”开关、批量设置和刷新数据按钮；父节点开启后参与 `sync:server-gfw-checks` 自动检测，自动墙检统计只计算父节点；子节点不独立检测但可控制是否随父节点自动隐藏 / 恢复
 - 节点行级菜单现已补齐“置顶节点”，会复用当前排序结果生成新的顺序 payload 并提交到 `server/manage/sort`
-- 节点列表中鼠标悬停节点名称会显示节点流量详情卡；`server/manage/getNodes` 会返回 `traffic_stats.today/month/total`，三组数据均来自 `v2_stat_server` 按节点聚合，前端统一按 B/KB/MB/GB/TB 自适应格式化展示上行、下行和合计
+- 节点列表中鼠标悬停节点名称会显示节点流量详情卡；`server/manage/getNodes` 会返回 `traffic_stats.today/yesterday/month/total`，其中今日、昨日和本月按半开时间窗口从 `v2_stat_server` 聚合，累计不加时间窗口，前端统一按 B/KB/MB/GB/TB 自适应格式化展示上行、下行和合计
 - 节点新增 / 编辑弹窗现支持月流量限额配置，字段包含启用开关、月流量额度 GB、重置日期、重置时间和时区；保存时会把 GB 转为字节写入 `transfer_enable`，并提交 `traffic_limit_*` 字段
-- 节点流量详情卡会在启用限额时追加“月额度”进度、限额状态和下次重置时间，节点标签区同步显示正常 / 接近额度 / 已限额状态；搜索关键字可匹配“流量限额 / 月流量 / 超额下线”
+- 节点流量详情卡会在启用限额时追加“月额度”进度、限额状态和下次重置时间，优先使用 `server/manage/getNodes` 返回的 `traffic_limit_snapshot` 展示同 `machine_id` 或同 host 的共享当前账期用量；后端缺少快照时回退 mi-node metrics / `u+d`，节点标签区同步显示正常 / 接近额度 / 已限额状态；搜索关键字可匹配“流量限额 / 月流量 / 超额下线”
 - 权限组管理页使用真实后端 `server/group/fetch`、`server/group/save` 与 `server/group/drop`，支持关键字搜索、新增/编辑中央弹窗、删除确认，以及从节点数量列跳转到 `#/nodes?group={id}` 的筛选联动
 - 路由管理页使用真实后端 `server/route/fetch`、`server/route/save` 与 `server/route/drop`，支持路由列表、关键词搜索、新增/编辑中央弹窗、删除与动作值展示
 - 路由管理页的节点引用摘要由 `server/manage/getNodes` 返回的 `route_ids` 推导，不在前端伪造额外接口

.helloagents/modules/node-traffic-limit.md

@@ -5,22 +5,32 @@
 - 保存节点级月流量限额配置、重置规则和运行状态
 - 将限额配置下发给 `mi-node`，由节点端执行真实内核停启
 - 在手动重置、定时重置和节点 metrics 回传时同步面板侧状态
+- 为管理端和 mi-node 下发提供共享月额度快照，统一计算同机器 / 同 host 节点的当前账期已用流量
 
 ## 行为规范
 
-- `v2_server.transfer_enable` 是节点月流量额度，单位为字节；新增字段只负责启用状态、重置日、重置时间、时区和运行状态
+- `v2_server.transfer_enable` 是节点月流量额度配置，单位为字节；新增字段只负责启用状态、重置日、重置时间、时区和运行状态
 - `traffic_limit_enabled=false` 或 `transfer_enable<=0` 时不启用节点限额，`ServerTrafficLimitService::buildNodeConfig()` 仍会下发 disabled 配置，旧行为保持不变
 - 重置日支持 `1-31`，短月按当月最后一天计算；重置时间使用 `HH:mm`，时区优先使用节点字段，空值或非法值回退 `config('app.timezone')`
+- 月额度使用量按共享范围计算：优先按 `machine_id` 聚合，未绑定机器时按规范化后的 `host` 聚合，空 host 回退单节点范围；同一范围内的节点在管理端快照中返回相同 `used / scope_key / scope_node_ids`
+- 共享月额度按当前账期统计：`ServerTrafficLimitService::calculateCurrentCycleStartAt()` 会取当前时间之前最近一次重置边界，`current_used` 优先聚合 `v2_stat_server.record_type='d'` 在 `[cycle_start_at, now]` 日粒度窗口内的 `u+d`
+- 当前账期没有统计行时回退共享范围内 `v2_server.u + v2_server.d`；同范围任一节点有当前有效的 mi-node runtime metrics 时，快照会取 metrics `used` 的最大值并保留同限额下的 `suspended` 运行态
+- `ServerTrafficLimitService::buildNodeConfig()` 下发给 mi-node 的 `traffic_limit.current_used` 使用共享账期口径，不再只使用当前单节点的 `u+d`
+- `ServerTrafficLimitService::buildSnapshotsForServers()` 为管理端节点列表批量生成 `traffic_limit_snapshot`，避免前端自行按 IP 猜测共享规则
 - 管理端保存节点后调用 `ServerTrafficLimitService::refreshSchedule()` 计算 `traffic_limit_next_reset_at`，并通过 `NodeSyncService::notifyConfigUpdated()` 通知节点更新配置
-- 手动重置和定时重置统一走 `ServerTrafficLimitService::resetServer()`：清空节点 `u/d`，恢复 `traffic_limit_status=normal`，记录 `traffic_limit_last_reset_at`，计算下一次重置时间，并触发 `notifyFullSync()`
+- 手动重置和定时重置统一走 `ServerTrafficLimitService::resetServer()`：清空当前节点 `u/d`，恢复 `traffic_limit_status=normal`，记录 `traffic_limit_last_reset_at`，计算下一次重置时间，并触发 `notifyFullSync()`；该接口不批量重置同共享范围的其他节点
 - `sync:server-traffic-limits` 每分钟扫描到期且启用限额的节点，只处理 `traffic_limit_next_reset_at <= now()` 的记录，不影响未启用限额的节点
 - `ServerService::updateMetrics()` 会缓存 `metrics.traffic_limit` 并把节点端 `suspended / last_reset_at / next_reset_at / suspended_at` 写回 `v2_server`
-- 限额下线不修改 `show`、`auto_online` 或墙检测字段；真实下线由 `mi-node` 调用内核 `Stop()` 完成
+- 限额下线不修改父节点自身的 `show`、`auto_online` 或墙检测字段；真实下线由 `mi-node` 调用内核 `Stop()` 完成
+- 父节点限额状态变为 `suspended` 时会通过 `ServerParentVisibilityService` 自动隐藏当时仍显示的直接子节点，并写入 `parent_auto_hidden=1`；限额重置或恢复 `normal` 后只恢复这些由父节点联动自动隐藏的子节点，原本手动隐藏的子节点保持隐藏
 
 ## 依赖关系
 
 - 依赖 `app/Services/ServerTrafficLimitService.php` 统一处理配置下发、时间计算、状态回写和重置
+- 依赖 `app/Services/ServerParentVisibilityService.php` 在父节点限额下线 / 恢复时同步直接子节点显隐
 - 依赖 `app/Services/ServerService.php` 在节点配置中追加 `traffic_limit` 并消费节点 metrics
+- 依赖 `app/Http/Controllers/V2/Admin/Server/ManageController.php` 在 `server/manage/getNodes` 响应中返回 `traffic_limit_snapshot`
+- 依赖 `v2_stat_server` 的日统计记录作为当前账期共享已用流量的主要来源
 - 依赖 `app/Observers/ServerObserver.php` 在限额配置变化时推送 `sync.config`
 - 依赖 `app/Console/Commands/SyncServerTrafficLimits.php` 与 Laravel Scheduler 执行到期重置
 - 依赖管理端 `admin-frontend/src/utils/nodeEditor*`、`admin-frontend/src/utils/nodes.ts` 和 `admin-frontend/src/views/nodes/*` 提供配置与展示入口