feat: 新增网关限流
All checks were successful
构建并部署前端到测试环境 / deploy (push) Successful in 56s

This commit is contained in:
luo
2026-10-24 16:22:28 +08:00
parent ecce4f6e7b
commit 049f8257fb
32 changed files with 3569 additions and 4 deletions

View File

@@ -0,0 +1,41 @@
## Context
项目使用 Vue 3、TypeScript、Element Plus 和 BaseService。后端控制菜单模式下,超级管理员直接使用全部静态路由,普通用户使用授权菜单;按钮控制复用现有 `useAuth`,身份复用 `userStore.isSuperAdmin`。
## Goals / Non-Goals
- Goals: 完整接入文档声明的 API、可操作的管理页面、可靠表单校验、清晰权限配置交付。
- Non-Goals: 不实现后端限流,不改变旧轮询/停复机行为,不部署,不猜测统计指标字段。
## Decisions
- 四页统一归属「轮询管理」,不新增一级菜单:
| 页面 | URL | 父菜单 |
| --- | --- | --- |
| 停复机记录 | `/polling-management/stop-resume-records` | 轮询管理 `/polling-management` |
| 上游错误分类 | `/polling-management/error-classifications` | 轮询管理 `/polling-management` |
| 网关限流组 | `/polling-management/rate-limit-groups` | 轮询管理 `/polling-management` |
| 网关调用统计 | `/polling-management/gateway-stats` | 轮询管理 `/polling-management` |
| 网关限流组详情(隐藏路由) | `/polling-management/rate-limit-groups/detail/:id` | 轮询管理 `/polling-management` |
- 页面权限分别为 `card_stop_resume_record:page`、`gateway_error_classification:page`、`gateway_rate_limit_group:page`、`gateway_call_stats:page`,隐藏详情路由使用 `gateway_rate_limit_group:detail_page`。普通操作权限为 `gateway_error_classification:test`、`gateway_rate_limit_group:detail`、`gateway_call_stats:trend`;单卡入口按资产类型使用 `iot_info:stop_resume_records` / `device_info:stop_resume_records`。这些是前端配置约定,不声称来自后端接口文档;详情页与按钮使用独立编码,避免菜单与按钮编码冲突。
- 超级管理员维护入口不定义供普通账号分配的增删改权限;UI 与事件处理双重身份检查,后端继续独立鉴权。
- 提取专用新模块承载网关契约,避免覆盖旧 `/api/cards/{iccid}/suspend-resume-records` 接口及其不同 DTO。
- 枚举请求失败显式展示错误和重试,不把不可用枚举误报为空;未知值在只读展示中保留原值。
- 时间统一转换 RFC3339;全局记录查询必须有完整区间,单卡可使用后端默认;分页最大 100。
- 统计内部字段使用 `unknown`/记录值承载,只展示实际返回字段,空值不转成业务零;不从不明确字段推导图表或指标。
- 界面复用项目现有表格、搜索区、分页、弹窗、主题变量及状态标签;参考 UI/UX skill 的加载反馈、可访问标签、键盘焦点与响应式原则,不更换全站字体、颜色或新增表单依赖。
- 用户补充要求:列表严格复用店铺列表的 ArtSearchBar / ArtTableHeader / ArtTable / ArtTableFullScreen;详情使用店铺详情的返回、标题和双列描述表。时间展示复用同一个 `formatDateTime`,不改变请求与数据源;展开按钮仅在搜索条件数 >= 4 时出现。
- 运营商账户一律名称搜索下拉,复用 `CarrierService.getCarriers({ page: 1, page_size: 20, carrier_name })`,保留原账户名称回显,选中后仍提交 ID;趋势额外保留「无法解析账户的卡」的值 0。
## Risks / Trade-offs
- 统计契约缺字段 → 接口和数据可查看,但正式业务趋势图需后端样例或完整 DTO 后再确定。
- 前端权限编码未在 API 文档定义 → 交付明确为菜单按钮配置编码,不替代后端鉴权。
- 31 天日期窗口和不同时区 → 按实际时间戳差值校验,测试边界与非法值。
- 用户已有未提交改动 → 不碰部署文件及 package 配置,不引入新依赖。
## Validation
服务契约测试覆盖所有 17 个接口;业务测试覆盖时间范围、QPS、优先级操作、超级管理员门禁、枚举值和统计未知字段。执行 `vue-tsc --noEmit`、Vite 构建、针对性 lint/格式/编码检查。没有真实后端响应时,明确区分本地 mock 验证与线上联调。

View File

@@ -0,0 +1,32 @@
# Change: 网关限流管理前端接入
## Why
`docs/网关限流.md` 新增 17 个管理端接口,当前前端缺少网关限流组、上游错误分类、全局停复机记录及按运营商统计的入口。需要完整接入已定义契约,并在交付时提供普通账号需要配置的菜单与按钮权限,不列出仅超级管理员的操作。
## What Changes
- 在现有「轮询管理」下新增「停复机记录」「上游错误分类」「网关限流组」「网关调用统计」四个页面。
- 接入全部 17 个接口及类型;枚举通过 `GET /api/admin/polling-options` 获取,不把可配置枚举仅写死在前端。
- 停复机记录支持文档内筛选、分页、必填时间范围和 31 天跨度校验;单卡信息及设备绑定卡提供单卡历史入口,使用卡 ID 请求新接口。
- 分类规则支持分页筛选、测试现有规则和草稿;限流组支持分页筛选和详情。新建、修改、启停、删除均仅向超级管理员开放,并在操作函数中再次检查身份。
- 限流组表单校验 QPS、预留额度与高优先级操作的关系,删除和启停提供确认与防重复提交。
- 网关统计支持账户汇总及账户趋势查询,校验各接口时间参数。
- 接入路由别名、静态路由和现有后端菜单模式;使用 `xxx:xxx` 格式前端权限常量控制普通用户操作。
- 新增契约、参数校验、权限分支和交互回归测试,运行类型检查、构建及编码检查。
- 完工后输出菜单配置清单(名称、URL、父菜单)与按钮权限编码;清单仅保留非超级管理员专属项。
## Impact
- Affected specs: `gateway-rate-limit-management`(新增)。当前 `openspec list --specs` 无已归档规范;现有 `add-polling-priority-queue` 已完成,与本次新增页面并列,不修改其行为。
- Affected code: `src/types/api/`、`src/api/modules/`、`src/config/constants/`、`src/views/polling-management/`、`src/views/asset-management/asset-information/`、`src/router/routesAlias.ts`、`src/router/routes/asyncRoutes.ts`、`scripts/tests/`。
- 不修改网关后端限流算法、既有轮询调度、停复机执行动作;不自动创建数据库菜单,不推送 Git,不执行生产部署。
- 保留用户在 `.gitea/workflows/deploy.yaml` 与 `package.json` 的现有修改。
## Contract boundary
文档未提供统计接口 `carriers[]`、`points[]` 内部字段,仓库当前也没有 `docs/admin-openapi.yaml` 可补全。实现不得假定次数、失败率、时间戳等字段:先按实际响应提供可查看的动态字段表格/原始数据,并清楚提示契约未展开;有真实字段样例后才绘制业务趋势图。不得用虚构字段或零值冒充统计结果。
权限编码是前端配置约定,并非接口文档声明的后端权限;实际授权仍由后端控制。仅超级管理员限制必须依据现有 `userStore.isSuperAdmin`,不能通过配置普通按钮权限绕过。
用户于 2026-10-24 回复「直接执行」,已批准按此范围实施。

View File

@@ -0,0 +1,98 @@
## ADDED Requirements
### Requirement: 停复机记录查询
The frontend SHALL provide global stop/resume records and single-card history using the two documented admin APIs. Global queries MUST include RFC3339 `start_time` and `end_time` with an ordered range no greater than 31 days, all documented optional filters and pagination of at most 100 rows. Single-card history MUST use the card ID rather than ICCID or device ID.
#### Scenario: 查询全局记录
- **WHEN** 用户进入页面或修改筛选、页码
- **THEN** 前端 MUST 请求 `/api/admin/card-stop-resume-records`,展示记录字段及 `items/page/size/total`
- **AND** 不合法或缺失的时间区间 MUST 阻止请求并显示明确提示。
#### Scenario: 查看单卡历史
- **WHEN** 获授权用户从单卡或设备绑定卡打开历史
- **THEN** 前端 MUST 请求 `/api/admin/iot-cards/{id}/stop-resume-records`
- **AND** 无卡 ID 或无入口权限时 MUST 不请求接口,切换卡后不得残留另一张卡的结果。
### Requirement: 上游错误分类规则
The frontend SHALL implement rule listing, creation, modification, status change, deletion and non-persistent testing according to the documented fields. Rule maintenance MUST be restricted to super administrators. Testing SHALL support the current rule set and an optional valid draft, and display `matched/rule_id/category/category_name/keyword/maybe_accepted`.
#### Scenario: 普通账号测试分类
- **WHEN** 具有测试权限的用户提交操作与上游原始信息
- **THEN** 前端 MUST 调用 `/api/admin/gateway-error-classifications/test` 并展示实际命中结果
- **AND** 空信息或超过 1000 字符 MUST 不得提交,不通过增删改接口测试草稿。
#### Scenario: 超级管理员维护
- **WHEN** 超级管理员提交合法规则或确认启停、删除
- **THEN** 前端 MUST 使用对应 CRUD 或 status 接口,成功后刷新列表
- **AND** 普通账号 MUST 不显示维护入口且无法从处理函数发起维护请求。
### Requirement: 网关限流组
The frontend SHALL implement group listing, details, creation, modification, status change and deletion, including carrier/global and status filters. Maintenance MUST be restricted to super administrators. `max_qps` MUST be an integer in 1–10000, `reserved_qps` MUST be a nonnegative integer less than `max_qps`, operations MUST be nonempty, high-priority operations MUST be a subset and MUST be nonempty when reserved QPS is positive.
#### Scenario: 维护限流组
- **WHEN** 超级管理员提交限流组
- **THEN** 前端 MUST 校验文档的必填、长度、范围及操作关联约束后调用 POST 或 PUT
- **AND** 全局组 MUST 使用空账户值,不得错误提交为具体账户。
#### Scenario: 查询限流组
- **WHEN** 获授权用户查询列表或详情
- **THEN** 前端 MUST 分别调用 `/api/admin/polling-rate-limit-groups` 或 `/{id}` 并展示真实字段
- **AND** 普通账号 MUST 不能通过详情页进入维护操作。
### Requirement: 动态枚举与统计
The frontend SHALL load all seven enum collections from `/api/admin/polling-options`, and SHALL implement carrier summary and trend requests with documented parameter bounds. Undefined inner fields in `carriers` and `points` MUST be presented transparently from actual response data without invented metrics, silently substituted zeros or assumed chart series.
#### Scenario: 加载枚举
- **WHEN** 页面需要筛选、编辑或显示网关枚举
- **THEN** 前端 MUST 使用接口的 label/value,失败时提供错误反馈及重试
- **AND** 未知只读枚举值 MUST 保留原始值,不被显示为另一个已知状态。
#### Scenario: 查询汇总与趋势
- **WHEN** 用户选择合法的统计区间、运营商和聚合粒度
- **THEN** 前端 MUST 请求对应 `/api/admin/polling-stats/carriers` 或 `/{carrier_id}/trend`
- **AND** 汇总 minutes 为 1–60,趋势 minutes 不超过 10080,粒度为有效正整数,账户 0 MUST 可用
- **AND** 契约缺失的内部字段 MUST 以实际字段或原始数据展示并说明限制。
### Requirement: 菜单权限与交付
The frontend SHALL register four pages under existing polling management and honor the existing static/superadmin and backend-menu routing modes. Normal actions MUST use explicit `xxx:xxx` permissions. The handoff SHALL list menu name, URL, parent menu and button permission codes only for non-superadmin-exclusive configuration.
#### Scenario: 普通账号访问
- **WHEN** 普通账号获得相应菜单和按钮权限
- **THEN** 对应页面和普通查询、测试操作 MUST 可用
- **AND** 未授权按钮和请求 MUST 不可用,超级管理员专属维护能力 MUST 不被普通按钮权限开启。
#### Scenario: 交付配置清单
- **WHEN** 实现和验证结束
- **THEN** 交付 MUST 列出实际实现的普通菜单与按钮权限,不列出仅超级管理员专属配置
- **AND** MUST 披露未进行真实后端联调或统计字段不完整等验证限制。
### Requirement: 店铺页面一致性
The frontend SHALL reuse the shop list search, table header, column settings, fullscreen and pagination components, and the shop detail back button, title and responsive description layout. All displayed business timestamps MUST use the same `formatDateTime` formatter as the shop list. Search expansion MUST be enabled if and only if there are at least four search fields. Carrier selection MUST be a remote dropdown searched by carrier name using `/api/admin/carriers?page=1&page_size=20&carrier_name=...` while requests keep numeric IDs.
#### Scenario: 展开与时间显示
- **WHEN** 页面有少于 4 个搜索条件
- **THEN** `show-expand` MUST 为 false;4 个及以上 MUST 为 true
- **AND** 已知列表、详情及统计数据中的业务时间 MUST 展示为店铺列表相同格式,不直接显示 RFC3339 字符串。
#### Scenario: 按名称搜索运营商
- **WHEN** 用户在运营商账户下拉输入名称
- **THEN** 前端 MUST 请求 carriers 列表并携带 page=1、page_size=20、carrier_name
- **AND** 编辑回显 MUST 保留原账户名称,筛选/保存 MUST 提交所选 numeric carrier_id,趋势未解析账户 MUST 仍可选择值 0。

View File

@@ -0,0 +1,29 @@
## 1. 契约和公共能力
- [x] 1.1 确认提案并记录审批。
- [x] 1.2 新增全部接口请求、响应类型和服务方法,统一导出,复用现有认证及错误处理。
- [x] 1.3 接入动态枚举、权限常量、分页与日期/限流参数校验工具。
## 2. 页面与入口
- [x] 2.1 新增停复机记录列表,支持全部筛选字段、分页、默认最近时间段和 31 天校验。
- [x] 2.2 单卡及设备绑定卡新增停复机历史入口,使用真实卡 ID,处理权限及卡切换状态。
- [x] 2.3 新增上游错误分类页,支持列表筛选、超级管理员维护及现有规则/草稿测试结果展示。
- [x] 2.4 新增网关限流组页,支持列表、详情、超级管理员维护及关联字段校验。
- [x] 2.5 新增网关调用统计页,支持汇总、趋势参数和未定义内部字段的透明展示。
- [x] 2.6 注册路由别名、四个菜单路由及隐藏详情路由、页面权限;复用现有后端菜单解析模式。
## 3. 验证与交付
- [x] 3.1 覆盖全部服务 URL、HTTP 方法、参数和响应的契约测试。
- [x] 3.2 覆盖时间、QPS、高优先级操作子集、权限和动态枚举回归测试。
- [x] 3.3 检查加载、错误、空数据、确认、重复提交和响应式显示。
- [x] 3.4 执行类型检查、构建、相关回归测试、格式与编码检查,记录实际结果。
- [x] 3.5 交付菜单名称/URL/父菜单和按钮权限编码,仅列非超级管理员专属配置。
## 验证结果
- 全量 Node 回归 153/153 通过,其中网关新增 23 项;`vue-tsc --noEmit`、生产构建、针对性 ESLint/Stylelint、格式和 UTF-8 检查通过。
- 本地 mock 浏览器验证:列表与详情、规则测试、按运营商名称搜索、账户 0 趋势、普通账号无维护按钮及授权隐藏详情路由;375px / 768px / 1024px / 1440px 检查与局部截图复核。
- 菜单与按钮清单写入 `docs/权限.md`,本地详细接入说明位于 `docs/网关限流-前端接入说明.md`(仓库默认忽略其他 docs 文件)。
- 未进行真实后端联调、Git 推送或生产部署;统计内部字段缺失时按实际响应展示。构建仍有项目既有常量绑定、循环依赖和大 chunk 警告。